第三章 ArcGIS Pro创建 python 脚本工具（五）

其实整个第三章介绍的内容很少，真正的实验步骤，一节左右就可以概述处理，只是原书作者对于基础与一些信息都给了介绍，所以内容才会显得较多。关于新建自定义脚本工具，我觉得简单的来说，步骤就是创建脚本（如何写脚本，需要去思考。结构上和逻辑上）、创建脚本工具、参数和其他的设置等。

3.7 编辑工具代码以接收参数

还需要对脚本的代码进行修改，需要修改的硬编码代码如下所示：

inputfc = "C:/Random/Data.gdb/points"
outputfc = "C:/Random/Data.gdb/random"
outcount = 5

需要将硬编码转为使用索引的软编码：

inputfc = arcpy.GetParameterAsText(0)
outputfc = arcpy.GetParameterAsText(1)
outcount = arcpy.GetParameter(2)

这里GetParameterAsText()函数用于非字符串的参数，但是值必须转换为适当的类型，例如：可以按照以下的方式接收第三个参数：

outcount = int(arcpy.GetParameterAsText(2))

最重要的第一点是：GetParameterAsText函数将值作为字符串返回，而GetParameter将值作为对象返回。在选择两个中的一个时，必须基于对传递给脚本的值的理解做出判断。

对代码修改后，就可以运行脚本工具了

书的作者在这里提出了两个问题：
如果特征数量输入负数会发生什么？
输入的数字大于输入要素类中的要素数量，会发生什么情况？

对于第一个问题，因为设置了筛选器，所以会报错，第二个问题会执行工具，但是因为代码：randomlist = random.sample(inlist, outcount)报错。错误是：ValueError: Sample larger than population or is negative.

3.8 自定义工具行为 Customizing tool behavior

添加参数后就可以设置自定义行为，自定义行为包括：

某些参数可能需要根据其他参数中包含的值来启用或禁用。
某些参数可能受益于具有基于其他参数中的值指定的默认值。
警告和错误消息可能需要自定义。

可以在工具属性对话框，验证选项卡设置工具行为，在验证界面，可以使用python代码，代码使用名为：ToolValidator的类。这个类控制如何根据用户输入更改对话框，还用于描述工具生成的输出数据，这在模型构建器中很重要。

TooValidator类可以创建更强大的工具，但是原书中没有提供详细的说明，需要在ARCGIS官网帮助中查询：Customizing Script Tool Behavoir 和 Programming a ToolValidator Class两个主题。

3.9 消息 messages的处理

将脚本作为脚本工具进行编写就是能够查看消息，这个消息指的是错误提示等等。脚本在编译器中运行时，消息直接打印到解释器中，没有工具对话框，也不能检索历史消息，也不能进行消息的共享。使用脚本工具，会自动创建消息，打印完成的时间、错误信息等等。有几个ArcPy函数用于消息的编写，包括以下内容：

AddMessage() - 用于一般信息消息 (严重性 = 0)
AddWarning() - 用于警告消息 (严重性 = 1)
AddError() - 用于错误消息 (严重性 = 2)
AddIDMessage() - 用于警告和错误消息
AddReturnMessage() — 对于所有消息，与严重性无关

使用AddReturnMessage()函数能检索之前运行的工具的消息，并且保留原始消息的严重性。下图是以Random Sample函数为例，返回的错误消息

当outcount的值大于inlist的值时，random.sample函数会导致错误。但是这个消息可能会误导，因为它指的是默认环境中的random.py脚本的潜在问题。为了增加工具的鲁棒性，可以在脚本中添加一个检查，来比较选择的特征数量与输入特征的数量。输入要素的数量是使用获取计数工具确定的。下面的代码应该加载接收工具参数的代码块之后，代码如下所示：

fcount = arcpy.GetCount_management(inputfc)[0]
if outcount > int(fcount):

当要选择的特征数量超过输入特征的数量时，AddError() 函数用于返回自定义消息：

arcpy.AddError("The number of features to be selected""exceeds the number of input features.")

发生此错误时，脚本应该结束。脚本可以使用以下代码结束：

    sys.exit(1)

当要选择的特征数量不超过输入特征的数量时，脚本应该照常继续，如下：

else:<rest of script>

最后的脚本如图所示：

当设置输出的要素多余输入要素时，无法进行采样，工具执行失败。从下图可以看到一些错误的信息

