Escribir nuevos algoritmos de procesamiento como scripts python

Puede crear sus propios algoritmos escribiendo el código Python correspondiente y añadiendo algunas líneas adicionales para suministrar la información adicional necesaria para definir la semántica del algoritmo. Puede encontrar un menú Crear nuevo script bajo el grupo Herramientas en el bloque de algoritmos Script de la caja de herramientas. Haga doble clic en él para abrir el diálogo de edición de script. Ahí es donde se debe escribir el código. Guardar el script desde allí en la carpeta scripts (el predeterminado cuando se abre el diálogo de guardar archivo), con la extensión .py, creará automáticamente el algoritmo correspondiente.

The name of the algorithm (the one you will see in the toolbox) is created from the filename, removing its extension and replacing low hyphens with blank spaces.

Vamos a tener el siguiente código, que calcula el Índice de Humedad Topográfico (TWI) directamente desde un DEM

##dem=raster
##twi=output raster
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea", dem,
                0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindextwi, ret_slope['SLOPE'],
                ret_area['AREA'], None, 1, 0, twi)

As you can see, it involves 3 algorithms, all of them coming from SAGA. The last one of them calculates the TWI, but it needs a slope layer and a flow accumulation layer. We do not have these ones, but since we have the DEM, we can calculate them calling the corresponding SAGA algorithms.

La parte del código donde este procesamiento se lleva a cabo no es difícil de entender si has leído el capítulo anterior. Las primeras líneas, sin embargo, necesitan una explicación adicional. Proporcionan la información que se necesita para convertir su código en un algoritmo que se pueda ejecutar desde cualquiera de los componentes GUI, como la caja de herramientas o el modelador gráfico.

