添加位置 (Network Analyst)

摘要

将输入要素或记录添加到网络分析图层。向特定子图层（如“停靠点”图层和“障碍”图层）添加输入。

了解有关添加位置工具如何在网络上定位分析输入的详细信息

使用情况

• 该工具可反复运行，以将多个网络分析对象追加到同一子图层中。例如，如果路径图层的停靠点来自于两个要素类，则该工具可被调用两次，即每个要素类调用一次。第二次，选中追加参数（在 Python 中为 append = "APPEND"）。

• 要在加载新对象之前删除现有的网络分析对象，请取消选中追加参数（在 Python 中为 append = "CLEAR"）。

• 在定位输入时，需考虑网络分析图层的出行模式和现有障碍。因此，在加载其他分析输入之前，建议您先设置用于分析的出行模式并加载障碍。

• 如果用作网络数据集中的网络源的要素类具有有效的最新的空间索引，那么该工具的运行速度将显著提高。

• 如果您的分析图层引用门户服务，则不会计算位置字段，直到您求解分析为止。对于这些图层，添加位置工具会将输入追加到分析图层，而无需计算位置字段。因此，某些工具参数不适用于这些图层，并将在工具对话框中被隐藏或在 Python 中被忽略。

参数

对话框

标注	说明	数据类型
输入网络分析图层	要添加网络分析对象的网络分析图层。	Network Analyst Layer
子图层	要添加网络分析对象的网络分析图层的子图层名称。	String
输入位置	包含要添加到网络分析子图层的位置的要素类或表。	Table View
字段映射 (可选)	您要添加位置的网络分析子图层的输入字段与输入数据或指定常量中的字段之间的映射。 网络分析图层的输入子图层具有一组输入字段，您可以根据分析需要来修改或填充这些输入字段。 将位置添加到子图层时，可以使用此参数将输入表中的字段值映射到子图层中的这些字段。 您还可以使用字段映射为每个属性指定恒定默认值。 如果属性的字段和默认值都没有指定，则生成的网络分析对象的属性值为空。 每个图层的文档中提供了每种网络分析图层类型的每个子图层的输入字段的完整列表。 例如，检查 Route 图层 Stops 子图层的输入字段。 如果正在加载的数据中含有基于用于分析的网络数据集的网络位置或位置范围，请从下拉菜单中选择使用网络位置字段选项。使用网络位置字段来添加网络分析对象比按照几何加载速度更快。 了解有关网络位置字段的详细信息	Network Analyst Class FieldMap
搜索容差 (可选)	在网络上定位输入要素所使用的搜索容差。 搜索容差以外的要素将保持未定位状态。 该参数包括容差的值和单位。 默认设置为 5000 米。 在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。 当输入网络分析图层的网络数据源为门户服务时，不使用此参数。	Linear Unit
排序字段 (可选)	当网络分析对象被添加到网络分析图层时用于排序网络分析对象的字段。默认设置为输入要素类或表中的 ObjectID 字段。	Field
搜索条件 (可选)	计算网络位置时将搜索网络数据集中的源以及将使用几何的部分（也称为捕捉类型）。 例如，如果网络数据集引用表示街道和人行道的单独要素类，则可以选择在街道上定位输入，而非人行道。 以下是每个网络源可用的捕捉类型选择： SHAPE - 点将位于此网络源中元素的最近点处。 MIDDLE - 点将位于此网络源中元素的最近中点处。 END - 点将位于此网络源中元素的最近端点处。 NONE - 点将不位于此网络源的元素上。 针对向后兼容性，将保留 MIDDLE 和 END 选项。 使用 SHAPE 选项在特定的网络源中查找输入；否则，请使用 NONE。 计算线或面要素的位置时，即使指定了其他捕捉类型，也将仅使用 SHAPE 捕捉类型。 除通过运行融合网络工具创建的覆盖交汇点和系统交汇点外（其默认值为 NONE），其他所有网络源的默认值为 SHAPE。 网络数据源为门户服务时此参数不可用。	Value Table
在所有类中查找最近的 (可选)	注： 此参数仅可通过 Python 获得。	Boolean
追加到现有位置 (可选)	指定是否将新网络分析对象附加到现有对象。 选中 - 会将新的网络分析对象追加到所选子图层中的现有对象集中。这是默认设置。 未选中 - 将删除现有的网络分析对象并使用新的对象来代替。	Boolean
捕捉到网络 (可选)	指定将输入捕捉到其计算出的网络位置，还是由其原始地理位置表示它。 要在分析中使用路边通道来控制车辆在靠近位置时必须使用道路的哪一侧，请勿将输入捕捉到其网络位置，或使用捕捉偏移来确保该点始终清晰地保持在道路的一侧。 在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。 当输入网络分析图层的网络数据源为门户服务时，不使用此参数。 注： 如果在添加位置后更改网络分析图层的出行模式，或者添加或移除障碍，则在求解时将自动重新计算受影响点的网络位置，以确保其仍然有效。此自动重新计算过程将不考虑先前在计算网络位置时使用的任何设置，例如搜索查询。相反，它仅使用输入要素的几何以及网络分析图层的出行模式和障碍。要在自动重新计算该点的网络位置时，提升选择相同网络位置的可能性，请使用此参数将输入捕捉到运行此工具时计算出的网络位置。这样，所需的网络位置将保留在输入点的几何中。 选中 - 网络位置的几何将被捕捉到其网络位置。 未选中 - 网络位置的几何将基于输入要素的几何。这是默认设置。	Boolean
捕捉偏移 (可选)	将点捕捉到网络时，您可以应用偏移距离。 偏移距离为零表示点将与网络要素（通常是线）重合。 要使点偏离网络要素，请输入偏移距离。 偏移与起始点的位置有关；即，如果起始点在左侧，它的新位置就会向左偏移。 如果起始点在右侧，它的新位置就会向右偏移。 默认值为 5 米。但是，如果未选中捕捉到网络，则会忽略此参数。 在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。 当输入网络分析图层的网络数据源为门户服务时，不使用此参数。	Linear Unit
排除网络中的受限部分 (可选)	注： 此参数仅可通过 Python 获得。	Boolean
搜索查询 (可选)	定义将搜索限制在源要素类的要素子集内的查询。 这在不想查找可能不适合分析的要素时很有用。 例如，您可以使用查询来排除具有特定道路类的所有要素。 可以为网络数据集的每个源要素类指定一个单独的 SQL 表达式。 默认情况下任何源都不使用查询。 网络数据源为门户服务时此参数不可用。 通过在名称列内选择源名称并在查询列中使用 SQL 表达式构建器来指定给定网络源的 SQL 表达式。 有关 SQL 语法的详细信息，请参阅在 ArcGIS 中使用的查询表达式的 SQL 参考。 在工具对话框中未明确指定的任何网络源都不会应用查询。	Value Table

