空间连接 (分析)—ArcGIS Pro

摘要

根据空间关系将一个要素的属性连接到另一个要素。目标要素和来自连接要素的被连接属性写入到输出要素类。

使用情况

空间连接根据要素的相对空间位置将连接要素值中的行匹配到目标要素值中的行。
默认情况下，连接要素的所有属性均附加到目标要素的属性并复制到输出要素类。您可以使用字段映射参数定义将写入输出的属性。
两个新字段 Join_Count 和 TARGET_FID 即会添加至输出要素类。 Join_Count 表示与每个目标要素 (TARGET_FID) 匹配的连接要素数。
在连接操作参数中指定一对多连接时，会向输出添加另一个新字段 JOIN_FID。
当将连接操作参数设置为一对多连接时，输出要素类中的每个目标要素都可以包含多个行。使用 JOIN_FID 字段可确定哪个要素连接到哪个目标要素 (TARGET_FID)。 JOIN_FID 字段的值为 -1，表示没有任何要素符合使用目标要素指定的空间关系。
如果满足以下两个条件，则所有输入目标要素将写入输出要素类。
- 连接操作设置为一对一连接。
- 已选中保留所有目标要素。
要将字段永久传递到目标要素类，请使用添加空间连接工具并选中其永久连接字段参数。
使用字段映射参数管理输出数据集中的字段及其内容。
- 您可以向字段列表中添加和移除字段，重新排序字段列表，并重命名字段。
- 输出字段的默认数据类型与它遇到的第一个输入字段（具有相同名称的字段）的数据类型相同。可以将数据类型更改为其他有效的数据类型。
- 使用操作确定如何将一个或多个输入字段的值合并到单个输出字段中。可用的操作包括第一个、最后一个、串连、求和、平均值、中位数、众数、最小值、最大值、标准差和计数。
- 当使用串连操作时，可以指定分隔符，例如逗号或其他字符。单击分隔符文本框的开始部分以添加分隔符。
- 单个输入值不支持标准差选项。
- 使用导出选项将字段映射另存为 .fieldmap 文件。
- 使用加载选项加载 .fieldmap 文件。文件中指定的要素图层或数据集必须与工具中使用的数据集相匹配。否则，将重置字段映射参数。
- 对于文本源字段，使用分割文本按钮，可以选择从输入值中提取到输出字段的字符。要访问分割文本按钮，需将鼠标悬停在输入字段列表中的文本字段上，然后指定起始和结束字符位置。
- 还可以在 Python 脚本中映射字段。
在字段映射参数中指定的操作仅应用于连接要素中的属性，并且仅当多个要素与目标要素相匹配 (Join_Count > 1) 时应用。例如，如果连接 DEPTH 属性值分别为 15.5、2.5 和 3.3 的三个要素，并应用平均值操作，则输出字段的值为 6.1。在进行统计计算时忽略连接字段中的空值。例如，15.5、null 值和 2.5 将得出的结果为：“平均值”为 9.0，“计数”为 2。
将匹配选项参数设置为最近或最近测地线时，可能会出现两个或多个连接要素与目标要素距离相等的情况。如果发生这种情况，系统会随机选择其中一个连接要素作为匹配要素（连接要素的对象 ID 不会影响此随机选择）。如果要查找排在第 2 位、第 3 位或第 n 位的最近要素，使用生成近邻表工具。
了解有关如何计算邻近值的详细信息
如果连接要素与多个目标要素具有空间关系，则在根据目标要素对其进行匹配时进行多次计数。例如，如果点位于三个面内，则该点将计数三次，即每个面计数一次。
匹配属性参数将根据匹配选项参数中指定的空间关系过滤要匹配的要素。除了空间关系外，还可以指定连接要素和目标要素中必须具有匹配属性的字段。
有关使用 3D 相交和在某一 3D 距离范围内空间关系的详细信息，请参阅按位置选择：3D 关系。.

参数

