26.9. Scrivere nuovi algoritmi di Processing tramite script Python

Ci sono due opzioni per scrivere algoritmi di Processing usando Python.

All’interno di QGIS, puoi usare Create new script nel menu Script in cima a Strumenti di Processing per aprire il Processing Script Editor dove puoi scrivere il tuo codice. Per semplificare il compito, puoi iniziare con un modello di script usando Crea Nuovo Script da Modello… dallo stesso menu. Questo apre un modello che estrae QgsProcessingAlgorithm.

Se salvi lo script nella cartella scripts (la posizione predefinita) con un’estensione .py, l’algoritmo diventerà disponibile in Strumenti di Processing.

26.9.1. Per estensione di QgsProcessingAlgorithm 

Il seguente codice

prende un layer vettoriale come input
conta il numero di elementi
esegue un’operazione di buffer
genera un layer raster dal risultato dell’operazione di buffer
restituisce il buffer layer, il layer raster e il numero di elementi

from qgis.PyQt.QtCore import QCoreApplication
from qgis.core import (QgsProcessing,
                       QgsProcessingAlgorithm,
                       QgsProcessingException,
                       QgsProcessingOutputNumber,
                       QgsProcessingParameterDistance,
                       QgsProcessingParameterFeatureSource,
                       QgsProcessingParameterVectorDestination,
                       QgsProcessingParameterRasterDestination)
from qgis import processing


class ExampleProcessingAlgorithm(QgsProcessingAlgorithm):
    """
    This is an example algorithm that takes a vector layer,
    creates some new layers and returns some results.
    """

    def tr(self, string):
        """
        Returns a translatable string with the self.tr() function.
        """
        return QCoreApplication.translate('Processing', string)

    def createInstance(self):
        # Must return a new copy of your algorithm.
        return ExampleProcessingAlgorithm()

    def name(self):
        """
        Returns the unique algorithm name.
        """
        return 'bufferrasterextend'

    def displayName(self):
        """
        Returns the translated algorithm name.
        """
        return self.tr('Buffer and export to raster (extend)')

    def group(self):
        """
        Returns the name of the group this algorithm belongs to.
        """
        return self.tr('Example scripts')

    def groupId(self):
        """
        Returns the unique ID of the group this algorithm belongs
        to.
        """
        return 'examplescripts'

    def shortHelpString(self):
        """
        Returns a localised short help string for the algorithm.
        """
        return self.tr('Example algorithm short description')

    def initAlgorithm(self, config=None):
        """
        Here we define the inputs and outputs of the algorithm.
        """
        # 'INPUT' is the recommended name for the main input
        # parameter.
        self.addParameter(
            QgsProcessingParameterFeatureSource(
                'INPUT',
                self.tr('Input vector layer'),
                types=[QgsProcessing.TypeVectorAnyGeometry]
            )
        )
        self.addParameter(
            QgsProcessingParameterVectorDestination(
                'BUFFER_OUTPUT',
                self.tr('Buffer output'),
            )
        )
        # 'OUTPUT' is the recommended name for the main output
        # parameter.
        self.addParameter(
            QgsProcessingParameterRasterDestination(
                'OUTPUT',
                self.tr('Raster output')
            )
        )
        self.addParameter(
            QgsProcessingParameterDistance(
                'BUFFERDIST',
                self.tr('BUFFERDIST'),
                defaultValue = 1.0,
                # Make distance units match the INPUT layer units:
                parentParameterName='INPUT'
            )
        )
        self.addParameter(
            QgsProcessingParameterDistance(
                'CELLSIZE',
                self.tr('CELLSIZE'),
                defaultValue = 10.0,
                parentParameterName='INPUT'
            )
        )
        self.addOutput(
            QgsProcessingOutputNumber(
                'NUMBEROFFEATURES',
                self.tr('Number of features processed')
            )
        )

    def processAlgorithm(self, parameters, context, feedback):
        """
        Here is where the processing itself takes place.
        """
        # First, we get the count of features from the INPUT layer.
        # This layer is defined as a QgsProcessingParameterFeatureSource
        # parameter, so it is retrieved by calling
        # self.parameterAsSource.
        input_featuresource = self.parameterAsSource(parameters,
                                                     'INPUT',
                                                     context)
        numfeatures = input_featuresource.featureCount()

        # Retrieve the buffer distance and raster cell size numeric
        # values. Since these are numeric values, they are retrieved
        # using self.parameterAsDouble.
        bufferdist = self.parameterAsDouble(parameters, 'BUFFERDIST',
                                            context)
        rastercellsize = self.parameterAsDouble(parameters, 'CELLSIZE',
                                                context)
        if feedback.isCanceled():
            return {}
        buffer_result = processing.run(
            'native:buffer',
            {
                # Here we pass on the original parameter values of INPUT
                # and BUFFER_OUTPUT to the buffer algorithm.
                'INPUT': parameters['INPUT'],
                'OUTPUT': parameters['BUFFER_OUTPUT'],
                'DISTANCE': bufferdist,
                'SEGMENTS': 10,
                'DISSOLVE': True,
                'END_CAP_STYLE': 0,
                'JOIN_STYLE': 0,
                'MITER_LIMIT': 10
            },
            # Because the buffer algorithm is being run as a step in
            # another larger algorithm, the is_child_algorithm option
            # should be set to True
            is_child_algorithm=True,
            #
            # It's important to pass on the context and feedback objects to
            # child algorithms, so that they can properly give feedback to
            # users and handle cancelation requests.
            context=context,
            feedback=feedback)

        # Check for cancelation
        if feedback.isCanceled():
            return {}

        # Run the separate rasterization algorithm using the buffer result
        # as an input.
        rasterized_result = processing.run(
            'qgis:rasterize',
            {
                # Here we pass the 'OUTPUT' value from the buffer's result
                # dictionary off to the rasterize child algorithm.
                'LAYER': buffer_result['OUTPUT'],
                'EXTENT': buffer_result['OUTPUT'],
                'MAP_UNITS_PER_PIXEL': rastercellsize,
                # Use the original parameter value.
                'OUTPUT': parameters['OUTPUT']
            },
            is_child_algorithm=True,
            context=context,
            feedback=feedback)

        if feedback.isCanceled():
            return {}

        # Return the results
        return {'OUTPUT': rasterized_result['OUTPUT'],
                'BUFFER_OUTPUT': buffer_result['OUTPUT'],
                'NUMBEROFFEATURES': numfeatures}

