Important

La traduction est le fruit d’un effort communautaire auquel vous pouvez vous joindre. Cette page est actuellement traduite à 100.00%.

27.9. Écrire de nouveaux algorithmes sous la forme de scripts Python

Il existe deux options pour écrire des algorithmes de traitement à l’aide de Python.

Dans QGIS, vous pouvez utiliser Créer un nouveau script dans le menu Scripts en haut de Boîte à outils de traitement pour ouvrir Éditeur de script de traitement où vous pouvez écrire votre code. Pour simplifier la tâche, vous pouvez commencer avec un modèle de script en utilisant Créer un nouveau script à partir du modèle dans le même menu. Cela ouvre un modèle qui étend la classe QgsProcessingAlgorithm.

Si vous enregistrez le script dans le dossier scripts (l’emplacement par défaut) avec l’extension .py, l’algorithme sera disponible dans la Boîte à outils de traitements.

27.9.1. Étendre QgsProcessingAlgorithm

Le code suivant permet de

  1. prendre une couche vectorielle en entrée

  2. compter le nombre d’entités

  3. effectuer une opération tampon

  4. créer une couche raster à partir du résultat de l’opération de tampon

  5. renvoyer la couche tampon, la couche raster et le nombre d’entités

  1from qgis.PyQt.QtCore import QCoreApplication
  2from qgis.core import (QgsProcessing,
  3                       QgsProcessingAlgorithm,
  4                       QgsProcessingException,
  5                       QgsProcessingOutputNumber,
  6                       QgsProcessingParameterDistance,
  7                       QgsProcessingParameterFeatureSource,
  8                       QgsProcessingParameterVectorDestination,
  9                       QgsProcessingParameterRasterDestination)
 10from qgis import processing
 11
 12
 13class ExampleProcessingAlgorithm(QgsProcessingAlgorithm):
 14    """
 15    This is an example algorithm that takes a vector layer,
 16    creates some new layers and returns some results.
 17    """
 18
 19    def tr(self, string):
 20        """
 21        Returns a translatable string with the self.tr() function.
 22        """
 23        return QCoreApplication.translate('Processing', string)
 24
 25    def createInstance(self):
 26        # Must return a new copy of your algorithm.
 27        return ExampleProcessingAlgorithm()
 28
 29    def name(self):
 30        """
 31        Returns the unique algorithm name.
 32        """
 33        return 'bufferrasterextend'
 34
 35    def displayName(self):
 36        """
 37        Returns the translated algorithm name.
 38        """
 39        return self.tr('Buffer and export to raster (extend)')
 40
 41    def group(self):
 42        """
 43        Returns the name of the group this algorithm belongs to.
 44        """
 45        return self.tr('Example scripts')
 46
 47    def groupId(self):
 48        """
 49        Returns the unique ID of the group this algorithm belongs
 50        to.
 51        """
 52        return 'examplescripts'
 53
 54    def shortHelpString(self):
 55        """
 56        Returns a localised short help string for the algorithm.
 57        """
 58        return self.tr('Example algorithm short description')
 59
 60    def initAlgorithm(self, config=None):
 61        """
 62        Here we define the inputs and outputs of the algorithm.
 63        """
 64        # 'INPUT' is the recommended name for the main input
 65        # parameter.
 66        self.addParameter(
 67            QgsProcessingParameterFeatureSource(
 68                'INPUT',
 69                self.tr('Input vector layer'),
 70                types=[QgsProcessing.TypeVectorAnyGeometry]
 71            )
 72        )
 73        self.addParameter(
 74            QgsProcessingParameterVectorDestination(
 75                'BUFFER_OUTPUT',
 76                self.tr('Buffer output'),
 77            )
 78        )
 79        # 'OUTPUT' is the recommended name for the main output
 80        # parameter.
 81        self.addParameter(
 82            QgsProcessingParameterRasterDestination(
 83                'OUTPUT',
 84                self.tr('Raster output')
 85            )
 86        )
 87        self.addParameter(
 88            QgsProcessingParameterDistance(
 89                'BUFFERDIST',
 90                self.tr('BUFFERDIST'),
 91                defaultValue = 1.0,
 92                # Make distance units match the INPUT layer units:
 93                parentParameterName='INPUT'
 94            )
 95        )
 96        self.addParameter(
 97            QgsProcessingParameterDistance(
 98                'CELLSIZE',
 99                self.tr('CELLSIZE'),
100                defaultValue = 10.0,
101                parentParameterName='INPUT'
102            )
103        )
104        self.addOutput(
105            QgsProcessingOutputNumber(
106                'NUMBEROFFEATURES',
107                self.tr('Number of features processed')
108            )
109        )
110
111    def processAlgorithm(self, parameters, context, feedback):
112        """
113        Here is where the processing itself takes place.
114        """
115        # First, we get the count of features from the INPUT layer.
116        # This layer is defined as a QgsProcessingParameterFeatureSource
117        # parameter, so it is retrieved by calling
118        # self.parameterAsSource.
119        input_featuresource = self.parameterAsSource(parameters,
120                                                     'INPUT',
121                                                     context)
122        numfeatures = input_featuresource.featureCount()
123
124        # Retrieve the buffer distance and raster cell size numeric
125        # values. Since these are numeric values, they are retrieved
126        # using self.parameterAsDouble.
127        bufferdist = self.parameterAsDouble(parameters, 'BUFFERDIST',
128                                            context)
129        rastercellsize = self.parameterAsDouble(parameters, 'CELLSIZE',
130                                                context)
131        if feedback.isCanceled():
132            return {}
133        buffer_result = processing.run(
134            'native:buffer',
135            {
136                # Here we pass on the original parameter values of INPUT
137                # and BUFFER_OUTPUT to the buffer algorithm.
138                'INPUT': parameters['INPUT'],
139                'OUTPUT': parameters['BUFFER_OUTPUT'],
140                'DISTANCE': bufferdist,
141                'SEGMENTS': 10,
142                'DISSOLVE': True,
143                'END_CAP_STYLE': 0,
144                'JOIN_STYLE': 0,
145                'MITER_LIMIT': 10
146            },
147            # Because the buffer algorithm is being run as a step in
148            # another larger algorithm, the is_child_algorithm option
149            # should be set to True
150            is_child_algorithm=True,
151            #
152            # It's important to pass on the context and feedback objects to
153            # child algorithms, so that they can properly give feedback to
154            # users and handle cancelation requests.
155            context=context,
156            feedback=feedback)
157
158        # Check for cancelation
159        if feedback.isCanceled():
160            return {}
161
162        # Run the separate rasterization algorithm using the buffer result
163        # as an input.
164        rasterized_result = processing.run(
165            'qgis:rasterize',
166            {
167                # Here we pass the 'OUTPUT' value from the buffer's result
168                # dictionary off to the rasterize child algorithm.
169                'LAYER': buffer_result['OUTPUT'],
170                'EXTENT': buffer_result['OUTPUT'],
171                'MAP_UNITS_PER_PIXEL': rastercellsize,
172                # Use the original parameter value.
173                'OUTPUT': parameters['OUTPUT']
174            },
175            is_child_algorithm=True,
176            context=context,
177            feedback=feedback)
178
179        if feedback.isCanceled():
180            return {}
181
182        # Return the results
183        return {'OUTPUT': rasterized_result['OUTPUT'],
184                'BUFFER_OUTPUT': buffer_result['OUTPUT'],
185                'NUMBEROFFEATURES': numfeatures}

