使用方法
空间连接根据要素的相对空间位置将连接要素中的行匹配到目标要素中的行。
默认情况下,连接要素的所有属性会被追加到目标要素的属性中并复制到输出要素类。通过在连接要素的字段映射参数中控制写入到输出中的属性,可以对其进行定义。
将向输出要素类添加两个新字段 Join_Count 和 TARGET_FID。其中,Join_Count 指示与各个目标要素 (TARGET_FID) 相匹配的连接要素数量。
在连接操作(Python 中的 join_operation)参数中指定一对多连接(Python 中为 JOIN_ONE_TO_MANY)时,会向输出中添加另一个新字段 JOIN_FID。
当连接操作参数为一对多连接时,输出要素类中的每个目标要素都可以包含多个行。使用 JOIN_FID 字段来确定所连接的要素与目标要素 (TARGET_FID) 的具体对应关系。JOIN_FID 字段的值为 -1,表示没有任何要素符合与目标要素存在的指定空间关系。
将所有输入目标要素写入到输出要素类的前提是满足以下两个条件:
- 将连接操作设置为一对一连接。
- 选中保留所有目标要素(Python 中为 join_type = "KEEP_ALL")。
您可以使用字段映射来控制输出数据集中所有字段以及各字段中的内容。
- 要更改字段顺序,请选择一个字段名称并将其拖动到首选位置。
- 输出字段的默认数据类型与其所遇到的第一个名称相同的输入字段的数据类型相同。您可以随时将该数据类型手动更改为其他任何有效的数据类型。
- 可以使用以下合并规则:first、last、join、sum、mean、median、mode、minimum、maximum、standard deviation 和 count。
- 如果使用连接合并规则,则可指定分隔符,例如,空格、逗号、句点和短划线等。要使用空格,请确保指针位于输入框的起始位置处,然后按一次空格键。
- 您可以使用格式选项来指定文本字段的起始和终止位置。
- 请勿对单个输入执行标准差计算,因为数字不能被零除,因此标准差不适用于单个输入。
连接要素的字段映射参数中指定的合并规则仅适用于连接要素中的属性,且仅适用于多个要素与目标要素匹配 (Join_Count > 1) 的情况。例如,如果连接 DEPTH 属性值分别为 15.5、2.5 和 3.3 的三个要素,并应用“平均值”合并规则,则输出字段的值为 6.1。在进行统计计算时忽略连接字段中的空值。例如,15.5、<空> 和 2.5 将得出的结果为:“平均值”为 9.0,“计数”为 2。
将匹配选项参数设置为最近或最近测地线时,可能会出现两个或多个连接要素与目标要素距离相等的情况。如果发生这种情况,将随机选择其中一个连接要素作为匹配要素(连接要素的对象 ID 对随机选择过程没有影响)。如果要查找排在第 2 位、第 3 位或第 N 位的最近要素,请使用生成近邻表工具。
如果连接要素与多个目标要素具有空间关系,则在将其与目标要素匹配时会进行多次计数。例如,如果点位于三个面内,则该点将计数三次,即每个面计数一次。
有关使用三维空间关系 3D 相交和在某一 3D 距离范围内的详细信息,请参阅按 3D 位置关系选择。
语法
arcpy.analysis.SpatialJoin(target_features, join_features, out_feature_class, {join_operation}, {join_type}, {field_mapping}, {match_option}, {search_radius}, {distance_field_name})
参数 | 说明 | 数据类型 |
target_features | 目标要素的属性和被连接要素的属性被传递到输出要素类。但是,可以在字段映射参数中定义属性的子集。 | Feature Layer |
join_features | 连接要素的属性将被连接到目标要素的属性中。有关连接操作的类型对所连接属性聚合的影响的详细信息,请参阅 join_operation 参数的说明。 | Feature Layer |
out_feature_class | 包含目标要素和连接要素的属性的新要素类。默认情况下,目标要素的所有属性和被连接要素的属性都被写入到输出。但是,可通过字段映射参数来控制要传递的属性集。 | Feature Class |
join_operation (可选) | 在具有相同空间关系的目标要素和连接要素之间存在一对多关系时,指定输出要素类中目标要素和连接要素之间的连接方式。
| String |
join_type (可选) | 指定是在输出要素类中保留所有目标要素(称为外部连接),还是仅保留那些与连接要素有指定空间关系的目标要素(称为内部连接)。
| Boolean |
field_mapping (可选) | 控制输出中要包含的属性字段。默认情况下,将包括输入的所有字段。 可以添加、删除、重命名和重新排序字段,且可以更改其属性。 合并规则用于指定如何将两个或更多个输入字段的值合并或组合为一个输出值。有多种合并规则可用于确定如何用值填充输出字段。
在 Python 中,您可使用 FieldMappings 类来定义此参数。 | Field Mappings |
match_option (可选) | 指定用于匹配行的条件。
| String |
search_radius (可选) | 如果连接要素与目标要素的距离在此范围内,则有可能进行空间连接。仅当已指定空间关系时(match_option 设置为 INTERSECT、WITHIN_A_DISTANCE、WITHIN_A_DISTANCE_GEODESIC、HAVE_THEIR_CENTER_IN、CLOSEST 或 CLOSEST_GEODESIC),搜索半径才有效。例如,当搜索半径设置为 100 米且空间关系设置为 WITHIN_A_DISTANCE 时,将会连接距离目标要素 100 米以内的要素。对于 WITHIN_A_DISTANCE 的三种关系而言,如果未指定 search_radius 的值,则距离将为 0。 | Linear Unit |
distance_field_name (可选) | 添加到输出要素类中的字段的名称,其中包含目标要素和最近连接要素之间的距离。仅当已指定空间关系时(match_option 设置为 CLOSEST 或 CLOSEST_GEODESIC),此参数才有效。如果在搜索半径内没有任何匹配的要素,则此字段的值为 -1。如果未指定字段名称,将不会向输出要素类中添加该字段。 | String |
代码示例
以下脚本演示了如何在 Python 窗口中使用 SpatialJoin 函数。
import arcpy
target_features = "C:/data/usa.gdb/states"
join_features = "C:/data/usa.gdb/cities"
out_feature_class = "C:/data/usa.gdb/states_cities"
arcpy.SpatialJoin_analysis(target_features, join_features, out_feature_class)
以下独立脚本演示了如何使用 SpatialJoin 函数将城市的属性连接到州。
# Name: SpatialJoin_Example2.py
# Description: Join attributes of cities to states based on spatial relationships.
# Requirements: os module
# Import system modules
import arcpy
import os
# Set local variables
workspace = r"C:\gpqa\mytools\spatialjoin\usa.gdb"
outWorkspace = r"C:\gpqa\mytools\spatialjoin\output.gdb"
# Want to join USA cities to states and calculate the mean city population
# for each state
targetFeatures = os.path.join(workspace, "states")
joinFeatures = os.path.join(workspace, "cities")
# Output will be the target features, states, with a mean city population field (mcp)
outfc = os.path.join(outWorkspace, "states_mcp2")
# Create a new fieldmappings and add the two input feature classes.
fieldmappings = arcpy.FieldMappings()
fieldmappings.addTable(targetFeatures)
fieldmappings.addTable(joinFeatures)
# First get the POP1990 fieldmap. POP1990 is a field in the cities feature class.
# The output will have the states with the attributes of the cities. Setting the
# field's merge rule to mean will aggregate the values for all of the cities for
# each state into an average value. The field is also renamed to be more appropriate
# for the output.
pop1990FieldIndex = fieldmappings.findFieldMapIndex("POP1990")
fieldmap = fieldmappings.getFieldMap(pop1990FieldIndex)
# Get the output field's properties as a field object
field = fieldmap.outputField
# Rename the field and pass the updated field object back into the field map
field.name = "mean_city_pop"
field.aliasName = "mean_city_pop"
fieldmap.outputField = field
# Set the merge rule to mean and then replace the old fieldmap in the mappings object
# with the updated one
fieldmap.mergeRule = "mean"
fieldmappings.replaceFieldMap(pop1990FieldIndex, fieldmap)
# Delete fields that are no longer applicable, such as city CITY_NAME and CITY_FIPS
# as only the first value will be used by default
x = fieldmappings.findFieldMapIndex("CITY_NAME")
fieldmappings.removeFieldMap(x)
y = fieldmappings.findFieldMapIndex("CITY_FIPS")
fieldmappings.removeFieldMap(y)
#Run the Spatial Join tool, using the defaults for the join operation and join type
arcpy.SpatialJoin_analysis(targetFeatures, joinFeatures, outfc, "#", "#", fieldmappings)
环境
许可信息
- Basic: 是
- Standard: 是
- Advanced: 是