Escrevendo novos algoritmos de processamento com scripts python¶

Você pode criar seus próprios algoritmos escrevendo com o código Python correspondente e adicionando algumas linhas extras para fornecer informações adicionais necessárias para definir a semântica do algoritmo. Você pode encontrar um menu Criar um novo script no grupo Ferramentas no bloco algoritmo Script da caixa de ferramentas. Dê um duplo clique sobre ele para abrir o diálogo edição script. É onde você deve digitar seu código. Salvando o script na pasta:` scripts` (o padrão quando você abrir o diálogo de salvar o arquivo), com: file:` extensão .py`, criará automaticamente o algoritmo correspondente.

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

Vamos ter o seguinte código, que calcula o índice de vertente topográfica (TWI) diretamente de um MDE

##dem=raster
##twi=output raster
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea", dem,
                0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindextwi, ret_slope['SLOPE'],
                ret_area['AREA'], None, 1, 0, twi)

Como você pode ver, envolve 3 algoritmos, todos eles provenientes da SAGA. O último deles calcula o TWI, mas precisa de uma camada de inclinação e uma camada de acumulação de fluxo. Não temos estas, mas uma vez que temos o MDE, podemos calculá-los chamando os algoritmos SAGA correspondentes.

A parte do código onde esta transformação substitui não é difícil de entender se você já leu o capítulo anterior. As primeiras linhas, no entanto, precisam de alguma explicação adicional. Eles fornecem a informação que é necessário para transformar o seu código em um algoritmo que pode ser executado a partir de qualquer um dos componentes da GUI, como a caixa de ferramentas ou o modelador gráfico.

Estas linhas de começo com um comentário símbolo duplo 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 suportadas no processamento de scripts, sua sintaxe e alguns exemplos.

raster. Uma camada raster
vetor. Uma camada vetor
tabela. Uma tabela
número. Um valor numérico. Um valor padrão deve ser fornecido. Por exemplo, profundidade=número 2.4
string. Uma cadeia de texto. Como no caso de valores numéricos, um valor padrão deve ser adicionado. Por exemplo, nome=texto Vitor
longstring. Igual um texto, mas uma caixa de texto maior será mostrado, por isso, é mais adequado para textos longos, como para um script esperam um trecho de código pequeno.
`` booleano``. Um valor booleano. Adicionar Verdadeiro ou `` Falso`` depois dele, para definir o valor padrão. Por exemplo, verbose=booleano Verdadeiro.
raster multiplo. Um conjunto de camadas raster de entrada.
vetor multiplo. Um conjunto de camadas vetor de entrada.
Campo. Um campo na tabela de atributos de uma camada de vetor. O nome da camada tem que ser adicionado após a tag Campo. Por exemplo, se você declarou um vetor de entrada com minhacamada=vetor, você poderia usar o minhacamada=campo minhacamada para adicionar um campo a partir dessa camada como parâmetro.
pasta. Um pasta
arquivo. Um arquivo
src. Um Sistema de Referência de Coordenada

O nome do parâmetro é o nome que será mostrado para o usuário durante a execução do algoritmo, e também o nome da variável a ser usado no código de script. O valor digitado pelo usuário para esse parâmetro será atribuído a uma variável com esse nome.

Ao mostrar o nome do parâmetro para o nome, o usuário irá editado-lo para melhorar a sua aparência, substituindo hífens baixos com espaços. Assim, por exemplo, se você quiser que o usuário veja um parâmetro denominado Um valor numérico, você pode usar o nome da variável A_numerical_value.

Valores de tabelas e camadas são sequências contendo o caminho de arquivo do objeto correspondente. Para transformá-los em um objeto do QGIS, você pode usar a função processing.getObjectFromUri(). Várias entradas também têm um valor de texto, que contém os caminhos de arquivos para todos os objetos selecionados, separados por ponto e vírgula (;).

Saídas são definidas de forma 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
texto de saída
extensão de saída

O valor atribuído às variáveis de saída é sempre um texto com um caminho de arquivo. Ele vai corresponder a um caminho de arquivo temporário, caso o usuário não informe qualquer arquivo de saída.

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

A última marca que você pode usar em seu cabeçalho roteiro é ##nomodeler. Use isso quando você não quer que seu algoritmo seja mostrado na janela de modelador. Isto deve ser utilizado para algoritmos que não têm uma sintaxe clara (por exemplo, se o número de camadas a serem criadas não é conhecido antecipadamente, a tempo de desenho), o que os torna inadequados para a modelagem gráfica

Entregando os dados produzidos pelo algoritmo¶

