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

.

Configurando as aplicações externas

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 application are managed by their own algorithm provider.

Este capítulo irá mostrar como configurar a infraestrutura do processamento para incluir estas aplicações adicionais, e irá explicar algumas características particulares baseado nos algoritmos. Uma vez feita a correta configuração do sistema, terá possibilidade de executar algoritmos externos a partir de qualquer componente como a caixa de ferramentas ou o modelador gráfico, assim como faz para outro geoalgoritmo.

By default, all algorithms that rely on an external appplication not shipped with QGIS are not enabled. You can enable them in the configuration dialog. Make sure that the corresponding application is already installed in your system. Enabling an algorithm provider without installing the application it needs will cause the algorithms to appear in the toolbox, but an error will be thrown when you try to execute them.

This is because the algorithm descriptions (needed to create the parameters dialog and provide the information needed about the algorithm) are not included with each application, but with QGIS instead. That is, they are part of QGIS, so you have them in your installation even if you have not installed any other software. Running the algorithm, however, needs the application binaries to be installed in your system.

Uma nota para usuários 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 in the simplified view of the toolbox will be ready to be run without needing any further configuration. If installing through OSGeo4W application, make sure you select for insttallation SAGA and OTB as well.

Se desejar saber mais sobre como os fornecedores trabalham, ou deseja usar alguns algoritmos que não estão incluídos na caixa de ferramentas simplificada (como por exemplo os scripts R), continue a leitura.

Uma nota para os formatos dos arquivos

When using an external software, opening a file in QGIS does not mean that it can be opened and processed as well in that other software. In most cases, other software can read what you have opened in QGIS, but in some cases, that might not be true. When using databases or uncommon file formats, whether for raster or vector layers, problems might arise. If that happens, try to use well-known file formats that you are sure are understood by both programs, and check the console output (in the history and log dialog) to know more about what is going wrong.

Usando as camadas raster GRASS, por exemplo, um dos casos em que pode ter problema e não seja possível completar o seu trabalho é se chamar um algoritmo externo usando uma camada como arquivo de entrada. Por esta razão, essas camadas não irão aparecer como disponíveis para os algoritmos.

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.

Providers not using external applications can process any layer that you can open in QGIS, since they open it for analysis through QGIS.

Regarding output formats, all formats supported by QGIS as output can be used, both for raster and vector layers. Some providers do not support certain formats, but all can export to common raster layer formats that can later be transformed by QGIS automatically. As in the case of input layers, if this conversion is needed, that might increase the processing time.

If the extension of the filename specified when calling an algorithm does not match the extension of any of the formats supported by QGIS, then a suffix will be added to set a default format. In the case of raster layers, the .tif extension is used, while .shp is used for vector layers.

Uma nota para as seleções da camada vetorial

External applications may also be made aware of the selections that exist in vector layers within QGIS. However, that requires rewriting all input vector layers, just as if they were originally in a format not supported by the external application. Only when no selection exists, or the Use only selected features option is not enabled in the processing general configuration, can a layer be directly passed to an external application.

Noutros casos, exportando apenas os elementos seleccionados é necessário, o que em alguns casos os tempos de execução serão mais longos.

SAGA

SAGA algorithms can be run from QGIS if you have SAGA installed in your system and you configure the processing framework properly so it can find SAGA executables. In particular, the SAGA command-line executable is needed to run SAGA algorithms.

If you are running Windows, both the stand-alone installer and the OSGeo4W installer include SAGA along with QGIS, and the path is automatically configured, so there is no need to do anything else.

If you have installed SAGA yourself (remember, you need version 2.1), the path to the SAGA executable must be configured. To do this, open the configuration dialog. In the SAGA block, you will find a setting named SAGA Folder. Enter the path to the folder where SAGA is installed. Close the configuration dialog, and now you are ready to run SAGA algorithms from QGIS.

If you are running Linux, SAGA binaries are not included with SEXTANTE, so you have to download and install the software yourself. Please check the SAGA website for more information. SAGA 2.1 is needed.

