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

Использование SEXTANTE в консоли

Введение

Командная строка позволяет опытным пользователям значительно увеличить производительность работы и выполнять сложные операции, которые невозможно выполнить, используя графический интерфейс SEXTANTE. В командной строке можно создавать модели, объединяющие несколько алгоритмов и такие дополнительные операции, как циклы и условные операторы, что позволяет создавать более гибкие и мощные процессы обработки.

У SEXTANTE нет отдельной командной строки, вместо этого все команды SEXTANTE доступны из консоли Python QGIS. Это значит, что в нашем распоряжении все возможности API QGIS и SEXTANTE одновременно.

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

В этом параграфе мы покажем как использовать SEXTANTE их консоли Python, а также как создавать свои собственные алгоритмы.

Запуск алгоритмов в консоли

Первое, что нужно сделать при использовании SEXTANTE из командной строки — импортировать модуль SEXTANTE:

>>> import sextante

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

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

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

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

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

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

>>> sextante.runalg{name_of_the_algorithm, param1, param2, ..., paramN,
         Output1, Output2, ..., OutputN)

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

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

  • растровый слой, векторный слой или таблица. Можно указывать имя слоя QGIS (если слой загружен в проект), путь к файлу (если слой не загружен). Также можно передавать переменную — экземпляр соответствующего класса QGIS (например, QgsVectorLayer). Если параметр является необязательным и не используется — просто укажите None

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

    >>> sextante.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 API, либо обратившись к методам SEXTANTE.

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

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

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

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

Рассмотрим простой скрипт для расчета Topographic Wetness Index (TWI) из DEM

##dem=raster
##twi=output
ret_slope = sextante.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = sextante.runalg("saga:catchmentarea(mass-fluxmethod)", dem,
                0, False, False, False, False, None, None, None, None, None)
sextante.runalg("saga:topographicwetnessindex(twi), ret_slope['SLOPE'],
                ret_area['AREA'], None, 1, 0, twi)

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

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

Такие строки начинаются с двойного символа комментария и имеют вид:

[parameter_name]=[parameter_type] [optional_values]

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

  • 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. Файл (текстовый или любой другой файл, не подпадающий под перечисленные выше типы)

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

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

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

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

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

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

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

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

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

##average=output number

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

average = 5

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

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

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

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

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

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