Fonctions standard de l’algorithme de traitement:

  • createInstance (obligatoire)

    Doit renvoyer une nouvelle copie de votre algorithme. Si vous modifiez le nom de la classe, assurez-vous également de mettre à jour la valeur renvoyée ici pour correspondre!

  • nom (obligatoire)

    Renvoie un nom d’algorithme unique, utilisé pour identifier l’algorithme.

  • displayName (obligatoire)

    Renvoie le nom de l’algorithme traduit.

  • group

    Renvoie le nom du groupe auquel appartient cet algorithme.

  • groupId

    Renvoie l’ID unique du groupe auquel appartient cet algorithme.

  • shortHelpString

    Renvoie une courte chaîne d’aide localisée pour l’algorithme.

  • initAlgorithm (obligatoire)

    Nous définissons ici les entrées et sorties de l’algorithme.

    INPUT et OUTPUT sont des noms recommandés pour les paramètres d’entrée principale et de sortie principale, respectivement.

    Si un paramètre dépend d’un autre paramètre, parentParameterName est utilisé pour spécifier cette relation (peut être le champ / la bande d’une couche ou les unités de distance d’une couche).

  • processAlgorithm (obligatoire)

    C’est là que le traitement a lieu.

    Les paramètres sont récupérés à l’aide de fonctions spéciales, par exemple parameterAsSource et parameterAsDouble.

    processing.run peut être utilisé pour exécuter d’autres algorithmes de traitement à partir d’un algorithme de traitement. Le premier paramètre est le nom de l’algorithme, le second est un dictionnaire des paramètres de l’algorithme. is_child_algorithm et est normalement défini sur True lors de l’exécution d’un algorithme à partir d’un autre algorithme. context et feedback informent l’algorithme de l’environnement à exécuter et du canal de communication avec l’utilisateur (capture de la demande d’annulation, rapport de progression, retour d’informations textuelles). Lors de l’utilisation des paramètres de l’algorithme (parent) en tant que paramètres des algorithmes « enfants », les valeurs de paramètre d’origine doivent être utilisées (par exemple, parameters ['OUTPUT']).

    Il est recommandé de vérifier autant que possible l’objet de retour pour annulation! Cela permet une annulation réactive, au lieu de forcer les utilisateurs à attendre qu’un traitement indésirable se produise.

    L’algorithme doit renvoyer des valeurs pour tous les paramètres de sortie qu’il a définis en tant que dictionnaire. Dans ce cas, il s’agit du tampon et des couches de sortie tramées, ainsi que du nombre d’entités traitées. Les clés du dictionnaire doivent correspondre aux noms de paramètre/sortie d’origine.

