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

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

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

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

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

Свойство	Описание
displayName	Имя параметра, как отображается на панели Геообработка.
name	Имя параметра, отображаемое в синтаксисе инструмента в Python.
datatype	Каждый параметр инструмента в наборе инструментов Python имеет соответствующий тип данных. После открытия диалогового окна инструмента-скрипта, геообработка использует типы данных для проверки значений параметров. Тип данных также используется для обзора данных – только данные с совпадающим типом данных параметра будут показаны в диалоговом окне Обзор. Список типов данных параметров приведен в разделе Определение типов данных параметров в наборах инструментов Python.
parameterType	Для parameterType доступны три варианта: Required – инструмент не работает, пока не задано значение. Optional – для параметра не обязательно вводить значение. Derived – параметр только для выходных параметров (см. параметр direction ниже). Производный выходной параметр не отображается в диалоговом окне инструмента.
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

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

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

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

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

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

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

Ниже приведен пример элемента управления multivalue:

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

Параметры таблицы значений позволяют указывать несколько входных записей. Например, можно включить несколько наборов данных для параметра Входные объекты в инструментах Присоединить, Объединение и некоторых других инструментах; вы также можете включить несколько полей для параметра Поля статистики в инструментах Слияние по атрибутам и Суммарная статистика.

Параметры с таблицами значений определяются путем установки для datatype значения GPValueTable и определения для свойства columns типов данных и заголовков столбцов параметра. В приведенном ниже примере параметр с таблицей значений задается двумя столбцами, которые принимают значения имен полей и текстовые значения для параметра Statistic Type (GPString). С помощью фильтра ValueList и списка значений можно сформировать ниспадающий список под соответствующим столбцом GPValueTable. Для определения значений по умолчанию для параметра таблицы значений используйте свойство values и задайте значения для параметра в виде списка списков значений.

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

    param1 = arcpy.Parameter(
        displayName='Statistics Field(s)',
        name='stat_fields',
        datatype='GPValueTable',
        parameterType='Required',
        direction='Input')

    param1.parameterDependencies = [param0.name]
    param1.columns = [['Field', 'Field'], ['GPString', 'Statistic Type']]
    param1.filters[1].type = 'ValueList'
    param1.values = [['NAME', 'SUM']]
    param1.filters[1].list = ['SUM', 'MIN', 'MAX', 'STDEV', 'MEAN']

Дополнительно, чтобы сделать столбец только для чтения, свойство columns может быть задано с дополнительным ReadOnly значением. Значение ReadOnly используется для представления столбца только для информационных целей, например, param1.columns = [['Field', 'Field', 'ReadOnly'], ['GPString', 'Statistic Type']].

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

Установить значение по умолчанию для параметра можно двумя способами: непосредственной установкой значения с помощью свойства 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"

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

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

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

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

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

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

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.lyrx')

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

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

Геообработка автоматически создает фильтры для параметров, имеющих тип string, long, double, класс пространственных объектов, файл, поле и рабочая область. Даже если вы не хотите устанавливать фильтр для параметра, он все равно существует и связан с параметром – просто он является пустым. Пустой фильтр равнозначен отсутствию фильтра. Добавляя значения в пустой фильтр, вы его активируете, и тогда варианты, из которых может выбирать пользователь, будут ограничены содержимым фильтра.

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

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

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

Тип фильтра	Значения
Список значений	Список строковых или числовых значений, которые используются с типами данных String, Long, Double, Boolean, Linear Unit, Areal Unit и Time Unit. Для фильтров Linear Unit, Area Unit и Time Unit ValueList укажите список строк ключевых слов единиц измерения, и только значения, использующие эти единицы, будут считаться допустимыми и отображаться в раскрывающемся списке единиц измерения в диалоговом окне инструмента.
Диапазон	Минимальное и максимальное значение используется с типами данных Long, Double, Linear Unit, Areal Unit и Time Unit. Для фильтров Linear Unit, Areal Unit и Time Unit Range укажите список с двумя элементами: минимальное и максимальное значение, включая единицу измерения, например, ["1 Meters", "100 Meters"].
Класс пространственных объектов	Список возможных типов классов пространственных объектов: "Point" (Точка), "Multipoint" (Мультиточка), "Polyline" (Полилиния), "Polygon" (Полигон), "MultiPatch" (Мультипатч), "Annotation" (Аннотация) и "Dimension" (Размер). В фильтре можно задать несколько значений.
Файл	Список суффиксов файлов, например, ['zip', 'xml'].
Поле	Список возможных типов полей: Short, Long, Single, Double, Text, Date, OID, Geometry, Blob, Raster, GUID, GlobalID и XML. В фильтре можно задать несколько значений.
Рабочая область	Список возможных типов рабочей области: File System, Local Database или Remote Database. Может быть задано более одного значения.
Тип единиц измерения режима передвижения	Список допустимых атрибутов импеданса режима движения: Время, Расстояние, другое.

