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

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

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

>>> import processing

Теперь можно использовать платформу геообработки в консоли, а именно запускать алгоритмы на выполнение. Для этого предназначен метод runalg(), которому передаётся имя алгоритма в качестве первого параметра и затем переменный набор дополнительных параметров, зависящий от алгоритма. Таким образом, первое, что необходимо знать — это имя алгоритма. Обратите внимание, в качестве имени алгоритма используется не тот текст, который отображается в панели инструментов, а уникальное внутренее имя алгоритма. Узнать правильное имя можно при помощи метода alglist(). Просто введите в консоли:

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

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

Чтобы не просматривать полный список в поисках нужного алгоритма, можно передать методу строковый параметр, и будут выведены только те алгоритмы, в описании которых есть заданная подстрока. Например, чтобы найти алгоритмы, рассчитывающие уклон по DEM достаточно ввести alglist("slope") и получить следующий результат:

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.

После того как мы узнали имя алгоритма, необходимо выяснить какие параметры ему нужны для работы, т.е. узнать синтаксис вызова. Для этого предусмотрен метод alghelp(имя_алгоритма), который выдаёт список входных параметров, а также список результирующих файлов, генерируемых агоритмом. Единственный аргумент метода — внутренее имя алгоритма, описание которого мы хотим получить.

Например, для алгоритма saga:slopeaspectcurvature будет выведена следующая информация:

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

Значения параметров вводятся в зависимости от их типа. Ниже даётся краткий обзор соглашений, используемых при указании исходных данных разных типов:

• растровый слой, векторный слой или таблица. Можно указывать имя слоя QGIS (если слой загружен в проект), путь к файлу (если слой не загружен). Также можно передавать переменную — экземпляр соответствующего класса QGIS. Если параметр является необязательным и не используется — просто укажите 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)
  

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

• список. Список нескольких элементов, разделенных точкой с запятой (;). В качестве элементов могут быть как имена объектов, так и пути к файлам.

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

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

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

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

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

Такие параметры, как числовые, строковые и логические, могут иметь значения по умолчанию. Чтобы использовать их, укажите None в соответствующей позиции.

Для результатов указывается путь к файлу, или, если он должен сохраняться во временный файл, — None. Формат файла определяется по заданному расширению, если указано неправильное или неподдерживаемое расширение, будет использован формат по умолчанию, и соответствующее расширение будет добавлено к имени файла.

В отличие от запуска алгоритма из панели инструментов, по окончанию обработки результаты не загружаются в проект автоматически. Если вы хотите отобразить результаты, необходимо самостоятельно загрузить их в QGIS после окончания обработки. Сделать это можно либо используя QGIS API, либо обратившись к вспомогательным методам платформы.

Метод runalg() возвращает словарь, ключами в нем будут названия результатов (такие же, как и в описании алгоритма), а значениями — пути к соответствующим файлам. Загрузить эти слои можно передав их пути в метод load().

Дополнительные функции для работы с данными¶

Помимо функций, используемых для запуска алгоритмов, модуль processing предоставляет ряд вспомогательных функций, которые облегчают работу с данными, в частности с векторными данными. Все эти функции являются обёртками над функциями QGIS API, и, обычно, имеют более простой синтаксис. Рекомендуется использовать их при создании новых алгоритмов, т.к. они упрощают работу с исходными данными.

Ниже описаны некоторые из этих функций. Подробную информацию можно получить, изучив классы пакета processing/tools а также примеры скриптов, входящие в состав QGIS.

• getobject(obj): Возвращает объект QGIS (слой или таблицу) по переданной строке, которая может содержать путь к файлу или имя слоя в списке слоёв QGIS.

• values(layer, fields): Возвращает значения таблицы атрибутов векторного слоя для заданных полей. Поля могут быть заданы именами или индексом (индексация идёт с 0). Результат работы записывается в словарь списков, где ключом является идентификатор поля. Учитывается наличие выбранных объектов.

• getfeatures(layer): Возвращает итератор по объектам слоя с учётом наличия выбранных объектов.

• uniquelabels(layer, field): Возвращает список уникальных значение указанного атрибута. Атрибут задаётся именем или индексом (индексация с 0). Учитывается наличие выбранных объектов.

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

Пользователь может создавать свои собственные алгоритмы, написав соответствующий код на Python и добавив к нему несколько строк со специальной семантической информацией. Простой редактор скриптов можно вызвать из панели инструментов: в группе Scripts, в разделе Tools находится пункт Create new script. Двойно щелчок по этому пункту откроет окно редактора скриптов. Здесь вводится код скрипта. Сохранение набранного кода в каталог scripts (по умолчанию, можно изменить в настройках) папки processing в домашнем каталоге пользователя QGIS с расширением .py, автоматически создаст соответствующий алгоритм.

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

