Nieuwe algoritmen voor Processing schrijven als scripts voor Python¶

QgsProcessingAlgorithm uitbreiden
De decorator @alg
Typen invoer en uitvoer voor algoritmes van Processing
- Typen invoer
- Typen uitvoer
Uitvoer algoritme afhandelen
Communiceren met de gebruiker
Documenteren van uw scripts
Vlaggen
Best practices voor het schrijven van algoritmen als scripts

Er bestaan twee opties voor het schrijven van algoritmes voor Processing met Python.

Uitbreiden van QgsProcessingAlgorithm
De decarotor @alg gebruiken

In QGIS kunt u Nieuw script maken in het menu Scripts boven in de Processing Toolbox gebruiken om de Processing Script bewerken te openen waar u uw code kunt schrijven. U kunt, om de taak te vereenvoudigen, beginnen met een sjabloon voor een script door Nieuw script uit sjabloon maken uit hetzelfde menu te gebruiken. Dat opent een sjabloon dat QgsProcessingAlgorithm uitbreidt.

Als u het script opslaat in de map scripts (de standaard locatie) met de extensie .py, zal het algoritme beschikbaar komen in de Processing Toolbox.

QgsProcessingAlgorithm uitbreiden ¶

De volgende code

neemt een vectorlaag als invoer
telt het aantal objecten
doet een bewerking voor een buffer
maakt een rasterlaag als resultaat van de bewerking voor de buffer
geeft de laag voor de buffer, de rasterlaag en het aantal objecten terug

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}

Standaard functies voor algoritmes van Processing

createInstance (verplicht)
Moet een nieuwe kopie van uw algoritme teruggeven. Als u de naam van de klasse wijzigt, zorg er dan voor dat u ook de hier teruggegeven waarde bijwerkt zodat die overeenkomt!
name (verplicht)
Geeft de unieke naam van het algoritme terug, gebruikt voor het identificeren van het algoritme.
displayName (verplicht)
Geeft de vertaalde naam van het algoritme terug.
group
Geeft de naam van de groep terug waartoe dit algoritme behoort.
groupId
Geeft de unieke ID van de groep terug waartoe dit algoritme behoort.
shortHelpString
Geeft een gelokaliseerde korte tekenreeks voor Help voor het algoritme terug.
initAlgorithm (verplicht)
Hier definiëren we de in- en uitvoer voor het algoritme.

INPUT en OUTPUT zijn aanbevolen namen voor de parameters voor de respectievelijke hoofdinvoer en hoofduitvoer.

Als een parameter afhankelijk is van een andere parameter, wordt parentParameterName gebruikt om deze relatie te specificeren (zou het veld / band van een laag of de eenheden voor afstand van een laag kunnen zijn).
processAlgorithm (verplicht)
Dit is waar de verwerking plaatsvindt.

Parameters worden opgehaald met behulp van functies voor speciale doelen, bijvoorbeeld parameterAsSource en parameterAsDouble.

processing.run kan worden gebruikt om andere algoritmes van Processing uit te voeren vanuit een algoritme van Processing. De eerste parameter is de naam van het algoritme, de tweede is een woordenboek van de parameters voor het algoritme. is_child_algorithm is normaal ingesteld op True bij het uitvoeren van een algoritme vanuit een ander algoritme. context en feedback informeert het algoritme over de omgeving waarin het moet worden uitgevoerd en het kanaal voor het communiceren met de gebruiker (opvangen verzoek tot annuleren, voortgang rapporteren, tekstuele terugkoppeling geven). Bij het gebruiken van de parameters van (ouder) algoritmes als parameters voor “kind”-algoritmes, zouden de originele waarden voor de parameter moeten worden gebruikt (bijv. parameters['OUTPUT']).

Het is goed gebruik om het object feedback te controleren op annuleren zo vaak als enigszins mogelijk is! Door dit te doen maakt het reageren op annuleren mogelijk, in plaats van gebruikers te forceren te wachten tot ongewenste verwerking optreedt.

