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¶

Aqui está um rápido resumo das idéias a serem consideradas ao criar seus algoritmos de script e, essecialmente, se você quer compartilhar com outros usuários do QGIS. Seguindo estas regras simples irá assegurar a coerência entre os diferentes elementos de processamento, tais como a caixa de ferramentas, o modelador ou a interface de processamento em lote.

Não coloque resultados das camadas. Vamos trabalhar o Processamento com seus resultados e carregar suas camadas se necessárias.
Sempre declare as saídas de seu algoritmo criadas. Evite coisas como decalring uma saída e, em seguida, usando o nome do arquivo de destino definido para que a saída para criar uma coleção deles. Isso vai quebrar a semântica correta do algoritmo e tornar impossível usá-lo com segurança no modelador. Se você tem que escrever um algoritmo assim, certifique-se de adicionar a etiqueta ##nomodeler.
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
Como regra geral, não se esqueça que o seu agoritmo pode ser executado em um contexto que não seja a caixa de ferramentas de processamento.

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