Importante

La traduzione è uno sforzo comunitario you can join. Questa pagina è attualmente tradotta al 79.41%.

23.7. Usare gli algoritmi di Processing dalla console dei comandi

La console permette ad utenti esperti di aumentare la propria produttività e di eseguire operazioni complesse che non possono essere eseguite utilizzando uno qualsiasi degli altri elementi dell’interfaccia grafica di Processing. I modelli che richiamano diversi algoritmi possono essere definiti utilizzando l’interfaccia della riga di comando, e le operazioni aggiuntive, come i loop e le frasi condizionali possono essere aggiunte per creare flussi di lavoro più flessibili e potenti.

Non c’è una console di processing in QGIS, ma tutti i comandi di processing sono invece resi disponibili dalla predefinita QGIS Python console. Ciò significa che puoi incorporare tali comandi nellal tuo console operativa e collegare gli algoritmi di elaborazione a tutte le altre funzionalità (inclusi i metodi delle API di QGIS) lì disponibili.

Il codice che puoi eseguire dalla console di python, anche se non richiama un metodo specifico di Processing, può essere convertito in un nuovo algoritmo che potrai richiamare in seguito dagli Strumenti, dal Modellatore grafico o da qualunque altra parte, proprio come ogni altro algoritmo. Alcuni algoritmi che trovi in Strumenti sono in effetti degli script semplici.

In questa sezione verrà spiegato come usare gli algoritmi di Processing dalla console di Python e anche come scrivere un algoritmo usando Python.

23.7.1. Richiamare algoritmi dalla console di python

La prima cosa da fare è importare le funzioni di Processing con la seguente istruzione:

>>> 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())

Vedrai qualcosa del genere (con qualche trattino in più aggiunto per migliorare la leggibilità).

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
...

Questa è una lista di tutti gli ID degli algoritmi disponibili, ordinati per nome della fonte e nome dell’algoritmo, insieme ai loro nomi corrispondenti.

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.

Richiamando il metodo con native:buffer come parametro (qgis:buffer è un alias di native:buffer e funzionerà ugualmente), ottieni la seguente descrizione:

>>> 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'})

Se un parametro è opzionale e non vuoi usarlo, allora non includerlo nel dizionario.

Se un parametro non è specificato, verrà utilizzato il valore predefinito.

A seconda del tipo di parametro, i valori sono inseriti in maniera diversa. Il seguente elenco dà una rapida panoramica di come inserire valori per ogni tipo di parametro in input:

  • Layer Raster, Layer Vettoriale o Tabella. Basta usare una stringa con il nome che identifica il data object da usare (il nome che ha nella Table of Contents di QGIS) o un nome di file (se il layer corrispondente non è aperto, verrà aperto ma non aggiunto alla mappa). Se hai un’istanza di un oggetto QGIS che rappresenta il layer, puoi anche passarlo come parametro.

  • 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

    In questo caso, il parametro ha tre opzioni. Da notare che l’ordine è su base zero.

  • Boolean. Use True or False.

  • Input multipli. Il valore è una stringa con descrittori in input separati da un punto e virgola (;). Come nel caso di layer singoli o tabelle, ogni descrittore in input può essere il nome dell’oggetto o il suo percorso.

  • Campo di una Tabella da XXX. Inserisci una stringa con il nome del campo da usare. Il parametro è sensibile alle lettere maiuscole.

  • Tabella fissa. Inserisci l’elenco di tutti i valori delle tabelle separati da una virgola (,) e racchiusi fra virgolette ("). I valori partono dalla riga in alto e proseguono da sinistra verso destra. Puoi usare un array 2-D per i valori che rappresentano la tabella.

  • SR. Inserisci il codice EPSG del SR desiderato.

  • Estensione. Usa un stringa con valori xmin, xmax, ymin e ymax separati da virgole (,).

Parametri booleani, di file, di stringa e numerici non hanno bisogno di ulteriori spiegazioni.

I parametri di input come stringhe, booleani o valori numerici hanno valori predefiniti. Il valore predefinito viene utilizzato se la voce corrispondente del parametro è mancante.

Per i dati di output, digitare il percorso del file da utilizzare per salvarlo, proprio come si fa dal pannello degli strumenti. Se non viene specificato l’oggetto di output, il risultato viene salvato in un file temporaneo (o omesso se si tratta di un output opzionale). L’estensione del file determina il formato del file. Se si inserisce un’estensione di file non supportata dall’algoritmo, verrà utilizzato il formato di file predefinito per quel tipo di output, e la sua estensione corrispondente verrà aggiunta al percorso indicato.

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

Puoi caricare il risultato nel progetto come un qualsiasi comune layer:

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. Creare script ed eseguirli da Strumenti

Puoi creare i tuoi algoritmi scrivendo codice Python. Gli script di processing hanno una QgsProcessingAlgorithm, quindi devi aggiungere alcune linee di codice extra per implementare le funzioni obbligatorie. Puoi trovare Crea nuovo script… ( scheda pulita) e Crea Nuovo Script da Modello… (modello che include il codice per le funzioni obbligatorie di QgsProcessingAlgorithm) sotto il menu a discesa Script in cima alla finestra degli strumenti di Processing. Si aprirà l’Editor di script di Processing, ed è lì che dovresti digitare il tuo codice. Salvando lo script da lì nella cartella scripts (la cartella predefinita quando apri la finestra di dialogo di salvataggio del file) con un’estensione .py dovrebbe creare l’algoritmo corrispondente.

Il nome dell’algoritmo (quello che vedrai nella casella degli strumenti) è definito all’interno del codice.

Diamo un’occhiata al seguente codice, che definisce un algoritmo di Processing che esegue un’operazione di buffer con una distanza di buffer definita dall’utente su un layer vettoriale che è specificato dall’utente, dopo aver prima smussato il layer.

 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}

