23.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.
23.9.1. Étendre QgsProcessingAlgorithm
Le code suivant permet de
prendre une couche vectorielle en entrée
compter le nombre d’entités
effectuer une opération tampon
créer une couche raster à partir du résultat de l’opération de tampon
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.
INPUTetOUTPUTsont 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,
parentParameterNameest 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
parameterAsSourceetparameterAsDouble.processing.runpeut ê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_algorithmet est normalement défini surTruelors de l’exécution d’un algorithme à partir d’un autre algorithme.contextetfeedbackinforment 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.
23.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
utiliser une couche vectorielle comme entrée
compter le nombre d” entités
faire une opération buffer
créer une couche raster à partir du résultat de l’opération de tampon
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.
23.9.3. Types d’entrée et de sortie pour les algorithmes de traitement
Voici la liste des types d’entrée et de sortie pris en charge dans le Module de Traitements avec leurs constantes de décorateur correspondantes ( algfactory.py contient la liste complète des constantes). Trié par nom de classe.
23.9.3.1. Types d’entrées
Classe |
Constante d’Algorithme |
Description |
|---|---|---|
|
Permet aux utilisateurs de sélectionner parmi les configurations d’authentification disponibles ou de créer de nouvelles configurations d’authentification |
|
|
Une bande d’une couche raster |
|
|
Une valeur booléenne |
|
|
Une couleur |
|
|
Une opération sur les coordonnées (transformation de SCR) |
|
|
Un système de référence de coordonnées |
|
|
Un schéma de base de données |
|
|
Une table de base de données |
|
|
Une date-heure (ou une date ou heure simple) |
|
|
Un double paramètre numérique pour les valeurs de distance |
|
|
Une énumération, permettant la sélection à partir d’un ensemble de valeurs prédéfinies |
|
|
Une expression |
|
|
Une étendue spatiale définie par xmin, xmax, ymin, ymax |
|
|
Un champ dans la table attributaire d’une couche vectorielle |
|
|
Un nom de fichier d’un fichier existant |
|
|
Un nom de fichier pour un fichier de sortie nouvellement créé |
|
|
Un répertoire (répertoire de destination) |
|
|
Un nombre entier |
|
|
Une mise en page |
|
|
Un élément de mise en page |
|
|
Une couche de carte |
|
|
Un thème de carte d’un projet |
|
|
Une matrice |
|
|
Une couche maillée |
|
|
Un ensemble de couches |
|
|
Une valeur numérique |
|
|
Un point |
|
|
Une connexion disponible à un fournisseur de base de données |
|
|
Une plage de valeurs |
|
|
Une couche raster |
|
|
Une couche raster |
|
|
Une échelle de carte |
|
|
A feature sink |
|
|
Une source d’entités |
|
|
Une chaîne de texte |
|
|
Une couche vecteur |
|
|
Une couche vecteur |
23.9.3.2. Types de sortie
Classe |
Constante d’Algorithme |
Description |
|---|---|---|
|
Une valeur booléenne |
|
|
Un double paramètre numérique pour les valeurs de distance |
|
|
Un nom de fichier d’un fichier existant |
|
|
Un dossier |
|
|
HTML |
|
|
Un entier |
|
|
Une définition de couche |
|
|
Une couche de carte |
|
|
Un ensemble de couches |
|
|
Une valeur numérique |
|
|
Une couche raster |
|
|
Une chaîne de texte |
|
|
Une couche vecteur |
23.9.4. 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.
23.9.5. 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, …)
23.9.6. Documenter ses scripts
Vous pouvez documenter vos scripts en surchargeant helpString() et helpUrl(), méthodes de la classe QgsProcessingAlgorithm.
23.9.7. 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.
23.9.8. 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 uneQgsProcessingException.
Il existe déjà de nombreux algorithmes de traitement disponibles dans QGIS. Vous pouvez trouver du code sur https://github.com/qgis/QGIS/blob/release-3_16/python/plugins/processing/algs/qgis.