In this case, there is no need to configure the path to the SAGA executable, and you will not see those folders. Instead, you must make sure that SAGA is properly installed and its folder is added to the PATH environment variable. Just open a console and type saga_cmd to check that the system can find where the SAGA binaries are located.

Sobre as limitações do sistema de grid do SAGA

Most SAGA algorithms that require several input raster layers require them to have the same grid system. That is, they must cover the same geographic area and have the same cell size, so their corresponding grids match. When calling SAGA algorithms from QGIS, you can use any layer, regardless of its cell size and extent. When multiple raster layers are used as input for a SAGA algorithm, QGIS resamples them to a common grid system and then passes them to SAGA (unless the SAGA algorithm can operate with layers from different grid systems).

A definição do sistema de projeção comum é controlado pelo usuário, você vai encontrar vários parâmetros no grupo SAGA da janela de configuração para definí-lo. Existem duas maneiras de definir o sistema de projeção:

  • Configure-o manualmente. Você define a extensão configurando os valores dos seguintes parâmetros:

    • Reamostragem do X min

    • Reamostragem do X máx

    • Reamostragem do Y min

    • Reamostragem do Y máx

    • Reamostragem do tamanho da célula

    Notice that QGIS will resample input layers to that extent, even if they do not overlap with it.

  • Configurando automaticamente a partir das camadas de entrada. Para selecionar esta opção, verifique a opção:guilabel:Use min covering grid system for resampling. Todas as outras configurações irão ser ignoradas e a extensão mínima que cobre todas as camadas de entrada serão usadas. O tamanho de célula da camada de destino é o máximo de tamanho de célula de todas as camadas de entrada.

Para algoritmos que não usam camadas raster múltiplas, ou para aquelas que não necessitam de um único sistema de grid de entrada, não será feito uma reamostragem antes de chamar o SAGA, e esses parâmetros não serão usados.

Limitações para camadas multi-banda

Unlike QGIS, SAGA has no support for multi-band layers. If you want to use a multiband layer (such as an RGB or multispectral image), you first have to split it into single-banded images. To do so, you can use the ‘SAGA/Grid - Tools/Split RGB image’ algorithm (which creates three images from an RGB image) or the ‘SAGA/Grid - Tools/Extract band’ algorithm (to extract a single band).

Limitações na resolução espacial

O SAGA pressupõe que as camadas raster têm o mesmo tamanho de célula no eixo X e Y. Se estiver trabalhando com uma camada com diferentes valores para o tamanho de célula horizontal e vertical, deverá obter resultados inesperados. Nesse caso, um aviso será adicionado ao registo do processamento, indicando que a camada de entrada não se adapta de forma a ser processado pelo SAGA.

Registrando

When QGIS calls SAGA, it does so using its command-line interface, thus passing a set of commands to perform all the required operations. SAGA shows its progress by writing information to the console, which includes the percentage of processing already done, along with additional content. This output is filtered and used to update the progress bar while the algorithm is running.

Both the commands sent by QGIS and the additional information printed by SAGA can be logged along with other processing log messages, and you might find them useful to track in detail what is going on when QGIS runs a SAGA algorithm. You will find two settings, namely Log console output and Log execution commands, to activate that logging mechanism.

A maioria dos outros fornecedores que usam uma aplicação externa e chamam a partir da linha de comandos têm opções semelhantes, portanto irá encontrar noutros sítios da lista de configurações do processamento.

R. Creating R scripts

R integration in QGIS is different from that of SAGA in that there is not a predefined set of algorithms you can run (except for a few examples). Instead, you should write your scripts and call R commands, much like you would do from R, and in a very similar manner to what we saw in the section dedicated to processing scripts. This section shows you the syntax to use to call those R commands from QGIS and how to use QGIS objects (layers, tables) in them.

The first thing you have to do, as we saw in the case of SAGA, is to tell QGIS where your R binaries are located. You can do this using the R folder entry in the processing configuration dialog. Once you have set that parameter, you can start creating and executing your own R scripts.

