Écrire de nouveaux algorithmes sous la forme de scripts python

Vous pouvez créer vos propres algorithmes en écrivant le code Python correspondant et en ajoutant quelques lignes supplémentaires nécessaires à la définition de la sémantique de l’algorithme. Vous pouvez trouver un Créer un nouveau script sous le menu Outils du bloc Script de la boîte à outils. Double-cliquez dessus pour ouvrir la fenêtre d’édition de script. C’est ici que vous pouvez écrire votre code. En sauvegardant votre script dans le répertoire des scripts (le répertoire par défaut qui s’affiche quand vous ouvrez la fenêtre de sauvegarde) avec l’extension .py, vous créez automatiquement l’algorithme correspondant.

The name of the algorithm (the one you will see in the toolbox) is created from the filename, removing its extension and replacing low hyphens with blank spaces.

Voici par exemple le code permettant de calculer l’Indice Topographique d’Humidité (Topographic Wetness Index, TWI) directement à partir d’un MNE

##dem=raster
##twi=output raster
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea", dem,
                0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindextwi, ret_slope['SLOPE'],
                ret_area['AREA'], None, 1, 0, twi)

As you can see, it involves 3 algorithms, all of them coming from SAGA. The last one of them calculates the TWI, but it needs a slope layer and a flow accumulation layer. We do not have these ones, but since we have the DEM, we can calculate them calling the corresponding SAGA algorithms.

Le bout de code où le traitement est effectué n’est pas compliqué à comprendre si vous avez lu les sections précédentes. Cependant, les premières lignes nécessitent quelques explications. Elles fournissent les informations nécessaires pour convertir votre code en un algorithme utilisable à partir d’autres contextes de l’interface graphique, comme la boîte à outils ou le modeleur graphique.