27.9.2. Le décorateur @alg

En utilisant le décorateur @alg, vous pouvez créer vos propres algorithmes en écrivant le code Python et en ajoutant quelques lignes supplémentaires pour fournir les informations supplémentaires nécessaires pour en faire un algorithme de traitement approprié. Cela simplifie la création d’algorithmes et la spécification des entrées et sorties.

Une limitation importante de l’approche par décorateurs est que les algorithmes créés de cette manière seront toujours ajoutés au fournisseur de scripts de traitement d’un utilisateur - il n’est pas possible d’ajouter ces algorithmes à un fournisseur personnalisé, par ex. pour une utilisation dans les extensions.

Le code suivant utilise le décorateur @alg pour

  1. utiliser une couche vectorielle comme entrée

  2. compter le nombre d” entités

  3. faire une opération buffer

  4. créer une couche raster à partir du résultat de l’opération de tampon

  5. renvoyer la couche tampon, la couche raster et le nombre d’entités

 1from qgis import processing
 2from qgis.processing import alg
 3from qgis.core import QgsProject
 4
 5@alg(name='bufferrasteralg', label='Buffer and export to raster (alg)',
 6     group='examplescripts', group_label='Example scripts')
 7# 'INPUT' is the recommended name for the main input parameter
 8@alg.input(type=alg.SOURCE, name='INPUT', label='Input vector layer')
 9# 'OUTPUT' is the recommended name for the main output parameter