不同的场景可能会导致不同的错误，这需要我们在设计的时候，在逻辑上有一个清晰的思路，能够进行提前的预判可能出现的情况，比如当要采样的点数和要素数量一样的时候，就会复制所有的要素，并不会执行失败，但是也没有任何提示，可以添加一个警告信息，使用AddWarning()函数。如下所示：

    # 添加警告信息if outcount == int(fcount):arcpy.AddWarning("The number of features to be selected""is the same as the number of input features.""This means the tool created a copy of the""input features without creating a sample.")

上述的代码可以添加在else块内，添加到脚本的末尾。警告消息不会阻止程序运行。

另一种级别的控制是适合用AddIDMessage()函数来完成。这个函数是使得脚本工具中使用系统消息称为可能。

AddIDMessage(message_type, message_ID, {add_argument1}, {add_argument2})

这个消息类型可以设置为 ERROR、INFORMATIVE 或 WARNING。消息 ID 号表示特定的 Esri 系统消息。根据消息，可能需要额外的参数。在以下示例代码中，如果输出要素类已存在，则会生成一条消息 ID 号为 12 的错误消息：

import arcpy
infc = arcpy.GetParameterAsText(0)
outfc = arcpy.GetParameterAsText(1)
if arcpy.Exists(outfc):arcpy.AddIDMessage("ERROR", 12, outfc)
else:arcpy.CopyFeatures_management(infc, outfc)

关于000012这个error message语法是：000012: <value> already exists
这个消息有一个参数，在本例中是要素类的名称。有超过一千个消息代码，ArcGIS Pro 帮助页面中没有所有这些代码的单一列表。您可以在帮助页面中输入消息代码以查看说明，但您无法浏览和搜索消息说明。在 Python 中，您可以使用 arcpy.GetIDMessage() 函数来获取与特定消息 ID 关联的描述，如下所示：

import arcpy
m_id = 12
print(arcpy.GetIDMessage(m_id))

结果是：

%s already exists

%s是文件名称，这里就是000012 的占位符。

为了使信息更有用，可以构建与ige包含所有消息ID和关联字符串的字典：

import arcpy
dict_id = {}
for k in range(1000000):v = arcpy.GetIDMessage(k)if v:dict_id[k] = v

错误代码是使用6位数组成，从1到999999。在创建字典后，可以搜索感兴趣的系统消息，如下所示，以下代码将会打印所有将JSON作为字符串的一部分的系统消息。

for k,v in dict_id.items():if "JSON" in v:print(k, v)

结果如下所示：

1303 Invalid JSON in WebMap.
1451 Unable to parse service configuration JSON.
2092 Failed to export diagram layer definition to JSON.
...

3.10 处理独立脚本和工具的消息

Python 脚本可以作为独立脚本或工具运行。每个消息的工作方式都略有不同。但是，可以设计一个脚本来处理这两种情况。对于独立脚本，无法查看消息，必须将它们打印到交互式解释器。对于工具，使用诸如 AddError() 之类的函数而不是打印消息来确保消息出现在地理处理环境中，包括地理处理历史。标准做法是编写一个消息处理例程，将消息写入交互式解释器和地理处理环境，对前者使用 print() 函数，对 ArcPy 函数（如 AddError()、AddWarning() 和 AddMessage()后者。

3.11 自定义工具进度信息

在arcpy中，progress 函数处理进度信息。包括以下内容：
SetProgressor()——设置进度条的类型
SetProgressorLabel()——改变进度条的标签
SetProgressorPosition()——将步进进度条移动一个增量
ResetProgressor()——重置进度条

进度条类型有两种，一种是默认的，一种是步进式。在进度条上方会提供当前地理处理操作的信息。默认的进度条格式是进行循环往复的蓝色进度条，步进式则提供进度的百分比。
关于SetProgressor函数，语法如下：

SetProgressor(type, {message}, {min_range}, {max_range}, {step_value})

其中type是设置为default或 step。message是执行时出现的进度标签，其余三个参数仅仅适用于step式的进度条。典型的步进式进度条，起始值为0，最大值为处理中的许多进程，步骤的间隔为1。

SetProgressorLabel()函数用于更新进度条标签的设置，通常是每个步骤的特定字符串。SetProgressorPosition（）函数根据已经完成的步骤百分比以增量移动步骤进度。这几个函数通常组合使用，以便于标签更新，工具执行完成后可以使用ResetProgressor进行重置。

以下示例脚本说明了步进进度器的使用。脚本与将所有 shapefiles 从一个工作空间复制到地理数据库的脚本工具相关联。使用步进进度器，步数由列表中的要素类数得出。在for循环中，将label更改为正在复制的shapeAle的名称，复制完shapefile后，step progressor移动了一个增量。
\脚本如下：