Рассмотрим простой скрипт для расчета Topographic Wetness Index (TWI) из 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)

Как видно, ничего сложного в нем нет, вызывается три алгоритма SAGA. Последних из них выполняет расчет TWI, но ему требуются слои уклонов и накопления потоков. У нас их нет, но т.к. у мы располагаем DEM, то можем легко получить необходимые данные, вызвав соответствующие алгоритмы SAGA.

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

Эти строки начинаются с двойного символа комментария Python (##) и имеют вид:

[parameter_name]=[parameter_type] [optional_values]

Список всех параметров, доступных в скриптах геообработки, синтаксис их описания и примеры даются ниже.

• raster. Растровый слой

• vector. Векторный слой

• table. Таблица

• number. Число (целое или с плавающей запятой). В поле дополнительных значений необходимо указать значение по умолчанию. Например, depth=number 2.4

• string. Текстовая строка, как и в случае числового параметра, в поле дополнительных значений необходимо указать значение по умолчанию. Например, name=string Victor

• boolean. Логическая величина. Необходимо указать, какое она должна принимать значение по умолчанию: True или False. Например, verbose=boolean True

• multiple raster. Набор растровых слоёв

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

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

• folder. Каталог

• file. Файл (текстовый или любой другой файл, не подпадающий под перечисленные выше типы)

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

При использовании названия параметра в качестве подписи, производится замена подчеркиваний на пробелы. Т.е. если мы назовем параметр A_numerical_value, то при запуске алгоритма пользователь увидит надпись A numerical value.

Растровые и векторные слои, а также таблицы задаются строками, содержащими полный путь к соответствующим файлам на диске. Получить из них объекты QGIS можно при помощи метода processing.getObjectFromUri(). Множественные объекты представляются строкой, содержащей разделенные точкой с запятой (;) пути к файлам.

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

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

В переменные-результаты всегда записывается строка, содержащая полный путь к файлу. Если пользователь не указал путь для сохранения результата, это будет путь к временному файлу.

Алгоритм будет пытаться загрузить в проект все описанные в заголовке скрипта результаты по окончанию обработки. Именно поэтому, не смотря на то, что метод runalg() не загружает слои, конечный слой TWI будет загружен в QGIS. Ведь он сохраняется в файл, указанных пользователем как значение соответствующего выходного параметра.

Не используйте метод load() в своих скриптах, он нужен только при работе в консоли. Если создаваемый слой является результатом работы алгоритма, он должен быть соответствующим образом описан. В противном случае алгоритм нельзя будет использовать в построителе моделей, т.к. его синтаксис (заданный при помощи описанных выше тегов) не соответствует реальным результатам работы.

Скрытые результаты (строки и числа) не имеют значения. Вместо этого вы должны самостоятельно присвоить им правильные значения. Для этого просто присвойте переменной с именем, совпадающим с именем выходного параметра, значение. Например, используется такое описание:

##average=output number

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

average = 5

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

Если алгоритм будет выполняться длительное время, стоит отображать прогресс выполнения. Для этого служит объект progress: метод setText(text) позволяет выводить различные информационные сообщения, а метод setPersentage(percent) — менять величину индикатора прогресса.

В состав платформы геообработки входит несколько примеров. Пожалуйста, ознакомьтесь с ними, чтобы лучше понять как создавать новые алгоритмы. Также вы можете вызвать контекстное меню и выбрать пункт Edit script контекстного меню чтобы просмотреть или использовать код скрипта.

Документирование скриптов¶

Как и в случае моделей, скрипт можно (и нужно) сопровождать документацией. Добавить описание к любому скрипту можно, открыв его в редакторе скриптов SEXTANTE и нажав кнопку [Edit script help]. Принцип создания справки совпадает с аналогичным процессом для моделей и в дополнительных пояснениях не нуждается.

Файлы документации сохраняются в том же каталоге, что и сам скрипт, и имеют расширение .help. Обратите внимание, редактировать справку можно до первого сохранения скрипта. Если вы потом закроете редактор скриптов без сохранения (т.е. откажетесь от создания скрипта), содержимое справки будет потеряно. Если скрипт уже сохранен и ему соответствует файл на диске, запись выполняется автоматически.

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

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

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

В разделе General диалога настройки платформы находится два поля ввода: Pre-execution script file и Post-execution script file, где и указываются используемые хуки.