Estas líneas comienzan con un doble símbolo de comentario en Python (##) y tiene la siguiente estructura

[parameter_name]=[parameter_type] [optional_values]

Here is a list of all the parameter types that are supported in processign scripts, their syntax and some examples.

  • raster. Una capa ráster

  • vector. Una capa vectorial

  • table. Una tabla

  • number. Un valor numérico. Un valor predeterminado debe ser proporcionado. Por ejemplo, depth=number 2.4

  • string. Una cadena de texto. Como en el caso de los valores numéricos, un valor predeterminado se debe añadir. Por ejemplo, name=string Victor

  • longstring. Igual que el string, pero un cuadro de texto más grande se mostrará, por lo que es más adecuado para cadenas largas, como para un script esperando un pequeño fragmento de código.

  • boolean. Un valor boolean. Añade True o False después para establecer el valor predeterminado. Por ejemplo, verbose=boolean True.

  • multiple raster. Un conjunto de capas ráster de entrada.

  • multiple vector`. Un conjunto de capas vectoriales de entrada.

  • field. Un campo en la tabla de atruibutos de una capa vectorial. El nombre de la capa se tiene que añadir después de la etiqueta field. Por ejemplo, si ha declarado una vectorial de entrada con mylayer=vector, podría utilizar myfield=field mylayer para añadir un campo de esa capa como parámetro.

  • folder. Una carpeta

  • file. Un nombre de archivo

  • crs. Un Sistema de Referencia de Coordenadas

El nombre del parámetro es el nombre que se mostrará al usuario cuando ejecute el algoritmo, y también el nombre de la variable a utilizar en el código del script. El valor introducido por el usuario para ese parámetro será asignado a una variable con ese nombre.

When showing the name of the parameter to the user, the name will be edited it to improve its appearance, replacing low hyphens with spaces. So, for instance, if you want the user to see a parameter named A numerical value, you can use the variable name A_numerical_value.

Layers and tables values are strings containing the filepath of the corresponding object. To turn them into a QGIS object, you can use the processing.getObjectFromUri() function. Multiple inputs also have a string value, which contains the filepaths to all selected objects, separated by semicolons (;).

Las salidas son definidas en una manera similar, utilizando las siguientes etiquetas:

  • ráster de salida

  • vector de salida

  • tabla de salida

  • html de salida

  • archivo de salida

  • número de salida

  • texto de salida

  • Extensión de salida

El valor asignado a las variables de salida es siempre una cadena con una ruta de archivo. Corresponderá a una ruta de archivo temporal en el caso de que el usuario no ha introducido ningún nombre de archivo de salida.

Además de las etiquetas para los parámetros y resultados, también puede definir el grupo en las que se muestra el algoritmo, utilizando la etiqueta group.

La última etiqueta que se puede utilizar en su cabecera guión es ##nomodeler. Utilice que cuando no quiere que su algoritmo se muestra en la ventana modelador. Esto se debe utilizar para los algoritmos que no tienen una sintaxis clara (por ejemplo, si el número de capas que se crearon no se conoce de antemano, en tiempo de diseño), que los hacen inadecuados para el modelador gráfico

Manipulación de datos producidos por el algoritmo

When you declare an output representing a layer (raster, vector or table), the algorithm will try to add it to QGIS once it is finished. That is the reason why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded, since it is saved to the file entered by the user, which is the value of the corresponding output.

No utilice el método load() en sus algoritmos de script, sino sólo cuando se trabaja con la línea de la consola. Si se crea una capa como salida de un algoritmo, que debe ser declarada como tal. De lo contrario, usted no será capaz de utilizar correctamente el algoritmo en el modelador, ya que su sintaxis (según la definición de las etiquetas se ha explicado anteriormente) no coincidirá con lo que crea realmente el algoritmo.

Salidas ocultas (números y cadenas) no tienen un valor. En cambio, es quien tiene que asignar un valor a los mismos. Para ello, acaba de establecer el valor de una variable con el nombre que utilizó para declarar la salida. Por ejemplo, si ha usado esta declaración,

##average=output number

En la siguiente línea se establezerá el valor de la salida a 5:

average = 5

La comunicación con el usuario

Si su algoritmo toma mucho tiempo para procesar, es una buen idea informar al usuario. Se tiene un nombre global progreso disponible, con dos métodos disponibles: setText(text) y setPercentage(percent) para modificar el texto y la barra de progreso.

Si tiene información para proporcionar al usuario, no relacionada al progreso del algoritmo, se puede utilizar el método setInfo(text), también del objeto progreso.

Si su script tiene algún problema, la forma correcta de propagación es plantear una excepción de tipo GeoAlgorithmExecutionException(). Se puede pasar un mensaje como argumento al constructor de la excepción. El procesamiento se hará cargo de la manipulación y comunicación con el usuario, dependiendo desde donde se este ejecutando el algoritmo (Caja de herramientas, modelador, consola Python...)

Documentando sus scripts

As in the case of models, you can create additional documentation for your script, to explain what they do and how to use them. In the script editing dialog you will find a [Edit script help] button. Click on it and it will take you to the help editing dialog. Check the chapter about the graphical modeler to know more about this dialog and how to use it.

Help files are saved in the same folder as the script itself, adding the .help extension to the filename. Notice that you can edit your script’s help before saving it for the first time. If you later close the script editing dialog without saving the script (i.e. you discard it), the help content you wrote will be lost. If your script was already saved and is associated to a filename, saving is done automatically.

Scripts de ejemplo

Varios ejemplos están disponibles en la colección en línea de scripts, que pueden acceder al seleccionarlo la herramienta Obtener script de la colección de script en línea bajo la entrada Scripts/herramientas en la caja de herramientas.

../../../_images/script_online.png

Por favor, compruebe con ellos para ver ejemplos reales de cómo crear algoritmos que utilizan las clases de la arquitectura de procesamiento. Puede hacer clic derecho sobre cualquier algoritmo de secuencia de comandos y seleccione Editar script para editar su código o simplemente para verlo.

Las mejores practivas al escribir scripts de algoritmos

Aquí esta un resumen rápido de ideas a considerar cuando crea su propio script de algoritmos y especialemente, si se desea compartir con otros usuarios de QGIS. Siguiendo estas sencillas reglas asegurará la consistencia entre los diferentes elementos de procesamiento, tales como la caja de herramientas, el modelador o la interfaz de procesamiento por lotes.

  • No cargar la capa resultante. Deje al Procesamiento manejar sus resultados y cargue sus capas si es necesario.

  • Declarar siempre las salidas de su algoritmo creado. Evitar cosas tales como declarar una salida y luego usando el nombre de archivo de destino establecido para esa salida para crear una colección de ellos. Eso romperá la semántica correcta del algoritmo y hará que sea imposible usar de forma segura en el modelador. Si usted tiene que escribir un algoritmo así, asegúrese de agregar la etiqueta ##nomodeler.

  • No mostrar cajas de mensaje o utilice algún elemento GUI desde el script. Si desea comunicarse con el usuario, utilice el método setInfo() o lance GeoAlgorithmExecutionException

  • Como una regla de oro, no olvide que su algoritmo puede ser ejecutado en un contexto que no sea la caja de herramientas de procesamiento.

Pre y post ejecución de ganchos de scripts

Los scripts también pueden ser utilizados para establecer ganchos pre y post ejecución, que se ejecutan antes y después de un algoritmo. Esto se puede utilizar para automatizar tareas que deben realizarse cada vez que se ejecuta un algoritmo.

La sintaxis es idéntica a la que se ha explicado anteriormente, pero una variable global adicional llamada alg esta disponible, lo que representa el algoritmo que acaba de ser (o esta a punto de ser) ejecutado.

En el grupo General del cuadro de diálogo de configuración de procesamiento se encuentran dos entradas llamadas Archivo de script de pre-ejecución y el script :guilabel: Archivo script post-ejecución donde el nombre de archivo de los scripts que deben ejecutarse en cada caso se pueden introducir.