Определение параметров в наборе инструментов Python

Практически все инструменты имеют параметры, и вы задаете их значения в диалоговом окне или внутри скрипта. При запуске инструмента, значения параметров отправляются в исходный код инструмента. Инструмент считывает эти значения и продолжает работу.

Более подробно о параметрах см. Понятие параметров инструмента-скрипта.

В наборе инструментов Python (.pyt) параметры инструментов определяются в методе getParameterInfo класса инструментов путем создания объектов Parameter и установки их свойств.

У объектов Parameter есть много свойств для чтения/записи, но свойства, которые необходимо установить для каждого параметра, включают следующие:

Свойство	Описание
displayName (отобразить имя)	Имя параметра, отображаемое в диалоговом окне инструмента.
name	Имя параметра, отображаемое в синтаксисе инструмента в Python.
datatype	Каждый параметр инструмента в наборе инструментов Python имеет соответствующий тип данных. После открытия диалогового окна инструмента-скрипта, геообработка использует типы данных для проверки значений параметров. Тип данных также используется для обзора данных – только данные с совпадающим типом данных параметра будут показаны в диалоговом окне Обзор. Список типов данных параметров приведен в разделе Определение типов данных параметров в наборах инструментов Python. Существует обширное количество типов данных, но среди наиболее часто используемых типов данных можно назвать следующие: String (строковые), Double (числа с двойной точностью), Boolean (логические), Feature Layer (векторный слой) и Raster Dataset (набор растровых данных).
parameterType	Для свойства parameterType существует три возможности: Required (Обязательный) – Инструмент не работает, пока не задано значение. Optional (Факультативный) – Для параметра не требуется значения. Derived (Производный) – Параметр только для выходных параметров (см. параметр direction ниже). Производный выходной параметр не отображается в диалоговом окне инструмента.
направление	В данном свойстве определяется, представляет ли параметр входные данные для инструмента или выходные. Если для свойства parameterType установлено значение Derived, то для параметра direction (направление) должно быть установлено значение Output (Выход).

В приведенном ниже примере определено три параметра инструмента: входной параметр, который принимает значение типа векторный слой, входной параметр, который принимает новое имя поля и производный выходной параметр, основанный на первом входном параметре. Для отражения параметров в инструменте необходимо возвращать параметр по завершении выполнения метода getParameterInfo.

def getParameterInfo(self):
    #Define parameter definitions

    # First parameter
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")

    # Second parameter
    param1 = arcpy.Parameter(
        displayName="Sinuosity Field",
        name="sinuosity_field",
        datatype="Field",
        parameterType="Optional",
        direction="Input")

    param1.value = "sinuosity"

    # Third parameter
    param2 = arcpy.Parameter(
        displayName="Output Features",
        name="out_features",
        datatype="GPFeatureLayer",
        parameterType="Derived",
        direction="Output")

    param2.parameterDependencies = [param0.name]
    param2.schema.clone = True

    params = [param0, param1, param2]

    return params

Работа с производными выходными данными

Последний параметр в приведенном выше примере является производным выходным параметром. Существует пять следующих способов использования производных выходных параметров:

• На выходе получается то же, что и на входе, например Calculate Field (Расчет поля) или как в примере выше. Вычислить поле изменяет значение определенного поля во входной таблице – он не создает новой таблицы и не изменяет схему входных данных. Другие инструменты, где выходные данные совпадают с входными, можно найти в Наборе инструментов Редактирование (Editing toolbox).
• Инструмент изменяет схему входных данных, например Добавить поле (Add Field). Добавить поле добавляет поле во входную таблицу – он не создает новой выходной таблицы.
• Инструмент формирует выходные данные, используя информацию в других параметрах, например, инструмент Создать класс пространственных объектов (Create Feature Class). С помощью инструмента Создать класс пространственных объектов, можно задать рабочую область и имя нового класса объектов, после чего будет создан класс пространственных объектов.
• В противоположность набору данных, инструмент дает на выходе скалярное значение. Посчитать строки (Get Count), например, дает на выходе значение типа long -длинное целое (количество записей). Всегда, когда инструмент дает на выходе скалярное значение, выходные данные имеют тип Derived (производный).
• Инструмент будет создавать данные в известном местонахождении. Например, может существовать скрипт, который обновляет существующую таблицу в известной рабочей области. Пользователь не должен указывать таблицу в диалоговом окне или в скрипте.

Создание многозначных параметров

Если необходимо, чтобы параметр работал со списком значений, а не с одним значением, установите для свойства multiValue значение True.

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

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

Оба типа многозначных элементов управления проиллюстрированы ниже.

