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

Le nom de l’algorithme (celui qui apparaît dans la boîte à outils) est généré à partir du nom de fichier, en enlevant son extension et en remplaçant les underscores (‘_’) par des espaces.

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)

Comme vous pouvez le voir, il utilise 3 algorithmes, provenant de SAGA. Le dernier calcule le TWI, mais nécessite de une couche représentant la pente et une autre d’accumulation des flux. Dans la mesure où ces deux couches n’existent pas mais que nous disposons d’un MNT, nous allons les calculer en faisant appel aux algorithmes SAGA adéquats.

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]

Voici la liste des types de paramètres gérés par les scripts de traitement, leur syntaxe ainsi que quelques exemples.

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

• extent. Une emprise spatiale définie par xmin, xmax, ymin, ymax

• folder. Un répertoire

• file. Un nom de fichier

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

• selection. Un menu . Par exemple``unités=selection sq_km;sq_miles;sq_degrees``

• name. Le nom du script. Il s’affichera dans la Boîte à outils de traitements. Par exemple Nom de mon Algorithme=name

• group. Nom du groupe dans lequel le script apparaîtra dans la boîte à outils de traitements. Par exemple, en ajoutant``Outils=groups`` ajoutera le script dans le groupe Outils des Scripts.

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.

A l’affichage du nom de paramètre, les underscores (‘_’) sont convertis en espaces pour améliorer la lisibilité. Ainsi, par exemple, si vous souhaitez que l’utilisateur saisisse une valeur appelée ‘Valeur numérique’, vous devez utiliser une variable nommée Valeur_numérique.

Les valeurs de couches et de tables sont des chaînes de caractères contenant le chemin du fichier de l’objet correspondant. Pour les transformer en objets QGIS, vous pouvez utiliser la fonction processing.getObjectFromUri(). Les entrées multiples ont également une valeur de chaîne qui contient les chemins des fichiers des objets sélectionnés, séparés par des points-virgules (;).

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¶

Lorsque vous définissez une sortie de type couche (raster, vecteur ou table), l’algorithme tentera de l’ajouter à QGIS à l’issue de son exécution. C’est la raison pour laquelle la couche résultat TWI, nommée explicitement par l’utilisateur, sera chargée, même si la méthode runalg() ne le fait pas.

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¶

Comme pour les modèles, vous pouvez ajouter des commentaires à votre script, pour expliciter le traitement effectué et son utilisation. Dans la fenêtre d’édition du script se situe un bouton [Editer l’aide], qui vous amènera à la fenêtre d’édition de l’aide. Veuillez vous reporter au chapitre Modeleur graphique pour plus d’information sur cette fenêtre.

Les fichiers d’aide sont sauvegardés dans le même répertoire que les scripts, avec l’extension .help.Veuillez noter qu’à la première édition de l’aide, la fermeture de la fenêtre ne sauvegarde pas vos modifications. Par contre, si le fichier a déjà été sauvegardé une fois préalablement, les modifications seront conservées.

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.

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.