Uma vez mais, isto é diferente no Linux, e só tem de ter certeza que a pasta do R está incluída na variável de ambiente PATH. Se conseguir iniciar o R, apenas introduza R na consola, e estará pronto a começar.

To add a new algorithm that calls an R function (or a more complex R script that you have developed and you would like to have available from QGIS), you have to create a script file that tells the processing framework how to perform that operation and the corresponding R commands to do so.

Os arquivos de script R têm a extensão .rsx e é fácil criá-los se tiver o conhecimento básico da sintaxe do R e do código R. Eles devem ficar armazenados na pasta scripts R. Pode definir esta pasta no grupo de configurações R (disponível a partir do diálogo de configurações do processamento), como faz com a pasta para scripts normais do processamento.

Let’s have a look at a very simple script file, which calls the R method spsample to create a random grid within the boundary of the polygons in a given polygon layer. This method belongs to the maptools package. Since almost all the algorithms that you might like to incorporate into QGIS will use or generate spatial data, knowledge of spatial packages like maptools and, especially, sp, is mandatory.

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

The first lines, which start with a double Python comment sign (##), tell QGIS the inputs of the algorithm described in the file and the outputs that it will generate. They work with exactly the same syntax as the SEXTANTE scripts that we have already seen, so they will not be described here again.

When you declare an input parameter, QGIS uses that information for two things: creating the user interface to ask the user for the value of that parameter and creating a corresponding R variable that can later be used as input for R commands.

In the above example, we are declaring an input of type vector named polyg. When executing the algorithm, QGIS will open in R the layer selected by the user and store it in a variable also named polyg. So, the name of a parameter is also the name of the variable that we can use in R for accesing the value of that parameter (thus, you should avoid using reserved R words as parameter names).

Spatial elements such as vector and raster layers are read using the readOGR() and brick() commands (you do not have to worry about adding those commands to your description file – QGIS will do it), and they are stored as Spatial*DataFrame objects. Table fields are stored as strings containing the name of the selected field.

Tabelas são abertas usando o comando read.csv(). Se uma tabela inserida pelo usuário não está no formato CSV, será convertida antes de importá-la para R.

Adicionalmente, os arquivos raster pode ser lidos usando o comando readGDAL() em vez de brick(), usando o ##usereadgdal.

If you are an advanced user and do not want QGIS to create the object representing the layer, you can use the ##passfilename tag to indicate that you prefer a string with the filename instead. In this case, it is up to you to open the file before performing any operation on the data it contains.

Com a informação em cima, podemos agora perceber a primeira linha do nosso primeiro script exemplo (a primeira linha que não começa com o comentário Python).

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

A variável polygon já contém o objecto SpatialPolygonsDataFrame, portanto pode ser usado para chamar o método spsample, tal como o numpoints, que indica o número de pontos a ser adicionados ao grid de amostra criada.

Desde que declarado uma saída do tipo vetor chamado out, temos que criar uma variável chamada out e armazenar um ` Spatial*DataFrame objeto nele (neste caso, um SpatialPointsDataFrame). Você pode usar qualquer nome para as variáveis ​​intermediárias. Apenas certifique-se de que a variável que armazena o resultado final tem o mesmo nome que você usou para declará-la, e que contém um valor adequado.

In this case, the result obtained from the spsample method has to be converted explicitly into a SpatialPointsDataFrame object, since it is itself an object of class ppp, which is not a suitable class to be returned to QGIS.

Se o seu algoritmo gera camadas raster, a maneira como eles são salvos vai depender se você tem usado ou não usou a opção `` #dontuserasterpackag . O que você tem usado, as camadas são salvas usando o método `` writeGDAL () ``. Se não, o `` writeRaster () `` método do pacote de  ``raster será usado.

Se usou a opção #passfilename, os arquivos de saída são gerados usando o pacote raster (com writeRaster()), mesmo que não seja usado nos arquivos de entrada.

Se o seu algoritmo não gera qualquer camada, mas sim um resultado de texto no console em vez disso, você tem que indicar que deseja que o console seja exibido uma vez que a execução seja concluída. Para isso, basta começar as linhas de comando que produzem os resultados que você deseja imprimir com a > (‘greater’) sign. A saída de todas as outras linhas não serão mostradas. Por exemplo, aqui está o arquivo de descrição de um algoritmo que realiza um teste de normalidade em um determinado campo (coluna) dos atributos de uma camada vetorial:

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

The output of the last line is printed, but the output of the first is not (and neither are the outputs from other command lines added automatically by QGIS).

Se o seu algoritmo criar qualquer tipo de gráficos (usando o método ``plot()), adicione a seguinte linha:

##showplots

This will cause QGIS to redirect all R graphical outputs to a temporary file, which will be opened once R execution has finished.

Tanto os gráficos como os resultados do console serão exibidos no gestor de resultados do processamento.

For more information, please check the script files provided with SEXTANTE. Most of them are rather simple and will greatly help you understand how to create your own scripts.

Nota

rgdal and maptools libraries are loaded by default, so you do not have to add the corresponding library() commands (you just have to make sure that those two packages are installed in your R distribution). However, other additional libraries that you might need have to be explicitly loaded. Just add the necessary commands at the beginning of your script. You also have to make sure that the corresponding packages are installed in the R distribution used by QGIS. The processing framework will not take care of any package installation. If you run a script that requires a package that is not installed, the execution will fail, and Processing will try to detect which packages are missing. You must install those missing libraries manually before you can run the algorithm.

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. Additionaly, 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.

Se está a trabalhar em Linux, só necessita de ter a certeza que o GRASS está corretamente instalado, e pode ser executado sem problema a partir do console.

GRASS algorithms use a region for calculations. This region can be defined manually using values similar to the ones found in the SAGA configuration, or automatically, taking the minimum extent that covers all the input layers used to execute the algorithm each time. If the latter approach is the behaviour you prefer, just check the Use min covering region option in the GRASS configuration parameters.

The last parameter that has to be configured is related to the mapset. A mapset is needed to run GRASS, and the processing framework creates a temporary one for each execution. You have to specify if the data you are working with uses geographical (lat/lon) coordinates or projected ones.

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

Em seguida, configure o caminho para a pasta onde estão as ferramentas da linha de comandos OTB e as bibliotecas estão instaladas:

  • nix normalmente OTB applications folder encaminha para /usr/lib/otb/applications e OTB command line tools folder é /usr/bin

  • win If you use the OSGeo4W installer, then install otb-bin package and enter C:\OSGeo4W\apps\orfeotoolbox\applications as OTB applications folder and C:\OSGeo4W\bin as OTB command line tools folder. These values should be configured by default, but if you have a different OTB installation, configure them to the corresponding values in your system.

TauDEM

To use this provider, you need to install TauDEM command line tools.

Windows

Please visit the TauDEM homepage for installation instructions and precompiled binaries for 32-bit and 64-bit systems. IMPORTANT: You need TauDEM 5.0.6 executables. Version 5.2 is currently not supported.

Linux

There are no packages for most Linux distributions, so you should compile TauDEM by yourself. As TauDEM uses MPICH2, first install it using your favorite package manager. Alternatively, TauDEM works fine with Open MPI, so you can use it instead of MPICH2.

Download TauDEM 5.0.6 source code and extract the files in some folder.

Abra o arrquivo linearpart.h e depois a linha

#include "mpi.h"

adicione uma nova linha com

#include <stdint.h>

e irá obter

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

Salve as alterações e feche o arquivo. Agora abra o arquivo tiffIO.h, encontre a linha #include "stdint.h" e substitua as entre aspas (“”) com ``<>, para que possa obter

#include <stdint.h>

Save the changes and close the file. Create a build directory and cd into it

mkdir build
cd build

Configure your build with the command

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

and then compile

make

Finally, to install TauDEM into /usr/local/bin, run

sudo make install