Funzioni standard algoritmo di Processing:

createInstance (obbligatorio)
Deve restituire una nuova copia del tuo algoritmo. Se cambi il nome della classe, assicurati di aggiornare qui anche il valore restituito per farlo corrispondere!
name (obbligatorio)
Restituisce il nome univoco dell’algoritmo, usato per identificare l’algoritmo.
displayName (obbligatorio)
Restituisce il nome tradotto dell’algoritmo.
group
Restituisce il nome del gruppo a cui appartiene questo algoritmo.
groupId
Restituisce l’ID univoco del gruppo a cui questo algoritmo appartiene.
shortHelpString
Restituisce una breve stringa di aiuto per l’algoritmo localizzata.
initAlgorithm (obbligatorio)
Qui definiamo gli ingressi e le uscite dell’algoritmo.

INPUT e OUTPUT sono nomi raccomandati per i parametri in ingresso e in uscita principali, rispettivamente.

Se un parametro dipende da un altro parametro, parentParameterName è usato per specificare questa relazione (potrebbe essere il campo/banda di un layer o le unità di distanza di un layer).
processAlgorithm (obbligatorio)
Qui è dove avviene l’elaborazione.

I parametri sono richiamati usando funzioni speciali, per esempio parameterAsSource e parameterAsDouble.

processing.run può essere usato per eseguire altri algoritmi di elaborazione da un algoritmo di processing. Il primo parametro è il nome dell’algoritmo, il secondo è un dizionario dei parametri dell’algoritmo. is_child_algorithm è normalmente impostato a True quando si esegue un algoritmo da un altro algoritmo. context e feedback informano l’algoritmo circa l’ambiente in cui eseguire e il canale per comunicare con l’utente ( intercettare la richiesta di cancellazione, riportare i progressi, fornire un feedback testuale). Quando si usano i parametri dell’algoritmo (padre) come parametri di algoritmi «figli», si dovrebbero usare i valori originali dei parametri (ad esempio, parameters['OUTPUT']).

