` `

Configuration des applications tierces

The processing framework can be extended using additional applications. Currently, SAGA, GRASS, OTB (Orfeo Toolbox) and R are supported, along with some other command-line applications that provide spatial data analysis functionalities. Algorithms relying on an external applications are managed by their own algorithm provider.

This section will show you how to configure the processing framework to include these additional applications, and it will explain some particular features of the algorithms based on them. Once you have correctly configured the system, you will be able to execute external algorithms from any component like the toolbox or the graphical modeler, just like you do with any other geoalgorithm.

Par défaut, tous les algorithmes qui reposent sur une application tierce non fournie avec QGIS sont désactivés. Vous pouvez les activer dans la fenêtre de configuration. Vérifiez que l’application correspondante est préalablement installée sur votre ordinateur.

Note pour les utilisateurs de Windows

If you are not an advanced user and you are running QGIS on Windows, you might not be interested in reading the rest of this chapter. Make sure you install QGIS in your system using the standalone installer. That will automatically install SAGA, GRASS and OTB in your system and configure them so they can be run from QGIS. All the algorithms from these providers will be ready to be run without needing any further configuration. If installing through OSGeo4W application, make sure you select for installation SAGA, GRASS and OTB as well.

If you want to know more about how these providers work, or if you want to use some algorithms not included in the simplified toolbox (such as R scripts), keep on reading.

A propos des formats de fichiers

Le fait d’ouvrir un fichier dans QGIS ne garantit pas que ce fichier pourra être ouvert et traité par l’application tierce. Dans la plupart des cas, celui-ci pourra lire ce que vous avez ouvert dans QGIS, mais parfois, cela ne sera pas le cas. C’est particulièrement le cas des connections aux bases de données et les fichiers peu communs, aussi bien raster que vectoriels, qui pourront présenter des problèmes. Si cela arrivait, essayez de convertir vos données dans un format usuel reconnu par l’application tierce et vérifiez dans la console (historique et messages) le résultat du traitement pour analyser l’origine des erreurs.

Si vous utilisez des couches raster GRASS, par exemple, vous allez peut-être rencontrer des problèmes et ne pas pouvoir mener à bien votre travail si vous appelez des algorithmes externes ayant cette couche comme entrée. C’est pour cette raison que ces couches ne seront pas disponibles pour les algorithmes.

You should, however, find no problems at all with vector layers, since QGIS automatically converts from the original file format to one accepted by the external application before passing the layer to it. This adds extra processing time, which might be significant if the layer has a large size, so do not be surprised if it takes more time to process a layer from a DB connection than it does to process one of a similar size stored in a shapefile.

Les algorithmes n’utilisant pas d’application tierce peuvent traiter toutes les couches qui peuvent s’ouvrir dans QGIS puisque qu’ils sont lancés depuis QGIS.

Concernant les formats de sortie, tous les formats gérés par QGIS peuvent être utilisés en sortie, à la fois pour les couches raster et vecteur. Certains formats ne sont pas gérés par certaines applications tierces mais celles-ci permettent toutes d’exporter dans des formats courants qui peuvent ensuite être convertis automatiquement par QGIS. Comme pour les couches d’entrée, si une conversion est opérée, le temps de traitement peut être allongé.

A propos des sélections sur les couches vectorielles

Les applications tierces peuvent prendre en compte les sélections qui existent sur les couches vecteur dans QGIS. Cependant, cela nécessite de réécrire toutes les couches vecteur d’entrée, comme si elles étaient dans un format non géré par l’application tierce. Une couche peut être passée directement à une application tierce uniquement lorsqu’il n’y a pas de sélection ou que l’option N’utiliser que les entités sélectionnées n’ pas activée dans les paramètres de configuration généraux du module de traitement.

Dans les cas où l’export de la sélection est nécessaire cela rallonge les temps d’exécution.

SAGA

Les algorithmes de SAGA peuvent être exécutés depuis QGIS si SAGA est installé sur votre ordinateur et que le module de traitements QGIS est configuré correctement pour trouver les fichiers nécessaires. En particulier, l’exécutable en ligne de commande de SAGE est nécessaire pour utiliser les algorithmes.

