Importante

La traducción es un esfuerzo comunitario puede unirse. Esta página está actualmente traducida en |progreso de traducción|.

23.7. Utilizar algoritmos de procesamiento desde la consola

La consola permite a los usuarios avanzados incrementar su productividad y realizar operaciones complejas que no se pueden realizar utilizando cualquiera de los otros elementos de la GUI del marco de procesamiento. Modelos que involucran varios algoritmos se pueden definir mediante la interfaz de línea de comandos y operaciones adicionales tales como bucles y sentencias condicionales que se pueden añadir para crear flujos de trabajo más flexibles y potentes.

No hay una consola de procesamiento en QGIS, pero todos los comandos de procesamiento están disponibles en su lugar desde el constructor de QGIS consola de Python. Eso significa que puede incorporar esos comandos en el trabajo de su consola y conectar algoritmos de procesamiento a todas las demás funciones (incluidos los métodos de la API de QGIS) disponibles desde allí.

El código se puede ejecutar desde la consola de Python, incluso si no especifica ningún método de procesamiento, se puede convertir en un nuevo algoritmo que más tarde puede llamar desde la caja de herramientas, el modelador gráfico o algún otro componente, tal como lo hace con cualquier otro algoritmo. De hecho, algunos de los algoritmos que se pueden encontrar en la caja de herramientas son sencillas secuencias de comandos.

En esta sección, veremos como utilizar algoritmos de procesado desde la consola de Python de QGIS, y también cómo escribir algoritmos utilizando Python.

23.7.1. Invocando algoritmos desde la consola de Python

Lo primero que tiene que hacer es importar las funciones de procesamiento con la siguiente línea:

>>> from qgis import processing

Now, there is basically just one (interesting) thing you can do with that from the console: ute an algorithm. That is done using the run() method, which takes the id of the algorithm to ute as its first parameter, and then a variable number of additional parameters depending on the requirements of the algorithm. So the first thing you need to know is the name of the algorithm to ute. That is not the name you see in the toolbox, but rather a unique command–line name. To find the right name for your algorithm, you can use the processingRegistry. Type the following line in your console:

>>> for alg in QgsApplication.processingRegistry().algorithms():
        print(alg.id(), "->", alg.displayName())

Verá algo como esto (con algunos guiones adicionales agregados para mejorar la legibilidad).

3d:tessellate --------------> Tessellate
gdal:aspect ----------------> Aspect
gdal:assignprojection ------> Assign projection
gdal:buffervectors ---------> Buffer vectors
gdal:buildvirtualraster ----> Build Virtual Raster
gdal:cliprasterbyextent ----> Clip raster by extent
gdal:cliprasterbymasklayer -> Clip raster by mask layer
gdal:clipvectorbyextent ----> Clip vector by extent
gdal:clipvectorbypolygon ---> Clip vector by mask layer
gdal:colorrelief -----------> Color relief
gdal:contour ---------------> Contour
gdal:convertformat ---------> Convert format
gdal:dissolve --------------> Dissolve
...

Esa es una lista de todos los ID de algoritmos disponibles, ordenados por nombre de proveedor y nombre de algoritmo, junto con sus nombres correspondientes.

Once you know the command-line name of the algorithm, the next thing to do is to determine the right syntax to ute it. That means knowing which parameters are needed when calling the run() method.

There is a method to describe an algorithm in detail, which can be used to get a list of the parameters that an algorithm requires and the outputs that it will generate. To get this information, you can use the algorithmHelp() method. Pass as parameter the ID of the algorithm, not the full descriptive name.

Llamando al método con native:buffer como parámetro (qgis:buffer es un alias para native:buffer y también funcionará), obtienes la siguiente descripción:

>>> processing.algorithmHelp("native:buffer")
Buffer (native:buffer)

This algorithm computes a buffer area for all the features in an
input layer, using a fixed or dynamic distance.

The segments parameter controls the number of line segments to
use to approximate a quarter circle when creating rounded
offsets.

The end cap style parameter controls how line endings are handled
in the buffer.

The join style parameter specifies whether round, miter or
beveled joins should be used when offsetting corners in a line.