È una buona pratica verificare l’oggetto feedback per cancellare il più possibile! Questo permette una cancellazione rapida, invece di costringere gli utenti ad aspettare che avvenga un processing indesiderato.

L’algoritmo dovrebbe restituire valori per tutti i parametri in uscita che ha definito come dizionario. In questo caso, sono il buffer e i layer risultato rasterizzati, e il conteggio degli elementi processati. Le chiavi del dizionario devono corrispondere ai nomi originali dei parametri/output.

26.9.2. Il decoratore @alg 

Usando il decoratore @alg, puoi creare i tuoi algoritmi scrivendo il codice Python e aggiungendo qualche riga in più per fornire informazioni aggiuntive necessarie a renderlo un algoritmo di Processing corretto. Questo semplifica la creazione di algoritmi e la specificazione di input e output.

Una limitazione importante con l’approccio del decoratore è che gli algoritmi creati in questo modo saranno sempre aggiunti al provider Processing Scripts di un utente – non è possibile aggiungere questi algoritmi ad un provider personalizzato, ad esempio per l’uso nei plugin.

Il seguente codice usa il decorativo @alg per

usare un layer vettoriale come input
contare il numero di elementi
fare un’operazione di buffer
creare un layer raster dal risultato dell’operazione di buffer
restituisce il buffer layer, il layer raster e il numero di elementi

from qgis import processing
from qgis.processing import alg
from qgis.core import QgsProject

@alg(name='bufferrasteralg', label='Buffer and export to raster (alg)',
     group='examplescripts', group_label='Example scripts')
# 'INPUT' is the recommended name for the main input parameter
@alg.input(type=alg.SOURCE, name='INPUT', label='Input vector layer')
# 'OUTPUT' is the recommended name for the main output parameter
@alg.input(type=alg.RASTER_LAYER_DEST, name='OUTPUT',
           label='Raster output')
@alg.input(type=alg.VECTOR_LAYER_DEST, name='BUFFER_OUTPUT',
           label='Buffer output')
@alg.input(type=alg.DISTANCE, name='BUFFERDIST', label='BUFFER DISTANCE',
           default=1.0)
@alg.input(type=alg.DISTANCE, name='CELLSIZE', label='RASTER CELL SIZE',
           default=10.0)
@alg.output(type=alg.NUMBER, name='NUMBEROFFEATURES',
            label='Number of features processed')

def bufferrasteralg(instance, parameters, context, feedback, inputs):
    """
    Description of the algorithm.
    (If there is no comment here, you will get an error)
    """
    input_featuresource = instance.parameterAsSource(parameters,
                                                     'INPUT', context)
    numfeatures = input_featuresource.featureCount()
    bufferdist = instance.parameterAsDouble(parameters, 'BUFFERDIST',
                                            context)
    rastercellsize = instance.parameterAsDouble(parameters, 'CELLSIZE',
                                                context)
    if feedback.isCanceled():
        return {}
    buffer_result = processing.run('native:buffer',
                               {'INPUT': parameters['INPUT'],
                                'OUTPUT': parameters['BUFFER_OUTPUT'],
                                'DISTANCE': bufferdist,
                                'SEGMENTS': 10,
                                'DISSOLVE': True,
                                'END_CAP_STYLE': 0,
                                'JOIN_STYLE': 0,
                                'MITER_LIMIT': 10
                                },
                               is_child_algorithm=True,
                               context=context,
                               feedback=feedback)
    if feedback.isCanceled():
        return {}
    rasterized_result = processing.run('qgis:rasterize',
                               {'LAYER': buffer_result['OUTPUT'],
                                'EXTENT': buffer_result['OUTPUT'],
                                'MAP_UNITS_PER_PIXEL': rastercellsize,
                                'OUTPUT': parameters['OUTPUT']
                               },
                               is_child_algorithm=True, context=context,
                               feedback=feedback)
    if feedback.isCanceled():
        return {}
    return {'OUTPUT': rasterized_result['OUTPUT'],
            'BUFFER_OUTPUT': buffer_result['OUTPUT'],
            'NUMBEROFFEATURES': numfeatures}