Si vous utilisez Windows, les installateurs indépendant et OSGeo4W incluent SAGA aux côtés de QGIS, et le chemin d’accès est automatiquement configuré. Il n’y a donc rien à faire d’autre.

Si vous avez installé vous-même SAGA et que votre installeur QGIS ne l’inclut pas, le chemin vers l’exécutable SAGA doit être configuré. pour cela, ouvrez la fenêtre de configuration. Dans le bloc SAGA, vous trouverez un paramètre nommé Répertoire SAGA. Entrez le chemin du dossier d’installation de SAGA et fermez la fenêtre. Vous êtes prêts à utiliser les algorithmes de SAGA depuis QGIS.

Si vous êtes sur Linux, les exécutables SAGA ne sont pas inclus dans le module de Traitements. Vous devez donc télécharger et installer le logiciel vous-même. Référez au site web de SAGA pour plus d’informations.

Dans ce cas, il n’est pas nécessaire de configurer le chemin vers l’exécutable de SAGA et vous ne verrez pas ces répertoires. Vérifiez que SAGA est correctement installé et que le chemin d’installation figure dans la variable d’environnement PATH. Pour vérifier que les fichiers binaires de SAGA sont accessibles, ouvrez une console et tapez saga_cmd.

A propos des limitations du système de grille de SAGA

La plupart des algorithmes SAGA nécessitent habituellement des couches Raster en entrée sur la même emprise et la même grille, couvrant la même emprise et ayant la même résolution. A l’appel d’un algorithme SAGA depuis QGIS, vous pouvez cependant utiliser n’importe quelle couche, quelles que soient leur emprise et leur résolution. Quand plusieurs couches raster son indiquées en entré d’un algorithme SAGA, QGIS les rééchantillonne sur une grille commune avant de les transmettre à SAGA (à moins que l’algorithme SAGA manipule directement des couches dans des grilles différentes).

La définition de cette grille commune est contrôlée par l’utilisateur et peut se faire selon plusieurs paramètres, présents dans le groupe SAGA de la fenêtre de configuration. Deux façons de procéder existent:

  • La configuration manuelle. Vous définissez l’emprise à l’aide des paramètres suivants:

    • Rééchantillonner la valeur minimum de X

    • Rééchantillonner la valeur maximum de X

    • Rééchantillonner la valeur minimum de Y

    • Rééchantillonner la valeur maximum de Y

    • Rééchantillonner la taille de la cellule

    Veuillez noter que QGIS rééchantillonnera les couches en entrées sur cette emprise, même si elles ne la recoupent pas.

  • La configuration automatique à partir des couches en entrée. Pour choisir cette option, activez l’option Utiliser la grille minimale pour le rééchantillonnage. Toutes les autres options seront ignorées et l’emprise minimum couvrant toutes les couches sera utilisée. La taille de la cellule de la couche cible sera la plus grande des tailles de cellules des couches en entrée.

Pour les algorithmes qui n’utilisent pas plusieurs couches raster, ou pour ceux qui n’ont pas besoin d’une grille unique, le rééchantillonnage n’est pas nécessaire et ces paramètres ne seront pas utilisés.

Limitations pour les couches multi-bandes

Contrairement à QGIS, SAGA ne gère pas les couches multi-bande. Si vous utilisez de telles couches (par exemple une image RVB ou multispectrale), vous devez tout d’abord la séparer en couches mono-bande. Pour ce faire, vous pouvez utilisez l’algorithme ‘SAGA/Grid - Tools/Split RGB image’ (qui crée trois images à partir d’une image RVB) ou l’algorithme ‘SAGA/Grid - Tools/Extract band’ (qui extrait une bande en particulier).

Limitations dans la résolution

SAGA suppose que la couche raster possède la même résolution en X et en Y. Si vous travaillez sur une couche avec des résolutions différentes entre les deux axes, les résultats peuvent être incohérents. Dans ce cas, un message d’avertissement est ajouté au journal, indiquant que la couche n’est pas adaptée au traitement par SAGA.