标注	说明	数据类型
目标要素	会将目标要素中的属性和已连接要素中的属性传递到输出要素类。但是，可以通过字段映射参数定义属性的子集。	Feature Layer
连接要素	连接要素的属性将被连接到目标要素的属性中。有关连接操作的类型对所连接属性聚合的影响的详细信息，请参阅连接操作参数的说明。	Feature Layer
输出要素类	此新要素类包含目标要素和连接要素的属性。默认情况下，目标要素的所有属性和连接要素的属性将写入输出。但是，可通过字段映射参数定义要传递的属性集。	Feature Class
连接操作 (可选)	如果发现多个连接要素与单个目标要素具有相同的空间关系，此操作将在输出要素类中连接目标要素类和连接要素。一对一连接—如果发现多个连接要素与单一目标要素具有相同的空间关系，则将按照字段映射合并规则聚合来自多个连接要素的属性。例如，如果在两个独立的面连接要素中找到了同一个点目标要素，将对这两个面的属性进行聚合，然后将其传递到输出点要素类。如果一个面要素的属性值为 3，另一个面要素的属性值为 7，且指定了“总和”合并规则，则输出要素类中的聚合值将为 10。这是默认设置。一对多连接—如果发现多个连接要素与单一目标要素具有相同的空间关系，则输出要素类将包含目标要素的多个副本（记录）。例如，如果在两个独立的面连接要素中找到了同一个点目标要素，则输出要素类将包含目标要素的两个副本：分别包含两个面的属性记录。	String
保留所有目标要素 (可选)	指定是在输出要素类中保留所有目标要素（外部连接），还是仅保留那些与连接要素有指定空间关系的目标要素（称为内部连接）。选中 - 在输出中保留所有目标要素（外部连接）。这是默认设置。未选中 - 在输出要素类中仅保留那些与连接要素有指定空间关系的目标要素（内部连接）。例如，如果将某个点要素类指定为目标要素，将某个面要素类指定为连接要素，并选择范围内作为匹配选项值，则输出要素类将仅包含那些位于面连接要素内部的目标要素。不在连接要素内的所有目标要素将从输出中排除。	Boolean
字段映射 (可选)	在输出要素类中将包含具有各自属性和源字段的字段。默认情况下，输出包括连接和目标要素中的所有字段。使用字段映射来添加、删除、重命名和重新排序字段，以及更改其他字段属性。字段映射可以用于将两个或多个输入字段的值合并为单个输出字段。	Field Mappings
匹配选项 (可选)	指定将用于匹配行的条件。相交—如果连接要素与目标要素相交，将匹配连接要素中相交的要素。这是默认设置。在搜索半径参数中指定距离。 3D 相交—如果连接要素中的要素与三维空间（x、y 和 z）中的某一目标要素相交，则将匹配这些要素。在搜索半径参数中指定距离。在某一距离范围内—如果连接要素在目标要素的指定距离之内，将匹配处于该距离内的要素。在搜索半径参数中指定距离。在某一测地线距离范围内—与在某一距离范围内相同，不同之处在于采用测地线距离而非平面距离。将使用测地线公式计算要素间的距离，这种方法考虑到椭球体的曲率，并可以正确处理跨越日期变更线和两极及其附近的数据。如果您的数据涵盖较大地理范围或输入的坐标系不适合进行距离计算，请使用此选项。在某一 3D 距离范围内—在三维空间内，如果连接要素中的要素与目标要素间的距离在指定范围内，则匹配这些要素。在搜索半径参数中指定距离。包含—如果目标要素中包含连接要素中的要素，将匹配连接要素中被包含的要素。目标要素必须是面或折线。对于此选项，目标要素不能为点，且仅当目标要素为面时连接要素才能为面。完全包含—如果目标要素完全包含连接要素中的要素，将匹配连接要素中被包含的要素。面可以完全包含任意要素。点不能完全包含任何要素，甚至不能包含点。折线只能完全包含折线和点要素。包含 (Clementini)—该空间关系产生的结果与完全包含相同，但有一种情况例外：如果连接要素完全位于目标要素的边界上（没有任何一部分完全位于内部或外部），则不会匹配要素。 Clementini 将边界面定义为用来分隔内部和外部的线，将线的边界定义为其端点，点的边界始终为空。位于—如果目标要素位于连接要素内，将匹配连接要素中包含目标要素的要素。这与包含相反。对于此选项，只有当连接要素也为面时目标要素才可为面。仅当点为目标要素时，连接要素才能为点。完全位于—如果目标要素完全在连接要素范围内，则匹配连接要素中完全包含目标要素的要素。这与完全包含相反。位于 (Clementini)—结果与范围内相同，但下述情况例外：如果连接要素中的全部要素均位于目标要素的边界上，则不会匹配要素。 Clementini 将边界面定义为用来分隔内部和外部的线，将线的边界定义为其端点，点的边界始终为空。与其他要素相同—如果连接要素与目标要素相同，将匹配连接要素中相同的要素。连接要素和目标要素必须具有相同的形状类型 - 点到点、线到线或者面到面。边界接触—如果连接要素中具有边界与目标要素相接的要素，将匹配这些要素。如果目标和连接要素为线或面，则连接要素的边界只可接触目标要素的边界，且连接要素的任何部分均不可跨越目标要素的边界。与其他要素共线—如果连接要素中具有与目标要素共线的要素，将匹配这些要素。连接要素和目标要素必须是线或面。与轮廓交叉—如果连接要素中具有轮廓与目标要素交叉的要素，则将匹配这些要素。连接要素和目标要素必须是线或面。如果将面用于连接或目标要素，则会使用面的边界（线）。将匹配在某一点交叉的线，而不会匹配共线的线。中心在要素范围内—如果目标要素的中心位于连接要素内，将匹配这些要素。要素中心的计算方式如下：对于面和多点，将使用几何的质心；对于线输入，则会使用几何的中点。在搜索半径参数中指定距离。最近—将匹配连接要素中与目标要素最近的要素。有关详细信息，请参阅使用提示。在搜索半径参数中指定距离。最近测地线—与最近相同，不同之处在于采用测地线距离而非平面距离。如果您的数据涵盖较大地理范围或输入的坐标系不适合进行距离计算，请使用此选项最大重叠—连接要素中的要素将与具有最大重叠的目标要素进行匹配。	String
搜索半径 (可选)	如果连接要素与目标要素的距离在此范围内，则有可能进行空间连接。仅当已指定空间关系时（匹配选项参数设置为相交、在某一距离范围内、在某一测地线距离范围内、质心在以下图层中的要素内、最近或最近测地线），搜索半径才有效。例如，当搜索半径设置为 100 米且使用在某一距离范围内空间关系时，将会连接距离目标要素 100 米以内的要素。对于在某一距离范围内的三种关系而言，如果未指定搜索半径的值，则将使用距离 0。	Linear Unit
距离字段名称 (可选)	包含目标要素与最近连接要素间距的字段的名称。此字段将添加至输出要素类。仅当指定空间关系（匹配选项设置为最近或最近测地线）时，此参数才有效。如果搜索半径中没有匹配的要素，则此字段的值为 -1。如果未提供字段名称，将不会向输出要素类中添加该字段。	String
匹配字段 (可选)	连接要素和目标要素之间的字段对将用于属性匹配。仅与目标要素具有匹配字段值的连接要素记录才会参与空间连接。	Value Table