Het algoritme zou waarden terug moeten geven voor alle waarden van de parameters voor de uitvoer die zijn gedefinieerd als een woordenboek. In dit geval zijn dat de buffer en de gerasteriseerde uitvoerlagen, en het aantal verwerkte objecten. De sleutels voor het woordenboek moeten overeen komen met de originele parameters/namen van de uitvoer.

De decorator @alg ¶

Door de decorator @alg te gebruiken kunt u uw eigen algoritmen maken door de code voor Python te schrijven en een aantal extra regels toe te voegen, om aanvullende informatie te verschaffen die nodig is om een correct algoritme voor Processing te maken. Dit vereenvoudigt het maken van algoritmen en het specificeren van in- en uitvoer.

Één belangrijke beperking met de benadering van de decorator is dat algoritmen die op deze manier worden gemaakt worden toegevoegd aan de Processing Scriptsprovider van de gebruiker – het is niet mogelijk om deze algoritmen toe te voegen aan een aangepaste provider, bijv om in plug-ins te gebruiken.

De volgende code gebruikt de decorator @alg om

een vectorlaag als invoer te gebruiken
het aantal objecten te tellen
een bewerking voor een buffer uit te voeren
een rasterlaag te maken uit het resultaat van de bewerking voor de buffer
geeft de laag voor de buffer, de rasterlaag en het aantal objecten terug

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}

Zoals u kunt zien zijn twee algoritmen betrokken (‘native:buffer’ en ‘qgis:rasterize’). De laatste (‘qgis:rasterize’) maakt een rasterlaag uit de bufferlaag die werd gemaakt door het eerste (‘native:buffer’).

Het deel van de code waar deze verwerking plaatsvindt is niet moeilijk te begrijpen, als u het vorige hoofdstuk hebt gelezen. De eerste regels moeten echter even nader worden uitgelegd. Zij verschaffen de informatie die nodig is om van uw code een algoritme te maken dat kan worden uitgevoerd vanuit elk van de componenten van de GUI, zoals de Toolbox of Grafische modellen maken.

Deze regels zijn allemaal aanroepen naar functies van de decorator @alg, die helpen de codering van het algoritme te vereenvoudigen.

De decorator @alg wordt gebruikt om de naam en locatie te definiëren van het algoritme in de Toolbox.
De decorator @alg.input wordt gebruikt om de invoer voor het algoritme te definiëren.
De decorator @alg.output wordt gebruikt om de uitvoer voor het algoritme te definiëren.

Typen invoer en uitvoer voor algoritmes van Processing ¶

Hier is de lijst van typen invoer en uitvoer die in Processing worden ondersteund, met hun overeenkomende alg decorator constanten (algfactory.py bevat de volledige lijst met alg constanten). Gesorteerd op naam van de klasse.

Typen invoer ¶

