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

.

Usando os algoritmos do processamento a partir do Terminal Python.

O terminal permite que usuários avançados aumente sua produtividade e execute operações complexas que não podem ser utilizados através dos outros elementos GUI da caixa de processamento. Modelos envolvendo vários algoritmos podem ser definidos usando a interface de linha de comando e operações adicionais como loops e sentenças condicionais podem ser adicionados para criar fluxos de trabalho mais flexíveis e poderosos.

Não há um terminal de processamento específico no QGIS, mas todo os comandos de processamentos estão disponíveis embutidos no Terminal Python em vez do QGIS. Isso significa que poderá incorporar os comandos em seu terminal de trabalho e conectar algoritmos de processamentos de todos os outros recursos disponíveis (incluindo métodos da | qg | API) a partir deste terminal.

O código que pode executar a partir do Terminal Python, mesmo quando não chama nenhum método específico do processamento, pode ser convertido num novo algoritmo que pode mais tarde chamar da caixa de ferramentas, o modelador gráfico ou qualquer outro componente, como faz para outro algoritmo. De fato, alguns algoritmos que encontra na caixa de ferramentas são scripts simples.

Nesta seção, veremos como usar algoritmos de processamento do QGIS console Python e também a forma de escrever algoritmos usando Python.

Chamando os algoritmos a partir do Terminal Python

A primeira coisa que tem de fazer é importar as funções do processamento com a seguinte linha:

>>> import processing

Agora, basicamente é uma (interessante) coisa que pode fazer a partir do terminal: executar um algoritmo. Isso é feito usando o método runalg(), que toma o nome do algoritmo a ser executado como o seu primeiro parâmetro, então o número da variável de um parâmetro adicional depende dos requisitos do algoritmo. Portanto a primeira coisa que necessita saber é o nome do algoritmo a executar. Não será o nome que vê na caixa de ferramentas, mas um único nome da linha de comando. Para encontrar o nome correto do seu algoritmo, pode usar o método alslist(). Introduza a seguinte linha no seu terminal:

>>> processing.alglist()

Irá ver algo como isto.

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

Esta é a lista de todos os algoritmos disponíveis, ordenados alfabeticamente, juntamente com os seus nomes da linha de comandos correspondentes.

É possível usar uma cadeia 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 esta cadeia. Se, por exemplo, está procurando um algoritmo para calcular a 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.

Assim é mais fácil encontrar o algoritmo que procura e o seu nome da linha de comandos, neste caso saga:slopeaspectcurvature.

Uma vez conhecido o nome da linha de comandos do algoritmo, a próxima coisa a fazer é determinar a sintaxe correta para executá-lo. Isto significa saber quais os parâmetros necessários e a ordem que devem passar quando chamado pelo método runalg(). Existe um método para descrever um algoritmo em detalhe, o qual pode ser usado para obter uma lista de parâmetros que requer uns algoritmos e os arquivos de saída que irão gerar. Para fazer isso, pode usar o método alghelp(name_of_the_algorithm). Use o nome do algoritmo na linha de comando, não o nome descritivo completo.

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

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

Agora tem tudo o que necessita para correr qualquer algoritmo. Como já tínhamos mencionado, existe apenas um comando para executar algoritmos: runalg(). A sua síntaxe é como está descrito a seguir:

>>> processing.runalg(name_of_the_algorithm, param1, param2, ..., paramN,
         Output1, Output2, ..., OutputN)

A lista de parâmetros e arquivos de saída para adicionar dependem do algoritmo que quer correr, e é exatamente a lista que o método alghelp() lhe dá, na mesma ordem que é exibido.