Come puoi vedere, coinvolge due algoritmi (“native:buffer” e “qgis:rasterize”). L’ultimo (“qgis:rasterize”) crea un layer raster dal layer buffer che è stato generato dal primo (“native:buffer”).

La parte del codice in cui avviene questa elaborazione non è difficile da capire se hai letto il capitolo precedente. Le prime righe, tuttavia, necessitano di qualche spiegazione aggiuntiva. Esse forniscono le informazioni necessarie per trasformare il codice in un algoritmo che può essere eseguito da uno qualsiasi dei componenti della GUI, come il toolbox o il model designer.

Queste linee sono tutte chiamate alle funzioni del decoratore @alg che aiutano a semplificare la codifica dell’algoritmo.

Il decoratore @alg è usato per definire il nome e la posizione dell’algoritmo negli Strumenti di Processing.
Il decoratore @alg.input è usato per definire quanto in ingresso dell’algoritmo.
Il decoratore @alg.output è usato per definire i risultati dell’algoritmo.

26.9.3. Tipi di input e output per algoritmi di processing 

Ecco l’elenco dei tipi di input e output supportati da Processing con le corrispondenti costanti del decoratore alg (il file algfactory.py contiene l’elenco completo delle costanti alg). Ordinate in base al nome della classe.

26.9.3.1. Tipi in ingresso 