Из приведенной иллюстрации видно, что если бы пользователь выбрал все типы дорог, для параметра было бы установлено значение ["Interstates", "Primary roads", "Secondary roads"] (["Шоссе", "Автострады", "Улицы"]).

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input",
        multiValue=True)

Создание параметров с таблицами значений

Для некоторых параметров, которые носят название таблицы значений, возможен ввод нескольких значений. Например, можно включить несколько наборов данных для параметра Входные объекты (Input Features) в Присоединение (Append), Объединение (Union) и некоторых других инструментах, или можно включить несколько полей для параметра Поле (я) статистики (Statistics Field(s)) в инструментах Слияние (Dissolve) и Суммарная статистика (Summary Statistics).

Параметры таблицы значений определяются установкой datatype (типа данных) для GPValueTable и настройкой свойства columns (столбцы) для определения типов данных и заголовков столбцов параметра. В приведенном ниже примере параметр с таблицей значений задается двумя столбцами, которые принимают значения слоя пространственных объектов и целочисленные значения (GPLong).

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName='Input Features',
        name='in_features',
        datatype='GPValueTable',
        parameterType='Required',
        direction='Input')

    param0.columns = [['Feature Layer', 'Features'], ['Long', 'Ranks']]

Для задания значения по умолчанию для параметра с таблицей значений, используйте свойство values (значения), и задайте значения для параметра в виде списка списков значений.

Установка значений параметра по умолчанию

Установить значение по умолчанию для параметра можно двумя способами: непосредственной установкой значения с помощью свойства value (значение), или использованием значения параметра среды с помощью defaultEnvironmentName.

Значению по умолчанию будет присваиваться содержимое параметра, когда открыто диалоговое окно инструмента скрипта. Это же значение будет использовано, если для параметра в скрипте вводится #. Если не задается value (значение), значение параметра будет пустым, когда откроется диалоговое окно скрипта.

Установка значения по умолчанию на основе параметра среды

Для значения по умолчанию для параметра можно установить значение параметра среды путем установки в свойстве defaultEnvironmentName имени параметра среды. Как только выбран параметр среды, свойство value (значение) будет игнорироваться.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Workspace",
        name="in_workspace",
        datatype="DEWorkspace",
        parameterType="Required",
        direction="Input")

    # In the tool's dialog box, the first parameter will show 
    #  the workspace environment's value (if set)
    param0.defaultEnvironmentName = "workspace"

Определение схемы параметра

У каждого выходного параметра следующих типов: класс пространственных объектов, таблица, растр или рабочая область – есть объект схемы. Только у выходных классов пространственных объектов, таблиц, растров и рабочих областей есть объект схемы, у других типов его нет. Объект схемы создается для вас процессом геообработки. К схеме осуществляется доступ через объект 'параметр', и устанавливаются правила для описания выходных данных инструмента. После установки правил схемы код внутренней проверки анализирует эти правила и обновляет описание выходных данных.

Дополнительная информация о работе со схемами приведена в разделе Схема.

Когда тип данных входного параметра – это Feature Set (Набор объектов) или Record Set (Набор записей), необходимо установить fieldsRule и geometryType вводимых объектов.

О наборах объектов и наборах записей

Типы Feature Set (Набор объектов) и Record Set (Набор записей) позволяют выполнять ввод данных интерактивно. Feature Set (Набор объектов) позволяет пользователю скрипта интерактивно создавать пространственные объекты в ArcMap, щелкая на карте. Record Set (Набор записей) позволяет пользователю интерактивно создавать строки в простой таблице.

Для элемента управления Feature Set (Набор объектов) и Record Set (Набор записей) можно задать условные обозначения и схему (атрибуты и тип геометрии) при помощи свойства value (значение), указав класс пространственных объектов, таблицу или файла слоя (.lyr)

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Feature Set",
        name="in_feature_set",
        datatype="GPFeatureRecordSetLayer",
        parameterType="Required",
        direction="Input")

    # Use __file__ attribute to find the .lyr file (assuming the
    #  .pyt and .lyr files exist in the same folder)
    param0.value = os.path.join(os.path.dirname(__file__),
                                "Fire_Station.lyr")

Для получения более подробной информации по наборам объектов и записей, перейдите по указанным ниже ссылкам.

Тема	Описание
FeatureSets и RecordSets	В данном разделе рассказывается, как в Python используются объекты FeatureSet (Набор объектов) и RecordSet (Набор записей).
Использование средств интерактивного ввода объектов и записей	В данном разделе рассказывается, как использовать элементы управления Набор объектов и Набор записей.

Разделы с информацией по наборам объектов и наборам записей

Применение фильтров к параметру

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