Свойства filter

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

Как правило, можно выбрать только один тип фильтра. Только для параметров Long, Double, Linear Unit, Areal Unit и Time Unit есть два варианта: ValueList и Range.

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

Фильтр списка значений оптимален при определении набора ключевых слов. Многие инструменты уже имеют предопределенный набор ключевых слов, например, параметр Тип поля для инструмента Добавить поле или параметр Соединить атрибуты для многих инструментов в Группе инструментов Наложение.

Фильтр Список значение может использоваться с типами данных Long, Double, Linear Unit, Areal Unit и Time Unit. Для этих типов введите допустимые числовые значения или единицы измерения.

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 и false. Истинное значение (true) всегда идет в списке первым. Значения, указанные в списке Значение, используются в Python при установке значения. Например, Добавить поле и ключевые слова NULLABLE и NON_NULLABLE используются для параметра Field IsNullable.

Диапазон

Для параметра Long, Double, Linear Unit, Areal Unit и Time Unit может быть фильтр диапазона. У фильтров диапазона два значения: минимум и максимум. Первым в списке идет минимальное значение. Диапазон является инклюзивным, то есть в него входят минимальное и максимальное значения.

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]

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

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

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

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 geodatabases
    param0.filter.list = ["Local Database"]

Тип единиц измерения режима передвижения

Тип единиц измерения режима передвижения можно использовать для установки допустимых типов режима передвижения на основе единиц измерения атрибута Импеданс режима передвижения. Допускаются опции Время, Расстояние и Другое.

def getParameterInfo(self):
    param1 = arcpy.Parameter(
        displayName="Travel Mode",
        name="travel_mode",
        datatype="NetworkTravelMode",
        parameterType="Required",
        direction="Input")

     # Set the parameter to be dependent on the Network Data Source parameter
     param1.parameterDependencies = [param0.name]
     # Set the filter to accept only time-based travel modes
     param1.filter.list = ["Time"]

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 только для определенных входных параметров, как показано в таблице ниже.

Типы данных parameterDependencies

Тип данных параметра	Тип данных зависимого параметра
Единицы площади (GPArealUnit)	Географический набор данных, используемый для определения единиц измерения по умолчанию. Например, можно использовать тип данных Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).
Поле (Field)	Таблица, содержащая поля. Например, можно использовать тип данных Вид таблицы (GPTableView), Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).
Сопоставления полей (GPFieldMapping)	Набор полей в одной или более входных таблицах. Например, можно использовать тип данных Вид таблицы (GPTableView), Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).
Таблица геостатистических значений ( GPGAValueTable)	Таблица наборов данных и полей, используемых в инструментах Geostatistical Analyst. Используйте тип данных Геостатистический слой (GPGALayer).
Линейные единицы измерения (GPLinearUnit)	Географический набор данных, используемый для определения единиц измерения по умолчанию. Например, можно использовать тип данных Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).
Настройки иерархии Network Analyst (GPNAHierarchySettings)	Набор сетевых данных, содержащий информацию об иерархии. Используйте тип данных Набор сетевых данных (DENetworkDataset).
Режим передвижения по сети (NetworkTravelMode)	Список режимов передвижения. Используйте тип данных Источник сетевых данных (GPNetworkDataSource), Набор сетевых данных (DENetworkDataset) или Слой набора сетевых данных (GPNetworkDatasetLayer).
Выражение SQL (GPSQLExpression)	Таблица, содержащая поля. Например, можно использовать тип данных Вид таблицы (GPTableView), Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).

symbology

Если выходными данными инструмента являются набор пространственных объектов, растр, TIN или слой Network Analyst, то можно указать расположение файла слоя (.lyrx) с помощью свойства symbology. Когда ваш инструмент выполняется, результат выводится на экран и отображается с использованием символов, определенных в файле слоя символов.

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.lyrx')

Примечание:

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

category

Параметры могут быть сгруппированы в различные категории, чтобы минимизировать размер диалогового окна инструмента, или в связанные с группой параметры, которые будут редко использоваться. Параметры, которые устанавливают category в одно и то же строковое значение, будут объединены в группу. Несколько инструментов ArcGIS Network Analyst extension используют категории как показано ниже.

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