Classe	Alg costanti	Descrizione
`QgsProcessingParameterAnnotationLayer`	`alg.ANNOTATION_LAYER`	Un layer annotazione
`QgsProcessingParameterAuthConfig`	`alg.AUTH_CFG`	Permette agli utenti di scegliere tra le configurazioni di autenticazione disponibili o di creare nuove configurazioni di autenticazione
`QgsProcessingParameterBand`	`alg.BAND`	Una banda di un layer raster
`QgsProcessingParameterBoolean`	`alg.BOOL`	Un valore booleano
`QgsProcessingParameterColor`	`alg.COLOR`	Un colore
`QgsProcessingParameterCoordinateOperation`	`alg.COORDINATE_OPERATION`	Un’operazione sulle coordinate (per le trasformazioni SR)
`QgsProcessingParameterCrs`	`alg.CRS`	Un sistema di riferimento delle coordinate
`QgsProcessingParameterDatabaseSchema`	`alg.DATABASE_SCHEMA`	Uno schema database
`QgsProcessingParameterDatabaseTable`	`alg.DATABASE_TABLE`	Una tabella database
`QgsProcessingParameterDateTime`	`alg.DATETIME`	Un datetime (o una data o un’ora)
`QgsProcessingParameterDistance`	`alg.DISTANCE`	Un doppio parametro numerico per i valori di distanza
`QgsProcessingParameterEnum`	`alg.ENUM`	Una numerazione, che permette la selezione da un insieme di valori predefiniti
`QgsProcessingParameterExpression`	`alg.EXPRESSION`	Una espressione
`QgsProcessingParameterExtent`	`alg.EXTENT`	Un’estensione spaziale definita da xmin, xmax, ymin, ymax
`QgsProcessingParameterField`	`alg.FIELD`	Un campo nella tabella degli attributi di un layer vettoriale
`QgsProcessingParameterFile`	`alg.FILE`	Un nome di un file esistente
`QgsProcessingParameterFileDestination`	`alg.FILE_DEST`	Un nome per un file in uscita appena creato
`QgsProcessingParameterFolderDestination`	`alg.FOLDER_DEST`	Una cartella (cartella di destinazione)
`QgsProcessingParameterGeometry`	`alg.GEOMETRY`	Una geometria
`QgsProcessingParameterNumber`	`alg.INT`	Un intero
`QgsProcessingParameterLayout`	`alg.LAYOUT`	Un layout
`QgsProcessingParameterLayoutItem`	`alg.LAYOUT_ITEM`	Un oggetto di layout
`QgsProcessingParameterMapLayer`	`alg.MAPLAYER`	Un layer mappa
`QgsProcessingParameterMapTheme`	`alg.MAP_THEME`	Un tema di mappa del progetto
`QgsProcessingParameterMatrix`	`alg.MATRIX`	Una matrice
`QgsProcessingParameterMeshLayer`	`alg.MESH_LAYER`	Un layer mesh
`QgsProcessingParameterMultipleLayers`	`alg.MULTILAYER`	Un insieme di layer
`QgsProcessingParameterNumber`	`alg.NUMBER`	Un valore numerico
`QgsProcessingParameterPoint`	`alg.POINT`	Un punto
`QgsProcessingParameterPointCloudDestination`	`alg.POINTCLOUD_LAYER_DEST`	Un parametro di destinazione del layer nuvola di punti, per specificare il percorso di destinazione di un layer della nuvola di punti creato dall’algoritmo.
`QgsProcessingParameterPointCloudLayer`	`alg.POINTCLOUD_LAYER`	Un layer nuvola di punti
`QgsProcessingParameterProviderConnection`	`alg.PROVIDER_CONNECTION`	Una connessione disponibile per un fornitore di database
`QgsProcessingParameterRange`	`alg.RANGE`	Un intervallo di numeri
`QgsProcessingParameterRasterLayer`	`alg.RASTER_LAYER`	Un layer Raster
`QgsProcessingParameterRasterDestination`	`alg.RASTER_LAYER_DEST`	Un parametro di destinazione del layer raster, per specificare il percorso di destinazione di un layer raster creato dall’algoritmo
`QgsProcessingParameterScale`	`alg.SCALE`	Una scala per le mappe
`QgsProcessingParameterFeatureSink`	`alg.SINK`	Un elemento bacino
`QgsProcessingParameterFeatureSource`	`alg.SOURCE`	Un’origine delle funzionalità
`QgsProcessingParameterString`	`alg.STRING`	Una stringa di testo
`QgsProcessingParameterVectorLayer`	`alg.VECTOR_LAYER`	Un vettore
`QgsProcessingParameterVectorDestination`	`alg.VECTOR_LAYER_DEST`	Un parametro di destinazione del layer vettore, per specificare il percorso di destinazione di un layer vettore creato dall’algoritmo.

26.9.3.2. Tipologie di output 

Classe	Alg costanti	Descrizione
`QgsProcessingOutputBoolean`	`alg.BOOL`	Un valore booleano
`QgsProcessingOutputNumber`	`alg.DISTANCE`	Un doppio parametro numerico per i valori di distanza
`QgsProcessingOutputFile`	`alg.FILE`	Un nome di un file esistente
`QgsProcessingOutputFolder`	`alg.FOLDER`	Una cartella
`QgsProcessingOutputHtml`	`alg.HTML`	HTML
`QgsProcessingOutputNumber`	`alg.INT`	Un intero
`QgsProcessingOutputLayerDefinition`	`alg.LAYERDEF`	Una definizione layer
`QgsProcessingOutputMapLayer`	`alg.MAPLAYER`	Un layer mappa
`QgsProcessingOutputMultipleLayers`	`alg.MULTILAYER`	Un insieme di layer
`QgsProcessingOutputNumber`	`alg.NUMBER`	Un valore numerico
`QgsProcessingOutputPointCloudLayer`	`alg.POINTCLOUD_LAYER`	Un layer nuvola di punti
`QgsProcessingOutputRasterLayer`	`alg.RASTER_LAYER`	Un layer Raster
`QgsProcessingOutputString`	`alg.STRING`	Una stringa di testo
`QgsProcessingOutputVectorLayer`	`alg.VECTOR_LAYER`	Un vettore

26.9.4. Manipolazione del risultato dell’algoritmo 

Quando si indica un risultato che rappresenta un layer (raster o vettoriale), l’algoritmo cercherà di aggiungerlo a QGIS una volta finito.

