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

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

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

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

ToolValidator является классом Python, который содержит четыре метода: initializeParameters, isLicensed, updateParameters и updateMessages. В нем также содержится стандартный метод инициализации класса Python, __init__. Для просмотра и редактирования класса ToolValidator щелкните правой кнопкой мыши на инструменте-скрипте, выберите Свойства и далее Проверка. Пример кода ниже показывает код класса ToolValidator по умолчанию. Код Python можно редактировать на месте или, в качестве альтернативы, нажмите кнопку Открыть в редакторе скриптов для редактирования кода.

Класс и методы ToolValidator по умолчанию
import arcpy

class ToolValidator(object):
    """Class for validating a tool's parameter values and controlling
    the behavior of the tool's dialog."""

    def __init__(self):
        """Setup arcpy and the list of tool parameters.""" 
        self.params = arcpy.GetParameterInfo()

    def initializeParameters(self): 
        """Refine the properties of a tool's parameters. This method is 
        called when the tool is opened."""

    def isLicensed(self):
        """Set whether tool is licensed to execute."""
        return True

    def updateParameters(self):
        """Modify the values and properties of parameters before internal
        validation is performed. This method is called whenever a parameter
        has been changed."""

    def updateMessages(self):
        """Modify the messages created by internal validation for each tool
        parameter. This method is called after internal validation."""

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

Примечание:

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

Ниже приведены некоторые примеры кода ToolValidator. Полное описание всех методов с примерами можно найти в Программирование класса ToolValidator.

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

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

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 = True
    else:
        self.params[8].enabled = False

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

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

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].valueAsText:
        if not self.params[6].altered:
            extent = arcpy.Describe(self.params[0]).extent
            if extent.width > extent.height:
                self.params[6].value = extent.width / 100
            else:
                self.params[6].value = extent.height / 100

    return

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

Ниже приведен пример динамического обновления Фильтра списка значений, содержащего список выбора ключевых слов. Если пользователь введет OLD_FORMAT во втором параметре, то в третьем параметре будут содержаться POINT, LINE и POLYGON. Если введено NEW_FORMAT, то третий параметр будет содержать три дополнительных варианта.

import arcpy

class ToolValidator:
    def __init__(self): 
        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

    if self.params[0].valueAsText:
        shapetype = arcpy.Describe(self.params[0]).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

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

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

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

В классе ToolValidator вы можете использовать объект Schema, чтобы задать правила построения описания выходных данных; к примеру, вы можете установить такие правила:

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

Выходные параметры содержат Schema

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

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

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

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

parameterDependencies берет список.

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

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

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

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

Добавить поле копирует определение входного параметра и добавляет указанное пользователем поле. Ссылка ниже показывает, как будет реализован инструмент Добавить поле в ToolValidator.

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

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

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

Это статическое и динамическое поведение становится очевидным в следующем способе вызова класса ToolValidator:

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

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

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

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

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

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

Программирование класса ToolValidator предлагает описание объектов Parameter, Schema и Filter и дает примеры кодов.

Все системные инструменты на основе скриптов, такие как Множественный буфер, имеют код ToolValidator, по которому можно проводить проверку и обучаться. Многие инструменты из набора инструментов Пространственная статистика являются инструментами-скриптами и имеют форму ToolValidator, которое вы можете изучить.

Связанные разделы

Отзыв по этому разделу?