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

.

Изпользование алгоритмов геообработки в консоли

Консоль позволяет опытным пользователям повысить продуктивность и выполнение более сложных действий, которые не могут быть выполнены при использовании любого другого GUI (ГИП - графический интерфейс пользователя). Разные алгоритмы могут быть определены используя строчно-командный интерфейс, а также, дополнительные действия, такие как: цикличность и условные команды могут быть добавлены для более высокой гибкости и продуктивного рабочего процесса.

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 commands into your console work and connect processing algorithms to all the other features (including methods from the QGIS API) available from there.

Код, выполняемый в консоли Python, даже если он не вызывает ни одного алгоритма платформы геообработки, может быть преобразован в новый алгоритм, который в дальнейшем может вызываться из панели инструментов или использоваться в редакторе моделей, как любой другой алгоритм. Более того, некоторые алгоритмы, которые вы видите в панели инструментов, на самом деле являются обычными скриптами.

In this section, we will see how to use processing algorithms from the QGIS Python console, and also how to write algorithms using Python.

Вызов алгоритмов из консоли Python

ервое, что нужно сделать при использовании платформы геообработки из командной строки — импортировать модуль processing:

>>> import processing

Now, there is basically just one (interesting) thing you can do with that from the console: 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 parameters 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 your console:

>>> processing.alglist()

На консоль будет выведено что-то вроде этого

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

Это список всех активных алгоритмов, отсортированный в алфавитном порядке (слева название, справа — внутренее имя).

You can use a string as a parameter for this method. Instead of returning the full list of algorithms, it will only display those that include that string. If, for instance, you are looking for an algorithm to calculate slope from a DEM, type alglist("slope") to get the following result:

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]

Вывод может несколько отличаться, т.к. он зависит от доступных у вас алгоритмов.

Теперь намного легче найти имя необходимого алгоритма, в нашем случае saga:slopeaspectcurvature.

Once you know the command-line name of the algorithm, the next thing to do is to determine 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 algorithm requires and the outputs that it will generate. To get this information, you can use the alghelp(name_of_the_algorithm) method. Use the command-line name of the algorithm, not the full descriptive name.

Calling the method with saga:slopeaspectcurvature as parameter, you get the following description:

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

Теперь у нас есть вся необходимая для запуска алгоритма информация. Как уже было сказано, запуск алгоритма выполняется при помощи метода runalg(). Он имеет следующий синтаксис:

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

Список параметров и результатов зависит от алгоритма, и должен указываться в том порядке, в котором их выдаёт метод alghelp().

Depending on the type of parameter, values are introduced differently. The next list gives 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.

  • выбор из списка предустановленных значений. Значение указывается как целочисленный индекс, соответствующий значению. Получить список доступных значений и соответствующие им индексы можно при помощи метода algoptions(). Например:

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

    In this case, the algorithm has one such parameter, with seven options. Notice that ordering is zero-based.

  • 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 file path.

  • имя поля. Регистрозависимое название поля атрибутивной таблицы

  • 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 2-D array of values representing the table.

  • система координат. Указывается код EPSG нужной системы координат

  • охват. Значения xmin, xmax, ymin и ymax, разделенные запятыми (,).

Логические, строковые и числовые значения, а также пути к файлам в дополнительных пояснениях не нуждаются.

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

For output data objects, type the file path to be used to save it, just as it is done from the toolbox. If you want to save the result to a temporary file, use None. The extension of the file determines the file format. If you enter a file extension not supported by the algorithm, the default file format for that output type will be used, and its corresponding extension appended to the given file path.

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 the map canvas, 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 tasks.