派生输出

标注	说明	数据类型
更新的输入网络分析图层	已更新的网络分析图层。	网络分析图层

Python

arcpy.na.AddLocations(in_network_analysis_layer, sub_layer, in_table, {field_mappings}, {search_tolerance}, {sort_field}, {search_criteria}, {match_type}, {append}, {snap_to_position_along_network}, {snap_offset}, {exclude_restricted_elements}, {search_query})

名称	说明	数据类型
in_network_analysis_layer	要添加网络分析对象的网络分析图层。	Network Analyst Layer
sub_layer	要添加网络分析对象的网络分析图层的子图层名称。	String
in_table	包含要添加到网络分析子图层的位置的要素类或表。	Table View
field_mappings (可选)	您要添加位置的网络分析子图层的输入字段与输入数据或指定常量中的字段之间的映射。 网络分析图层的输入子图层具有一组输入字段，您可以根据分析需要来修改或填充这些输入字段。 将位置添加到子图层时，可以使用此参数将输入表中的字段值映射到子图层中的这些字段。 您还可以使用字段映射为每个属性指定恒定默认值。 如果属性的字段和默认值都没有指定，则生成的网络分析对象的属性值为空。 每个图层的文档中提供了每种网络分析图层类型的每个子图层的输入字段的完整列表。 例如，检查 Route 图层 Stops 子图层的输入字段。 从 NAClassFieldMappings 类中获得的 NAClassFieldMappings 对象用于指定参数值。NAClassFieldMappings 对象是 NAClassFieldMap 对象的集合，允许您指定默认值或从网络分析对象属性的输入要素中映射字段名。如果正在加载的数据含有用于分析的网络数据集的网络位置或位置范围，请将网络位置字段从输入要素映射到网络位置属性。在字段映射中指定网络位置字段与使用工具对话框中的使用网络位置字段选项相类似。 了解有关网络位置字段的详细信息 警告： 如果为其中的任意一个网络位置属性指定字段映射，那么您必须为其余的网络位置属性指定字段映射，以避免工具执行错误。	Network Analyst Class FieldMap
search_tolerance (可选)	在网络上定位输入要素所使用的搜索容差。 搜索容差以外的要素将保持未定位状态。 该参数包括容差的值和单位。 默认设置为 5000 米。 在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。 当输入网络分析图层的网络数据源为门户服务时，不使用此参数。	Linear Unit
sort_field (可选)	当网络分析对象被添加到网络分析图层时用于排序网络分析对象的字段。默认设置为输入要素类或表中的 ObjectID 字段。	Field
search_criteria [[Source, SnapType],...] (可选)	计算网络位置时将搜索网络数据集中的源以及将使用几何的部分（也称为捕捉类型）。 例如，如果网络数据集引用表示街道和人行道的单独要素类，则可以选择在街道上定位输入，而非人行道。 以下是每个网络源可用的捕捉类型选择： SHAPE - 点将位于此网络源中元素的最近点处。 MIDDLE - 点将位于此网络源中元素的最近中点处。 END - 点将位于此网络源中元素的最近端点处。 NONE - 点将不位于此网络源的元素上。 针对向后兼容性，将保留 MIDDLE 和 END 选项。 使用 SHAPE 选项在特定的网络源中查找输入；否则，请使用 NONE。 计算线或面要素的位置时，即使指定了其他捕捉类型，也将仅使用 SHAPE 捕捉类型。 除通过运行融合网络工具创建的覆盖交汇点和系统交汇点外（其默认值为 NONE），其他所有网络源的默认值为 SHAPE。 网络数据源为门户服务时此参数不可用。 该参数值被指定为具有嵌套列表的列表。 嵌套列表由两个值组成，分别表示每个网络源的名称和捕捉类型。 例如，参数值 [["Streets","SHAPE"],["Streets_ND_Junctions","NONE"]] 指定搜索可定位于 Streets 源的形状，而不可定位于 Streets_ND_Junctions 源。 未包含在本列表中的任何网络源将使用其默认捕捉类型。 建议将所有网络源包含在列表中并为每个网络源明确地设置捕捉类型。 对于地理数据库网络数据集，可以为网络源的每个子类型指定捕捉类型。 例如，如果网络具有名为 Streets 的源，且该源具有名为 Local Streets 的子类型，请使用 ["Streets : Local Streets", "SHAPE"] 来指定地方街道的捕捉类型。	Value Table
match_type (可选)	指定网络位置的匹配方式。 MATCH_TO_CLOSEST—新网络位置将与已在搜索条件中指定捕捉类型的所有源中的最近网络源相匹配。 这是默认设置。 PRIORITY—新网络位置将与已在搜索条件中指定捕捉类型的第一个网络源相匹配。 这些源按照优先级顺序进行搜索，当在搜索容差内找到位置时，搜索停止。 在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。 当输入网络分析图层的网络数据源为门户服务时，不使用此参数。	Boolean
append (可选)	指定是否将新网络分析对象附加到现有对象。 APPEND—会将新的网络分析对象追加到所选子图层中的现有对象集中。这是默认设置。 CLEAR—将删除现有的网络分析对象并使用新的对象来代替。	Boolean
snap_to_position_along_network (可选)	指定将输入捕捉到其计算出的网络位置，还是由其原始地理位置表示它。 要在分析中使用路边通道来控制车辆在靠近位置时必须使用道路的哪一侧，请勿将输入捕捉到其网络位置，或使用捕捉偏移来确保该点始终清晰地保持在道路的一侧。 在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。 当输入网络分析图层的网络数据源为门户服务时，不使用此参数。 注： 如果在添加位置后更改网络分析图层的出行模式，或者添加或移除障碍，则在求解时将自动重新计算受影响点的网络位置，以确保其仍然有效。此自动重新计算过程将不考虑先前在计算网络位置时使用的任何设置，例如搜索查询。相反，它仅使用输入要素的几何以及网络分析图层的出行模式和障碍。要在自动重新计算该点的网络位置时，提升选择相同网络位置的可能性，请使用此参数将输入捕捉到运行此工具时计算出的网络位置。这样，所需的网络位置将保留在输入点的几何中。 NO_SNAP— 网络位置的几何将基于输入要素的几何。这是默认设置。 SNAP—网络位置的几何将被捕捉到其网络位置。	Boolean
snap_offset (可选)	将点捕捉到网络时，您可以应用偏移距离。 偏移距离为零表示点将与网络要素（通常是线）重合。 要使点偏离网络要素，请输入偏移距离。 偏移与起始点的位置有关；即，如果起始点在左侧，它的新位置就会向左偏移。 如果起始点在右侧，它的新位置就会向右偏移。 在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。 默认值为 5 米。但是，如果将 snap_to_position_along_network 设置为 NO_SNAP，则会忽略此参数。 在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。 当输入网络分析图层的网络数据源为门户服务时，不使用此参数。	Linear Unit
exclude_restricted_elements (可选)	指定是否将排除受限网络元素。 EXCLUDE—网络位置将仅放置在网络的可遍历部分。这样可防止将网络位置放在因限制或障碍而无法到达的元素上。使用该选项添加网络位置之前，请确保已经向输入网络分析图层添加了所有限制型障碍，以得到预期结果。添加障碍对象时，此参数不适用。在这种情况下，使用 "#" 作为参数值。这是默认设置。 INCLUDE—网络位置将放置在网络的所有元素上。如果通过该参数添加的网络位置被放置在受限元素上，那么在求解过程中，可能无法到达这些网络位置。 当输入网络分析图层的网络数据源为门户服务时，不使用此参数。	Boolean
search_query [[Source, Expression],...] (可选)	定义将搜索限制在源要素类的要素子集内的查询。 这在不想查找可能不适合分析的要素时很有用。 例如，您可以使用查询来排除具有特定道路类的所有要素。 可以为网络数据集的每个源要素类指定一个单独的 SQL 表达式。 默认情况下任何源都不使用查询。 网络数据源为门户服务时此参数不可用。 该参数值被指定为嵌套列表的列表。 嵌套列表由两个值组成，分别表示所有网络源的名称和 SQL 表达式。 有关 SQL 语法的详细信息，请参阅在 ArcGIS 中使用的查询表达式的 SQL 参考。 未包含在本列表中的任何网络源都不会应用查询。 同样，指定为空字符串的表达式也将解释为无查询。 例如，参数值 [["Streets", "\"CFCC\" = 'A15'"], ["Streets_ND_Junctions", ""]] 指定对 Streets 源要素类的查询，以仅在 CFCC 字段值为 A15 的街道上定位输入。 Streets_ND_Junctions 源要素类未应用任何查询。	Value Table