10@alg.input(type=alg.RASTER_LAYER_DEST, name='OUTPUT',
11           label='Raster output')
12@alg.input(type=alg.VECTOR_LAYER_DEST, name='BUFFER_OUTPUT',
13           label='Buffer output')
14@alg.input(type=alg.DISTANCE, name='BUFFERDIST', label='BUFFER DISTANCE',
15           default=1.0)
16@alg.input(type=alg.DISTANCE, name='CELLSIZE', label='RASTER CELL SIZE',
17           default=10.0)
18@alg.output(type=alg.NUMBER, name='NUMBEROFFEATURES',
19            label='Number of features processed')
20
21def bufferrasteralg(instance, parameters, context, feedback, inputs):
22    """
23    Description of the algorithm.
24    (If there is no comment here, you will get an error)
25    """
26    input_featuresource = instance.parameterAsSource(parameters,
27                                                     'INPUT', context)
28    numfeatures = input_featuresource.featureCount()
29    bufferdist = instance.parameterAsDouble(parameters, 'BUFFERDIST',
30                                            context)
31    rastercellsize = instance.parameterAsDouble(parameters, 'CELLSIZE',
32                                                context)
33    if feedback.isCanceled():
34        return {}
35    buffer_result = processing.run('native:buffer',
36                               {'INPUT': parameters['INPUT'],
37                                'OUTPUT': parameters['BUFFER_OUTPUT'],
38                                'DISTANCE': bufferdist,
39                                'SEGMENTS': 10,
40                                'DISSOLVE': True,
41                                'END_CAP_STYLE': 0,
42                                'JOIN_STYLE': 0,
43                                'MITER_LIMIT': 10
44                                },
45                               is_child_algorithm=True,
46                               context=context,
47                               feedback=feedback)
48    if feedback.isCanceled():
49        return {}
50    rasterized_result = processing.run('qgis:rasterize',
51                               {'LAYER': buffer_result['OUTPUT'],
52                                'EXTENT': buffer_result['OUTPUT'],
53                                'MAP_UNITS_PER_PIXEL': rastercellsize,
54                                'OUTPUT': parameters['OUTPUT']
55                               },
56                               is_child_algorithm=True, context=context,
57                               feedback=feedback)
58    if feedback.isCanceled():
59        return {}
60    return {'OUTPUT': rasterized_result['OUTPUT'],
61            'BUFFER_OUTPUT': buffer_result['OUTPUT'],
62            'NUMBEROFFEATURES': numfeatures}

Comme vous pouvez le voir, cela implique deux algorithmes (“native: buffer” et “qgis: rasterize”). Le dernier (“qgis: rasterize”) crée une couche raster à partir de la couche tampon qui a été générée par la première (“native: buffer”).

La partie du code où s’effectue ce traitement n’est pas difficile à comprendre si vous avez lu le chapitre précédent. Les premières lignes nécessitent cependant quelques explications supplémentaires. Ils fournissent les informations nécessaires pour transformer votre code en un algorithme pouvant être exécuté à partir de n’importe quel composant de l’interface graphique, comme la boîte à outils ou le modeleur graphique.

Ces lignes sont toutes des appels aux fonctions du décorateur @alg qui aident à simplifier le codage de l’algorithme.

  • Le décorateur @alg est utilisé pour définir le nom et l’emplacement de l’algorithme dans la boîte à outils.

  • Le décorateur @alg.input est utilisé pour définir les entrées de l’algorithme.

  • Le décorateur @alg.output est utilisé pour définir les sorties de l’algorithme.

Pour les paramètres disponibles et leur correspondance, lire Types d’entrée et de sortie pour les algorithmes de traitement.

27.9.3. Sortie de l’algorithme

Lorsque vous déclarez une sortie représentant une couche (raster ou vecteur), l’algorithme essaie de l’ajouter à QGIS une fois qu’il est terminé.

  • Sortie de la couche raster: QgsProcessingParameterRasterDestination / alg.RASTER_LAYER_DEST.

  • Sortie de couche vectorielle: QgsProcessingParameterVectorDestination / alg.VECTOR_LAYER_DEST.