Ces lignes commencent par deux symboles de commentaires Python (##) et ont la structure suivante :

[parameter_name]=[parameter_type] [optional_values]

Here is a list of all the parameter types that are supported in processign scripts, their syntax and some examples.

  • raster. Une couche raster

  • vector. Une couche vectorielle

  • table. Un tableau

  • number. Une valeur numérique. Une valeur par défaut doit être définie. Par exemple, depth=number 2.4

  • string. Une chaîne de caractères. Comme pour les valeurs numériques, une valeur pas défaut doit être ajoutée. Par exemple, name=string Victor

  • longstring. Comme pour la chaîne de caractères, mais ici une plus large zone de texte sera affichée, ce qui est mieux adaptée pour les longues chaînes de texte, comme pour un script attendant un petit extrait de code.

  • boolean. Une valeur booléenne. Ajoutez True ou False après avoir défini une valeur par défaut. Par exemple, verbose=boolean True.

  • multiple raster. Une série de couches raster.

  • multiple vector. Un ensemble de couches vectorielles.

  • field. Un champ de la table d’attributs d’une couche vectorielle. Le nom de la couche doit être ajoutée après l’étiquette field. Par exemple, si vous déclarez une couche vectorielle macouche=vector en entrée, vous pouvez utilisez monchamp=field macouche pour ajouter en paramètre le champ de cette couche.

  • folder. Un répertoire

  • file. Un nom de fichier

  • crs. Système de coordonnées de référence

Le nom du paramètre correspond à ce qui sera affiché lorsque l’utilisateur exécutera l’algorithme, ainsi qu’au nom de variable à utiliser dans le script. La valeur saisie par l’utilisateur pour ce paramètre sera assignée à cette variable, portant ce nom.

When showing the name of the parameter to the user, the name will be edited it to improve its appearance, replacing low hyphens with spaces. So, for instance, if you want the user to see a parameter named A numerical value, you can use the variable name A_numerical_value.

Layers and tables values are strings containing the filepath of the corresponding object. To turn them into a QGIS object, you can use the processing.getObjectFromUri() function. Multiple inputs also have a string value, which contains the filepaths to all selected objects, separated by semicolons (;).

Les sorties sont définies de la même manière, avec les étiquettes suivantes :

  • output raster
  • output vector
  • output table
  • output html
  • output file
  • output number
  • output string
  • output extent

La valeur attribuée à une variable de sortie est toujours une chaîne de caractères contenant le chemin de l’objet. Si le nom est vide, un fichier temporaire sera créé.

En complément des étiquettes définissant les paramètres et les sorties, vous pouvez définir la catégorie dans laquelle l’algorithme apparaîtra, en utilisant l’étiquette group.

La dernière étiquette que vous pouvez utiliser dans votre en-tête de script est ##nomodeler. L’utiliser indique que vous ne voulez pas que votre algorithme soit affiché dans la fenêtre du modeleur. Elle doit être utilisée pour les algorithmes qui n’ont pas une syntaxe claire (par exemple su le nombre de couches à créer n’est pas connu à l’avance au moment de la modélisation), ce qui les rend non disponibles dans le modeleur graphique.

Gérer les données produites par l’algorithme

When you declare an output representing a layer (raster, vector or table), the algorithm will try to add it to QGIS once it is finished. That is the reason why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded, since it is saved to the file entered by the user, which is the value of the corresponding output.

N’utilisez donc pas la méthode load() dans vos scripts, mais uniquement à partir de la console. Si un algorithme définit une couche en sortie, celle-ci doit être déclarée ainsi. Dans le cas contraire, vous ne pourriez pas l’utiliser dans le modeleur parce que sa syntaxe (comme définie par ses étiquettes, exposées précédemment) ne correspond pas à ce que l’algorithme crée effectivement.

Les sorties masquées (nombres ou chaînes) n’ont pas de valeur. C’est à vous de leur assigner une valeur. Pour cela, affecter une valeur à la variable pour la déclarer en sortie. Par exemple, vous pourriez utiliser la déclaration suivante,

##average=output number

l’instruction suivante fixe la valeur de sortie à 5:

average = 5

Communiquer avec l’utilisateur

Si votre algorithme requiert un temps assez long de calcul, il est conseillé d’informer l’utilisateur de l’avancée du traitement de l’algorithme. Vous disposez de la variable globale progress, avec deux méthodes, setText(text) et setPercentage(percent) pour modifier le message et la barre de progression.

Si vous devez fournir de l’information à l’utilisateur sans rapport avec la progression de l’algorithme, vous pouvez utiliser la méthode setInfo(text) de l’objet progress.

Si votre script rencontre des problèmes, le moyen correct de propager l’erreur est de lever une exception de type GeoAlgorithmExecutionException(). Vous pouvez y passer un message comme argument dans le constructeur de l’exception. Les Traitements tiennent compte de cette exception et communiquent avec l’utilisateur en fonction de l’endroit où l’algorithme a été exécuté (boîte à outils, modeleur, console Python, etc.).

Documenter ses scripts

As in the case of models, you can create additional documentation for your script, to explain what they do and how to use them. In the script editing dialog you will find a [Edit script help] button. Click on it and it will take you to the help editing dialog. Check the chapter about the graphical modeler to know more about this dialog and how to use it.

Help files are saved in the same folder as the script itself, adding the .help extension to the filename. Notice that you can edit your script’s help before saving it for the first time. If you later close the script editing dialog without saving the script (i.e. you discard it), the help content you wrote will be lost. If your script was already saved and is associated to a filename, saving is done automatically.

Exemples de scripts:

Plusieurs exemples sont disponibles sur la collection de scripts en ligne dont vous pouvez avoir accès en sélectionnant l’outil Récupérer un script de la collection de scripts en ligne dans l’entrée Scripts/outils de la boîte à outils.

../../../_images/script_online.png

Veuillez vous y reporter pour visualiser des exemples réels de création d’algorithmes avec les classes de l’API des Traitements. Cliquez avec le bouton droit sur un script et choisissez Éditer le script pour voir et éditer le code correspondant.

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 des algorithmes que vous avez créés. Évitez de déclarer une sortie et d’utiliser le nom de fichier de destination de cette sortie comme un emplacement de collection de fichiers. Cela brise la syntaxe correcte des algorithmes et empêche un fonctionnement correct dans le modeleur. Si vous devez écrire un tel algorithme, assurez-vous d’utiliser l’étiquette ##nomodeler.

  • N’affichez pas de boîte à messages ou n’utilisez pas d’éléments graphiques depuis le script. Si vous voulez communiquer avec l’utilisateur, utilisez la méthode setInfo() ou lancez une exception GeoAlgorithmExecutionException.

  • La règle d’or consiste à ne pas oublier que votre algorithme peut être exécuté dans un contexte différent de la boîte à outils des Traitements.

Scripts de pré et post-exécution

Des scripts peuvent également être utilisés en amont et en aval de l’exécution d’un algorithme. Ce mécanisme peut être utilisé pour automatiser des tâches qui doivent être lancé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 de configuration des traitements, vous trouverez deux entrées nommées Script de pré-exécution et Script de post-exécution où les noms des scripts à lancer dans chacun des cas peuvent être saisis.