В процессе геообработки автоматически создаются фильтры для типов: string (строковый), long (длинное целое), double (с двойной точностью), feature class (класс пространственных объектов), file (файл), field (поле) и рабочая область. Даже если вы не хотите устанавливать фильтр для параметра, он все равно существует и связан с параметром – просто он является пустым. Пустой фильтр равнозначен отсутствию фильтра. Добавляя значения в пустой фильтр, вы его активируете, и тогда варианты, из которых может выбирать пользователь, будут ограничены содержимым фильтра.

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

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

Тип фильтра	Значения
Список значений	Список строковых или числовых значений. Используется со следующими типами данных параметра: String (Строковый), Long (Длинное целое), Double (с двойной точностью) и Boolean (Логический).
Диапазон	Минимальное и максимальное значение. Используется с типами данных Long (Длинное целое) и Double (Вещественное с двойной точностью).
Класс пространственных объектов	Список возможных типов классов пространственных объектов: Point (Точка), Multipoint (Мультиточка), Polyline (Полилиния), Polygon (Полигон), MultiPatch (Мультипатч), Sphere (Сфера), Annotation (Аннотация) и Dimension (Размерность). В фильтре можно задать несколько значений.
Файлы	Список расширений файла. Пример: txt; e00; ditamap.
Поле	Список возможных типов полей: Short (Короткое целое), Long (Длинное целое), Single (Вещественное с одной точностью), Double (Вещественное с двойной точностью), Text (Текст), Date (Дата), OID (Идентификатор объекта), Geometry (Геометрия), Blob (Большой двоичный объект), Raster (Растр), GUID (Глобальный уникальный идентификатор), GlobalID (Глобальный идентификатор) и XML. В фильтре можно задать несколько значений.
Рабочая область	Список возможных типов рабочей области: File System (Файловая система), Local Database (Локальная база данных) или Remote Database (Удаленная база данных). Может быть задано более одного значения.

Тип и значения фильтра

Свойство	Описание
type	Тип фильтра (Список значений (Value List), Диапазон (Range), Класс объектов (Feature Class), Файл (File), Поле (Field), и Рабочая область (Workspace)). Вы можете задать тип фильтра при работе с параметрами Long и Double (см. примечание ниже). Для других типов параметров существует только один корректный тип фильтра, поэтому задание типа для этих параметров игнорируется. Если вы не хотите фильтровать значения, установите свойство списка на пустой список (empty list).
list	Список Python, содержащий значения для фильтра. Если вы не хотите фильтровать значения, установите свойство списка на пустой список (empty list).

Свойства filter

Как правило, можно выбрать только один тип фильтра. Только для типов данных Long (Длинное целое) и Doubles (Вещественное с двойной точностью) существует два варианта: Value List (Список значений) и Range (Диапазон).

Список значений

Фильтр списка значений оптимален при определении набора ключевых слов. Многие инструменты уже имеют предопределенный набор ключевых слов, например параметр Тип поля (Field Type) для инструмента Добавить поле (Add Field) или параметр Соединить атрибуты (Join Attributes) для многих инструментов в Группе инструментов наложения (Overlay toolset).

Фильтр списка значений может использоваться для данных типа Long и Double. Для этих типов вводятся допустимые числовые значения.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input value",
        name="in_value",
        datatype="GPLong",
        parameterType="Required",
        direction="Input")

    # Set a value list of 1, 10 and 100
    param0.filter.type = "ValueList"
    param0.filter.list = [1, 10, 100]

Если необходимо, чтобы пользователь имел возможность выбрать более одного значения, установите для свойства multiValue значение True (Истина).

Фильтр списка значений может использоваться для логического типа данных. Для типа данных Boolean (Логический) Список значений содержит два значения: истина и ложь. Истинное значение (true) всегда идет в списке первым. Эти значения используются в командной строке при установке значения. См., например, ключевые слова Add Field (Добавить поле) и {NULLABLE | NON_NULLABLE}, используемые для свойства IsNullable.

Диапазон

Для параметров с типом данных Long (Длинное целое) и Double (С двойной точностью) может быть установлен фильтр диапазона. У фильтров диапазона два значения: минимум и максимум. Первым в списке идет минимальное значение. Диапазон является инклюзивным, то есть в него входят минимальное и максимальное значения.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input range",
        name="in_range",
        datatype="GPLong",
        parameterType="Required",
        direction="Input")

    # Set an acceptable range of 1 to 10
    param0.filter.type = "Range"
    param0.filter.list = [1, 10]

Класс пространственных объектов

В данном фильтре выберите одно или несколько значений фильтра. Входные классы объектов будут сравниваться со значениями, установленными в фильтре. Так, например, если в фильтре установлен только тип Point (Точка), то в качестве значений параметра пользователь сможет вводить только классы точечных пространственных объектов.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")
    param0.filter.list = ["Polygon"]

