Using SEXTANTE from the console

Introdução

O console permite que usuários avançados possam aumentar sua produtividade e realizar operações complexas, que não podem ser realizadas usando qualquer um dos outros elementos do GUI SEXTANTE. Modelos que envolvem vários algoritmos podem ser definidos usando a interface de linha de comando e operações adicionais, tais como loops e frases condicionais podem ser adicionados para criar fluxos de trabalho mais flexíveis e poderosos.

Não existe nenhum console SEXTANTE no QGIS, mas todos os comandos SEXTANTE estão disponíveis e embutido no console Python em vez de estarem no QGIS. Isso significa que é possivel incorporar os comandos de trabalho em consoles e conectar algoritmos SEXTANTE para todos os outros recursos disponíveis (incluindo métodos da API do QGIS).

The code that you can execute from the Python console, even if it does call any SEXTANTE method, can be converted into a new SEXTANTE algorithm that you can later call from the toolbox, the graphical modeler or any other SEXTANTE component, just like you do with any other SEXTANTE algorithm. In fact, some algorithms that you can find in the toolbox, like all the ones in the mmqgis group, are simple scripts.

Neste capítulo, vamos ver como usar o console SEXTANTE Python do QGIS, além de como escrever seus próprios algoritmos usando Python.

Iniciando o console SEXTANTE Python

A primeira coisa que você tem a fazer é importar as funções SEXTANTE com a seguinte linha:

>>> import sextante

Agora, há, basicamente, apenas uma coisa (interessante) que você pode fazer com o console SEXTANTE: a execução de um algoritmo. Isso é feito usando o método runalg(), que tem o nome do algoritmo a ser executado como seu primeiro parâmetro e, em seguida, um número variável de parâmetros adicionais, dependendo dos requisitos do algoritmo. Então a primeira coisa que você precisa para executar é saber o nome do algoritmo. Esse não é o nome que você vê na caixa de ferramentas, mas sim o nome de linha de comando único. Para encontrar o nome certo para o seu algoritmo, você pode usar o método algslist(), Digite a seguinte linha no console:

>>> sextante.alglist()

Você verá algo como isso.

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

Essa é uma lista de todos os algoritmos disponíveis, ordenados por ordem alfabética, juntamente com seus correspondentes nomes de linha de comando.

É possível usar um campo de texto como parâmetro para este método. Em vez de retornar a lista completa de algoritmo, ele só irá exibir aqueles que incluem esse campo. Se, por exemplo, você está procurando um algoritmo para calcular inclinação de um MDE, digite alglist("slope") para obter o seguinte resultado:

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]

Este resultado pode mudar dependendo dos algoritmos que estão disponíveis.

It is easier now to find the algorithm you are looking for and its command-line name, in this case saga:slopeaspectcurvature.