The miter limit parameter is only applicable for miter join
styles, and controls the maximum distance from the offset curve
to use when creating a mitered join.


----------------
Input parameters
----------------

INPUT: Input layer

   Parameter type: QgsProcessingParameterFeatureSource

   Accepted data types:
      - str: layer ID
      - str: layer name
      - str: layer source
      - QgsProcessingFeatureSourceDefinition
      - QgsProperty
      - QgsVectorLayer

DISTANCE: Distance

   Parameter type: QgsProcessingParameterDistance

   Accepted data types:
      - int
      - float
      - QgsProperty

SEGMENTS: Segments

   Parameter type: QgsProcessingParameterNumber

   Accepted data types:
      - int
      - float
      - QgsProperty

END_CAP_STYLE: End cap style

   Parameter type: QgsProcessingParameterEnum

   Available values:
      - 0: Round
      - 1: Flat
      - 2: Square

   Accepted data types:
      - int
      - str: as string representation of int, e.g. '1'
      - QgsProperty

JOIN_STYLE: Join style

   Parameter type: QgsProcessingParameterEnum

   Available values:
      - 0: Round
      - 1: Miter
      - 2: Bevel

   Accepted data types:
      - int
      - str: as string representation of int, e.g. '1'
      - QgsProperty

MITER_LIMIT: Miter limit

   Parameter type: QgsProcessingParameterNumber

   Accepted data types:
      - int
      - float
      - QgsProperty

DISSOLVE: Dissolve result

   Parameter type: QgsProcessingParameterBoolean

   Accepted data types:
      - bool
      - int
      - str
      - QgsProperty

OUTPUT: Buffered

   Parameter type: QgsProcessingParameterFeatureSink

   Accepted data types:
      - str: destination vector file, e.g. 'd:/test.shp'
      - str: 'memory:' to store result in temporary memory layer
      - str: using vector provider ID prefix and destination URI,
             e.g. 'postgres:...' to store result in PostgreSQL table
      - QgsProcessingOutputLayerDefinition
      - QgsProperty

----------------
Outputs
----------------

OUTPUT:  <QgsProcessingOutputVectorLayer>
   Buffered

Now you have everything you need to run any algorithm. As we have already mentioned, algorithms can be run using: run(). Its syntax is as follows:

>>> processing.run(name_of_the_algorithm, parameters)

Where parameters is a dictionary of parameters that depend on the algorithm you want to run, and is exactly the list that the algorithmHelp() method gives you.

1 >>> processing.run("native:buffer", {'INPUT': '/data/lines.shp',
2               'DISTANCE': 100.0,
3               'SEGMENTS': 10,
4               'DISSOLVE': True,
5               'END_CAP_STYLE': 0,
6               'JOIN_STYLE': 0,
7               'MITER_LIMIT': 10,
8               'OUTPUT': '/data/buffers.shp'})

Si un parámetro es opcional y no desea utilizarlo, no lo incluya en el diccionario.

Si no se especifica un parámetro, se utilizará el valor predeterminado.