Файлы

Фильтр файлов содержит список допустимых суффиксов файлов, таких как txt (простой текстовый файл) или csv (значения, разделенные запятыми). Можно использовать любое расширение. Совсем не обязательно, чтобы приложение ArcGIS распознавало расширение. Расширение может иметь любую длину и не должно содержать точек.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input File",
        name="in_file",
        datatype="DEFile",
        parameterType="Required",
        direction="Input")

    # To define a file filter that includes .csv and .txt extensions,
    #  set the filter list to a list of file extension names
    param0.filter.list = ['txt', 'csv']

Поле

В фильтре полей задаются допустимые типы полей: Short (Короткое целое), Long (Длинное целое), Float (С плавающей точкой), Single (С одной точностью), Double (С двойной точностью), Text (Текст), Date (Дата), OID (Идентификатор объекта), Geometry (Геометрия), Blob (Большой двоичный объект), Raster (Растр), GUID (Глобальный уникальный идентификатор), GlobalID (Глобальный идентификатор), XML. В фильтре можно задать несколько значений.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")

    param1 = arcpy.Parameter(
        displayName="Field",
        name="field",
        datatype="Field",
        parameterType="Required",
        direction="Input")

    # Set the filter to accept only fields that are Short or Long type
    param1.filter.list = ['Short', 'Long']
    param1.parameterDependencies = [param0.name]

Рабочая область

В фильтре рабочей области указываются типы допустимых рабочих областей на входе. Существует три значения:

Фильтры рабочей области	Описание
Файловая система	Системная папка, используемая для хранения шейп-файлов, покрытий, таблиц INFO и сеток
Локальная база данных	Персональная или файловая база геоданных
Удаленная база данных	Подключение базы данных ArcSDE

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Workspace",
        name="in_workspace",
        datatype="DEWorkspace",
        parameterType="Required",
        direction="Input")

    # Set the filter to accept only local (personal or file) geodatabases
    param0.filter.list = ["Local Database"]

parameterDependencies

Свойство parameterDependencies используется для двух целей:

• Для производного выходного параметра: свойству parameterDependencies присваивается значение входного параметра, которое будет изменено инструментом.
• Для входных параметров: parameterDependencies содержит имена других параметров, используемых этим типом данных.

# Third parameter
param2 = arcpy.Parameter(
    displayName="Output Features",
    name="out_features",
    datatype="GPFeatureLayer",
    parameterType="Derived",
    direction="Output")

param2.parameterDependencies = [param0.name]
param2.schema.clone = True

Задать parameterDependencies можно только для определенных входных параметров, как проиллюстрировано в таблице ниже.

Тип входных данных	Тип данных зависимого параметра	Описание
Поле или выражение SQL	Таблица	Таблица, содержащая поля
Элемент INFO или выражение INFO	Таблица INFO	Таблица INFO, содержащая элементы
Класс пространственных объектов покрытия	Покрытие	Покрытие, содержащее объекты
Единицы площади и длины	Набор геоданных (GeoDataset)	Географический набор данных, используемый для определения единиц по умолчанию
Система координат	Рабочая область	Рабочая область, используемая для определения системы координат по умолчанию
Настройки иерархии Network Analyst	Набор сетевых данных	Набор сетевых данных, содержащий информацию иерархии
Таблица геостатистических значений	Геостатистический слой	Слой анализа, содержащий таблицы

Типы данных parameterDependencies

символ(symbology)

Если на выходе инструмента возвращается набор пространственных объектов, растр, TIN, Слой сетевых данных, то можно указать расположение файла слоя (.lyr) со свойством symbology (условные обозначения). Если инструмент запускается из ArcMap, ArcGlobe или ArcScene, и включена опция Добавить к изображению результаты операций геообработки (Add results of geoprocessing operations to the display), то будут отображаться выходные результаты и прорисовка выполняется с использованием условных обозначений, определенных в файле слоя условных обозначений.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Raster",
        name="in_raster",
        datatype="DERasterDataset",
        parameterType="Required",
        direction="Input")

    param1 = arcpy.Parameter(
        displayName="Output Raster",
        name="out_raster",
        datatype="DERasterDataset",
        parameterType="Required",
        direction="Output")

    # Use __file__ attribute to find the .lyr file (assuming the
    #  .pyt and .lyr files exist in the same folder).
    param1.symbology = os.path.join(os.path.dirname(__file__), 
                                    'raster_symbology.lyr')

Примечание:

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

категория (category)

Для уменьшения размера диалогового окна инструмента можно разместить параметры по категориям. В Инструментах сетевых данных (Network Analyst) используются категории, как показано далее. Параметры с одним и тем же названием категории будут сгруппированы вместе.

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