ArcGIS Help 10.1 - Настройка поведения инструмента-скрипта

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

Подробнее о проверке значений вы можете узнать в разделе Понятие проверки в инструментах-скриптах

Вы можете задать пользовательское поведение для диалогового окна вашего инструмента-скрипта, например, включение или отключение параметров, задание значений по умолчанию, и изменение строковых ключевых слов. Для того чтобы добавить пользовательское поведение для вашего инструмента-скрипта, щелкните правой кнопкой мыши на инструменте-скрипте, выберите Свойства (Properties), а затем щелкните на закладке Проверка (Validation). На панели Проверка (Validation) вы можете задать код Python, который выполнит класс Python, именуемый ToolValidator.

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

ToolValidator является классом Python, в котором содержатся три метода: initializeParameters(self), updateParameters(self), and updateMessages(self). Он также содержит метод инициализации стандартного класса Python __init__(self). Для просмотра и редактирования класса ToolValidator щелкните правой кнопкой мыши на инструменте-скрипте, нажмите Свойства и перейдите на закладку Проверка (Validation). Ниже на рисунке показана закладка Проверка (Validation) с кодом класса ToolValidator по умолчанию. Нажмите кнопку Редактировать (Edit), чтобы изменить код, а затем нажмите OK или Применить (Apply), чтобы сделанные изменения вступили в силу.