Dependendo do tipo de parâmetro, os valores são introduzidos diferentemente. A próxima explicação é uma rápida revisão de como introduzir valores para cada tipo de parâmetro de entrada:

  • Camada Raster, Camada Vetorial e Tabela. Simplesmente usa uma cadeia de texto com nome que identifica o objeto de dados a usar ( o nome está na Tabela de Conteúdos do QGIS) ou o nome do arquivo (se a camada correspondente não for aberta, mas não adicionada no enquadramento do mapa). Se tiver uma instância do objeto QGIS representado na camada, pode também passá-lo como parâmetro. Se o arquivo de entrada for opcional e não quer usá-lo como qualquer tipo de objeto de dados, use None.

  • Seleção. Se algum algoritmo tiver um parâmetro de seleção, o valor desse parâmetro deve ser introduzido usando um valor inteiro. Para saber as opções disponíveis, pode usar o comando algoptions(), como é exibido no seguinte exemplo:

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

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

  • Múltiplas entradas. O valor é uma cadeia de texto com descritores de entrada separados por ponto e vírgula (;). Como no caso das camadas ou tabelas únicas, cada descritor de entrada pode ser o nome do objeto ou o caminho do arquivo.

  • Campo da Tabela de XXX. Use uma cadeia de texto com o nome do campo a usar. O parâmetro é caso sensitivo.

  • Tabela Fixa. Digite a lista de todos os valores da tabela separadas por vírgulas (,) e feche entre aspas ("). Os valores começam na linha superior e vai da esquerda para a direita. Pode também usar uma matriz 2D de valores que representam a tabela.

  • SRC. Introduza o número do código EPSG do SRC desejado.

  • Extensão. Deve usar uma cadeia de texto com xmin, xmax, ymin e ymax valores separados por vírgulas (,).

Os parâmetros booleanos, de arquivo, cadeia de texto e numéricos não necessitam de explicações adicionais.

Input parameters such as strings, booleans, or numerical values have default values. To use them, specify None for the corresponding parameter entry.

Para objetos de saída de dados, digite o caminho de arquivo a ser utilizado para salvá-lo, como é feito a partir da caixa de ferramentas. Caso queira 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 suportada pelo algoritmo, será utilizado o formato de arquivo padrão para esse tipo de saída e a sua extensão correspondente anexado ao conjunto de arquivos de dados.

Contrariamente, quando o algoritmo é executado a partir da caixa de ferramentas, osarquivos de saída não são adicionados ao enquadramento do mapa se executar o mesmo algoritmo a partir do Terminal Python. Se quiser adicionar um arquivo de saída, você tem de adicioná-lo depois de correr o algoritmo, Para o fazer, pode usar os comandos do API QGIS ou, mais fácil, use um dos métodos úteis para esta tarefa.

O método runalg retorna um dicionário com os nomes de saída (os que são exibidos na descrição do algoritmo) como chaves ou caminhos de arquivo dessas saídas como valores. Pode carregar essas camadas passando o seu caminho de arquivo correspondente pelo método load().

Funções adicionais para a manipulação dos dados

Além das funções usadas para chamar os algoritmos, importar o pacote processamento irá também importar algumas funções adicionais que facilitará o trabalho dos dados, particularmente os dados vetoriais. São funções de conveniência que envolvem alguma funcionalidade a partir da API do QGIS, usualmente com uma sintaxe menos complexa. Estas funções devem ser usadas quando são programados novos algoritmos, para tornar mais fácil a operação com o os dados de entrada.

Abaixo está uma lista de algum dos comandos. Mais informação podem ser encontradas nas classes sob o pacote processing/tools e também nos exemplos de script fornecidos no QGIS.

  • getobject(obj): Returns a QGIS object (a layer or table) from the passed object, which can be a filename or the name of the object in the QGIS Table of Contents.
  • values(layer,fields): Retorna os valores da tabela de atributos de uma camada vetorial para os campos validados. Os campos podem ser validados como nomes de campos ou índices de campo iniciados em zero. Retorna um dicionário de listas com campos de identificadores validados como chaves. Considera a seleção existente.

  • getfeatures(layer): Returns an iterator over the features of a vector layer, considering the existing selection.
  • uniquelabels(layer, field): Returns a list of unique values for a given attribute. Attributes can be passed as a field name or a zero-based field index. It considers the existing selection.

Criando scripts e correndo-os a partir da caixa de ferramentas

Pode criar os seus próprios algoritmos através da escrita do código Python correspondente e adicionar algumas linhas extras para fornecer informação adicional necessária para definir as semânticas do algoritmo. Pode encontrar um Criar novo script menu sob o :guilabel: Tools no grupo Script bloco de algoritmos da caixa de ferramentas. Faça duplo clique nele e irá abrir um diálogo de edição do script. É onde deverá digitar o código. Guarde o script na pasta scripts (a pasta padrão quando abre o diálogo de guardar ficheiro), com a extensão .py, irá automaticamente criar o algoritmo correspondente.

O nome do algoritmo (aquele que irá ver na caixa de ferramentas) é criado a partir do nome do arquivo, removendo a extensão e substituindo os hífens inferiores com espaços em branco.

Vamos ter o seguinte código, que calcula o Índice Topográfico de Umidade (ITW) diretamente do MDE.

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

Como pode ver, o cálculo envolve 3 algoritmos, todos eles provêem do SAGA. O último deles calcula o ITW, mas necessita da camada de dados do declive e outra de acumulação de escoamento. Nós não temos estas camadas, mas uma vez que temos o MDE, podemos calculá-los chamando os algoritmos SAGA correspondentes.

A parte do código onde este processamento tem lugar não é difícil de perceber se leu-o as seções anteriores deste capítulo. Contudo, as primeiras linhas, necessitam de uma explicação adicional. Eles fornecem a informação que é necessária para tornar o código num algoritmo que possa ser corrido a partir qualquer componente do GUI, como por exemplo a caixa de ferramentas ou o modelador gráfico.

Estas linhas começam com o símbolo de duplo comentário Python (##) e tem a seguinte estrutura:

[parameter_name]=[parameter_type] [optional_values]

Aqui está uma lista de todos os tipos de parâmetros que são suportados nos scripts de processamento, sua sintaxe e alguns exemplos.

  • raster. Uma camada raster.

  • vector. Uma camada vetorial.

  • table. Uma tabela.

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

  • string. Um campo de texto. 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

  • múltiplos raster. Um conjunto de camadas rasters de entrada.

  • vetores múltiplos. Um conjunto de camadas vetoriais de entrada.

  • campo. Um campo da tabela de atributos de uma camada vetorial. O nome da camada tem de ser adicionada depois da etiqueta campo. Por exemplo, se declarou um arquivo de entrada vetorial com mylayer=vector, poderá usar myfield=field mylayer para adicionar o campo a partir dessa camada como parâmetro.

  • folder`. Uma pasta.

  • file`. Nome do arquivo

O nome do parâmetro é o nome que será exibido ao utilizado quando executa o algoritmo, e também o nome da variável a usar no código do script. O valor introduzido pelo usuário para esse parâmetro será atribuído à variável com esse nome.

Quando é exibido o nome do parâmetro ao usuário, o nome irá ser editado para melhorar a aparência, substituindo o hífen inferior com espaços. Portanto, por exemplo, se quer que o usuário veja o parâmetro chamado Um valor numérico, pode usar o nome da variável A_numerical_value.

Os valores das camadas e tabelas são cadeias de texto que contêm caminhos de arquivos para o objeto correspondente. Para transformá-los em objetos|qg|, pode usar a função processing.getObjectFromUri(). Os múltiplos dados de entrada também têm um valor de cadeia de texto, que contêm caminhos de arquivos para todos os objetos selecionados, separados por ponto e vírgulas (;).

Os arquivos de saída são definidos numa maneira semelhante, usando as seguintes etiquetas:

  • raster de saída

  • vetor de saída

  • tabela de saída

  • html de saída

  • arquivo de saída

  • número de saída

  • cadeia de texto de saída

O valor atribuído às variáveis ​​de saída sempre são conjuntos de caracteres que representam o caminho dos arquivos. Corresponderá a um caminho de arquivos temporários, caso o usuário não inserir um nome de arquivo de saída.

Quando declara um arquivo de saída, o algoritmo irá tentar adicioná-lo no QGIS uma vez finalizado. É por isso que, embora o método runalg() não carrega camadas quando as produz, a camada TWI final será carregada ( usando o caso do nosso exemplo anterior) uma vez que é salvo no arquivo digitado pelo usuário, que é o valor do arquivo de saída correspondente.

Não use a o método load() nos algoritmos, mas apenas quando se trabalha com a linha do terminal. Se a camada é criada como saída de um algoritmo, deve ser declarado como tal. Caso contrário, você não será capaz de usar adequadamente o algoritmo no modelador, desde 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 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 linha seguinte irá configurar o valor de saída para 5:

average = 5

Em adição às etiquetas para os parâmetros e arquivos de saída, pode também definir o grupo onde o algoritmo será exibido, usando a etiqueta group.

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

Vários exemplos são apresentados. Por favor, verifique-os para ver exemplos reais de como criar algoritmos usando as classes do quadro de processamento. Pode clicar com o botão direito do mouse em qualquer script do algoritmo e selecionar Editar script para editar o seu código ou apenas para vê-lo.

Documentando os seus scripts

Como no caso dos modelos, você pode criar documentação adicional para o seu script, para explicar o que fazem e como são usados. No diálogo de edição do script irá encontrar um botão [Editar ajuda do script]. Clique nele e irá levá-lo para o diálogo de edição da ajuda. Verifique o capítulo sobre o modelador gráfico para saber mais sobre este diálogo e como usá-lo.

Os arquivos de ajuda são salvos na mesma pasta como o próprio script, adicionando a extensão .help ao nome do ficheiro. Note que, você pode editar a ajuda do seu script antes de guardá-lo pela primeira vez. Se fechar mais tarde o diálogo de ajuda do script sem salvar o script (ex.: descartá-lo) o conteúdo da ajuda que escreveu será perdido. Se o seu script já estiver salvo e associado ao nome do arquvio, o conteúdo de ajuda será salvo automaticamente.

Pré- e pós-execução de encaixe da script

Os scripts podem também ser usados para definir um encaixe de pré- e pós-execução que correm antes e depois do algoritmo correr. Isto pode ser usado para automatizar tarefas que serão executados quando qualquer algoritmo é executado.

A sintaxe é identica à sintaxe explicada em cima, mas uma variável global alg está disponível, representando o algoritmo que foi (ou está prestes a ser) executado.

No grupo General do diálogo de configuração do processamento irá encontrar duas entradas denominados de Pré-execução do arquivo script e Post-execution script filet onde os nomes do arquivo dos scripts a serem executados em cada caso podem ser inseridos.