Uma vez que é conhecido o nome da linha de comando do algoritmo, a próxima coisa a ser feita é saber a sintaxe correta para executá-lo. Isso significa saber quais os parâmetros que são necessários e na ordem em que eles têm que ser passados, ​​ao chamar o método runalg()`. o SEXTANTE tem um método para descrever um algoritmo em detalhes, o qual pode ser usado para obter uma lista de parâmetros, que necessitam de um algoritmos e as saídas que irá gerar. Para fazer isso, você pode usar o método ``alghelp(nome do algoritmo). Use o nome de linha de comando do algoritmo, e não o nome descritivo completo.

Se for chamado o método saga:slopeaspectcurvature como parâmetro, você terá a seguinte descrição.

>>> sextante.alghelp("saga:slopeaspectcurvature")
ALGORITHM: Slope, Aspect, Curvature
   ELEVATION <ParameterRaster>
   METHOD <ParameterSelection>
   SLOPE <OutputRaster>
   ASPECT <OutputRaster>
   CURV <OutputRaster>
   HCURV <OutputRaster>
   VCURV <OutputRaster>

Now you have everything you need to run any algorithm. As we have already mentioned, there is only one single command to execute algorithms: runalg(). Its syntax is as follows:

>>> sextante.runalg{name_of_the_algorithm, param1, param2, ..., paramN,
         Output1, Output2, ..., OutputN)

The list of parameters and outputs to add depends on the algorithm you want to run, and is exactly the list that the alghelp() method gives you, in the same order as shown.

Dependendo do tipo de parâmetro, os valores são introduzidos de forma diferente. O próximo passo é uma revisão rápida de como introduzir os valores para cada tipo de parâmetro de entrada

  • Para usar camadas raster, vetoriais ou tabelas. Basta usar um campo de texto com o nome que identifica o objeto de dados (o nome que tem na lista de camadas do projeto em execução QGIS) ou o nome do arquivo (se a camada correspondente não estiver aberta no QGIS, ela será aberta, mas não adicionada à tela do mapa). Se você tiver uma instância de um objeto que representa a camada QGIS, você também pode passá-lo como parâmetro. Se a entrada for opcional e você não desejar usar qualquer objeto de dados, use None.

  • Seleção. Se um algoritmo tem um parâmetro de seleção, o valor do parâmetro que deve ser introduzido deve usar um valor inteiro. Para saber as opções disponíveis, você pode usar o comando algoptions, como mostrado no exemplo a seguir:

    >>> 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)
    

    Neste caso, o algoritmo tem um dos referidos parâmetros, com 7 opções. Observe que a ordenação é iniciada em zero.

  • Entradas múltiplas. O valor é um conjunto de caracteres com descritores de entrada separados por ponto e vírgula. Tal como no caso de camadas únicas ou tabelas, cada descritor de entrada pode ter o nome do elemento de dados, ou o caminho do seu arquivo.

  • Campos de tabelas para XXX. Utilize um conjunto de caracteres com o nome do campo a ser usado. Este parâmetro é sensível a maiúsculas.

  • Fixed Table. Type the list of all table values separated by commas and enclosed between quotes. Values start on the upper row and go from left to right. You can also use a 2D array of value representing the table.

  • CRS. Enter the EPSG code number of the desired CRS.

  • Extent. You must use a string with xmin, xmax, ymin and ymax values separated by commas.

Parâmetros Booleanos, campo de caracteres de arquivos e numérico não precisam de explicações adicionais.

Parâmetros de entrada, tais como o grupo de valores booleanos, os valores numéricos apresentam valores por padrão. Para usá-los, use o método None na entrada do parâmetro correspondente.

Para objetos de saída de dados, digite o caminho de arquivo a ser utilizado para salvá-lo, da mesma forma que é feito a partir da caixa de ferramentas. Se você quiser salvar o resultado em um arquivo temporário, use None. A extensão do arquivo determina o formato do arquivo. Se você digitar uma extensão de arquivo não incluída entre as que são suportados pelo algoritmo, será utilizado o formato de arquivo padrão para esse tipo de saída, bem como à sua extensão correspondente anexado ao conjunto de arquivos de dados.

Ao contrário de quando um algoritmo é executado a partir da caixa de ferramentas, as saídas não são adicionadas à tela do mapa, se você executar esse mesmo algoritmo no console Python. Se você desejar adicionar uma saída para à tela, você tem que fazê-lo manualmente após a execução do algoritmo. Para fazer isso, você pode usar os comandos da API QGIS, ou use um dos métodos úteis fornecidas pelo SEXTANTE para tal tarefa.

The runalg() method returns a dictionary with the output names (the ones shown in the algorithm description) as keys and the filepaths of those outputs as values. To add all the outputs generated by an algorithm, pass that dictionary to the loadFromAlg() method. You can also load an individual layer passing its filepath to the load() method.

Criando scripts e executando-os na caixa de ferramentas

You can create your own algorithms by writing the corresponding Python code and adding a few extra lines to supply additional information needed by SEXTANTE. You can find a Create new script under the tools group in the script algorithms block of the toolbox. Double click on it to open the script edition dialog. That’s where you should type your code. Saving the script from there in the scripts folder (the default one when you open the save file dialog), with .py extension, will automatically create the corresponding algorithm.

O nome do algoritmo (que você vai ver na caixa de ferramentas) é criado a partir do nome do arquivo, removendo a sua extensão e substituindo os underlines por espaços em branco.

Let’s have the following code, which calculates the Topographic Wetness Index (TWI) directly from a DEM

##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)

Como você pode ver, envolve três algoritmos, todos eles provenientes do provedor SAGA. O último deles calcula o TWI, mas precisa de uma camada de encostas e uma camada de acumulação de fluxo. Nós não temos estes, mas já que temos o MDE, podemos calculá-los por meio dos algoritmos SAGA correspondentes.

A parte do código onde esse processamento ocorre não é difícil de entender se você leu as seções anteriores deste capítulo. As primeiras linhas, no entanto, precisam de alguma explicação adicional. Elas fornecem ao SEXTANTE as informações que precisa para transformar seu código em um algoritmo que pode ser executado a partir de qualquer um de seus componentes, como a caixa de ferramentas ou o modelador gráfico.

These lines start with a double Python comment symbol and have the following structure:

[parameter_name]=[parameter_type] [optional_values]

Here is a list of all the parameter types that SEXTANTE supports in its scripts, their syntax and some examples.

  • raster. Camada raster

  • vector. Camada Vetorial

  • table. Tabela

  • number. Um valor numérico. Um valor padrão deve ser fornecido. Por exemplo, depth=number 2.4

  • string. Um campo de texto. Tal como no caso de valores numéricos, um valor por padrão deve ser adicionado. Por exemplo, name=string Victor

  • boolean. Um valor booleano. Adicione True ou False depois de definir o valor padrão. Por exemplo, verbose=boolean True

  • multiple raster. Conjunto de camadas raster de entrada.

  • multiple vector. Conjunto de camadas vetoriais.

  • field. Um campo na tabela de atributos de uma camada vetorial. O nome da camada tem que ser adicionada depois do parâmetro campo. Por exemplo, se você tem declarado um vetor de entrada com mylayer=vector, você poderia usar myfield=field mylayer para adicionar um campo á camada, como parâmetro.

  • folder. Pasta

  • file. Nome do arquivo

O nome do parâmetro é o nome que será mostrado para o usuário quando o algoritmo for executado, é também o nome da variável para usar no código do script. O valor digitado pelo usuário para esse parâmetro será atribuído a uma variável com esse nome.

When showing the name of the parameter to the user, SEXTANTE will edit it to improve its appearance, replacing low hyphens with blankspaces. So, for instance, if you want the user to see a parameter named A numerical value, you can use the variable name A_numerical_value.

Camadas e valores de tabelas são seqüências contendo o conjunto de arquivos do objeto correspondente. Para transformá-los em um objeto QGIS, você pode usar a função sextante.getObjectFromUri(). Várias entradas também têm um valor de seqüência, que contém os caminhos de arquivos de todos os objetos selecionados, separados por ponto e vírgula.

As saídas são definidas de uma maneira semelhante, utilizando-se as seguintes tags:

  • output raster
  • output vector
  • output table
  • output html
  • output file
  • output number
  • output string

The value assigned to the output variables is always a string with a filepath. It will correspond to a temporary filepath in case the use has not entered any output filename.

Quando for declarado uma saída, o SEXTANTE vai tentar adicioná-la ao QGIS uma vez que o algoritmo for concluído. Essa é a razão por que, embora o método runalg() não carrega as camadas que produz, a camada TWI final será carregada, uma vez que for salvo o arquivo digitado pelo usuário, que é o valor correspondente ao campo de saída.

Não use a o método load() em algoritmos, mas apenas quando se trabalha com a linha de console. Se a camada é criada como saída de um algoritmo, que deve ser declarado como tal. Caso contrário, você não será capaz de usar adequadamente o algoritmo no modelador, pois corre o risco de sua sintaxe (como definido pelas tags, explicado acima) não coincidir com o que o algoritmo realmente produz.

Saídas ocultas (números e textos) não têm um valor. Em vez disso, é o usuário quem tem que atribuir um valor a eles. Para isso, basta definir o valor de uma variável com um nome para declarar a saída. Por exemplo, se você usou esta declaração,

##average=output number

a seguinte linha irá definir o valor da saída para 5:

average = 5

Além das tags para os parâmetros e as saídas, você também pode definir o grupo em que o algoritmo será mostrado, usando a tag group.

Se o algoritmo leva um longo tempo para processar, é uma boa idéia informar ao usuário. Você tem um progresso global chamado progress, com dois métodos disponíveis: setText(text) e ``setPercentage(percent)` para modificar o texto de progresso e a barra de progresso.

Several examples are provided with SEXTANTE. Please, check them to see real examples of how to create algorithms using this feature of SEXTANTE. You can right-click on any script algorithm and select Edit script to edit its code or just to see it.

Documentando seus scripts

As in the case of models, you can create additional documentation for your script, to explain what they do and how to use them. In the script editing dialog you will find a [Edit script help] button. Click on it and it will take you to the help editing dialog. Check the chapter about the graphical modeler to know more about this dialog and how to use it.

Help files are saved in the same folder as the script itself, adding the .help extension to the filename. Notice that you can edit your script’s help before saving it for the first time. If you later close the script editing dialog without saving the script (i.e. you discard it), the help content you wrote will be lost. If your script was already saved and is associated to a filename, saving is done automatically.