Suivi du journal

Lorsque QGIS appelle SAGA, il le fait par son interface en lignes de commandes pour effectuer l’opération demandée. SAGA transmet son état d’avancement dans la console ainsi que d’autres informations. Ces messages sont filtrés et utilisés pour afficher la barre d’avancement pendant l’exécution de l’algorithme.

Les commandes envoyées par QGIS et les informations supplémentaires écrites par SAGA peuvent être consignées dans le log comme pour tous les algorithmes. Il peut être utile de suivre en détail ce qu’il se passe lorsque QGIS lance un algorithme SAGA. Vous avez deux options pour activer ce mécanisme : Log console output et Log execution commands.

La plupart des autres fournisseurs tiers qui sont appelés par la ligne de commandes ont des options similaires, que vous trouverez dans la rubrique configuration du module.

R. Creating R scripts

L’intégration de R est légèrement différente de celle de SAGA, dans la mesure où il n’y a pas d’ensemble prédéfini d’algorithmes à exécuter, hormis quelques exemples. Au lieu de cela, c’est à vous d’écrire les scripts à transmettre à R, comme vous le feriez depuis R. Un peu comme dans le chapitre sur les scripts. Ce chapitre va vous montrer comment appeler les commandes R à partir de QGIS et comment leur transmettre les objets QGIS (couches et tables).

La première chose à faire, comme nous l’avons vu pour SAGA, est de dire à QGIS où se situent les fichiers exécutables de R. Paramétrez l’entrée Répertoire R dans la fenêtre de configuration du module de traitements. Une fois cela fait, vous pouvez commencer à créer et exécuter vos propres scripts R.

Note

Pour les utilisateurs Windows, l’exécutable de R est situé dans le répertoire C:\Program Files\R\R-3.2. Ajoutez uniquement le répertoire et NON le binaire !

Une fois encore, pour Linux, cela est légèrement différent : vous n’avez qu’à vérifier que le répertoire R est inclus dans la variable d’environnement PATH. Si vous pouvez lancer R en tapant R dans un terminal, alors vous êtes prêt pour la suite.

Pour ajouter un nouvel algorithme qui appelle une fonction R (ou un script R plus complexe que vous auriez développé et que vous souhaiteriez utiliser dans QGIS), vous devez créer un fichier de script qui va indiquer au module de traitements comment effectuer l’opération et les commandes R correspondantes.

Les fichiers de scripts R ont l’extension .rsx et leur création est relativement simple si vous connaissez la syntaxe et le langage de script de R. Ils seront sauvegardés dans le répertoire de scripts de R. Vous pouvez configurer ce répertoire dans le groupe de configuration de R (dans la fenêtre Options du module de traitements), comme vous le feriez pour un script ordinaire.

Voyons un simple script, qui appelle la méthode spsample de R, pour créer une grille aléatoire à l’intérieur de l’emprise d’un ensemble de polygones d’une couche donnée. Cette fonction appartient au paquet maptools. Comme la plupart des algorithmes que vous aurez à intégrer dans QGIS utilisent ou génèrent des données spatiales, la connaissance des paquets spatiaux comme maptools et surtout sp est un prérequis.

##polyg=vector
##numpoints=number 10
##output=output vector
##sp=group
pts=spsample(polyg,numpoints,type="random")
output=SpatialPointsDataFrame(pts, as.data.frame(pts))

