Outdated version of the documentation. Find the latest one here.

Utiliser SEXTANTE depuis la console

Introduction

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 de SEXTANTE. 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 propre à SEXTANTE dans QGIS, mais toutes les commandes SEXTANTE sont disponibles à partir de la console Python de QGIS. Cela signifie que vous pouvez intégrer ces commandes dans vos développements et y relier les algorithmes SEXTANTE aux autres fonctionnalités de QGIS (voir l’API QGIS).

Le code exécuté à partir de la console Python, même utilsant des méthodes SEXTANTE, peut être converti en algorithme SEXTANTE pour être réutilisé dans la boîte à outils, le modeleur ou dans un autre flux de traitements, comme tout autre élément SEXTANTE. Ainsi certains algorithmes que vous pouvez trouver dans la boîte à outils, comme ceux du groupe mmqgis sont en fait de simples scripts.

Dans ces chapitre, nous allons voir comme utiliser SEXTANTE à partir de la console Python de QGIS et également comment écrire vos propres algorithmes en Python.

Appeler SEXTANTE depuis la console Python

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

>>> import sextante

A présent, la seule instruction (intéressante) à faire est d’exécuter un algorithme SEXTANTE. 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écessaire à 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, tapez alglist() dans la console:

>>> sextante.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 lal iste complète des algorithmes, elle filtrera les résultats selon la chaîne fournies. Par exemple, si vous recherchez un algorithme premettant 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(). SEXTANTE comprend une méthode destinée à décrire en détail un algorithme, qui 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). Veuillez à 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.

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

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

    >>> sextante.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 7 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 quotes. Les valeurs commencent en haut à gauche et se lisent en ligne. 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 caratè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.

Contrairement à la boîte à outils, les résultats d’un algorithme exécuté à partir de la console ne sont ajoutés au canevas de cartes. Pour les ajouter, il vous faudra le faire manuellement après l’exécution de l’algorithme. Vous pouvez utiliser pour cela les commandes de l’API QGIS ou plus simplement une des méthodes proposées par SEXTANTE.

La méthode runalg() renvoie une structure dictionnaire avec les clés (correspondant à la description des éléments de l’algorithme) et pour valeurs les chemins des résultats. Pour ajouter tous les résultats de l’algorithme au canevas, passez le dictionnaire renvoyé à la méthode loadFromAlg(). Vous pouvez également charger les couches individuellement en passant leur nom de fichier à la méthode load().

Créer des scripts et les exécuter depuis la boîte à outils

Vous pouvez créer vos propres algorithmes codés en Python et ajouter quelques lignes d’information pour que SEXTANTE les reconnaisse. L’outil Créer un nouveau script dans le group Outils de la boite à outils permet de vous y aider. Double-cliquez pour ouvrir un éditeur de script dans lequel mettre votre code. La sauvegarde du script s’effectuera dans le répertoire !file:scripts (le répertoire par défaut à l’ouverture de la fenêtre) avec une extension .py, et correspondra automatiquement à votre algorithme.

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 permettante de calculer l’Indice d’Humidité Topographique (Topographic Wetness Index, TWI) directement à partir d’un MNT

##dem=raster
##twi=output
ret_slope = sextante.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = sextante.runalg("saga:catchmentarea(mass-fluxmethod)", dem,
                0, False, False, False, False, None, None, None, None, None)
sextante.runalg("saga:topographicwetnessindex(twi), 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 pour la permeéabilité des sols. Dans la mesure où ces dexu 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 à SEXTANTE les informations nécessaires pour convertir votre code en un algorithme utilisables à partir d’autres contextes, comme la boîte à outils ou le modeleur graphique.

Ces lignes débutent par deux sympboles de commentaire Python et présentent la structure suivante:

[parameter_name]=[parameter_type] [optional_values]

Voici la liste des types de paramètres que SEXTANTE reconnaît, leurs syntaxes 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, SEXTANTE convertit les underscores (‘_’) en espaces. 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 variables Couches et Tables ont des chaînes de caractères contenant le chemin complet de l’objet correspondant. Pour les convertir en objet QGIS, utilisez la fonction sextante.getObjectFromUri(). Les entrées multiplessont également des chaînes de caractères, contenant les chemins des objets, 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

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, SEXTANTE tentera de l’ajouter à QGIS à l’issue de l’exécution de l’algorithme. 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 âs à 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.

Il est conseillé d’informer l’utilisateur de l’avancée du traitement de l’algorithme. Vous disposez de la variable globale progress, aevc deux méthodes, setText(text) et setPercentage(percent) pour modifier le message et la barre de progression.

Plusieurs exemples sont fournis avec SEXTANTE. Veuillez vous y reporter pour servir d’exemples.. Cliquez avec le bouton droit sur un script et choisissez Editer le script pour voir et éditer le code correspondant.

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