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.
El nombre del algoritmo (el que podrá ver en la caja de herramientas) se crea a partir del nombre de archivo, elimine su extensión y sustituya los guiones bajos con espacios en blanco.
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)
Como se puede ver, se trata de 3 algoritmos, todos ellos procedentes de SAGA. El último de ellos calcula el TWI, pero necesita una capa de pendiente y una capa de acumulación de flujo. Nosotros no tenemos estos, pero ya tenemos el DEM, podemos calcularlos llamando a los algoritmos de SAGA correspondientes.
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]
Aquí esta una lista de todos los tipos de parámetros que se admiten en scripts de procesamiento, su sintaxis y algunos ejemplos.
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.
extent. Una extensión espacial definida por xmin, xmax, ymin, ymax
folder. Una carpeta
file. Un nombre de archivo
crs. Un Sistema de Referencia de Coordenadas
selection. Un menú desplegable que permite al usuario seleccionar desde una lista prepoblada. Por ejemplo units=selection sq_km;sq_miles;sq_degrees
name. Nombre del script. Este se desplegará como el nombre del algoritmo en la caja de herramientas de procesado. Por ejemplo El nombre de mi algoritmo=name
group. EL nombre de la carpeta donde el script aparece en la caja de herramientas de procesado. Por ejemplo, añadir Utils=groups poner el script dentro de la carpeta Utils, dentro del los Scripts.
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.
Cuando muestra el nombre del parámetro al usuario, el nombre será editado para mejorar su apariencia, en sustitución de guiones bajos con espacios. Así, por ejemplo, si desea que el usuario vea un parámetro llamado Un valor numérico, puede utilizar el nombre de la variable A_numerical_value.
Los valores de capas y tablas son cadenas que contienen la ruta del archivo del objeto correspondiente. Para convertirlos en un objeto QGIS, puede utilizar la función processing.getObjectFromUri(). Las múltiples entradas también tienen un valor de cadena, que contiene las rutas de los archivos a todos los objetos seleccionados, separados por punto y coma (;).
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¶
Cuando se declara una representación de salida, una capa (raster, vector o tabla), el algoritmo intentará agregarlo a QGIS una vez que esté terminado. Esa es la razón por la cual, aunque el método runalg() no carga las capas que produce, la capa final TWI se cargará, ya que se guarda en el archivo introducido por el usuario, que es el valor de la salida correspondiente.
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¶
Al igual que en el caso de los modelos, se pueden crear documentación adicional para su script, para explicar qué hacen y cómo utilizarlos. En el diálogo de edición de scripts, encontrará un botón ** [Ayudar en la edición de scripts] **. Haga clic en él y le llevará al cuadro de diálogo de edición de ayuda. Compruebe el capítulo sobre el modelador gráfica para saber más acerca de este cuadro de diálogo y cómo usarlo.
Los archivos de ayuda se guardan en la misma capa como el script mismo, añadiendo la extensión .help al nombre del archivo. Tenga en cuenta que puede editar la ayuda de su script antes de guardarlo la primera vez. Si después cierra el diálogo de edición de script sin guardarlo (es decir, descartarlo), el contenido de la ayuda que escribió se perderá. Si su script ya fue guardado y tiene asociado un nombre de archivo, se guardara automáticamente.
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.
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.