Klasse	Alg constante	Beschrijving
`QgsProcessingParameterAuthConfig`	`alg.AUTH_CFG`	Stelt gebruikers in staat om te selecteren uit beschikbare configuraties voor authenticatie of nieuwe configuraties voor authenticatie te maken
`QgsProcessingParameterBand`	`alg.BAND`	Een band van een rasterlaag
`QgsProcessingParameterBoolean`	`alg.BOOL`	Een Booleaanse waarde
`QgsProcessingParameterColor`	`alg.COLOR`	Een kleur
`QgsProcessingParameterCrs`	`alg.CRS`	Een Coördinaten ReferentieSysteem
`QgsProcessingParameterDistance`	`alg.DISTANCE`	Een numerieke parameter Double voor waarden voor afstanden.
`QgsProcessingParameterEnum`	`alg.ENUM`	Een enumeratie, wat het mogelijk maakt te selecteren uit een set vooraf gedefinieerde waarden
`QgsProcessingParameterExpression`	`alg.EXPRESSION`	Een expressie
`QgsProcessingParameterExtent`	`alg.EXTENT`	Een ruimtelijk bereik gedefinieerd door xmin, xmax, ymin, ymax
`QgsProcessingParameterField`	`alg.FIELD`	Een veld in de attributentabel van een vectorlaag
`QgsProcessingParameterFile`	`alg.FILE`	Een bestandsnaam van een bestaand bestand
`QgsProcessingParameterFileDestination`	`alg.FILE_DEST`	Een bestandsnaam voor een nieuw gemaakt bestand voor uitvoer
`QgsProcessingParameterFolderDestination`	`alg.FOLDER_DEST`	Een map
`QgsProcessingParameterNumber`	`alg.INT`	Een integer (geheel getal)
`QgsProcessingParameterLayout`	`alg.LAYOUT`	Een lay-out
`QgsProcessingParameterLayoutItem`	`alg.LAYOUT_ITEM`	Een item voor lay-out
`QgsProcessingParameterMapLayer`	`alg.MAPLAYER`	Een kaartlaag
`QgsProcessingParameterMatrix`	`alg.MATRIX`	Een matrix
`QgsProcessingParameterMeshLayer`	`alg.MESH_LAYER`	Een laag met mazen
`QgsProcessingParameterMultipleLayers`	`alg.MULTILAYER`	Een set lagen
`QgsProcessingParameterNumber`	`alg.NUMBER`	Een numerieke waarde
`QgsProcessingParameterPoint`	`alg.POINT`	Een punt
`QgsProcessingParameterRange`	`alg.RANGE`	Een nummerreeks
`QgsProcessingParameterRasterLayer`	`alg.RASTER_LAYER`	Een rasterlaag
`QgsProcessingParameterRasterDestination`	`alg.RASTER_LAYER_DEST`	Een rasterlaag
`QgsProcessingParameterScale`	`alg.SCALE`	Een schaal voor de kaart
`QgsProcessingParameterFeatureSink`	`alg.SINK`	Een object afvoer
`QgsProcessingParameterFeatureSource`	`alg.SOURCE`	Een object bron
`QgsProcessingParameterScale`		Een schaal voor de kaart
`QgsProcessingParameterString`	`alg.STRING`	Een teksttekenreeks
`QgsProcessingParameterVectorLayer`	`alg.VECTOR_LAYER`	Een vectorlaag
`QgsProcessingParameterVectorDestination`	`alg.VECTOR_LAYER_DEST`	Een vectorlaag

Typen uitvoer ¶

Klasse	Alg constante	Beschrijving
`QgsProcessingOutputBoolean`	`alg.BOOL`	Een Booleaanse waarde
`QgsProcessingOutputNumber`	`alg.DISTANCE`	Een numerieke parameter Double voor waarden voor afstanden.
`QgsProcessingOutputFile`	`alg.FILE`	Een bestandsnaam van een bestaand bestand
`QgsProcessingOutputFolder`	`alg.FOLDER`	Een map
`QgsProcessingOutputHtml`	`alg.HTML`	HTML
`QgsProcessingOutputNumber`	`alg.INT`	Een integer (geheel getal)
`QgsProcessingOutputLayerDefinition`	`alg.LAYERDEF`	Een laag-definitie
`QgsProcessingOutputMapLayer`	`alg.MAPLAYER`	Een kaartlaag
`QgsProcessingOutputMultipleLayers`	`alg.MULTILAYER`	Een set lagen
`QgsProcessingOutputNumber`	`alg.NUMBER`	Een numerieke waarde
`QgsProcessingOutputRasterLayer`	`alg.RASTER_LAYER`	Een rasterlaag
`QgsProcessingOutputString`	`alg.STRING`	Een teksttekenreeks
`QgsProcessingOutputVectorLayer`	`alg.VECTOR_LAYER`	Een vectorlaag

Uitvoer algoritme afhandelen ¶

Wanneer u een uitvoer declareert die een laag weergeeft (raster of vector), zal het algoritme proberen het toe te voegen aan QGIS als het eenmaal voltooid is.

Rasterlaag uitvoer: QgsProcessingParameterRasterDestination / alg.RASTER_LAYER_DEST.
Vectorlaag uitvoer: QgsProcessingParameterVectorDestination / alg.VECTOR_LAYER_DEST.

Dus, zelfs als de methode processing.run() de lagen die het maakt niet toevoegt aan het huidige project van de gebruiker, zullen de twee uitvoerlagen (buffer en rasterbuffer) worden geladen, omdat zij zijn opgeslagen naar de doelen die zijn ingevoerd door de gebruiker (of naar tijdelijke doelen als de gebruiker geen doelen specificeert).