派生输出

名称	说明	数据类型
output_layer	已更新的网络分析图层。	网络分析图层

代码示例

AddLocations 示例 1（Python 窗口）

仅使用必需参数执行此工具。

hospitals = "C:/Data/SanFrancisco.gdb/Analysis/Hospitals"
arcpy.na.AddLocations("Route", "Stops", hospitals, "", "")

AddLocations 示例 2（Python 窗口）

使用所有参数执行此工具。

hospitals = "C:/Data/SanFrancisco.gdb/Analysis/Hospitals"
arcpy.na.AddLocations("Route", "Stops", hospitals,
                      "Name Name #;Attr_Minutes VisitTime 0;CurbApproach # 0",
                      "2 Miles", "FID",
                      [["Streets", "SHAPE"], ["Streets_ND_Junctions", "NONE"]],
                      "MATCH_TO_CLOSEST", "CLEAR", "SNAP", "10 Feet", "EXCLUDE",
                      [["Streets", '"FREEWAY" = 0'],
                      ["Streets_ND_Junctions", ""]])

AddLocations 示例 3（工作流）

以下独立 Python 脚本演示了如何使用 AddLocations 工具将起始点和目的地点加载到 OD 成本矩阵图层中。

旧版本：

GetNASublayer 功能可用于检索网络分析图层的子图层。 它是在 ArcGIS Pro 2.7 中引入的。 在以前的软件版本中，检索网络分析图层的子图层对象的最佳方法是使用网络分析 Layer 对象的 listLayers 方法，该方法将子图层名称用作通配符。