Метод	Описание
__init__	Инициализирует класс ToolValidator. Импортирует любые нужные вам библиотеки и инициализирует объект (object (self).
initializeParameters	Вызываются один раз, при первом открытии диалогового окна или при первом использовании инструмента в командной строке.
updateParameters	Вызывается при каждом изменении пользователем параметра в диалоговом окне инструмента. После возврата из updateParameters геообработка запускает стандартную внутреннюю проверку.
updateMessages	Вызывается после возврата из стандартной внутренней проверки. Вы можете просмотреть сообщения, созданные внутренней проверкой, и при необходимости изменить их.

Обзор методов ToolValidator

Примечание:

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

Примечание:

Вы должны реализовать три метода initializeParameters(self), updateParameters(self) и updateMessages(self). Они ничего не должны делать, кроме возврата, но они необходимы для ToolValidator, чтобы последний был действительным классом Python.

Ниже приведены некоторые примеры кода ToolValidator: Полное описание всех методов с примерами можно найти в Программирование класса ToolValidator (Programming a ToolValidator class).

Для того чтобы включить или отключить параметр

Это пример из инструмента Hot Spot Analysis (Анализ горячих точек):

def updateParameters(self):

  # If the option to use a weights file is selected (the user chose
  #  "Get Spatial Weights From File"), enable the parameter for specifying 
  #  the file, otherwise disable it
  #
  if self.params[3].value == "Get Spatial Weights From File":
    self.params[8].enabled = 1
  else:
    self.params[8].enabled = 0

Coding note: При установке Булевых переменных, таких как Включено (Enabled), вы можете использовать следующий синтаксис:

self.params[8].enabled = 1
self.params[8].enabled = bool(1)
self.params[8].enabled = True  # Note upper case: "True", not "true"

Любое значение или число, кроме нуля, считается истинным (true).

Чтобы установить значение по умолчанию

Этот пример тоже из инструмента Hot Spot Analysis (Анализ горячих точек):

def updateParameters(self):
  # Set the default distance threshold to 1/100 of the larger of the width
  #  or height of the extent of the input features.  Do not set if there is no 
  #  input dataset yet, or the user has set a specific distance (Altered is true).
  # 
  if self.params[0].value:
    if not self.params[6].altered:
      extent = arcpy.Describe(self.params[0].value).extent
      if extent.width > extent.height:
        self.params[6].value = extent.width / 100
      else:
        self.params[6].value = extent.height / 100

  return

Чтобы обновить фильтр

Ниже приведен пример динамического обновления Фильтра списка значений (Value List Filter), содержащего список выбора ключевых слов. Если пользователь введет "СТАРЫЙ ФОРМАТ (OLD_FORMAT)" во втором параметре, то третий параметр будет содержать "ТОЧКА (POINT)", "ЛИНИЯ (LINE)" и "ПОЛИГОН (POLYGON)". Если введено "НОВЫЙ ФОРМАТ (NEW_FORMAT)", то третий параметр будет содержать три дополнительных выбора.

class ToolValidator:
  def __init__(self): 
    import arcpy 
    self.params = arcpy.GetParameterInfo()

  def initializeParameters(self):
    return

  def updateParameters(self):
    # Provide default values for "file format type" and 
    #  "feature type in file"
    #
    if not self.params[1].altered:
      self.params[1].value = "OLD_FORMAT"
    if not self.params[2].altered:
      self.params[2].value = "POINT"

    # Update the value list filter of the "feature type in file" parameter 
    #   depending on the type of file (old vs. new format) input
    #
    if self.params[1].value == "OLD_FORMAT":
      self.params[2].filter.list = ["POINT", "LINE", "POLYGON"]
    elif self.params[1].value == "NEW_FORMAT":
      self.params[2].filter.list = ["POINT", "LINE", "POLYGON",
                                    "POINT_WITH_ANNO",
                                    "LINE_WITH_ANNO",
                                    "POLYGON_WITH_ANNO"]

    return

  def updateMessages(self):
    return

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

def updateParameters(self):
    # Update the value list filter in the second parameter based on the 
    #   shape type in the first parameter
    #
    stringFilter = self.params[1].filter
    fc = self.params[0].value
    if fc:
        shapetype = arcpy.Describe(fc).shapeType.lower()
        if shapetype == "point" or shapetype == "multipoint":
            stringFilter.list = ["RED", "GREEN", "BLUE"]
        elif shapetype == "polygon":
            stringFilter.list = ["WHITE", "GRAY", "BLACK"]
        else:
            stringFilter.list = ["ORANGE", "INDIGO", "VIOLET"]
    else:
        stringFilter.list = ["RED", "GREEN", "BLUE"]

    # If the user hasn't changed the keyword value, set it to the default value
    #  (first value in the value list filter).
    #
    if not self.params[1].altered:
        self.params[1].value = stringFilter.list[0]
        
    return

Для настройки сообщения

def updateMessages(self):
  self.params[6].clearMessage()

  # Check to see if the threshold distance contains a value of zero and the user has
  #  specified a fixed distance band.
  #
  if self.params[6].value <= 0:
    if self.params[3].value == "Fixed Distance Band":
      self.params[6].setErrorMessage("Zero or a negative distance is invalid \
                                      when using a fixed distance band. Please \
                                      use a positive value greater than zero." )
    elif self.params[6].value < 0:
      self.params[6].setErrorMessage("A positive distance value is required \
                                      when using a fixed distance band. \
                                      Please specify a distance.")

  return

Обновление описания выходных данных с помощью объекта Schema

В дополнение к настройке поведения диалогового окна инструмента ToolValidator может также использоваться для обновления описания переменных выходных данных для ModelBuilder. Вы можете рассматривать переменные данных в ModelBuilder не иначе, как краткие описания наборов данных, как проиллюстрировано ниже. Переменные данных содержат все свойства, которые доступны вам с помощью функции Описание (Describe) в Python.

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

В первом примере показана модель, содержащая инструменты Добавить поле (Add Field) и Вычислить поле (Calculate Field). В инструменте Добавить поле (Add Field) переменная выходных данных Parks (2) обновлена и содержит новое поле, TrackingID. Поскольку выходные данные обновились, диалоговое окно Вычислить поле (Calculate Field) в списке имен полей показывает TrackingID.

Второй пример (без иллюстрации) представляет собой модель, где выходные данные инструмента Вырезать (Clip) используются в качестве входных данных для инструмента Полигон в растр (Polygon To Raster). Поскольку инструмент Вырезать (Clip) использует для создания входных пространственных объектов простую обрезку под шаблон, выходной класс пространственных объектов имеет точно те же свойства, что и входной, за одним существенным исключением: другой географический экстент. Географический экстент выходного класса пространственных объектов является геометрическим пересечением экстента входного объекта с экстентом объекта вырезания. Инструмент Полигон в растр (Polygon To Raster) для определения размера ячеек по умолчанию использует новый географический экстент.

В классе ToolValidator для установки правил построения описания выходных данных вы можете использовать объект Схемы (Schema object). Например, вы можете задать правила, как указано ниже:

Скопировать описание набора входных данных и добавить в этот список полей новое поле (подобно инструменту Добавить поле (Add Field)), либо добавить список фиксированных полей (подобно Добавить координаты х и у (Add XY Coordinates)).
Настроить список выходных полей так, чтобы в нем были все поля из какой-либо коллекции наборов данных; по желанию добавить поля, предназначенные для хранения идентификаторов пространственных объектов в этой коллекции (как в инструментах Объединение (Union) и Пересечение (Intersect)).
Задать экстент, равный экстенту другого набора данных, либо объединению или пересечению (как в случае с инструментом Вырезать (Clip)) наборов данных, приведенных в отдельном списке параметров.
Задать определенный тип геометрии (точка, линия, полигон), либо задать тип соответственно другому набору данных, либо соответственно минимальному или максимальному типу из списка параметров. Минимальный и максимальный тип геометрии определяется следующим образом: точки = 0, полилинии = 1, полигоны = 2. Таким образом, минимальный тип геометрии в наборе {точка, полилиния, полигон} у точки, а максимальный – у полигона.

Выходные параметры имеют Схему (Schema)

Объект Схемы создан для вас геообработкой. Каждый выходной параметр класса объектов, таблицы, растра или рабочей области имеет объект Schema. Только типы класса пространственных объектов, таблиц, растров и рабочей области имеют схему — другие типы данных ее не имеют. Вы получаете доступ к этой схеме через объект Параметр (Parameter) и устанавливаете правила описания выходных данных. По возвращении из updateParameters стандартная внутренняя проверка осматривает установленные вами правила и обновляет описание выходных данных.

Установка зависимостей

При создании такого правила, как "копировать поля набора данных из параметра 3, затем добавить еще одно поле", необходимо указать для объекта Schema, из какого параметра следует копировать поля (из параметра 3). Это делается посредством добавления зависимостей в объект Параметр. Вы можете добавить более одной зависимости.

def initializeParameters(self):
  # Set the dependencies for the output and its schema properties
  #
  self.params[2].parameterDependencies = [0, 1]

parameterDependencies перечислены в списке Python.

Следующие примеры иллюстрируют установку и применение зависимостей.

Примеры установки зависимостей: Вырезать и Добавить Поле (Clip and Add Field)

Вспомните, что Вырезать (Clip) копирует определение входных пространственных объектов, а затем устанавливает экстент на пересечение входных объектов и объектов вырезания. Ниже приводится пример того, как это правило реализуется в ToolValidator: (Поскольку Вырезать (Clip) является встроенным инструментом, а не скриптом, он не использует класс ToolValidator (проверка инструмента) Python. Встроенные инструменты выполняют проверку при помощи внутренних процессов, которые по существу не отличаются от тех, которые происходят в ToolValidator. Но если класс ToolValidator Python используется, то вот как это выглядит.)

def initializeParameters(self):
  # Set the dependencies for the output and its schema properties
  #
  self.params[2].parameterDependencies = [0, 1]

  # Feature type, geometry type, and fields all come from the first 
  #  dependent (parameter 0), the input features
  #
  self.params[2].schema.featureTypeRule = "FirstDependency"
  self.params[2].schema.geometryTypeRule = "FirstDependency"
  self.params[2].schema.fieldsRule = "FirstDependency"

  # The extent of the output is the intersection of the input features and 
  #  the clip features (parameter 1)
  #
  self.params[2].schema.extentRule = "Intersection"

  return

def updateParameters(self):
  return

Добавить поле (Add Field) копирует определение входного параметра и добавляет указанное пользователем поле. Пройдя по ссылке внизу вы увидите, как был бы выполнен Добавить поле (Add Field) в ToolValidator.

Просмотреть пример использования ДополнительныеПоля (AdditionalFields)

Установка схемы в initializeParameters (инициализировать параметры) в сравнении с updateParameters (обновить параметры)

Обратите внимание на то, что вышеупомянутый пример Вырезать (Clip) изменяет объект Схема (Schema) в initializeParameters и что updateParameters не делает ничего, кроме возврата. С другой стороны, Добавить поле (Add Field) должно изменить объект Схема (Schema) в updateParameters, потому что у него нет определения поля для добавления до тех пор, пока пользователь не укажет соответствующую информацию (и updateParameters не будет вызвано).

Эти два случая могут рассматриваться как статический в сравнении с динамическим. Вырезать (Clip) не зависит ни от чего, кроме наборов данных, находящихся в зависимых параметрах (статический случай), в то время как Добавить поле (Add Field) требуются другие параметры (такие, как имя поля и тип поля), которые не являются зависимыми параметрами (динамический случай).

Это статическое и динамическое поведение становится очевидным, когда вызывается класс ToolValidator:

Сразу после открытия диалогового окна инструмента модели вызывается функция initializeParameters. Вы устанавливаете статические правила для описания выходных данных. В этот раз не было создано никаких выходных описаний, поскольку пользователь не указал значения ни для одного параметра.
Как только пользователь начинает как-либо работать с диалоговым окном, происходит вызов updateParameters (обновить параметры).
updateParameters может изменить схему с учетом динамического поведения, которое не может быть определено из зависимостей параметра, как например добавление нового поля, такого как Добавить поле (Add Field).
После возврата из updateParameters происходит вызов стандартной внутренней проверки, и применяются правила объекта Схемы для обновления описания выходных данных.
Затем происходит вызов updateMessages (обновить сообщения). Вы можете просматривать предупредительные сообщения и сообщения об ошибках, создаваемые внутренней проверкой, а также изменять их или добавлять новые предупредительные сообщения или сообщения об ошибках.

Имя выходного набора данных: Клонирование производных выходных данных в сравнении с необходимыми выходными данными

Когда вы устанавливаете для свойства Schema.Clone значение истина (true), вы тем самым инструктируете геообработку сделать точную копию (клон) описания в первом зависимом параметре списка зависимости параметров. Как правило, вы устанавливаете Клон (Clone) на значение истина (true) в initializeParameters а не в updateParameters, поскольку он требует установки только однажды.

Если значение ParameterType параметра выходных данных задано как Производное (Derived), это будет означать, что сделана точная копия. Это было поведение инструмента Добавить поле (Add Field).

Если ParameterType задан как Обязательный (Required), это значит, что точная копия также сделана, но изменился путь каталога к набору данных. Поскольку большинство инструментов создает новые данные, это поведение является наиболее распространенным.

Более подробно

Программирование класса ToolValidator обеспечивает детали объектов Параметр (Parameter), Схема (Schema) и Фильтр (Filter) и дает примеры кодов.

Все основанные на скриптах системные интрументы, такие как Множественный буфер (Multiple Ring Buffer), имеют код ToolValidato, который можно просматривать. Многие инструменты из набора инструментов Пространственная статистика (Spatial Statistics) являются инструментами-скриптами и имеют исполнение ToolValidator, которое вы можете просмотреть.

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

Связанные темы

Общая информация о проверке в инструментах-скриптах

Программирование для класса ToolValidator

Отладка класса ToolValidator (Валидатор инструмента)

Что такое инструмент-скрипт?

9/10/2013