ArcPy常用函数梳理
1 地理处理环境及其设置
1) 获取和设置地理处理环境
地理处理环境设置以env类的属性的方式访问。这些属性可用于检索或设置当前值。环境可作为环境类中的读/写属性进行访问，方法为arcpy.env.<环境名称>。示例1为设置地理处理环境。
示例1：设置地理处理环境值
| import arcpy # 设置地理处理环境值 acpy.env.worksapce = "c:/St_Johns/data.gdb" |
2) 重新设置环境
由于地理处理环境对工具操作和输出有着很大的影响，因此需要保证能够追踪环境设置并在必要时将其重置为默认状态。可以使用ResetEnvironments函数恢复默认环境值，或者使用ClearEnvironment函数重置特定环境，如示例2-2所示。
示例2：重置地理处理环境值
| import arcpy # 恢复默认的环境值 arcpy.ResetEnvironments() # 重置特定环境 arcpy.ClearEnvironment("workspace") |
2 描述数据
描述数据主要使用Describe函数。Describe函数返回的Describe对象包含多个属性，如数据类型、字段、索引。该对象的属性是动态的，也就是说不同的数据类型，会有不同的描述属性可供使用。
Describe属性被组织成一系列属性组。任何特定数据集都将至少获取其中一个组的属性。例如，如果要描述一个地理数据库要素类，可以访问GDB要素类、要素类、表和数据集属性组中的属性。所有的数据，不管是哪种数据类型，总会获取通用的Describe对象属性。
值得注意的是，arcpy.da.Describe也可以获取相同的描述信息，唯一的区别在于该方法以字典的方式返回描述信息。
在某些情况下，Describe返回的对象并不包含为其设计的所有属性。例如，地图中图层的Describe对象不会包含图层属性集。只有在描述.lyr文件时，该属性才会存在。如果试图访问Describe对象不具有的属性，它会抛出错误异常或返回空值（如：None、0或-1或空字符串）。如果不是很确定描述对象是否含某个属性，可以使用Python的hasattr()函数进行检查。
可以通过Describe函数获取描述信息的数据类型如表1所示。
表1 可使用Describe函数获取描述信息的数据类型
| ArcInfo Workstation 项属性 |
ArcInfo Workstation 表属性 |
CAD 工程图数据集属性 |
| CAD 要素类属性 |
地籍结构属性 |
Coverage 要素类属性 |
| Coverage 属性 |
数据集属性 |
dBASE 表属性 |
| 编辑器追踪数据集属性 |
要素类属性 |
文件属性 |
| 文件夹属性 |
GDB 要素类属性 |
GDB 表属性 |
| 几何网络属性 |
LAS 数据集属性 |
图层属性 |
| 地图文档属性 |
镶嵌数据集属性 |
Network Analyst 图层属性 |
| 网络数据集属性 |
Prj 文件属性 |
波段栅格属性 |
| 栅格目录属性 |
栅格数据集属性 |
RecordSet和FeatureSet 属性 |
| 关系类属性 |
制图表达类属性 |
逻辑示意图数据集属性 |
| 逻辑示意图属性 |
逻辑示意图文件夹属性 |
SDC 要素类属性 |
| Shapefile 要素类属性 |
表属性 |
表视图属性 |
| 文本文件属性 |
Tin 属性 |
工具属性 |
| 工具箱属性 |
拓扑属性 |
VPF Coverage 属性 |
| VPF 要素类属性 |
VPF 表属性 |
工作空间属性 |
注：详细信息请查阅http://pro.arcgis.com/zh-cn/pro-app/arcpy/functions/describe.htm。
Dscribe函数的语法及返回值说明分别如表2和表3所示。其中，Describe类型对象的属性信息如表4所示。
表2 Describe函数语法
| 参数 |
数据类型 |
说明 |
| value |
String |
要描述的指定数据元素或地理处理对象。 |
表3 Describe函数返回值
| 数据类型 |
说明 |
| Describe |
返回具有用于详细描述所描述的数据元素的属性的对象。某些返回的对象属性会包含文本值或对象。 |
表4 Describe类型对象属性信息
| 属性 |
数据类型 |
说明 |
| baseName (只读) |
String |
文件基本名称 |
| catalogPath (只读) |
String |
数据路径 |
| children (只读) |
Describe |
子元素列表 |
| childrenExpanded (只读) |
Boolean |
指示子元素是否已扩展 |
| dataElementType (只读) |
String |
元素的元素类型 |
| datatype (只读) |
String |
元素类型 |
| extension (只读) |
String |
文件扩展名 |
| file (只读) |
String |
文件名称 |
| fullPropsRetrieved (只读) |
Boolean |
指示是否已检索完整属性 |
| metadataRetrieved (只读) |
Boolean |
指示是否已检索元数据 |
| name (只读) |
String |
元素名称 |
| path (只读) |
String |
文件路径 |
Dscribe函数示例如示例3所示。
示例3：Describe函数
| import arcpy # 从参数中获取Layer对象 layerString = arcpy.GetParameterAsText(0) # 获取Layer对象的描述信息 desc = arcpy.Describe(layerString) # 打印Layer对象的名称 print("Name: {}".format(desc.name)) # 判断描述信息中是否函数layer属性 if hasattr(desc, "layer"): print("Layer name: {}".format(desc.layer.name)) print("Layer data source: {}".format(desc.layer.catalogPath)) print(".lyr file: {}".format(desc.catalogPath)) else: print("Layer name: {}".format(desc.name)) print("Layer data source: {}".format(desc.catalogPath)) |
3 游标
3.1 InsertCursor
InsertCursor可返回一个分发Row对象的枚举对象，可以实现向要素类、shapefile或表中插入行。可使用newRow方法从插入行的枚举对象获取新的Row对象。光标每次调用insertRow方法都会在表中创建新行，该行的初始值设置为输入行中的值。
InsertCursor函数的调用方式为：InsertCursor (dataset, {spatial_reference})，其语法以及返回值信息分别如表5和6所示。
表5 InsertCursor函数语法
| 参数 |
数据类型 |
说明 |
| dataset |
String |
将向其中插入行的表、要素类或shapefile。 |
| spatial_reference |
SpatialReference |
在提供的spatial_reference中指定的坐标，并动态转换到数据集的坐标系。 |
表6 InsertCursor函数返回值
| 数据类型 |
说明 |
| Cursor |
返回针对指定要素类、shapefile或表的Cursor对象。 |
InsertCursor函数示例如示例4所示。
示例4：InsertCursor函数
| import arcpy # 通过InsertCursor为Table创建Cursor对象 rows = arcpy.InsertCursor("c:/base/data.gdb/roads_lut") # 添加25行新数据 for x in range(1, 26): row = rows.newRow() row.setValue("rowid", x) row.setValue("distance", 100) rows.insertRow(row) # 删除Cursor对象和行对象，主要是为了解除数据的锁定 del row del rows |
3.2 SearchCursor
SearchCursor函数用于在要素类或表上建立只读游标。SearchCursor函数可用于遍历Row对象并提取字段值，可使用where子句或字段限制搜索，并对结果排序。
SearchCursor函数的调用方式为：SearchCursor (dataset, {where_clause}, {spatial_reference}, {fields}, {sort_fields})，其语法以及返回值信息分别如表7和8所示。表7 SearchCursor函数语法
| 参数 |
数据类型 |
说明 |
| dataset |
String |
包含要搜索行的要素类、shapefile 或表。 |
| where_clause |
String |
用于限制在游标中返回的行的可选表达式。 |
| spatial_reference |
SpatialReference |
指定后，要素将使用提供的spatial_reference进行动态投影。 |
| fields |
String |
游标中包含以分号分隔的字符串字段。默认情况下，包含所有字段。 |
| sort_fields |
String |
在游标中对行进行排序的字段。 |
表8 InsertCursor函数返回值
| 数据类型 |
说明 |
| Cursor |
可分发Row对象的Cursor对象 |
Python中可用于迭代搜索游标的方式有两种：for循环或者while循环（通过游标的next方法返回下一行）。通过for循环以及通过while循环使用SearchCursor函数分别如示例5和示例6所示。
示例5：通过for循环使用SearchCursor。
|
|
示例6：通过while循环使用SearchCursor。
|
|
3.3 UpdateCursor
UpdateCursor函数可创建一个用于更新或删除指定要素类、shapefile和表中的行的游标。该游标将数据锁定保留至脚本完成或更新游标对象被删除时。
UpdateCursor函数的调用方式为：UpdateCursor (dataset, {where_clause}, {spatial_reference}, {fields}, {sort_fields})，其语法以及返回值信息分别如表9和10所示。表7 SearchCursor函数语法
| 参数 |
数据类型 |
说明 |
| dataset |
String |
包含要更新或删除行的要素类、shapefile或表。 |
| where_clause |
String |
用于限制在游标中返回的行的可选表达式。 |
| spatial_reference |
SpatialReference |
在提供的spatial_reference中指定的坐标，并动态转换到数据集的坐标系。 |
| fields [fields,...] |
String |
游标中包含以分号分隔的字符串字段。默认情况下，包含所有字段。 |
| sort_fields |
String |
用于在游标中对行进行排序的字段。 |
表8 InsertCursor函数返回值
| 数据类型 |
说明 |
| Cursor |
可分发Row对象的Cursor对象 |
Python中可用于迭代搜索游标的方式有两种：for循环或者while循环（通过游标的next方法返回下一行）。通过for循环以及通过while循环使用SearchCursor函数分别如示例7和示例8所示。
示例7：通过for循环使用UpdateCursor。
|
|
示例8：通过while循环使用UpdateCursor。
|
|
4 获取和设置参数
4.1 GetParameter
在参数列表中，按所需参数的索引值选择参数。参数以对象的形式返回。要将此参数用作文本字符串，可调用GetParameterAsText函数。
GetParameter函数调用方式为GetParameter(index)，其语法说明及返回值信息分别如表9和表10所示
表9 GetParameter函数语法
| 参数 |
数据类型 |
说明 |
| index |
Integer |
在参数列表中按索引选择指定参数。 |
表10 InsertCursor函数返回值
| 数据类型 |
说明 |
| Object |
对象通过指定参数返回。 |
GetParameter函数示例如示例9所示。
示例9： GetParameter函数。
| import arcpy # 获取第一个参数 spatial_ref = arcpy.GetParameter(0) # 显示投影坐标系信息 arcpy.AddMessage("Name is: {0}".format(spatial_ref.name)) arcpy.AddMessage("Type is: {0}".format(spatial_ref.type)) arcpy.AddMessage("Factory code is: {0}".format(spatial_ref.factoryCode)) |
4.2 GetParameterAsText
按照参数在参数列表中的索引位置以文本字符串的形式获取指定参数。无论参数的数据类型是什么，所有值都将作为字符串返回。
GetParameterAsText函数调用方式为GetParameterAsText (index)，其语法说明及返回值信息分别如表11和表12所示
表11 GetParameterAsText函数语法
| 参数 |
数据类型 |
说明 |
| index |
Integer |
在参数列表中按索引选择指定参数。 |
表12 GetParameterAsText函数返回值
| 数据类型 |
说明 |
| String |
以字符串形式返回的指定参数值。 |
GetParameterAsText函数示例如示例10所示。
示例10： GetParameterAsText函数
| import os import arcpy arcpy.env.workspace = arcpy.GetParameterAsText(0) in_featureclass = arcpy.GetParameterAsText(1) out_workspace = arcpy.GetParameterAsText(2) out_featureclass = os.path.join(out_workspace, os.path.basename(in_featureclass)) arcpy.CopyFeatures_management(in_featureclass, out_featureclass) |
5 几何
5.1 AsShape
将Esri JSON或GeoJSON转换为ArcPy几何对象或要素集对象。GeoJSON 是一种地理空间数据的交换格式，可用于对地理数据结构进行编码。AsShape不支持 GeoJSON 坐标参考系对象，通过 GeoJSON 创建的几何对象的空间参考将为未知。
AsShape函数调用方式为AsShape (geojson_struct, {esri_json})，其语法说明及返回值信息分别如表13和表14所示
表13 AsShape函数语法
| 参数 |
数据类型 |
说明 |
| geojson_struct |
Dictionary |
geojson_struct包括type和coordinates。type主要类型有：Point、LineString、Polygon、MultiPoint和MultiLineString。 |
| esri_json |
Boolean |
设置将输入JSON作为Esri JSON评估还是作为GeoJSON 评估。如果为True，则将输入作为Esri JSON评估。 |
表14 AsShape函数返回值
| 数据类型 |
说明 |
| Geometry |
AsShape将基于输入GeoJSON或Esri JSON对象返回几何对象（PointGeometry、Multipoint、Polyline或Polygon）。如果Esri JSON是要素集，AsShape将返回FeatureSet。 |
AsShape函数示例如示例11所示。
示例11： AsShape函数
| import arcpy geojson_point = { "type": "Point", "coordinates": [5.0, 5.0]} point = arcpy.AsShape(geojson_point) |
6 地理数据库管理
6.1 AcceptConnections
允许管理员启用或禁用非管理员用户连接到企业级地理数据库的功能。管理员可使用AcceptConnections函数暂时阻止到企业级地理数据库的连接。该函数用于补充ArcGIS Desktop中企业级地理数据库属性页面中的“连接”选项卡。
AcceptConnections函数调用方式为AcceptConnections (sde_workspace, accept_connections)，其语法说明别如表15所示
表15 AcceptConnections函数语法
| 参数 |
数据类型 |
说明 |
| sde_workspace |
String |
将改变连接属性的企业级地理数据库。企业级地理数据库中指定的连接属性必须为地理数据库管理员。 |
| accept_connections |
Boolean |
用于指示地理数据库将接受连接 (True) 或拒绝接受连接 (False) 的布尔值。 |
AcceptConnections函数示例如示例12所示。
示例12：AcceptConnection函数。
| import arcpy admin_workspace = "Database Connections/admin.sde" arcpy.AcceptConnections(admin_workspace, False) arcpy.DisconnectUser(admin_workspace, 'ALL') arcpy.ReconcileVersions_management(admin_workspace, 'ALL_VERSIONS', 'sde.DEFAULT', with_post='POST') arcpy.Compress_management(admin_workspace) # Allow connections. arcpy.AcceptConnections(admin_workspace, True) |
6.2 DisconnectUser
DisconnectUser函数能够实现允许管理员断开当前连接到企业级地理数据库的门户的连接。
DisconnectUser函数的调用方式为DisconnectUser(sde_workspace, {users})，其语法说明如表16所示。
表16 DisconnectUser函数语法
| 参数 |
数据类型 |
说明 |
| sde_workspace |
String |
包含要断开连接的用户的企业级地理数据库。在企业级地理数据库中指定的连接文件必须具有管理权限以允许用户断开其他连接。 |
| users[users,…] |
Interger |
指定将断开哪些用户与地理数据库的连接，可选参数为： 1) sde_id —从 ListUsers 函数返回的 ID 值。可将其作为单个 sde_id 或包含多个 sde_id 的列表传递到函数。 2) ALL —关键字指定应断开所有已连接的用户。 |
DisconnectUser函数使用示例如示例13所示。
示例13：使用DisconnectUser函数断开地理数据库所有用户连接。
| import arcpy arcpy.DisconnectUser("Database Connections/[email protected]", "ALL") |
7 栅格
7.1 NumPyArrayToRaster
该函数可将NumPy数组转换为栅格。所生成的栅格数据集的大小和数据类型取决于输入数组。其中x_cell_size和y_cell_size参数可支持矩形像元。
NumpyArrayToRaster支持将多维 NumPy 数组直接转换为多波段栅格。如果输入数组具有两个维度，则其返回的单波段栅格的大小由这两个维度（行、列）定义。如果输入数组具有三个维度，则在其返回的多波段栅格中，波段数等于第一维的长度，而且该栅格的大小由第二维和第三维（波段、行、列）定义。如果输入数组具有三个维度并且第一维的大小为 1，则会返回单波段栅格。
此函数支持以下地理处理环境设置：输出坐标系、范围、捕捉栅格、当前工作空间、临时工作空间。
NumpyArrayToRaster函数调用方式为：NumPyArrayToRaster (in_array, {lower_left_corner}, {x_cell_size}, {y_cell_size}, {value_to_nodata})，其语法说明及返回值信息分别如表17和表18所示。
表17 NumpyArrayToRaster函数语法
| 参数 |
数据类型 |
说明 |
| in_array |
NumPyArray |
要转换为栅格的二维或三维的NumPy数组。 |
| lower_left_corner |
Point |
定义地图单位中输出栅格左下角的点对象。默认情况下，左下角的坐标将设置为(0.0, 0.0)。默认值为None。 |
| x_cell_size |
Double |
x方向的像元大小用地图单位指定。输入可为指定的像元大小（类型：双精度）值或栅格。默认值为1.0 |
| y_cell_size |
Double |
y 方向的像元大小用地图单位指定。输入可为指定的像元大小（类型：双精度）值或栅格。默认值为 1.0。 |
| value_to_nodata |
Double |
在输出栅格中分配到NoData的NumPy数组值。如果没有为 value_to_nodata 指定任何值，则在生成的栅格中不会有任何NoData值。默认值为 None。 |
表18 NumpyArrayToRaster函数返回值
| 数据类型 |
说明 |
| Raster |
输出栅格。 |
AcceptConnections函数示例如示例14所示。
示例14：NumpyArrayToRaster函数。
| import arcpy import numpy myArray = numpy.random.random_integers(0,100,2500) myArray.shape = (50,50) myRaster = arcpy.NumPyArrayToRaster(myArray,x_cell_size=1) myRaster.save("C:/output/fgdb.gdb/myRandomRaster") |
7.2 RasterToNumPyArray
该方法实现将栅格转换为NumPy数组。Python NumPy数组专门用于处理大型数组。很多现有Python函数都是为了处理NumPy数组而创建的，NumPy数组是包含在Python的SciPy科学计算包中的最著名数组。
如果数组的定义（左下角以及行数和列数）超出in_raster的范围，则数组值将分配为 NoData；如果lower_left_corner与像元角不重合，则会自动捕捉到最近像元角的左下角，该捕捉方法采用的规则与“捕捉栅格”环境设置中的规则相同。
RasterToNumPyArray函数支持将多波段栅格直接转换为多维数组 (ndarray)。
1) 如果输入 Raster 实例基于多波段栅格，则会返回ndarry，其中第一维的长度表示波段数。该ndarry将具有三个维度：波段、行、列。
2) 如果输入 Raster 实例基于单个栅格或多波段栅格中的特定波段，则会返回含维度（行、列）的二维数组。
RasterToNumPyArray函数调用方式为：RasterToNumPyArray (in_raster, {lower_left_corner}, {ncols}, {nrows}, {nodata_to_value})，其语法说明及返回值信息分别如表19和表20所示。
表19 RasterToNumpyArray函数语法
| 参数 |
数据类型 |
说明 |
| in_raster |
Raster |
要转换为NumPy数组的输入栅格。 |
| lower_left_corner |
Point |
可从in_raster中的左下角提取处理块以转换为数组。x值和y值采用地图单位。若未指定值，则将使用输入栅格的原点。默认值为 None。 |
| ncols |
Integer |
in_raster中要转换为NumPy数组的lower_left_corner中的列数。若未指定值，则将使用输入栅格的列数。默认值为 None。 |
| nrows |
Integer |
in_raster中要转换为 NumPy 数组的lower_left_corner中的行数。若未指定值，则将使用输入栅格的行数。默认值为 None。 |
| nodata_to_value |
Variant |
在生成的 NumPy 数组中分配in_rasterNoData值的值。若未指定值，则将使用in_raster的 NoData 值。默认值为 None。 |
表20 NumpyArrayToRaster函数返回值
| 数据类型 |
说明 |
| NumPyArray |
输出的 NumPy 数组。 |
RasterToNumPyArray函数示例如示例15所示。
示例15：RasterToNumPyArray函数。
| import arcpy import numpy inRas = arcpy.Raster('C:/data/inRaster') lowerLeft = arcpy.Point(inRas.extent.XMin,inRas.extent.YMin) cellSize = ras.meanCellWidth arr = arcpy.RasterToNumPyArray(inRas,nodata_to_value=0) arrSum = arr.sum(1) arrSum.shape = (arr.shape[0],1) arrPerc = (arr)/arrSum #Convert Array to raster (keep the origin and cellsize the same as the input) newRaster = arcpy.NumPyArrayToRaster(arrPerc,lowerLeft,cellSize, value_to_nodata=0) newRaster.save("C:/output/fgdb.gdb/PercentRaster") |
参考： https://pro.arcgis.com/zh-cn/pro-app/arcpy/main/arcgis-pro-arcpy-reference.htm