Output layer Raster: QgsProcessingParameterRasterDestination / alg.RASTER_LAYER_DEST.
Output layer Vettoriale: QgsProcessingParameterVectorDestination / alg.VECTOR_LAYER_DEST.

Così, anche se il metodo processing.run() non aggiunge i layer che crea al progetto corrente dell’utente, i due layer in uscita (buffer e raster buffer) saranno caricati, poiché sono salvati nelle destinazioni inserite dall’utente (o in destinazioni temporanee se l’utente non specifica destinazioni).

Se un layer viene creato come risultato di un algoritmo, dovrebbe essere dichiarato come tale. Altrimenti, non sarà possibile utilizzare correttamente l’algoritmo nel modellatore, poiché ciò che è dichiarato non corrisponderà a ciò che l’algoritmo crea realmente.

Puoi restituire stringhe, numeri e altro specificandoli nel dizionario dei risultati (come dimostrato per «NUMBEROFFEATURES»), ma dovrebbero sempre essere definiti esplicitamente come risultati del tuo algoritmo. È consigliabile che gli algoritmi restituiscano quanti più valori utili possibile, poiché questi possono essere preziosi per l’uso in algoritmi successivi, quando l’algoritmo viene usato come parte di un modello.

26.9.5. Comunicare con l’utente 

Se il tuo algoritmo richiede molto tempo per essere processato, è una buona idea informare l’utente sul progresso. Puoi usare feedback (QgsProcessingFeedback) per questo.

Il testo di avanzamento e la barra di avanzamento possono essere aggiornati usando due metodi: setProgressText(text) e setProgress(percent).

Puoi ottenere più informazioni usando pushCommandInfo(text), pushDebugInfo(text), pushInfo(text) and reportError(text).

Se il tuo script ha un problema, il modo corretto di gestirlo è generare una QgsProcessingException. Puoi passare un messaggio come argomento al costruttore dell’eccezione. L’elaborazione si occuperà di gestirla e di comunicare con l’utente, a seconda di dove viene eseguito l’algoritmo (toolbox, modeler, console Python, …)

26.9.6. Documentare gli script 

Puoi documentare i tuoi script sovrapponendo i metodi helpString() e helpUrl() di QgsProcessingAlgorithm.

26.9.7. Flag 

Puoi sovrascrivere il metodo flags() di QgsProcessingAlgorithm per dire a QGIS di più sul tuo algoritmo. Puoi per esempio dire a QGIS che lo script deve essere nascosto al modellatore, che può essere annullato, che non è thread sicuro, e altro.

Suggerimento

Per impostazione predefinita, Processing esegue gli algoritmi in un thread separato in modo da mantenere QGIS reattivo mentre l’attività di elaborazione viene eseguita. Se il tuo algoritmo si blocca spesso, probabilmente stai usando chiamate API che non sono sicure da eseguire in un thread in background. Prova a ripristinare il flag QgsProcessingAlgorithm.FlagNoThreading dal metodo flags() del tuo algoritmo per forzare Processing ad eseguire il tuo algoritmo nel thread principale.

26.9.8. Le migliori tecniche per scrivere algoritmi script 

Ecco un rapido riassunto delle cose da tenere in considerazione quando crei i tuoi algoritmi di script e, soprattutto, se vuoi condividerli con altri utenti di QGIS. Seguire queste semplici regole assicurerà la coerenza tra i diversi elementi di Processing come la casella degli strumenti, il modellatore o l’interfaccia di elaborazione batch.

Non caricare i layer risultanti. Lascia che Processing gestisca i tuoi risultati e carica i tuoi layer se necessario.
Dichiara sempre gli output che il tuo algoritmo crea.
Non mostrare finestre di messaggio o usare alcun elemento dell’interfaccia grafica dallo script. Se vuoi comunicare con l’utente, usa i metodi dell’oggetto feedback (QgsProcessingFeedback) o lancia una QgsProcessingException.

In QGIS sono già disponibili molti algoritmi di elaborazione. Puoi trovare il codice nel repository QGIS.