Donc, même si la méthode processing.run() n’ajoute pas les couches qu’elle crée au projet actuel de l’utilisateur, les deux couches de sortie (tampon et tampon raster) seront chargées, car elles sont enregistrées dans les destinations entrées par l’utilisateur (ou vers des destinations temporaires si l’utilisateur ne spécifie pas de destinations).

Si une couche est créée en sortie d’un algorithme, elle doit être déclarée comme telle. Sinon, vous ne pourrez pas utiliser correctement l’algorithme dans le modeleur, car ce qui est déclaré ne correspondra pas à ce que l’algorithme crée réellement.

Vous pouvez renvoyer des chaînes, des nombres et bien plus en les spécifiant dans le dictionnaire de résultats (comme illustré pour « NUMBEROFFEATURES »), mais ils doivent toujours être explicitement définis comme sorties de votre algorithme. Nous encourageons les algorithmes à générer autant de valeurs utiles que possible, car celles-ci peuvent être utiles pour une utilisation dans des algorithmes ultérieurs lorsque votre algorithme est utilisé dans le cadre d’un modèle.

27.9.4. Communiquer avec l’utilisateur

Si votre algorithme prend beaucoup de temps à être traité, c’est une bonne idée d’informer l’utilisateur de la progression. Pour cela, vous pouvez utiliser feedback ( QgsProcessingFeedback).

Le texte de progression et la barre de progression peuvent être mis à jour à l’aide de deux méthodes: setProgressText (text) et setProgress (percent).

Vous pouvez fournir plus d’informations en utilisant pushCommandInfo(text), pushDebugInfo(text), pushInfo(text) and reportError(text).

Si votre script a un problème, la manière correcte de le gérer consiste à déclencher une QgsProcessingException. Vous pouvez passer un message comme argument au constructeur de l’exception. Le traitement se chargera de le gérer et de communiquer avec l’utilisateur, selon le lieu d’exécution de l’algorithme (boîte à outils, modeleur, console Python, …)

27.9.5. Documenter ses scripts

Vous pouvez documenter vos scripts en surchargeant helpString() et helpUrl(), méthodes de la classe QgsProcessingAlgorithm.

27.9.6. Flags

Vous pouvez remplacer la méthode flags() de QgsProcessingAlgorithm pour en dire plus à QGIS sur votre algorithme. Vous pouvez par exemple dire à QGIS que le script doit être caché au modeleur, qu’il peut être annulé, qu’il n’est pas sûr pour les threads, et plus encore.

Astuce

Par défaut, Processing exécute des algorithmes dans un thread séparé afin de maintenir QGIS réactif pendant l’exécution de la tâche de traitement. Si votre algorithme plante régulièrement, vous utilisez probablement des appels d’API qui ne sont pas sûrs à faire dans un thread d’arrière-plan. Essayez de renvoyer l’indicateur QgsProcessingAlgorithm.FlagNoThreading de la méthode flags () de votre algorithme pour forcer Processing à exécuter à la place votre algorithme dans le thread principal.

27.9.7. Bonnes pratiques d’écriture de scripts d’algorithmes

Voici un rapide résumé des idées à retenir lorsque vous créez vos scripts d’algorithmes et que vous souhaitez les partager avec d’autres utilisateurs QGIS. En suivant ces quelques règles, vous vous assurerez de fournir des éléments constants sur toutes les interfaces du menu Traitements telles que la boîte à outils, le modeleur et l’interface de commande.

  • Ne chargez pas les couches de résultat. Laissez les Traitements gérer ces résultats et charger vos couches si besoin.

  • Déclarez toujours les sorties créées par votre algorithme.

  • N’affichez pas de boîtes de message et n’utilisez aucun élément GUI du script. Si vous souhaitez communiquer avec l’utilisateur, utilisez les méthodes de l’objet de rétroaction ( QgsProcessingFeedback) ou lancez une QgsProcessingException.

Il existe déjà de nombreux algorithmes de traitement disponibles dans le dépôt du code de QGIS.