Quando você declara uma saída que representa uma camada (raster, vetor ou tabela), o algoritmo irá tentar adicioná-la ao QGIS uma vez que ela for concluída. Essa é a razão pela qual, apesar de o método runalg() não carregar as camadas que produz, a camada final TWI será carregada, uma vez que será salva no arquivo digitado pelo usuário, que é o valor da saída correspondente.

Não use o método load() em seus algoritmos de script, mas apenas quando se trabalha com a linha de console. Se uma camada é criada como saída de um algoritmo, que deve ser declarada como tal. Caso contrário, você não será capaz de usar corretamente o algoritmo no modelador, desde a sua sintaxe (como definido pelas etiquetas explicadas acima) não coincidir com o que o algoritmo realmente cria.

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

##average=output number

a seguinte linha foi definido o valor de saída para 5:

average = 5

Comunicação com o usuário¶

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

Se você tiver que fornecer algumas informações para o usuário, não relacionada com a evolução do algoritmo, você pode usar o método SetInfo (texto), também o progresso do objeto.

Se o seu script tiver algum problema, a maneira correta de propagação é para levantar uma exceção do tipo GeoAlgorithmExecutionException(). Você pode passar uma mensagem como argumento para o construtor da exceção. Processing vai cuidar de manuseá-lo e se comunicar com o usuário, dependendo de onde o algoritmo estiver sendo executado a partir da (caixa de ferramentas, modelador, console do Python ...)

Documentando seus scripts¶

Como no caso dos modelos, você pode criar a documentação adicional para o seu roteiro, para explicar o que eles fazem e como usá-los. Na caixa de diálogo de edição de script que você vai encontrar o botão [Editar roteiro ajuda]. Clique nele e ele irá levá-lo para o diálogo ajuda a edição. Confira o capítulo sobre o modelador gráfico para saber mais sobre este diálogo e como usá-lo.

Arquivos de ajuda são salvos na mesma pasta que o próprio script, acrescentando a extensão .help ao nome do arquivo. Observe que você pode editar a ajuda de seu script antes de salvá-la pela primeira vez. Se mais tarde você fechar o script de diálogo edição sem salvar o script (ou seja, você descartá-lo), o conteúdo da ajuda que você escreveu sera perdidos. Se o seu roteiro já foi salvo e está associado a um nome de arquivo, a gravação será feita automaticamente.

Exemplos de scripts¶

Vários exemplos estão disponíveis na coleção on-line de scripts, que podem ser acessados selecionando o script Adquirir script da coleção on-line a ferramenta sob o Scripts/ferramentas entrada na caixa de ferramentas.

Por favor, verifique-os para ver exemplos reais de como criar algoritmos usando as classes de estrutura de processamento. Você pode clicar o botão direito do mouse em qualquer algoritmo de roteiro e escolha: guilabel: Editar script para editar o seu código ou apenas para vê-lo.

Melhores práticas para algoritmos de script escrito¶

Here’s a quick summary of ideas to consider when creating your script algorithms and, especially, if you want to share with other QGIS users. Following these simple rules will ensure consistency across the different Processing elements such as the toolbox, the modeler or the batch processing interface.

Não coloque resultados das camadas. Vamos trabalhar o Processamento com seus resultados e carregar suas camadas se necessárias.
Always declare the outputs your algorithm creates. Avoid things such as declaring one output and then using the destination filename set for that output to create a collection of them. That will break the correct semantics of the algorithm and make it impossible to use it safely in the modeler. If you have to write an algorithm like that, make sure you add the ##nomodeler tag.
Não mostrar caixas de mensagens ou usar qualquer elemento GUI do script. Se você quer se comunicar com o usuário, use o método SetInfo()``ou lançar uma ``GeoAlgorithmExecutionException
As a rule of thumb, do not forget that your algorithm might be executed in a context other than the Processing toolbox.

Pré e pós-execução de ganchos de script¶

Os scripts também pode serem usados para definir ganchos pré e pós-execução que são executados antes e depois que algoritmo seja executado. Esta pode ser usada para automatizar as tarefas que devem ser executadas sempre que um algoritmo é executado.

A sintaxe é idêntica à sintaxe explicada acima, mas uma variável global adicional chamado alg está disponível, que representa o algoritmo que acaba de ser (ou está prestes a ser) executado.

No grupo Geral da janela de configuração de processamento, você vai encontrar duas entradas com o nome Arquivo de script de pré-execução e Arquivo de script de pós-execução onde o nome do arquivo dos scripts a serem executado em cada caso, podem ser inseridos.

Tabela de Conteúdos