空间连接 (分析)

摘要

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

查看空间关系示例

使用情况

• 空间连接根据要素的相对空间位置将连接要素值中的行匹配到目标要素值中的行。

• 默认情况下，连接要素的所有属性会被追加到目标要素的属性中并复制到输出要素类。 通过在连接要素的字段映射参数中控制写入到输出中的属性，可以对其进行定义。

• 将向输出要素类添加两个新字段：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 位置关系选择。

参数

对话框

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

Python

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 (可选)	在具有相同空间关系的目标要素和连接要素之间存在一对多关系时，指定输出要素类中目标要素和连接要素之间的连接方式。 JOIN_ONE_TO_ONE—如果找到与同一目标要素存在相同空间关系的多个连接要素，将使用字段映射合并规则对多个连接要素中的属性进行聚合。 例如，如果在两个独立的面连接要素中找到了同一个点目标要素，将对这两个面的属性进行聚合，然后将其传递到输出点要素类。 如果一个面要素的属性值为 3，另一个面要素的属性值为 7，且指定了“总和”合并规则，则输出要素类中的聚合值将为 10。 这是默认设置。 JOIN_ONE_TO_MANY—如果找到多个与同一目标要素存在相同空间关系的连接要素，输出要素类将包含目标要素的多个副本（记录）。 例如，如果在两个独立的面连接要素中找到了同一个点目标要素，则输出要素类将包含目标要素的两个副本：分别包含两个面的属性记录。	String
join_type (可选)	指定是在输出要素类中保留所有目标要素（称为外部连接），还是仅保留那些与连接要素有指定空间关系的目标要素（称为内部连接）。 KEEP_ALL—在输出中保留所有目标要素（外部连接）。 这是默认设置。 KEEP_COMMON—在输出要素类中仅保留那些与连接要素有指定空间关系的目标要素（内部连接）。 例如，如果将某个点要素类指定为目标要素，将某个面要素类指定为连接要素，则在 match_option = "WITHIN" 的情况下，输出要素类将仅包含那些位于面连接要素内部的目标要素。 非连接要素内部的目标要素将被从输出中排除。	Boolean
field_mapping (可选)	控制输出中要包含的属性字段。默认情况下，将包括输入的所有字段。 可以添加、删除、重命名和重新排序字段，且可以更改其属性。 合并规则用于指定如何将两个或更多个输入字段的值合并或组合为一个输出值。有多种合并规则可用于确定如何用值填充输出字段。 First - 使用输入字段的第一个值。 Last - 使用输入字段的最后一个值。 Join - 串连（连接）输入字段的值。 Sum - 计算输入字段值的总和。 Mean - 计算输入字段值的平均值。 Median - 计算输入字段值的中值。 Mode - 使用具有最高频率的值。 Min - 使用所有输入字段值中的最小值。 Max - 使用所有输入字段值中的最大值。 Standard deviation - 对所有输入字段值使用标准差分类方法。 Count - 查找计算中所包含的记录数。 在 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 相同，不同之处在于采用测地线距离而非平面距离。如果您的数据涵盖较大地理范围或输入的坐标系不适合进行距离计算，请选择此项	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

代码示例

空间连接 (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: 是