Dopo aver fatto le importazioni necessarie, vengono specificate le seguenti funzioni QgsProcessingAlgorithm:

  • name(): L’id dell’algoritmo (minuscolo).

  • displayName(): Un nome interpretabile per l’algoritmo.

  • createInstance(): Crea una nuova istanza nella classe algoritmo.

  • initAlgorithm(): Configura la parameterDefinitions e outputDefinitions.

    Qui descrivi i parametri e l’output dell’algoritmo. In questo caso, una geometria per l’input, una geometria per il risultato e un numero per la distanza del buffer.

  • processAlgorithm(): Esegue.

    Qui eseguiamo prima l’algoritmo moothgeometry per smussare la geometria, e poi eseguiamo l’algoritmo buffer sull’output smussato. Per poter eseguire algoritmi dall’interno di un altro algoritmo dobbiamo impostare lil parametro is_child_algorithm a True`. Puoi vedere come i parametri di input e output sono usati come parametri per gli algoritmi moothgeometry e buffer.

Sono disponibili diversi tipi di parametri sia per quanto riguarda gli ingressi che per quanto riguarda i risultati. L’elenco completo si trova in Tipi di dati in ingresso e in uscita degli Algoritmi di Processing.

Il primo parametro è il nome del parametro e il secondo è la descrizione del parametro (per l’interfaccia utente). Il resto dei parametri sono specifici del tipo di parametro.

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.

Gli algoritmi che si comportano bene dovrebbero definire e restituire tanti output quanti hanno importanza. Gli output non relativi alle funzionalità, come numeri e stringhe, sono molto utili quando si esegue l’algoritmo come parte di un modello più grande, poiché questi valori possono essere utilizzati come parametri di input per gli algoritmi successivi all’interno del modello. Si consideri l’aggiunta di output numerici per cose come il numero di elementi processati, il numero di elementi non validi incontrati, il numero di elementi in uscita, ecc. Più output restituite, più utile diventa il vostro algoritmo!

23.7.2.1. Feedback

L’oggetto feedback passato a processAlgorithm() dovrebbe essere usato per il feedback/interazione dell’utente. Puoi usare la funzione setProgress() dell’oggetto feedback per aggiornare la barra di avanzamento (da 0 a 100) per informare l’utente sul avanzamento dell’algoritmo. Questo è molto utile se il tuo algoritmo richiede molto tempo per essere completato.

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.

Gli algoritmi dovrebbero evitare di usare altre forme per fornire feedback agli utenti, come istruzioni di stampa o di notifica a QgsMessageLog, e dovrebbero invece usare sempre l’oggetto feedback. Questo permette un log dettagliato per l’algoritmo, ed è anche thread-safe (il che è importante, dato che gli algoritmi sono tipicamente eseguiti in un thread in background).

23.7.2.2. Gestire gli errori

Se il tuo algoritmo incontra un errore che ne impedisce l’esecuzione, come valori di input non validi o qualche altra condizione da cui non può o non dovrebbe recuperare, allora dovresti generare una QgsProcessingException. Ad esempio:

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

Cerca di evitare di generare QgsProcessingException per errori non fatali (ad esempio quando una feature ha una geometria nulla), e invece segnala semplicemente questi errori tramite feedback.reportError() e salta la stessa. Questo aiuta a rendere il tuo algoritmo «model-friendly», poiché evita di interrompere l’esecuzione di un intero algoritmo quando si incontra un errore non fatale.

23.7.2.3. Documentare gli script

Come nel caso dei modelli, puoi creare una documentazione aggiuntiva per i tuoi script, per spiegare cosa fanno e come usarli.

QgsProcessingAlgorithm fornisce le funzioni per questo scopo helpString(), shortHelpString() e helpUrl(). Specifica / sovrascrive queste funzioni per fornire più aiuto all’utente.

shortDescription() è usato quando il puntatore del mouse passa sopra l’algoritmo nella casella degli strumenti.

23.7.3. Script agganciati pre e post esecuzione

Gli script possono anche essere usati come controlli pre- e post-esecuzione che vengono eseguiti rispettivamente prima e dopo l’esecuzione di un algoritmo. Questo può essere usato per automatizzare i processi che dovrebbero essere eseguiti ogni volta che un algoritmo viene eseguito.

La sintassi è identica alla sintassi spiegato sopra, ma hai a disposizione anche una variabile globale chiamata alg che rappresenta l’algoritmo che è appena stato (o che sta per essere) eseguito.

Nel gruppo General della finestra di dialogo delle opzioni di processing, troverai due voci chiamate Pre-execution script e Post-execution script dove possono essere inseriti i nomi dei file degli script da eseguire caso per caso.