.
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.
There is not a proccesing console in QGIS, but all processing commands are available instead from the QGIS built-in Python console. That means that you can incorporate those commands into your console work and connect processing algorithms to all the other features (including methods from the QGIS API) available from there.
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.
In this section, we will see how to use processing algorithms from the QGIS Python console, and also how to write algorithms using 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 :
Raster Layer, Vector Layer or Table. Simply use a string with the name that identifies the data object to use (the name it has in the QGIS Table of Contents) or a filename (if the corresponding layer is not opened, it will be opened but not added to the map canvas). If you have an instance of a QGIS object representing the layer, you can also pass it as parameter. If the input is optional and you do not want to use any data object, use 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.
Unlike when an algorithm is executed from the toolbox, outputs are not added to the map canvas if you execute that same algorithm from the Python console. If you want to add an output to the map canvas, you have to do it yourself after running the algorithm. To do so, you can use QGIS API commands, or, even easier, use one of the handy methods provided for such tasks.
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().
Apart from the functions used to call algorithms, importing the processing package will also import some additional functions that make it easier to work with data, particularly vector data. They are just convenience functions that wrap some functionality from the QGIS API, usually with a less complex syntax. These functions should be used when developing new algorithms, as they make it easier to operate with input data.
Below is a list of some of these commands. More information can be found in the classes under the processing/tools package, and also in the example scripts provided with 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.
Layers and table values are strings containing the file path 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 file paths to all selected object, separated by semicolons (;).
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éé.
When you declare an output, the algorithm will try to add it to QGIS once it is finished. That is why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded (using the case of our previous example), 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
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.