.
La console permet aux utilisateurs confirmés d’accroître leur productivité en réalisant des opérations complexes qui ne pourraient par ê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 branchements conditionnels 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 nouveau 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.
La première chose à faire est d’importer les fonctions de traitement à l’aide de l’instruction suivante:
>>> import processing
A présent, la seule instruction (intéressante) à faire est d’exécuter un algorithme. Cela est effectué en utilisant la méthode runalg(), qui prend en premier paramètre le nom de l’algorithme à lancer, puis tous les paramètres nécessaires à son exécution. Vous devez donc connaître le nom de commande de l’algorithme, qui peut être différent de celui affiché dans la boîte à outils. Pour le trouver, utilisez alglist() dans la console et tapez :
>>> processing.alglist()
Vous devriez avoir quelque chose qui ressemble à ceci.
Accumulated Cost (Anisotropic)---------------->saga:accumulatedcost(anisotropic)
Accumulated Cost (Isotropic)------------------>saga:accumulatedcost(isotropic)
Add Coordinates to points--------------------->saga:addcoordinatestopoints
Add Grid Values to Points--------------------->saga:addgridvaluestopoints
Add Grid Values to Shapes--------------------->saga:addgridvaluestoshapes
Add Polygon Attributes to Points-------------->saga:addpolygonattributestopoints
Aggregate------------------------------------->saga:aggregate
Aggregate Point Observations------------------>saga:aggregatepointobservations
Aggregation Index----------------------------->saga:aggregationindex
Analytical Hierarchy Process------------------>saga:analyticalhierarchyprocess
Analytical Hillshading------------------------>saga:analyticalhillshading
Average With Mask 1--------------------------->saga:averagewithmask1
Average With Mask 2--------------------------->saga:averagewithmask2
Average With Thereshold 1--------------------->saga:averagewiththereshold1
Average With Thereshold 2--------------------->saga:averagewiththereshold2
Average With Thereshold 3--------------------->saga:averagewiththereshold3
B-Spline Approximation------------------------>saga:b-splineapproximation
...
Il s’agit de la liste des algorithmes disponibles, par ordre alphabétique, accompagnés des noms de commande.
Vous pouvez également passer une chaine de caractères en paramètre de cette méthode. Au lieu de retourner la liste complète des algorithmes, elle filtrera les résultats selon la chaîne fournies. Par exemple, si vous recherchez un algorithme permettant de calculer la pente d’un MNT, l’instruction alglist("slope") donnera le résultat suivant :
DTM Filter (slope-based)---------------------->saga:dtmfilter(slope-based)
Downslope Distance Gradient------------------->saga:downslopedistancegradient
Relative Heights and Slope Positions---------->saga:relativeheightsandslopepositions
Slope Length---------------------------------->saga:slopelength
Slope, Aspect, Curvature---------------------->saga:slopeaspectcurvature
Upslope Area---------------------------------->saga:upslopearea
Vegetation Index[slope based]----------------->saga:vegetationindex[slopebased]
Ce résultat peut différer d’un système à l’autre selon les algorithmes disponibles.
Il est ainsi facile de trouver l’algorithme recherché et son nom de commande, ici saga:slopeaspectcurvature.
Une fois trouvé le nom de commande de l’algorithme, il s’agit de connaître la bonne syntaxe pour l’exécuter. Cela comprend la liste et l’ordre des paramètres à fournir à l’appel de la méthode runalg(). Une méthode est destinée à décrire en détail un algorithme et renvoie la liste des paramètres nécessaires et le type de sorties générées : il s’agit de la méthode alghelp(nom_de_l_algorithme). Veillez à bien utiliser le nom de commande et non le nom descriptif.
L’appel à la méthode avec le paramètre saga:slopeaspectcurvature donnera la description suivante :
>>> processing.alghelp("saga:slopeaspectcurvature")
ALGORITHM: Slope, Aspect, Curvature
ELEVATION <ParameterRaster>
METHOD <ParameterSelection>
SLOPE <OutputRaster>
ASPECT <OutputRaster>
CURV <OutputRaster>
HCURV <OutputRaster>
VCURV <OutputRaster>
Vous avez à présent tout ce qu’il faut pour exécute n’importe quel algorithme. Comme indiqué précédemment, l’instruction runalg() suffit pour exécuter un algorithme. Sa syntaxe est la suivante:
>>> processing.runalg(name_of_the_algorithm, param1, param2, ..., paramN,
Output1, Output2, ..., OutputN)
La liste des paramètres et des sorties à fournir dépend de l’algorithme à exécuter et correspond au résultat, dans l’ordre donné, de la méthode alghelp().
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, vectorielles 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. Si l’entrée est optionnelle et que vous ne souhaitez pas fournir de données particulières, utilisez la valeur None.
Sélection. Si un algorithme possède un paramètre sélection, cette valeur doit être une valeur entière. Pour connaître les options possibles, vous pouvez utilisez la commande algoptions(), comme dans l’exemple suivant :
>>> processing.algoptions("saga:slopeaspectcurvature")
METHOD(Method)
0 - [0] Maximum Slope (Travis et al. 1975)
1 - [1] Maximum Triangle Slope (Tarboton 1997)
2 - [2] Least Squares Fitted Plane (Horn 1981, Costa-Cabral & Burgess 1996)
3 - [3] Fit 2.Degree Polynom (Bauer, Rohdenburg, Bork 1985)
4 - [4] Fit 2.Degree Polynom (Heerdegen & Beran 1982)
5 - [5] Fit 2.Degree Polynom (Zevenbergen & Thorne 1987)
6 - [6] Fit 3.Degree Polynom (Haralick 1983)
Dans l’exemple, l’algorithme présente ces types de paramètres, avec sept options. Notez que le premier élément a pour numéro 0.
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ère contenant le nom du champ à utiliser. Ce paramètre est sensible à la casse.
Table fixée. 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.
Pour spécifier les valeurs par défaut des paramètres tels que chaînes de caractères, booléens ou valeurs numériques, entrez None dans l’entrée correspondante.
Pour les données en sortie, entrez le chemin à utiliser, comme dans la boîte à outils. Si vous préférez sauvegarder le résultat dans un fichier temporaire, indiquez None. L’extension du fichier déterminera le format de fichier utilisé. Si elle n’est pas reconnue par l’algorithme, le format de fichier par défaut sera utilisé et l’extension sera ajouté à la fin du nom de fichier.
À la différence des algorithmes exécutés depuis la boîte à outils, les sorties ne sont pas ajoutées automatiquement au canevas de la carte s’ils sont exécutés depuis la console Python. Si vous souhaitez ajouter une couche à la carte, vous devez le faire vous même après avoir exécuté l’algorithme. Pour ce faire, vous pouvez utiliser les commandes de l’API QGIS ou, encore plus simple, utiliser une des méthodes fournies pour ce genre de tache.
La méthode runalg renvoie un dictionnaire Python avec pour clés les noms des sorties (correspondant à la description des éléments de l’algorithme) et pour valeurs les chemins des résultats. Vous pouvez charger ces couches de résultat en passant les chemins correspondants à la méthode load().
En plus des fonctions utilisées pour appeler les algorithmes, importer le module processing permet d’importer des fonctions additionnelles qui facilitent le travail avec les données et plus particulièrement avec les données vecteur. Il s’agit juste de commodités qui font appel à des fonctions de l’API QGIS, en utilisant en général une syntaxe moins complexe. Il est conseillé d’utiliser ces fonctions lors du développement de nouveaux algorithmes car elle facilitent grandement la manipulation des données.
Voici, ci-dessous, certaines de ces commandes. Plus d’information peut être trouvée dans les classes du paquet processing/tools et dans les scripts d’exemples fournis avec QGIS.
getObject(obj) : Renvoie un objet QGIS (une couche ou une table) issu de l’objet passé en paramètre, qui peut correspondre à un nom de fichier ou un nom d’objet dans le panneau Couches de QGIS.
values(couche, champs) : Renvoie les valeurs de la table d’attributs de la couche vecteur pour le champ passé en paramètre. Les champs peuvent être passés en tant que noms de champ ou index du champ dans la table, en commençant par zero. Renvoie un dictionnaire de listes, dont les clés correspondent à la liste des champs passée en paramètre. La sélection existante est prise en compte.
features(couche) : Renvoie un itérateur sur les entités d’une couche vecteur, prenant en compte la sélection existante.
uniqueValues(couche, champ) : Renvoie la liste des valeurs uniques trouvées dans un champ. Le champ peut être passé en paramètre en tant que nom ou index dans la table, en commençant par zéro. La sélection existante est prise en compte.
Vous pouvez créer vos propres algorithmes en écrivant le code Python correspondant et en ajoutant quelques lignes fournissant les informations nécessaires pour le faire fonctionner. Vous trouverez le menu Créer un nouveau script dans le groupe 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 d’ici 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 d’Humidité Topographique (Topographic Wetness Index, TWI) directement à partir d’un MNT.
##dem=raster
##twi=output
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea(mass-fluxmethod)", dem,
0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindex(twi), ret_slope['SLOPE'],
ret_area['AREA'], None, 1, 0, twi)
Comme vous pouvez le voir, le calcul utilise trois 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, comme la boîte à outils ou le modeleur graphique.
Ces lignes débutent par deux symboles de commentaire Python (##) et présentent 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. Une table.
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ère. Comme pour les valeurs numériques, une valeur par défaut doit être définie. Par exemple, name=string Victor.
boolean. Une valeur booléenne. Ajoutez True (Vrai) ou False (Faux) pour définir la valeur par défaut. Par exemple, verbose=boolean True pour plus un rendu plus parlant.
multiple raster. Un ensemble de couches raster en entrée.
multiple vector. Un ensemble de couches vectorielles en entrée.
field. Un champ dans 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=champ1 macouche pour ajouter en paramètre le champ de cette couche.
folder. Un répertoire.
file. Un nom de fichier.
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 table 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:
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éé.
Si un résultat est défini, 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
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.
Si votre algorithme est long, 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.
Plusieurs exemples sont fournis. Veuillez vous y reporter pour servir d’exemples. Cliquez avec le bouton droit sur un script et choisissez Éditer le script pour voir et éditer le code correspondant.
Comme pour les modèles, vous pouvez ajouter des commentaires à vos scripts, 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 à la section 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.
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 alogrithme qui vient (ou qui va) être lancé.
Dans le groupe Général de la boîte de dialogue de configuration des géo-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.