Dependiendo del tipo de parámetro, los valores se introducen de manera diferente. La siguiente lista da una rápida revisión de cómo introducir los valores para cada tipo de parámetro de entrada.

  • Capa ráster, capa vectorial o tabla. Simplemente use una cadena con el nombre que identifica el objeto de datos a usar (el nombre que tiene en la Tabla de contenido de QGIS) o un nombre de archivo (si la capa correspondiente no está abierta, se abrirá pero no se agregará al lienzo del mapa) . Si tiene una instancia de un objeto QGIS que representa la capa, también puede pasarla como parámetro.

  • Enumeration. If an algorithm has an enumeration parameter, the value of that parameter should be entered using an integer value. To know the available options, you can use the algorithmHelp() command, as above. For instance, the native:buffer algorithm has an enumeration called JOIN_STYLE:

    JOIN_STYLE: Join style

   Parameter type: QgsProcessingParameterEnum

   Available values:
      - 0: Round
      - 1: Miter
      - 2: Bevel

   Accepted data types:
      - int
      - str: as string representation of int, e.g. '1'
      - QgsProperty

    En este caso, el parámetro tiene tres opciones. Tenga en cuenta que el orden parte de cero.

  • Boolean. Use True or False.

  • La entrada múltiple. El valor es una cadena con descriptores de entrada separadas por punto y coma (;). Como en el caso de capas individuales o tablas, cada descriptor de entrada se puede el nombre del objeto de datos, o su ruta de archivo.

  • El campo de la tabla de XXX. Utilice una cadena con el nombre del campo a usar. Este parámetro es sensible a mayúsculas y minúsculas.

  • Tabla fija. Escribir la lista de todas las tablas de valores separadas por comas (,) y cerrar entre comillas ("). Los valores que empiezan en la fila superior y van de izquierda a derecha. También se puede utilizar un arreglo 2-D de valores que representen la tabla.

  • SRC. Introduzca el número del código EPSG del SRC deseado.

  • Extensión. Se debe utilizar una cadena con valores de xmin, xmax, ymin y ymax` separados por comas (,``).

Los parámetros boolean, archivo, cadena y numéricos no necesitan alguna explicación adicional.

Los parámetros de entrada como cadenas, booleanos o valores numéricos tienen valores predeterminados. El valor predeterminado se utiliza si falta la entrada de parámetro correspondiente.

Para los objetos de datos de salida, escriba la ruta del archivo que se utilizará para guardarlos, tal como se hace en la caja de herramientas. Si no se especifica el objeto de salida, el resultado se guarda en un archivo temporal (o se omite si es una salida opcional). La extensión del archivo determina el formato del archivo. Si ingresa una extensión de archivo no admitida por el algoritmo, se utilizará el formato de archivo predeterminado para ese tipo de salida y su extensión correspondiente se agregará a la ruta de archivo dada.

Unlike when an algorithm is uted from the toolbox, outputs are not added to the map canvas if you ute that same algorithm from the Python console using the run() method. That method returns a dictionary with one or more output names (the ones shown in the algorithm description) as keys and the file paths of those outputs as values:

 1 >>> myresult = processing.run("native:buffer", {'INPUT': '/data/lines.shp',
 2               'DISTANCE': 100.0,
 3               'SEGMENTS': 10,
 4               'DISSOLVE': True,
 5               'END_CAP_STYLE': 0,
 6               'JOIN_STYLE': 0,
 7               'MITER_LIMIT': 10,
 8               'OUTPUT': '/data/buffers.shp'})
 9 >>> myresult['OUTPUT']
10 /data/buffers.shp

A continuación, puede cargar la salida en el proyecto como cualquier capa común:

1 >>> buffered_layer = myresult['OUTPUT']
2 >>> QgsProject.instance().addMapLayer(buffered_layer)

To immediately load the processing outputs in the project, you can use the runAndLoadResults() method instead of run().

1 >>> processing.runAndLoadResults("native:buffer", {parameters:values})

If you want to open an algorithm dialog from the console you can use the createAlgorithmDialog method. The only mandatory parameter is the algorithm id, but you can also define the dictionary of parameters so that the dialog will be filled automatically:

 1 >>> my_dialog = processing.createAlgorithmDialog("native:buffer", {
 2               'INPUT': '/data/lines.shp',
 3               'DISTANCE': 100.0,
 4               'SEGMENTS': 10,
 5               'DISSOLVE': True,
 6               'END_CAP_STYLE': 0,
 7               'JOIN_STYLE': 0,
 8               'MITER_LIMIT': 10,
 9               'OUTPUT': '/data/buffers.shp'})
10 >>> my_dialog.show()

The execAlgorithmDialog method opens the dialog immediately:

1 >>> processing.execAlgorithmDialog("native:buffer", {
2               'INPUT': '/data/lines.shp',
3               'DISTANCE': 100.0,
4               'SEGMENTS': 10,
5               'DISSOLVE': True,
6               'END_CAP_STYLE': 0,
7               'JOIN_STYLE': 0,
8               'MITER_LIMIT': 10,
9               'OUTPUT': '/data/buffers.shp'})

23.7.2. Crear scripts y ejecurarlos desde le Caja de Herramientas

Puede crear sus propios algoritmos escribiendo código Python. Los scripts de procesamiento extienden QgsProcessingAlgorithm, por lo que necesita agregar algunas líneas adicionales de código para implementar funciones obligatorias. Puede encontrar Create new script (hoja limpia) y Create New Script from Template (plantilla que incluye código para funciones obligatorias de QgsProcessingAlgorithm) en el menú desplegable Scripts desplegable en la parte superior de la caja de herramientas de Procesamiento. Se abrirá Processing Script Editor, y ahí es donde debe escribir su código. Guardar el script desde allí en la carpeta scripts (la carpeta predeterminada cuando abre el cuadro de diálogo para guardar el archivo) con una extensión .py debería crear el algoritmo correspondiente.

El nombre del algoritmo (el que verá en la caja de herramientas) se define dentro del código.

Echemos un vistazo al siguiente código, que define un algoritmo de procesamiento que realiza una operación de búfer con una distancia de búfer definida por el usuario en una capa vectorial especificada por el usuario, después de suavizar primero la capa.

 1from qgis.core import (QgsProcessingAlgorithm,
 2       QgsProcessingParameterNumber,
 3       QgsProcessingParameterFeatureSource,
 4       QgsProcessingParameterFeatureSink)
 5
 6from qgis import processing
 7
 8class algTest(QgsProcessingAlgorithm):
 9    INPUT_BUFFERDIST = 'BUFFERDIST'
10    OUTPUT_BUFFER = 'OUTPUT_BUFFER'
11    INPUT_VECTOR = 'INPUT_VECTOR'
12
13    def __init__(self):
14        super().__init__()
15
16    def name(self):
17        return "algTest"
18
19    def displayName(self):
20        return "algTest script"
21
22    def createInstance(self):
23        return type(self)()
24
25    def initAlgorithm(self, config=None):
26        self.addParameter(QgsProcessingParameterFeatureSource(
27            self.INPUT_VECTOR, "Input vector"))
28        self.addParameter(QgsProcessingParameterNumber(
29            self.INPUT_BUFFERDIST, "Buffer distance",
30            QgsProcessingParameterNumber.Double,
31            100.0))
32        self.addParameter(QgsProcessingParameterFeatureSink(
33            self.OUTPUT_BUFFER, "Output buffer"))
34
35    def processAlgorithm(self, parameters, context, feedback):
36        #DO SOMETHING
37        algresult = processing.run("native:smoothgeometry",
38            {'INPUT': parameters[self.INPUT_VECTOR],
39             'ITERATIONS':2,
40             'OFFSET':0.25,
41             'MAX_ANGLE':180,
42             'OUTPUT': 'memory:'},
43            context=context, feedback=feedback, is_child_algorithm=True)
44        smoothed = algresult['OUTPUT']
45        algresult = processing.run('native:buffer',
46            {'INPUT': smoothed,
47            'DISTANCE': parameters[self.INPUT_BUFFERDIST],
48            'SEGMENTS': 5,
49            'END_CAP_STYLE': 0,
50            'JOIN_STYLE': 0,
51            'MITER_LIMIT': 10,
52            'DISSOLVE': True,
53            'OUTPUT': parameters[self.OUTPUT_BUFFER]},
54            context=context, feedback=feedback, is_child_algorithm=True)
55        buffered = algresult['OUTPUT']
56        return {self.OUTPUT_BUFFER: buffered}

Después de hacer las importaciones necesarias, las siguientes funciones QgsProcessingAlgorithm son especificadas:

  • name(): La id del algoritmo (minúsculas).

  • displayName(): Un nombre de algoritmo legible por humanos

  • createInstance(): Crear una nueva instancia de la clase del algoritmo.

  • initAlgorithm(): Comfigurar las definiciones de Parámetro y Definiciones de Salida.

    Aquí describe los parámetros y la salida del algoritmo. En este caso, una fuente de objetos para la entrada, una salida de objetos para el resultado y un número para la distancia del búfer.

  • processAlgorithm(): Hacer el trabajo.

    Aquí primero ejecutamos el algoritmo smoothgeometry para suavizar la geometría, y luego ejecutamos el algoritmo buffer en la salida suavizada. Para poder ejecutar algoritmos desde otro algoritmo, debemos establecer el argumento is_child_algorithm en True. Puede ver cómo los parámetros de entrada y salida se utilizan como parámetros para los algoritmos smoothgeometry y buffer.

Existen varios tipos de parámetros de entrada y salida. Puede consultar la lista completa en Tipos de entrada y salida para algoritmos de procesamiento.

El primer parámetro para los constructores es el nombre del parámetro y el segundo es la descripción del parámetro (para la interfaz de usuario). El resto de los parámetros del constructor son específicos del tipo de parámetro.

The input can be turned into QGIS classes using the parameterAs… functions of QgsProcessingAlgorithm. For instance to get the number provided for the buffer distance as a double:

self.parameterAsDouble(parameters, self.INPUT_BUFFERDIST, context)).

The processAlgorithm() function should return a dictionary containing values for every output defined by the algorithm. This allows access to these outputs from other algorithms, including other algorithms contained within the same model.

Los algoritmos que se comportan bien deben definir y devolver tantas salidas como tenga sentido. Las salidas que no son objetos, como números y cadenas, son muy útiles cuando se ejecuta su algoritmo como parte de un modelo más grande, ya que estos valores se pueden usar como parámetros de entrada para algoritmos posteriores dentro del modelo. Considere agregar salidas numéricas para cosas como la cantidad de objetos procesados, la cantidad de objetos no válidos encontrados, la cantidad de objetos de salida, etc. ¡Cuantas más salidas devuelva, más útil se volverá su algoritmo!

23.7.2.1. Revisión

El objeto feedback pasado a processAlgorithm() debe usarse para la retroalimentación / interacción del usuario. Puede usar la función setProgress() del objeto feedback para actualizar la barra de progreso (0 a 100) para informar el usuario sobre el progreso del algoritmo. Esto es muy útil si su algoritmo tarda mucho en completarse.

The feedback object provides an isCanceled() method that should be monitored to enable cancellation of the algorithm by the user. The pushInfo() method of feedback can be used to send information to the user, and reportError() is handy for pushing non-fatal errors to users.

Los algoritmos deben evitar el uso de otras formas de proporcionar retroalimentación a los usuarios, como declaraciones de impresión o registro en QgsMessageLog, y siempre deben usar el objeto de retroalimentación en su lugar. Esto permite un registro detallado para el algoritmo y también es seguro para subprocesos (lo cual es importante, dado que los algoritmos generalmente se ejecutan en un subproceso en segundo plano).

23.7.2.2. Manejo de errores

Si su algoritmo encuentra un error que le impide ejecutarse, como valores de entrada no válidos o alguna otra condición de la que no puede o no debe recuperarse, entonces debe generar un QgsProcessingException. P.Ejemplo

if feature['value'] < 20:
  raise QgsProcessingException('Invalid input value {}, must be >= 20'.format(feature['value']))

Trate de evitar generar QgsProcessingException para errores no fatales (por ejemplo, cuando un objeto tiene una geometría nula) y, en su lugar, solo informe estos errores a través de feedback.reportError() y omita la función. Esto ayuda a que su algoritmo sea «compatible con el modelo», ya que evita detener la ejecución de un algoritmo completo cuando se encuentra un error no fatal.

23.7.2.3. Documentación de las secuencias de comandos

Como en el caso de los modelos, puede crear documentación adicional para sus scripts, para explicar qué hacen y cómo usarlos.

QgsProcessingAlgorithm proporciona las funciones helpString(), shortHelpString() y helpUrl() para ese propósito. Especificar / suplantar estos para proporcionar mas ayuda al usuario.

shortDescription() se utiliza en la información sobre herramientas al pasar el cursor sobre el algoritmo en la caja de herramientas.

23.7.3. Pre y post-ejecución de la secuencia de comandos hooks

Los scripts también se pueden utilizar como ganchos previos y posteriores a la ejecución que se ejecutan antes y después de la ejecución de un algoritmo, respectivamente. 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 está disponible, lo que representa el algoritmo que acaba de ser (o está a punto de ser) ejecutado.

En el grupo General del cuadro de diálogo de opciones de procesamiento, encontrará dos entradas denominadas Pre-execution script y Post-execution script donde se pueden introducir los nombres de archivo de los scripts a ejecutar en cada caso.