Important

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

23.7. Utiliser les algorithmes du module de traitements depuis la console Python

La console permet aux utilisateurs confirmés d’accroître leur productivité en réalisant des opérations complexes qui ne pourraient pas être réalisées à partir de l’interface graphique du module de Traitements. Les modèles impliquant plusieurs algorithmes peuvent être définis à partir de l’interface en lignes de commandes et des opérations additionnelles comme les boucles ou les opérations conditionnelles permettent de créer des flux de traitements plus puissants et plus flexibles.

Il n’y a pas de console spécifique au module de traitements de QGIS mais toutes les commandes du module sont disponibles via la console Python de QGIS. Cela signifie que vous pouvez intégrer ces commandes dans votre travail et les connecter aux autres fonctions accessibles depuis la console (dont les méthodes issues de l’API QGIS).

Le code exécuté à partir de la console Python, même s’il n’utilise pas de méthodes de traitements particulières, peut être converti en un nouvel algorithme pour être réutilisé dans la boîte à outils, le modeleur ou dans un autre flux de traitements, comme tout autre algorithme. Ainsi certains algorithmes que vous pouvez trouver dans la boîte à outils sont en fait de simples scripts.

Dans cette section, nous allons voir comme utiliser des algorithmes issus du module de Traitements à partir de la console Python de QGIS et également comment écrire des algorithmes en Python.

23.7.1. Appeler des algorithmes depuis la console Python

La première chose à faire est d’importer les fonctions de traitement à l’aide de l’instruction suivante:

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

Vous obtiendrez quelque chose de ce genre (avec quelques tirets en plus pour la lisibilité).

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

Il s’agit là de la liste des identifiants de tous les algorithmes disponibles, triés par le nom du fournisseur puis l’ID de l’algorithme, accompagnés du nom littéral de l’algorithme.

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.

En appelant la méthode avec native: buffer comme paramètre ( qgis: buffer est un alias pour native: buffer et fonctionnera également), vous obtenez la description suivante :

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

Lorsqu’un paramètre est facultatif et que vous ne souhaitez pas l’utiliser, ne l’incluez pas dans le dictionnaire.

Lorsqu’un paramètre n’est pas indiqué, sa valeur par défaut est appliquée.

Selon le type de paramètre, les valeurs peuvent être fournies selon plusieurs manières. Une rapide description de ces possibilités est donnée pour chaque type de paramètre d’entrée :

  • Les couches raster, vecteur ou les tables. Indiquez simplement le nom identifiant la donnée (le nom dans la liste de couches de QGIS) ou un nom de fichier (si la couche n’a pas encore été ouverte, elle sera chargée mais pas ajoutée au canevas). Si vous avez une instance d’un objet QGIS représentant une couche, vous pouvez également la transmettre en paramètre.

  • 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

    Dans ce cas, le paramètre a trois options. Notez que la commande est basée sur zéro.

  • Boolean. Use True or False.

  • Entrées multiples. La valeur est une chaîne de caractères, avec les entrées séparées par des points-virgules (;). Comme pour les couches simples et les tables, chaque élément d’entrée peut être le nom d’une variable objet ou un nom de fichier.

  • Champ de la table XXX. Insérez une chaîne de caractères contenant le nom du champ à utiliser. Ce paramètre est sensible à la casse.

  • Table fixe. Entrez la liste de toutes les valeurs, séparées par des virgules (,) et entre guillemets ("). Les valeurs commencent par la première ligne et se lisent de gauche à droite. Vous pouvez aussi utiliser un tableau à deux dimensions pour représenter la table.

  • SCR. Entrez le code EPSG du système de coordonnées désiré.

  • Étendue. Vous devez fournir une chaîne de caractères avec les valeurs xmin, xmax, ymin et ymax séparées par des virgules (,).

Booléen, fichier, chaîne de caractères et valeurs numériques ne nécessitent pas d’explications particulières.

Les paramètres d’entrée tels que les chaînes, les booléens ou les valeurs numériques ont des valeurs par défaut. La valeur par défaut est utilisée si l’entrée de paramètre correspondante est manquante.

Pour les objets de données en sortie, saisissez le chemin d’accès au fichier à utiliser pour l’enregistrer, comme cela se fait à partir de la boîte à outils. Si l’objet de sortie n’est pas spécifié, le résultat est enregistré dans un fichier temporaire (ou ignoré s’il s’agit d’une sortie facultative). L’extension du fichier détermine le format du fichier. Si vous entrez une extension de fichier non prise en charge par l’algorithme, le format de fichier par défaut pour ce type de sortie sera utilisé et son extension correspondante ajoutée au chemin du fichier donné.

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

Vous pouvez ensuite charger la sortie dans le projet, comme pour toute autre couche :

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. Créer des scripts et les exécuter depuis la boîte à outils

Vous pouvez créer vos propres algorithmes en écrivant du code Python. Les scripts de traitement étendent QgsProcessingAlgorithm, vous devez donc ajouter des lignes de code supplémentaires pour implémenter les fonctions obligatoires. Vous pouvez trouver Créer un nouveau script (feuille blanche) et Créer un nouveau script à partir d’un modèle (modèle qui inclut le code pour les fonctions obligatoires de QgsProcessingAlgorithm) sous le menu déroulant Scripts en haut de la boîte à outils Traitement. L’éditeur de script de traitement s’ouvre et c’est là que vous devez taper votre code. L’enregistrement du script à partir de là dans le dossier scripts (le dossier par défaut lorsque vous ouvrez la boîte de dialogue d’enregistrement du fichier) avec une extension .py devrait créer l’algorithme correspondant.

Le nom de l’algorithme (celui que vous verrez dans la boîte à outils) est défini dans le code.

Jetons un coup d’œil au code suivant, qui définit un algorithme de traitement qui effectue une opération de tampon avec une distance de tampon définie par l’utilisateur sur une couche vecteur spécifiée par l’utilisateur, après avoir d’abord lissée la couche.

 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}