arcpy.analysis.SpatialJoin(target_features, join_features, out_feature_class, {join_operation}, {join_type}, {field_mapping}, {match_option}, {search_radius}, {distance_field_name}, {match_fields})

名称	说明	数据类型
target_features	会将目标要素中的属性和已连接要素中的属性传递到输出要素类。但是，可以通过字段映射参数定义属性的子集。	Feature Layer
join_features	连接要素的属性将被连接到目标要素的属性中。有关连接操作的类型对所连接属性聚合的影响的详细信息，请参阅 join_operation 参数的说明。	Feature Layer
out_feature_class	此新要素类包含目标要素和连接要素的属性。默认情况下，目标要素的所有属性和连接要素的属性将写入输出。但是，可通过字段映射参数定义要传递的属性集。	Feature Class
join_operation (可选)	如果发现多个连接要素与单个目标要素具有相同的空间关系，此操作将在输出要素类中连接目标要素类和连接要素。 JOIN_ONE_TO_ONE—如果发现多个连接要素与单一目标要素具有相同的空间关系，则将按照字段映射合并规则聚合来自多个连接要素的属性。例如，如果在两个独立的面连接要素中找到了同一个点目标要素，将对这两个面的属性进行聚合，然后将其传递到输出点要素类。如果一个面要素的属性值为 3，另一个面要素的属性值为 7，且指定了“总和”合并规则，则输出要素类中的聚合值将为 10。这是默认设置。 JOIN_ONE_TO_MANY—如果发现多个连接要素与单一目标要素具有相同的空间关系，则输出要素类将包含目标要素的多个副本（记录）。例如，如果在两个独立的面连接要素中找到了同一个点目标要素，则输出要素类将包含目标要素的两个副本：分别包含两个面的属性记录。	String
join_type (可选)	指定是在输出要素类中保留所有目标要素（外部连接），还是仅保留那些与连接要素有指定空间关系的目标要素（称为内部连接）。 KEEP_ALL—将在输出（外部连接）中保留所有目标要素。这是默认设置。 KEEP_COMMON—将仅在输出要素类（内部连接）中保留那些与连接要素有指定空间关系的目标要素。例如，如果将某个点要素类指定为目标要素，并将某个面要素类指定为连接要素，WITHIN 值为 match_option，则输出要素类将仅包含位于面连接要素内的目标要素。不在连接要素内的所有目标要素将从输出中排除。	Boolean
field_mapping (可选)	在输出要素类中将包含具有各自属性和源字段的字段。默认情况下，输出包括连接和目标要素中的所有字段。使用字段映射来添加、删除、重命名和重新排序字段，以及更改其他字段属性。字段映射可以用于将两个或多个输入字段的值合并为单个输出字段。在 Python 中，使用 FieldMappings 类来定义此参数。	Field Mappings
match_option (可选)	指定将用于匹配行的条件。 INTERSECT—如果连接要素与目标要素相交，将匹配连接要素中相交的要素。这是默认设置。在 search_radius 参数中指定距离。 INTERSECT_3D—如果连接要素中的要素与三维空间（x、y 和 z）中的某一目标要素相交，则将匹配这些要素。在 search_radius 参数中指定距离。 WITHIN_A_DISTANCE—如果连接要素在目标要素的指定距离之内，将匹配处于该距离内的要素。在 search_radius 参数中指定距离。 WITHIN_A_DISTANCE_GEODESIC—与 WITHIN_A_DISTANCE 相同，不同之处在于采用测地线距离而非平面距离。将使用测地线公式计算要素间的距离，这种方法考虑到椭球体的曲率，并可以正确处理跨越日期变更线和两极及其附近的数据。如果您的数据涵盖较大地理范围或输入的坐标系不适合进行距离计算，请使用此选项。 WITHIN_A_DISTANCE_3D—在三维空间内，如果连接要素中的要素与目标要素间的距离在指定范围内，则匹配这些要素。在 search_radius 参数中指定距离。 CONTAINS—如果目标要素中包含连接要素中的要素，将匹配连接要素中被包含的要素。目标要素必须是面或折线。对于此选项，目标要素不能为点，且仅当目标要素为面时连接要素才能为面。 COMPLETELY_CONTAINS—如果目标要素完全包含连接要素中的要素，将匹配连接要素中被包含的要素。面可以完全包含任意要素。点不能完全包含任何要素，甚至不能包含点。折线只能完全包含折线和点要素。 CONTAINS_CLEMENTINI—该空间关系产生的结果与 COMPLETELY_CONTAINS 相同，但有一种情况例外：如果连接要素完全位于目标要素的边界上（没有任何一部分完全位于内部或外部），则不会匹配要素。 Clementini 将边界面定义为用来分隔内部和外部的线，将线的边界定义为其端点，点的边界始终为空。 WITHIN—如果目标要素位于连接要素内，将匹配连接要素中包含目标要素的要素。这与 CONTAINS 相反。对于此选项，只有当连接要素也为面时目标要素才可为面。仅当点为目标要素时，连接要素才能为点。 COMPLETELY_WITHIN—如果目标要素完全在连接要素范围内，则匹配连接要素中完全包含目标要素的要素。这与 COMPLETELY_CONTAINS 相反。 WITHIN_CLEMENTINI—结果与 WITHIN 相同，但下述情况例外：如果连接要素中的全部要素均位于目标要素的边界上，则不会匹配要素。 Clementini 将边界面定义为用来分隔内部和外部的线，将线的边界定义为其端点，点的边界始终为空。 ARE_IDENTICAL_TO—如果连接要素与目标要素相同，将匹配连接要素中相同的要素。连接要素和目标要素必须具有相同的形状类型 - 点到点、线到线或者面到面。 BOUNDARY_TOUCHES—如果连接要素中具有边界与目标要素相接的要素，将匹配这些要素。如果目标和连接要素为线或面，则连接要素的边界只可接触目标要素的边界，且连接要素的任何部分均不可跨越目标要素的边界。 SHARE_A_LINE_SEGMENT_WITH—如果连接要素中具有与目标要素共线的要素，将匹配这些要素。连接要素和目标要素必须是线或面。 CROSSED_BY_THE_OUTLINE_OF—如果连接要素中具有轮廓与目标要素交叉的要素，则将匹配这些要素。连接要素和目标要素必须是线或面。如果将面用于连接或目标要素，则会使用面的边界（线）。将匹配在某一点交叉的线，而不会匹配共线的线。 HAVE_THEIR_CENTER_IN—如果目标要素的中心位于连接要素内，将匹配这些要素。要素中心的计算方式如下：对于面和多点，将使用几何的质心；对于线输入，则会使用几何的中点。在 search_radius 参数中指定距离。 CLOSEST—将匹配连接要素中与目标要素最近的要素。有关详细信息，请参阅使用提示。在 search_radius 参数中指定距离。 CLOSEST_GEODESIC—与 CLOSEST 相同，不同之处在于采用测地线距离而非平面距离。如果您的数据涵盖较大地理范围或输入的坐标系不适合进行距离计算，请使用此选项 LARGEST_OVERLAP—连接要素中的要素将与具有最大重叠的目标要素进行匹配。	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 米以内的要素。对于在某一距离范围内的三种关系而言，如果未指定 search_radius 的值，则将使用距离 0。	Linear Unit
distance_field_name (可选)	包含目标要素与最近连接要素间距的字段的名称。此字段将添加至输出要素类。仅当指定空间关系时（match_option 设置为 CLOSEST 或 CLOSEST_GEODESIC），此参数才有效。如果搜索半径中没有匹配的要素，则此字段的值为 -1。如果未提供字段名称，将不会向输出要素类中添加该字段。	String
match_fields [[join_field, target_field],...] (可选)	连接要素和目标要素之间的字段对将用于属性匹配。仅与目标要素具有匹配字段值的连接要素记录才会参与空间连接。	Value Table

代码示例

SpatialJoin 示例 1（Python 窗口）

以下脚本演示了如何在 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.analysis.SpatialJoin(target_features, join_features, out_feature_class)

空间连接 (SpatialJoin) 示例 2（独立脚本）

以下独立脚本演示了如何使用 SpatialJoin 函数将城市的属性连接到州。

# Name: SpatialJoin_Example2.py
# Description: Join attributes of cities to states based on spatial relationships.

# 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.analysis.SpatialJoin(targetFeatures, joinFeatures, outfc, "#", "#", fieldmappings)

环境

默认输出 Z 值, M 分辨率, M 容差, 输出配置关键字, 输出 M 值域, 输出 XY 值域, 输出 Z 值域, 输出坐标系, 范围, 输出包含 M 值, 输出包含 Z 值, XY 分辨率, XY 容差, Z 分辨率, Z 容差

许可信息

Basic: 是
Standard: 是
Advanced: 是

摘要

使用情况

参数

代码示例

环境

许可信息

相关主题

在本主题中