import arcpy
import os
arcpy.env.workspace = arcpy.GetParameterAsText(0)
outworkspace = arcpy.GetParameterAsText(1)
fclist = arcpy.ListFeatureClasses()
fcount = len(fclist)
arcpy.SetProgressor("step", "Copying shapefiles to geodatabase...", 0, fcount, 1)
for fc in fclist:arcpy.SetProgressorLabel("Copying " + fc + "...")fcdesc = arcpy.Describe(fc)outfc = os.path.join(outworkspace, fcdesc.baseName)arcpy.CopyFeatures_management(fc, outfc)arcpy.SetProgressorPosition()

运行后：

一个重要的考虑因素是步进进度器中使用的步数。在许多脚本中，事先不知道必须处理多少要素、要素类、field 或记录。例如，使用搜索光标的脚本可能会遍历数百万条记录。如果每次迭代是一步，则进度对话框将需要更新数百万次，这可能会严重降低性能。因此，可能需要在脚本中包含一个部分来确定迭代次数（要素、要素类、行或任何情况），然后根据迭代次数确定适当的步数. ArcGIS Pro 帮助主题“控制脚本工具的进度器”中提供了用于确定步骤数的代码示例。

Points to remember

Although Python scripts can be run as stand-alone scripts outside ArcGIS Pro, there are many beneAts to creating custom tools within ArcGIS Pro. Tools allow a closer integration of scripts in the ArcGIS Pro geoprocessing framework. Tools also make it easier to share the workCows with others who may not have experience using Python.

there are two ways to develop tools for use in ArcGIS Pro using Python: script tools and Python toolboxes. Script tools are created using elements of the ArcGIS user interface whereas Python toolboxes are created entirely in Python.

A script tool can be created in a toolbox (.tbx) and reference a single Python script Ale (.py) that is called when the tool is run.

For tools to be usable and effective, script tool parameters must be created. Creating tool parameters includes setting parameters in the script tool properties, as well as including code in the script to receive the parameter values. Script tool parameters deAne what the tool dialog box looks like.

Effective tools have carefully designed parameters. Each parameter has several properties, including a data type, such as feature class, table, value, field, or other. the parameter properties provide detailed control of the allowable inputs for each parameter. this control ensures that the parameters passed from the script tool dialog box to the script are as expected.

All script tools should have outputs so that the tool can be used in ModelBuilder and other workCows. Sometimes the only way to achieve outputs is to use derived parameters, which do not appear on the tool dialog box.

Tool behavior can be further customized using a ToolValidator class.

Various message functions can be used to write messages that appear in the tool dialog box and in the geoprocessing history. the appearance of the progressor also can be modified. this progress indicator is particularly relevant if the tool is likely to carry out many iterations.

尽管 Python 脚本可以在 ArcGIS Pro 之外作为独立脚本运行，但在 ArcGIS Pro 中创建自定义工具有很多好处。工具允许在 ArcGIS Pro 地理处理框架中更紧密地集成脚本。工具还可以更轻松地与可能没有使用 Python 经验的其他人共享 workCows。
使用 Python 开发用于 ArcGIS Pro 的工具有两种方法：脚本工具和 Python 工具箱。脚本工具是使用 ArcGIS 用户界面的元素创建的，而 Python 工具箱则完全在 Python 中创建。
可以在工具箱 (.tbx) 中创建脚本工具，并引用运行该工具时调用的单个 Python 脚本 Ale (.py)。
为了使工具可用且有效，必须创建脚本工具参数。创建工具参数包括在脚本工具属性中设置参数，以及在脚本中包含代码以接收参数值。脚本工具参数定义工具对话框的外观。
有效的工具具有精心设计的参数。每个参数都有多个属性，包括数据类型，例如要素类、表、值、字段或其他。参数属性提供了对每个参数的允许输入的详细控制。此控件确保从脚本工具对话框传递到脚本的参数与预期的一样。
所有脚本工具都应该有输出，以便该工具可以在模型构建器和其他工作牛中使用。有时，实现输出的唯一方法是使用导出参数，这些参数不会出现在工具对话框中。
可以使用 ToolValidator 类进一步自定义工具行为。
各种消息函数可用于编写出现在工具对话框和地理处理历史中的消息。进度条的外观也可以修改。如果该工具可能进行多次迭代，则此进度指标尤其相关。