Als een laag wordt gemaakt als uitvoer van een algoritme, zou het ook zo moeten worden gedefinieerd. Anders zult u niet in staat zijn het algoritme op de juiste manier te gebruiken in Grafische modellen bouwen, omdat wat is gedefinieerd niet overeenkomt met wat het algoritme in werkelijkheid maakt.

U kunt tekenreeks, getallen en meer teruggeven door ze te specificeren in het woordenboek van het resultaat (zoals gedemonstreerd voor “NUMBEROFFEATURES”), maar ze zouden altijd expliciet moeten worden gedefinieerd als uitvoer vanuit uw algoritme. We propageren om algoritmen zoveel nuttige waarden als mogelijk uit te laten voeren, omdat die waardevol kunnen zijn bij later gebruik in algoritmen wanneer uw algoritme wordt gebruikt als deel van een model.

Communiceren met de gebruiker ¶

Als uw algoritme er lang over doet om te worden verwerkt, is het een goed idee om de gebruiker over de voortgang te informeren. U kunt feedback (QgsProcessingFeedback) hiervoor gebruiken.

De tekst voor de voortgang en de voortgangsbalk kunnen worden bijgewerkt met behulp van twee methoden: setProgressText(text) en setProgress(percent).

U kunt meer informatie verschaffen door te gebruiken pushCommandInfo(text), pushDebugInfo(text), pushInfo(text) en reportError(text).

Als uw script problemen heeft, is de juiste manier om door te gaan het een uitzondering te laten opkomen van een QgsProcessingException. U kunt een bericht doorgeven als argument aan de constructor van de uitzondering. Processing zal zorg dragen voor de afhandeling ervan en communiceren met de gebruiker, afhankelijk van waaruit het algoritme wordt uitgevoerd (Toolbox, Grafische modellen bouwen, console van Python, …)

Documenteren van uw scripts ¶

U kunt uw scripts documenteren door het overladen van de methoden helpString() en helpUrl() van QgsProcessingAlgorithm.

Vlaggen ¶

U kunt de methode flags van QgsProcessingAlgorithm overschrijven om QGIS meer te vertellen over uw algoritme. U kunt bijvoorbeeld QGIS vertellen dat het script moet worden verborgen in Grafische modellen bouwen, dat het kan worden geannuleerd, dat het niet veilig met threads is, en meer.

Tip

Standaard voert Processing algoritmen uit in een afzonderlijke om QGIS te kunnen laten reageren als de taak voor processing wordt uitgevoerd. Als uw algoritme regelmatig crasht, gebruikt u waarschijnlijk aanroepen naar de API die niet veilig kunnen worden uitgevoerd in een thread op de achtergrond. Probeer om de vlag QgsProcessingAlgorithm.FlagNoThreading terug te laten geven vanuit uit algoritmes methode flags() om Processing te forceren om uw algoritme in plaats daarvan in de hoofdthread uit te laten voeren.

Best practices voor het schrijven van algoritmen als scripts ¶

Hier is een snelle samenvatting van ideeën om te overwegen wanneer u uw algoritmen als scripts maakt en, in het bijzonder, als u ze wilt delen met andere gebruikers van QGIS. Volgen van deze eenvoudige regels zal zorgen voor consistentie in de verschillende elementen van Processing, zoals de Toolbox, Grafische modellen bouwen of de interface voor Batch-processing.

Laad geen resulterende lagen. Laat Processing uw resultaten afhandelen en lagen laden als dat nodig is.
Definieer altijd de uitvoer die uw algoritme maakt.
Geef geen berichtenvensters weer of gebruik een element van de GUI vanuit het script. Als u wilt communiceren met de gebruiker, gebruik dan de methoden van het object feedback (QgsProcessingFeedback) of werp een QgsProcessingException <qgis.core.QgsProcessingException>` op.

Er zijn al heel veel algoritmen voor Processing beschikbaar in QGIS. U kunt de code vinden op https://github.com/qgis/QGIS/blob/release-3_10/python/plugins/processing/algs/qgis.