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.
The name of the algorithm (the one you will see in the toolbox) is created from the filename, removing its extension and replacing underscores with blank spaces.
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)
As you can see, it involves 3 algorithms, all of them coming from SAGA. The last one of them calculates the TWI, but it needs a slope layer and a flow accumulation layer. We do not have these, but since we have the DEM, we can calculate them by calling the corresponding SAGA algorithms.
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]
Here is a list of all the parameter types that are supported in processing scripts, their syntax and some examples.
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.
- extent. A spatial extent defined by xmin, xmax, ymin, ymax
pasta. Um pasta
arquivo. Um arquivo
src. Um Sistema de Referência de Coordenada
- selection. A dropdown menu that allows the user to select from a pre-populated list. For example units=selection sq_km;sq_miles;sq_degrees
- name. Name of the script. This will be displayed as the algorithm name in the processing toolbox. For example My Algorithm Name=name
- group. Folder name where the script will appear in the Processing Toolbox. For Example, adding Utils=groups will put the script within a Utils folder within Scripts.
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.
When showing the name of the parameter to the user, the name will be edited to improve its appearance, replacing underscores with spaces. 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.
Layers and tables values are strings containing the filepath of the corresponding object. To turn them into a QGIS object, you can use the processing.getObjectFromUri() function. Multiple inputs also have a string value, which contains the filepaths to all selected objects, separated by semicolons (;).
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¶
When you declare an output representing a layer (raster, vector or table), the algorithm will try to add it to QGIS once it is finished. That is the reason why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded, since it is saved to the file entered by the user, which is the value of the corresponding output.
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¶
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 find out 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. Note 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 with a filename, saving is done automatically.
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.