The console allows advanced users to increase their productivity and perform complex operations that cannot be performed using any of the other GUI elements of the processing framework GUI. Models involving several algorithms can be defined using the command-line interface, and additional operations such as loops and conditional sentences can be added to create more flexible and powerful workflows.
There is not a proccesing console in QGIS, but all processing commands are available instead from the QGIS built-in Python console. That means that you can incorporate those command to your console work and connect processing algorithms to all the other features (including methods from the QGIS API) available from there.
The code that you can execute from the Python console, even if it does not call any specific processing method, can be converted into a new algorithm that you can later call from the toolbox, the graphical modeler or any other component, just like you do with any other algorithm. In fact, some algorithms that you can find in the toolbox are simple scripts.
In this chapter we will see how to use processing algorithms from the QGIS Python console, and also how to write your own algorithms using Python.
The first thing you have to do is to import the processing functions with the following line:
>>> import processing
Now, there is basically just one (interesting) thing you can do with that from the console: to execute an algorithm. That is done using the runalg() method, which takes the name of the algorithm to execute as its first parameter, and then a variable number of additional parameter depending on the requirements of the algorithm. So the first thing you need to know is the name of the algorithm to execute. That is not the name you see in the toolbox, but rather a unique command–line name. To find the right name for your algorithm, you can use the algslist() method. Type the following line in you console:
>>> processing.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.
Once you know the command-line name of the algorithm, the next thing to do is to know the right syntax to execute it. That means knowing which parameters are needed and the order in which they have to be passed when calling the runalg() method. There is a method to describe an algorithm in detail, which can be used to get a list of the parameters that an algorithms require and the outputs that it will generate. To do it, you can use the alghelp(name_of_the_algorithm) method. Use the command-line name of the algorithm, not the full descriptive name.
Se for 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>
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:
>>> processing.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.
Depending on the type of parameter, values are introduced differently. The next one is a quick review of how to introduce values for each type of input parameter:
Raster Layer, Vector Layer or Table. Simply use a string with the name that identifies the data object to use (the name it has in the QGIS Table of Contents) or a filename (if the corresponding layer is not opened, it will be opened, but not added to the map canvas). If you have an instance of a QGIS object representing the layer, you can also pass it as parameter. If the input is optional and you do not want to use any data object, use None.
Selection. If an algorithm has a selection parameter, the value of that parameter should be entered using an integer value. To know the available options, you can use the algoptions() command, as shown in the following example:
>>> 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. Observe que a ordenação é iniciada em zero.
Multiple input. The value is a string with input descriptors separated by semicolons (;). As in the case of single layers or tables, each input descriptor can be the data object name, or its filepath.
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 values 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.
Unlike when an algorithm is executed from the toolbox, outputs are not added to the map canvas if you execute that same algorithm from the Python Console. If you want to add an output to it, you have to do it yourself after running the algorithm. To do so, you can use QGIS API commands, or, even easier, use one of the handy methods provided for such task.
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. You can load those layers by passing its filepath to the load() method.
Apart from the functions used to call algorithms, importing the processing package will also import some additional functions that make it easier to work with data, particularly vector data. They are just convenience functions that wrap some functionality from the QGIS API, usually with a less complex syntax. These functions should be used when developing new algorithms, as they make it easier to operate with input data.
Below is a list of some of this commands. More information can be found in the classes under the processing/tools package, and aso in the example scripts provided with QGIS.
You can create your own algorithms by writing the corresponding Python code and adding a few extra lines to supply additional information needed to define the semantics of the algorithm. You can find a Create new script menu 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 = 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)
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 ones, but since we have the DEM, we can calculate them calling the corresponding SAGA algorithms.
The part of the code where this processing takes place is not difficult to understand if you have read the previous sections in this chapter. The first lines, however, need some additional explanation. They provide the information that is needed to turn your code into an algorithm that can be run from any of the GUI components, like the toolbox or the graphical modeler.
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 are supported in processign 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, the name will be edited it to improve its appearance, replacing low hyphens 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 object, separated by semicolons (;).
As saídas são definidas de uma maneira semelhante, utilizando-se as seguintes tags:
O valor atribuído às variáveis de saída sempre são conjuntos de caracteres que representam o caminho dos arquivos. Caso o usuário não entrar com nenhum caminho, corresponderá a um caminho de arquivos temporários.
When you declare an output, 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 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. Please, check them to see real examples of how to create algorithms using the processing framework classes. You can right-click on any script algorithm and select Edit script to edit its code or just to see it.
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.
Scripts can also be used to set pre- and post-execution hooks that are run before and after an algorithm is run. This can be used to automate tasks that should be performed whenever an algorithm is executed.
The syntax is identical to the syntax explained above, but an additional global variable named alg is available, representing the algorithm that has just been (or is about to be) executed.
In the General group of the processing config dialog you will find two entries named Pre-execution script file and Post-execution script file where the filename of the scripts to be run in each case can be entered.