# Name: AddLocations_Workflow.py
# Description: Calculate a travel time matrix between stores. Use the Add
#               Locations tool to load origins and destinations into an OD Cost
#               Matrix layer. Since the origins and destinations are the same in
#               this case, the origins are first loaded from the stores feature
#               class using geometry, and the destinations are loaded from the
#               origins using network location fields in order to speed up the
#               load times.
# Requirements: Network Analyst Extension

# Import system modules
import arcpy
from arcpy import env
import os

try:
    # Check out Network Analyst license if available. Fail if the Network Analyst license is not available.
    if arcpy.CheckExtension("network") == "Available":
        arcpy.CheckOutExtension("network")
    else:
        raise arcpy.ExecuteError("Network Analyst Extension license is not available.")
    
    # Set environment settings
    output_dir = "C:/Data"
    # The NA layer's data will be saved to the workspace specified here
    env.workspace = os.path.join(output_dir, "Output.gdb")
    env.overwriteOutput = True

    # Set inputs and outputs
    input_gdb = "C:/Data/SanFrancisco.gdb"
    network = os.path.join(input_gdb, "Transportation", "Streets_ND")
    layer_name = "StoreTravelTimeMatrix"
    travel_mode = "Driving Time"
    stores = os.path.join(input_gdb, "Analysis", "Stores")
    search_tolerance = "500 Meters"
    search_query = [["Streets", '"FREEWAY" = 0'], ["Streets_ND_Junctions", ""]]
    output_layer_file = os.path.join(output_dir, layer_name + ".lyrx")

    # Create a new OD cost matrix analysis layer. For this scenario, the default
    # value for all the remaining parameters statisfies the analysis requirements
    result_object = arcpy.na.MakeODCostMatrixAnalysisLayer(network, layer_name,
                                                    travel_mode)

    # Get the layer object from the result object. The OD cost matrix layer can
    # now be referenced using the layer object.
    layer_object = result_object.getOutput(0)

    # Get the names of all the sublayers within the OD layer.
    sublayer_names = arcpy.na.GetNAClassNames(layer_object)
    # Store the layer names for later use
    origins_layer_name = sublayer_names["Origins"]
    destinations_layer_name = sublayer_names["Destinations"]

    # Load store features as origins using the geometry of store features.
    # Ensure that the stores are not located on freeways by using a search query.
    arcpy.na.AddLocations(layer_object, origins_layer_name, stores, "",
                          search_tolerance,
                          exclude_restricted_elements="EXCLUDE",
                          search_query=search_query)

    # Because we want our origins and destinations to be the same, load the
    # origins as destinations using the network locations fields. Loading using
    # existing network location fields is much faster than loading using geometry
    # because the network locations have already been calculated.
    # Create a field mappings object that supports network location fields using
    # the candidate fields from origins
    origins_sublayer = arcpy.na.GetNASublayer(layer_object, "Origins")
    candidate_fields = arcpy.ListFields(origins_sublayer)
    field_mappings = arcpy.na.NAClassFieldMappings(layer_object,
                                                  destinations_layer_name, True,
                                                  candidate_fields)
    arcpy.na.AddLocations(layer_object, destinations_layer_name,
                            origins_sublayer, field_mappings, "")

    # Solve the od cost matrix layer. Halt the execution if there is an
    # invalid location
    arcpy.na.Solve(layer_object, "HALT")

    # Save the solved OD cost matrix layer as a layer file on disk
    layer_object.saveACopy(output_layer_file)

    print("Script completed successfully")

except Exception as e:
    # If an error occurred, print line number and error message
    import traceback, sys
    tb = sys.exc_info()[2]
    print("An error occurred on line %i" % tb.tb_lineno)
    print(str(e))

环境

当前工作空间

特殊情况

许可信息

• Basic: 是
• Standard: 是
• Advanced: 是