Les premières lignes, qui commencent avec un double signe de commentaire Python (##), indiquent à QGIS les entrées de l’algorithme décrit dans le fichier ainsi que les sorties qu’il génère. Ces lignes fonctionnent exactement avec la même syntaxe que les scripts du module de Traitements que nous avons déjà étudiés et elles ne seront pas décrites davantage ici.

Merci de jeter un oeil sur les chapitres consacrés à l’Introduction à R et à la Syntaxe R pour avoir plus d’informations sur la manière d’écrire vos propres scripts R.

Quand vous déclarez un paramètre d’entrée, QGIS utilise cette information pour deux choses : créer le formulaire pour demander à l’utilisateur la valeur de ce paramètre et créer la variable R correspondante qui sera ensuite utilisée dans les commandes R.

Dans l’exemple ci-dessus, nous avons déclaré une entrée de type vecteur appelée polyg. A l’exécution de l’algorithme, QGIS ouvrira la couche sélectionnée par l’utilisateur dans R et la stockera dans une variable nommée polyg. Ainsi le nom du paramètre est également le nom de la variable à utiliser dans R pour accéder à son contenu (par conséquent, évitez d’utiliser des mots réservés R comme noms de paramètre).

Les éléments spatiaux telles que les couches vecteur et raster sont lues en utilisant les commandes readOGR() et brick() (n’ajoutez pas ces commandes à votre description de fichier – QGIS s’en chargera). Elles sont stockées en tant qu’objets Spatial*DataFrame. Les champs des tables sont stockés en tant que chaînes de caractères contenant le nom du champ sélectionné.

Les tables sont ouvertes par la commande read.csv(). Si la table à charger n’est pas au format CSV, il faudra la convertir avant de l’importer dans R.

De plus, les couches raster peuvent être lues avec la commande readGDAL() au lieu de brick(), en utilisant ##usereadgdal.

Si vous êtes un utilisateur expert et que vous ne voulez pas que QGIS crée l’objet correspondant à une couche, vous pouvez utiliser le paramètre ##passfilename qui indique que vous préférez une chaîne de caractères contenant le nom du fichier à la place. Dans ce cas, c’est à vous d’ouvrir le fichier au préalable.

Avec l’information ci-dessus, nous pouvons maintenant comprendre la première ligne de notre premier exemple de script (la première ligne qui n’est pas un commentaire Python).

pts=spsample(polyg,numpoints,type="random")

La variable polygon contient déjà un objet SpatialPolygonsDataFrame, l’appel de la méthode spsample est donc simple. Il en est de même pour la méthode numpoints qui renvoit le nombre de points à ajouter pour créer la grille.

Comme nous avons déclaré une sortie de type vecteur nommée out, nous devons créer cette variable out et lui affecter un objet Spatial*DataFrame (dans notre cas, un SpatialPointsDataFrame). Vous pouvez utiliser n’importe quel nom pour les variables intermédiaires. Assurez-vous simplement que la variable qui stocke la valeur finale ait le même nom que la variable de sortie définie au début ainsi qu’une valeur compatible.

Dans notre exemple, le résultat de la méthode spsample doit être converti explicitement en objet SpatialPointsDataFrame, dans la mesure où c’est un objet de la classe ppp qui ne peut être retransmis à QGIS.

Si votre algorithme génère des couches raster, la façon dont elles sont enregistrées varie selon que vous ayez utilisé l’option ##dontuserasterpackage ou pas. Si oui, les couches seront sauvegardées en utilisant la méthode writeGDAL(). Si non, la méthode writeRaster() du paquet raster sera utilisée.

Si vous avez utilisé l’option #passfilenames, les sorties sont générées à l’aide du package raster (avec writeRaster()), bien qu’il ne soit pas utilisé pour les entrées.

Si votre algorithme ne renvoie pas de couche mais plutôt un résultat texte dans la console, vous devez préciser que la console doit s’afficher à la fin de son exécution. Pour cela, commencez les lignes qui doivent renvoyer les résultats par le signe >. Les sorties des autres lignes seront masquées. Par exemple, voici la description d’un algorithme qui réalise un test de normalisation sur un champ donné (ou une colonne) de la table d’attributs d’une couche vectorielle :

##layer=vector
##field=field layer
##nortest=group
library(nortest)
>lillie.test(layer[[field]])

La sortie de la dernière ligne est affichée, mais la sortie de la première ne l’est pas (ni celles des commandes ajoutées automatiquement par QGIS).

Si votre algorithme crée des graphiques (par la méthode plot()), ajoutez la ligne suivante:

##showplots

Ceci va indiquer à QGIS de rediriger toutes les sorties graphiques de R vers un fichier temporaire qui sera chargé une fois l’exécution de R terminée.

Les graphiques et les résultats dans la console seront affichés dans le gestionnaire de résultats.

Pour plus d’informations, veuillez vous référer aux scripts fournis avec le module de Traitements. Tous sont relativement simples et pourront vous aider à construire vos propres scripts.

Note

Les bibliothèques rgdal et raster sont chargées par défaut et vous n’avez donc pas besoin d’ajouter les commandes library() correspondantes (vous devez uniquement vous assurer que les deux paquets sont installés dans votre distribution de R). Néanmoins, d’autres bibliothèques additionnelles dont vous aurez besoin doivent être spécifiquement chargées en tapant library(ggplot2). Si le paquet n’est pas encore installé sur votre machine, Processing le téléchargera et l’installera. De cette manière, le paquet sera également disponible pour R. Attention, si le paquet doit être téléchargé, le premier lancement du script pourra prendre longtemps.

GRASS

Configuring GRASS is not much different from configuring SAGA. First, the path to the GRASS folder has to be defined, but only if you are running Windows. Additionally, a shell interpreter (usually msys.exe, which can be found in most GRASS for Windows distributions) has to be defined and its path set up as well.

By default, the processing framework tries to configure its GRASS connector to use the GRASS distribution that ships along with QGIS. This should work without problems in most systems, but if you experience problems, you might have to configure the GRASS connector manually. Also, if you want to use a different GRASS installation, you can change that setting and point to the folder where the other version is installed. GRASS 6.4 is needed for algorithms to work correctly.

Sous Linux, assurez-vous simplement que GRASS est correctement installé et qu’il peut être lancé depuis un terminal.

Les algorithmes GRASS nécessitent la définition d’une région. Cette région peut être définie manuellement, en fournissant les valeurs, comme pour la configuration de SAGA, ou de manière automatique, correspondant à l’emprise minimale des données d’entrée à l’exécution de l’algorithme. Si vous préférez ce dernier réglage, cochez l’option Utiliser l’emprise minimale dans les paramètres de configuration de GRASS.

GDAL

No additional configuration is needed to run GDAL algorithms. Since they are already incorporated into QGIS, the algorithms can infer their configuration from it.

Orfeo Toolbox

Orfeo Toolbox (OTB) algorithms can be run from QGIS if you have OTB installed in your system and you have configured QGIS properly, so it can find all necessary files (command-line tools and libraries).

As in the case of SAGA, OTB binaries are included in the stand-alone installer for Windows, but they are not included if you are running Linux, so you have to download and install the software yourself. Please check the OTB website for more information.

Once OTB is installed, start QGIS, open the processing configuration dialog and configure the OTB algorithm provider. In the Orfeo Toolbox (image analysis) block, you will find all settings related to OTB. First, ensure that algorithms are enabled.

Then, configure the path to the folder where OTB command-line tools and libraries are installed:

  • nix Usually OTB applications folder points to /usr/lib/otb/applications and OTB command line tools folder is /usr/bin.
  • win If you use any of the installers that include OTB, such as OSGeo4W, there is no need for further configuration. Processing will detect the path automatically and will not show the corresponding configuration entries. Otherwise, fill the OTB applications folder and OTB command line tools folder parameters with the to the corresponding values for your installation.

TauDEM

TauDEM (Terrain Analysis Using Digital Elevation Models) is a tools for the extraction and analysis of hydrological information from Digital Elevation Models (DEM). TauDEM can be used from QGIS if you have it installed in your system and configured QGIS properly, so it can find all necessary files.

There are two versions of TauDEM tools: singlefile (TauDEM 5.0.6 or 5.1.2) and multifile (TauDEM 5.2.0). The difference between these versions in the supported inputs/outputs. Single files version accepts only single raster file and write single file as output. Multifile version accepts a directory with rasters and writes directory with rasters as output. Such directory should contain rasters that will be treated as a single DEM grid.

TauDEM Processing provider supports both single- and multifile versions of TauDEM and even allows to use them simultaneously.

Note

While TauDEM Processing provider supports TauDEM 5.0.6, 5.1.2 and 5.2.0 we recommend to use 5.1.2 and/or 5.2.0 as this versions have some new tools available, like Gage Watershed and TWI.

Installing TauDEM under Windows

Please visit the TauDEM homepage and download desired version of the precompiled binaries for your platform (32-bit or 64-bit), usually this is “Command Line Executables”. Also you need to download Microsoft HPC Pack 2012 MS-MPI. First install Microsoft HPC Pack 2012 MS-MPI by runing mpi_x64.Msi for 64-bit platforms and mpi_x86.Msi for 32-bit platforms.

Note

If you want to use TauDEM 5.0.6

Installing TauDEM under Linux

Unfortunately there are no packages for most Linux distributions, so you should compile TauDEM by yourself. As TauDEM uses MPI it is necessary to install first any MPI implementation e.g MPICH or OpenMPI. Use your favorite package manager to install MPICH or OpenMPI.

Download TauDEM 5.2.0 source code package from GitHub repository and extract archive contents. Open terminal and cd into src directory inside extracted folder. Create build directory and cd into it

mkdir build
cd build

Configure your build (change install prefix if necessary) and compile

CXX=mpicxx cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
make

When compilation finished install TauDEM tools by running

sudo make install

Note

Executable files will be installed into bin subdirectory inside prefix you specified at the configure stage. For example if you specified prefix /opt/taudem5.2 than binaries will be installed into /opt/taudem5.2/bin.

To use singlefile version — download source package here and perform above mentioned steps to compile and install it.

Old TauDEM 5.0.6 also available. But before compiling this version it is necessary to edit some source files.

Open the linearpart.h file, and after line

#include "mpi.h"

add a new line with

#include <stdint.h>

so you’ll get

#include "mpi.h"
#include <stdint.h>

Save the changes and close the file. Now open tiffIO.h, find line #include "stdint.h" and replace quotes ("") with <>, so you’ll get

#include <stdint.h>

Save the changes and close the file.

Now configure, compile and install TauDEM 5.0.6 using same commands as described above.

Configuring TauDEM provider

Once TauDEM is installed, start QGIS, open the Processing options dialog from Processing ‣ Options... and configure the TauDEM algorithm provider. In the Providers group find TauDEM (hydrologic analysis) block, and expand it. Here you will see all settings related to TauDEM.

First, ensure that algorithms are enabled, and activate provider if necessary.

Next step is to configure MPI. The MPICH/OpenMPI bin directory setting used to define location of the mpiexec program. In most Linux distributions you can safely leave this empty, as mpiexec available in your PATH.

The Number of MPI parallel processes to use is a second setting related to MPI. It defines number of processes that will be used to execute TauDEM commands. If you don’t know which value to use, it is better to leave this value unchanged.

Now we need to configure the path to the folder(s) where TauDEM command-line tools are installed. As we already mention TauDEM provider supports both single- and multifile TauDEM, so there are two settings for TauDEM folders:

  • TauDEM command line tools folder used to set location of the singlefile tools
  • TauDEM multifile command line tools folder used to set location of the multifile tools

If you have both TauDEM versions installed in different directories it is possible to specify both options.

The last step is to define which TauDEM version to use:

  • with Enable multifile TauDEM tools option checked you will use multifile TauDEM tools from directory, specified in the TauDEM multifile command line tools folder. Multifile tools have same name as singlefile with “(multifile)” suffix added
  • with Enable single TauDEM tools option checked you will use multifile TauDEM tools from directory, specified in the TauDEM command line tools folder.

It is possible to enable both tools simultaneously. In this case you will have two instances of each tool in toolbox and can use them in your analysis.

Note

Be careful with developing Processing models using TauDEM!

As single- and multifile versions have different inputs, model created with singlefile algorithms will not work if only multifile algorithms are available. If you plan to share your model please specify which TauDEM version should be used or, better, provide two versions of your model: for single- and multifile TauDEM.