Après avoir effectué les importations nécessaires, les fonctions suivantes QgsProcessingAlgorithm sont spécifiées:

  • name() : L’id de l’algorithme (en minuscules).

  • displayName() : Un nom lisible par l’homme pour l’algorithme.

  • createInstance() : Pour créer une nouvelle instance de la classe d’algorithme.

  • initAlgorithm() : Configurer parameterDefinitions et outputDefinitions.

    Ici, vous décrivez les paramètres et la sortie de l’algorithme. Dans ce cas, une source d’entités pour l’entrée, un récepteur d’entités pour le résultat et un nombre pour la distance du tampon.

  • processAlgorithm() : Déclencher l’algorithme.

    Ici, nous exécutons d’abord l’algorithme smoothgeometry pour lisser la géométrie, puis nous exécutons l’algorithme buffer sur la sortie lissée. Pour pouvoir exécuter des algorithmes à partir d’un autre algorithme, nous devons définir le paramètre is_child_algorithm à True. Vous pouvez voir comment les paramètres d’entrée et de sortie sont utilisés comme paramètres pour les algorithmes de smoothgeometry et de buffer.

Plusieurs types de paramètres différents sont disponibles pour l’entrée et la sortie. Vous en trouverez une liste complète à Types d’entrée et de sortie pour les algorithmes de traitement.

Le premier paramètre pour les constructeurs est le nom du paramètre et le second est la description du paramètre (pour l’interface utilisateur). Les autres paramètres du constructeur sont spécifiques au type de paramètre.

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.

Des algorithmes bien comportés devraient définir et renvoyer autant de sorties que cela a du sens. Les sorties sans entité, telles que les nombres et les chaînes, sont très utiles lors de l’exécution de votre algorithme dans le cadre d’un modèle plus large, car ces valeurs peuvent être utilisées comme paramètres d’entrée pour les algorithmes suivants au sein du modèle. Pensez à ajouter des sorties numériques pour des choses comme le nombre d’entités traitées, le nombre d’entités non valides rencontrées, le nombre de sorties d’entités, etc. Plus vous renvoyez de sorties, plus votre algorithme devient utile!

23.7.2.1. Retour d’informations

L’objet feedback() passé à processAlgorithm() doit être utilisé pour les commentaires / interactions des utilisateurs. Vous pouvez utiliser la fonction setProgress de l’objet feedback pour mettre à jour la barre de progression (0 à 100) pour informer l’utilisateur sur la progression de l’algorithme. Ceci est très utile si votre algorithme prend beaucoup de temps.

L’objet feedback() fournit une méthode isCanceled() qui doit être surveillée pour permettre l’annulation de l’algorithme par l’utilisateur. La méthode pushInfo() de feedback() peut être utilisée pour envoyer des informations à l’utilisateur et reportError() est pratique pour transmettre des erreurs non fatales aux utilisateurs.

Les algorithmes doivent éviter d’utiliser d’autres formes de rétroaction pour les utilisateurs, telles que des instructions d’impression ou la journalisation de QgsMessageLog, et doivent toujours utiliser à la place l’objet de rétroaction. Cela permet une journalisation détaillée de l’algorithme et est également compatible avec les threads (ce qui est important, étant donné que les algorithmes sont généralement exécutés dans un thread d’arrière-plan).

23.7.2.2. Gestion des erreurs

Si votre algorithme rencontre une erreur qui l’empêche de s’exécuter, telle que des valeurs d’entrée non valides ou une autre condition à partir de laquelle il ne peut pas ou ne doit pas récupérer, alors vous devez déclencher une QgsProcessingException. Par exemple.:

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

Essayez d’éviter de déclencher QgsProcessingException pour les erreurs non fatales (par exemple lorsqu’une entité a une géométrie nulle), et au lieu de cela, signalez simplement ces erreurs via feedback.reportError() et ignorez l’entité. Cela permet de rendre votre algorithme «convivial pour le modèle», car il évite d’arrêter l’exécution d’un algorithme entier lorsqu’une erreur non fatale est rencontrée.

23.7.2.3. Documenter ses scripts

Comme dans le cas des modèles, vous pouvez créer une documentation supplémentaire pour vos scripts, pour expliquer ce qu’ils font et comment les utiliser.

La classe QgsProcessingAlgorithm() fournit les métodes helpString(), shortHelpString() et helpUrl() à cet effet. Spécifiez / remplacez-les pour fournir plus d’aide à l’utilisateur.

shortDescription() est utilisé dans l’info-bulle lors du survol de l’algorithme dans la boîte à outils.

23.7.3. Scripts de pré et post-exécution

Les scripts peuvent également être utilisés comme accrochage avant et après l’exécution et seront exécutés, respectivement, avant et après l’exécution d’un algorithme. Cela peut être utilisé pour automatiser les tâches qui doivent être effectuées chaque fois qu’un algorithme est exécuté.

La syntaxe est identique à celle qui est expliquée plus haut mais une variable globale nommée alg est disponible. Elle représente l’objet algorithme qui vient (ou qui va) être lancé.

Dans le groupe Général de la boîte de dialogue des options de traitement, vous trouverez deux entrées nommées Script de pré-exécution et Script de post-exécution où les noms de fichiers des scripts à exécuter chaque cas peut être saisi.