The runalg method returns a dictionary with the output names (the ones shown in the algorithm description) as keys and the file paths of those outputs as values. You can load those layers by passing the corresponding file paths 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 these commands. More information can be found in the classes under the processing/tools package, and also in the example scripts provided with 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): Returns the values in the attributes table of a vector layer, for the passed fields. Fields can be passed as field names or as zero-based field indices. Returns a dict of lists, with the passed field identifiers as keys. It considers the existing selection.
  • features(layer): Returns an iterator over the features of a vector layer, considering the existing selection.
  • uniqueValues(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.

Создание скриптов и из запуск

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 editing dialog. That’s where you should type your code. Saving the script from there in the scripts folder (the default folder when you open the save file dialog) with .py extension will automatically create the corresponding algorithm.

Имя файла будет использоваться в качестве имени алгоритма в панели инструментов (при этом расширение отбрасывается, а подчеркивания заменяются пробелами).

Let’s have a look at 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, the calculation involves three algorithms, all of them coming from SAGA. The last one calculates the TWI, but it needs a slope layer and a flow accumulation layer. We do not have these layers, but since we have the DEM, we can calculate them by calling the corresponding SAGA algorithms.

Если вы внимательно читали предыдущий раздел, разобраться в коде будет достаточно легко. Сейчас наибольший интерес для нас представляют первые три строчки, начинающиеся символами ##. Эти строки, необходимы для правильной работы со скриптом, именно они позволяют выполнять скрипт, а также использовать его в моделях, как и любой другой алгоритм.

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 processing scripts, their syntax and some examples.

  • raster. A raster layer.
  • vector. A vector layer.
  • table. A table.
  • number. A numerical value. A default value must be provided. For instance, depth=number 2.4.
  • string. A text string. As in the case of numerical values, a default value must be added. For instance, name=string Victor.
  • boolean. A boolean value. Add True or False after it to set the default value. For example, verbose=boolean True.
  • multiple raster. Набор растровых слоёв

  • multiple vector. Набор векторных слоёв

  • field. Поле атрибутивной таблицы, необходимо указать слой или таблицу, из которого будет браться поле. Например, если задан параметр mylayer=vector, то поле атрибутивной таблицы слоя mylayer описывается так myfield=field mylayer

  • folder. A folder.
  • file. A filename.

Название параметра будет использоваться как в качестве подписи соответствующего поля ввода при запуске алгоритма, так и в качестве переменной внутри скрипта, которой будет присвоено введенное пользователем значение.

When showing the name of the parameter to the user, the name will be edited 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 table values are strings containing the file path 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 file paths to all selected object, separated by semicolons (;).

Результаты описываются точно также, с использованием следующих типов:

  • output raster
  • output vector
  • output table
  • output html
  • output file
  • output number
  • output string

The value assigned to the output variables is always a string with a file path. It will correspond to a temporary file path in case the user has not entered any output filename.

When you declare an output, the algorithm will try to add it to QGIS once it is finished. That is why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded (using the case of our previous example), since it is saved to the file entered by the user, which is the value of the corresponding output.

Do not use the load() method in your script algorithms, just when working with the console line. If a layer is created as output of an algorithm, it should be declared as such. Otherwise, you will not be able to properly use the algorithm in the modeler, since its syntax (as defined by the tags explained above) will not match what the algorithm really creates.

Hidden outputs (numbers and strings) do not have a value. Instead, you have to assign a value to them. To do so, just set the value of a variable with the name you used to declare that output. For instance, if you have used this declaration,

##average=output number

следующая строка установит значение выходного параметра равным 5:

average = 5

В дополнение к тегам параметров и результатов, можно задавать группу, в которой будет отображаться новый алгоритм. Для этого служит тег group.

If your algorithm takes a long time to process, it is a good idea to inform the user. You have a global named progress available, with two possible methods: setText(text) and setPercentage(percent) to modify the progress text and the progress bar.

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 scripts, to explain what they do and how to use them. In the script editing dialog, you will find an [Edit script help] button. Click on it and it will take you to the help editing dialog. Check the section 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 the script 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 the help content is done automatically.

Хуки пред- и постобработки

Скрипты также могут использоваться для создания хуков пред- и постобработки, которые будут выполняться перед запуском алгоритма и по окончанию обработки. Эта возможность может пригодиться для автоматизации задач, выполняемых перед обработкой данных.

Синтаксис идентичек описанному выше, в дополнение доступна глобальная переменная alg, являющаяся алгоритмом, которы был (или будет) выполнен.

In the General group of the processing configuration 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.