返回顶部

添加位置 (Network Analyst)

在本主题中

  1. 摘要
  2. 使用情况
  3. 参数
  4. 环境
  5. 许可信息

摘要

将输入要素或记录添加到网络分析图层。 向特定子图层（如“停靠点”图层和“障碍”图层）添加输入。 当网络分析图层引用网络数据集作为其网络数据源时，该工具会计算输入的网络位置，除非预先计算的网络位置字段是从输入映射的。

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

使用情况

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

  • 将根据存储在输入网络分析图层中的位置属性自动填充搜索容差、搜索条件和搜索查询参数。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。

    了解有关网络分析图层位置设置的详细信息

  • 如您更改了搜索容差、搜索条件或搜索查询参数的值，则运行该工具将更新所选子图层的网络分析图层的位置设置替代。 将这些位置设置存储在网络分析图层中可确保在求解时完成的任何自动重定位都使用您在最初计算网络位置时已使用的相同位置设置。

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

参数

对话框Python

标注说明数据类型
输入网络分析图层

要添加网络分析对象的网络分析图层。

Network Analyst Layer
子图层

要添加网络分析对象的网络分析图层的子图层名称。

String
输入位置

包含要添加到网络分析子图层的位置的要素类或表。

Table View
字段映射
(可选)

您要添加位置的网络分析子图层的输入字段与输入数据或指定常量中的字段之间的映射。

网络分析图层的输入子图层具有一组输入字段，可以填充这些字段以修改或控制分析行为。 将位置添加到子图层时，可以使用此参数将输入表中的字段值映射到子图层中的这些字段。 您还可以使用字段映射为每个属性指定恒定默认值。

如果属性的字段和默认值都没有指定，则生成的网络分析对象的属性值为空。

每个图层的文档中提供了每种网络分析图层类型的每个子图层的输入字段的完整列表。 例如，检查 Route 图层 Stops 子图层的输入字段。

如果加载的数据包含基于用于分析的网络数据源和出行模式预先计算的网络位置或位置范围，请从下拉菜单中选择使用网络位置字段选项。 使用网络位置字段来添加网络分析对象比按照几何加载速度更快。

了解有关网络位置字段的详细信息

注：

ArcGIS Online 和一些 ArcGIS Enterprise 门户不支持使用网络位置字段。 对于使用这些门户之一作为网络数据源的网络分析图层，所有输入都将在求解时定位，并且任何映射的位置字段都将被忽略。

Network Analyst Class FieldMap
搜索容差
(可选)

在网络上定位输入要素所需的最大搜索距离。 搜索容差以外的要素将保持未定位状态。 该参数包括值和单位。

此参数的默认值由存储在输入网络分析图层中的位置属性确定。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。 为此参数设置非默认值将更新网络分析图层的位置设置，覆盖选定子图层。

在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。

使用现有网络位置字段添加位置时不使用此参数。

旧版本：

当网络分析图层的网络数据源为早于 11.0 版本的 ArcGIS Enterprise 门户时，不使用此参数。

Linear Unit
排序字段
(可选)

当网络分析对象被添加到网络分析图层时用于排序网络分析对象的字段。 默认设置为输入要素类或表中的 ObjectID 字段。

Field
搜索条件
(可选)

在网络上定位输入时，将搜索的网络数据集中的边和交汇点源。 例如，如果网络数据集引用表示街道和人行道的单独要素类，则可以选择在街道上定位输入，而非人行道。

以下是每个网络源可用的捕捉类型选择：

  • NONE - 点将不位于此网络源的元素上。
  • SHAPE - 点将位于此网络源中元素的最近点处。
  • MIDDLE - 此选项已弃用，其行为与 Shape 相同。
  • END - 此选项已弃用，其行为与 Shape 相同。

此参数的默认值由存储在输入网络分析图层中的位置属性确定。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。 为此参数设置非默认值将更新网络分析图层的位置设置，覆盖选定子图层。

使用现有网络位置字段添加位置时不使用此参数。

当网络分析图层的网络数据源为 ArcGIS Online 时，不使用此参数。

旧版本：

当网络分析图层的网络数据源为早于 11.0 版本的 ArcGIS Enterprise 门户时，不使用此参数。

Value Table
在所有类中查找最近的
(可选)

旧版本：
此参数已弃用和维护，只是为了向后兼容。 输入将始终与用于定位的所有源中最近的网络源匹配，对应于参数值 MATCH_TO_CLOSEST 或 True。

Boolean
追加到现有位置
(可选)

指定是否将新网络分析对象附加到现有对象。

  • 选中 - 会将新的网络分析对象追加到所选子图层中的现有对象集中。 这是默认设置。
  • 未选中 - 将删除现有的网络分析对象并使用新的对象来代替。
Boolean
捕捉到网络
(可选)

指定将输入捕捉到其计算出的网络位置，还是由其原始地理位置表示它。

要在分析中使用路边通道来控制车辆在靠近位置时必须使用道路的哪一侧，请勿将输入捕捉到其网络位置，或使用捕捉偏移来确保该点始终清晰地保持在道路的一侧。

在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。

当输入网络分析图层的网络数据源为门户服务时，不使用此参数。

  • 选中 - 网络位置的几何将被捕捉到其网络位置。
  • 未选中 - 网络位置的几何将基于输入要素的几何。 这是默认设置。
Boolean
捕捉偏移
(可选)

将点捕捉到网络时将应用的偏移距离。 偏移距离为零表示点将与网络要素（通常是线）重合。 要使点偏离网络要素，请输入偏移距离。 偏移与起始点的位置有关；即，如果起始点在左侧，它的新位置就会向左偏移。 如果起始点在右侧，它的新位置就会向右偏移。

默认设置为 5 米。 但是，如果未选中捕捉到网络，则会忽略此参数。

在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。

当输入网络分析图层的网络数据源为门户服务时，不使用此参数。

Linear Unit
排除网络的受限部分
(可选)

旧版本：
此参数已弃用和维护，只是为了向后兼容。 分析输入永远不会位于受限制的网络元素上，对应于 EXCLUDE 或 True 的参数值。

Boolean
搜索查询
(可选)

将搜索限制在源要素类的要素子集内的查询。 这在不想查找可能不适合网络位置的要素时很有用。 例如，如果您不想定位在高速公路坡道上，则可定义一个查询将其排除。 可以为网络数据集的每个边或交汇点源要素类指定一个单独的 SQL 表达式。

任何在地理处理窗格中未明确指定的网络源都不会应用查询。

此参数的默认值由存储在输入网络分析图层中的位置属性确定。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。 为此参数设置非默认值将更新网络分析图层的位置设置，覆盖选定子图层。

使用现有网络位置字段添加位置时不使用此参数。

当网络分析图层的网络数据源为 ArcGIS Online 时，不使用此参数。

旧版本：

当网络分析图层的网络数据源为早于 11.0 版本的 ArcGIS Enterprise 门户时，不使用此参数。

Value Table
允许在求解时自动重新定位
(可选)

指定是否可以在求解时自动重定位具有现有网络位置字段的输入，以确保分析的位置字段有效并且可路由。

  • 选中 - 位于限制网络元素上的点和受障碍影响的点将在求解时重定位至最近的可路由位置。 这是默认设置。
  • 取消选中 - 求解时网络位置字段将按原样使用（即使点无法访问），并且这可能会导致求解失败。

此参数的默认值由存储在输入网络分析图层中的位置属性确定。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。 为此参数设置非默认值将更新网络分析图层的位置设置，覆盖选定子图层。

即使不允许在求解时自动重新定位，也将在求解时定位没有位置字段或位置字段不完整的输入。

当网络分析图层的网络数据源为 ArcGIS Online 时，不使用此参数。

当网络分析图层的网络数据源是不支持使用网络位置字段的 ArcGIS Enterprise 门户时，不使用此参数。

旧版本：

当网络分析图层的网络数据源为早于 11.0 版本的 ArcGIS Enterprise 门户时，不使用此参数。

Boolean

派生输出

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

已更新的网络分析图层。

Network Analyst Layer

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}, {allow_auto_relocate})
名称说明数据类型
in_network_analysis_layer

要添加网络分析对象的网络分析图层。

Network Analyst Layer
sub_layer

要添加网络分析对象的网络分析图层的子图层名称。

String
in_table

包含要添加到网络分析子图层的位置的要素类或表。

Table View
field_mappings
(可选)

您要添加位置的网络分析子图层的输入字段与输入数据或指定常量中的字段之间的映射。

网络分析图层的输入子图层具有一组输入字段，可以填充这些字段以修改或控制分析行为。 将位置添加到子图层时，可以使用此参数将输入表中的字段值映射到子图层中的这些字段。 您还可以使用字段映射为每个属性指定恒定默认值。

如果属性的字段和默认值都没有指定，则生成的网络分析对象的属性值为空。

每个图层的文档中提供了每种网络分析图层类型的每个子图层的输入字段的完整列表。 例如，检查 Route 图层 Stops 子图层的输入字段。

从 NAClassFieldMappings 类中获得的 NAClassFieldMappings 对象用于指定参数值。 NAClassFieldMappings 对象是 NAClassFieldMap 对象的集合，允许您指定默认值或从网络分析对象属性的输入要素中映射字段名。 如果正在加载的数据含有用于分析的网络数据集的网络位置或位置范围，请将网络位置字段从输入要素映射到网络位置属性。 在字段映射中指定网络位置字段与使用工具对话框中的使用网络位置字段选项相类似。

了解有关网络位置字段的详细信息

注：

ArcGIS Online 和一些 ArcGIS Enterprise 门户不支持使用网络位置字段。 对于使用这些门户之一作为网络数据源的网络分析图层，所有输入都将在求解时定位，并且任何映射的位置字段都将被忽略。

Network Analyst Class FieldMap
search_tolerance
(可选)

在网络上定位输入要素所需的最大搜索距离。 搜索容差以外的要素将保持未定位状态。 该参数包括值和单位。

此参数的默认值由存储在输入网络分析图层中的位置属性确定。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。 为此参数设置非默认值将更新网络分析图层的位置设置，覆盖选定子图层。

在将位置添加到具有线或面几何（如“线障碍”和“面障碍”）的子图层时，不使用该参数。

使用现有网络位置字段添加位置时不使用此参数。

旧版本：

当网络分析图层的网络数据源为早于 11.0 版本的 ArcGIS Enterprise 门户时，不使用此参数。

Linear Unit
sort_field
(可选)

当网络分析对象被添加到网络分析图层时用于排序网络分析对象的字段。 默认设置为输入要素类或表中的 ObjectID 字段。

Field
search_criteria
[[Source, SnapType],...]
(可选)

在网络上定位输入时，将搜索的网络数据集中的边和交汇点源。 例如，如果网络数据集引用表示街道和人行道的单独要素类，则可以选择在街道上定位输入，而非人行道。

该参数值被指定为具有嵌套列表的列表。 嵌套列表由两个值组成，分别表示每个网络源的名称和捕捉类型。

以下是每个网络源可用的捕捉类型选择：

  • NONE - 点将不位于此网络源的元素上。
  • SHAPE - 点将位于此网络源中元素的最近点处。

例如，参数值 [["Streets","SHAPE"],["Streets_ND_Junctions","NONE"]] 指定搜索可定位于 Streets 源的形状，而不可定位于 Streets_ND_Junctions 源。

未包含在本列表中的任何网络边或交汇点源源将使用其默认捕捉类型。 建议将所有网络源包含在列表中并为每个网络源明确地设置捕捉类型。

旧版本：
该工具历来支持的捕捉类型有 MIDDLE、END 和 MIDDLE_END。 为了进行向后兼容性，将弃用这些选项并加以维护。 如果指定了这些选项之一，该工具将恢复为该网络源的 SHAPE 选项。

此参数的默认值由存储在输入网络分析图层中的位置属性确定。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。 为此参数设置非默认值将更新网络分析图层的位置设置，覆盖选定子图层。

使用现有网络位置字段添加位置时不使用此参数。

当网络分析图层的网络数据源为 ArcGIS Online 时，不使用此参数。

旧版本：

当网络分析图层的网络数据源为早于 11.0 版本的 ArcGIS Enterprise 门户时，不使用此参数。

Value Table
match_type
(可选)

旧版本：
此参数已弃用和维护，只是为了向后兼容。 输入将始终与用于定位的所有源中最近的网络源匹配，对应于参数值 MATCH_TO_CLOSEST 或 True。

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 或 True 的参数值。

Boolean
search_query
[[Source, Expression],...]
(可选)

将搜索限制在源要素类的要素子集内的查询。 这在不想查找可能不适合网络位置的要素时很有用。 例如，如果您不想定位在高速公路坡道上，则可定义一个查询将其排除。 可以为网络数据集的每个边或交汇点源要素类指定一个单独的 SQL 表达式。

该参数值被指定为具有嵌套列表的列表，其中每个网络源具有一个条目。 每个内部列表由两个值组成，分别表示网络源的名称和用作该源的查询的 SQL 表达式。 空字符串 "" 表示不查询特定源。

例如，值 [["Streets", "ROAD_CLASS <> 3"], ["Streets_ND_Junctions", ""]] 指定了 Streets 源要素类的 SQL 表达式，而没有指定 Streets_ND_Junctions 源要素类的表达式。 如果列表中不包含网络源，则将其解释为无查询。 值 [["Streets", "ROAD_CLASS <> 3"]] 等同于 [["Streets", "ROAD_CLASS <> 3"], ["Streets_ND_Junctions", ""]]。

有关 SQL 语法的详细信息，请参阅在 ArcGIS 中使用的查询表达式的 SQL 参考。

此参数的默认值由存储在输入网络分析图层中的位置属性确定。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。 为此参数设置非默认值将更新网络分析图层的位置设置，覆盖选定子图层。

使用现有网络位置字段添加位置时不使用此参数。

当网络分析图层的网络数据源为 ArcGIS Online 时，不使用此参数。

旧版本：

当网络分析图层的网络数据源为早于 11.0 版本的 ArcGIS Enterprise 门户时，不使用此参数。

Value Table
allow_auto_relocate
(可选)

指定是否可以在求解时自动重定位具有现有网络位置字段的输入，以确保分析的位置字段有效并且可路由。

  • ALLOW—位于限制网络元素上的点和受障碍影响的点将在求解时重定位至最近的可路由位置。 这是默认设置。
  • NO_ALLOW—求解时网络位置字段将按原样使用（即使点无法访问），并且这可能会导致求解失败。

此参数的默认值由存储在输入网络分析图层中的位置属性确定。 如果网络分析图层具有所选子图层的位置设置替代，则将使用这些设置。 否则，将使用网络分析图层的默认位置设置。 为此参数设置非默认值将更新网络分析图层的位置设置，覆盖选定子图层。

即使不允许在求解时自动重新定位，也将在求解时定位没有位置字段或位置字段不完整的输入。

当网络分析图层的网络数据源为 ArcGIS Online 时，不使用此参数。

当网络分析图层的网络数据源是不支持使用网络位置字段的 ArcGIS Enterprise 门户时，不使用此参数。

旧版本：

当网络分析图层的网络数据源为早于 11.0 版本的 ArcGIS Enterprise 门户时，不使用此参数。

Boolean

派生输出

名称说明数据类型
output_layer

已更新的网络分析图层。

Network Analyst Layer

代码示例

AddLocations 示例 1（Python 窗口）

在 Python 窗口中运行该工具以将停靠点添加到名为 Route 的路径分析图层。

import arcpy
hospitals = "C:/Data/SanFrancisco.gdb/Analysis/Hospitals"
arcpy.na.AddLocations("Route", "Stops", hospitals)
AddLocations 示例 2（工作流）

以下独立 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, 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: 是

相关主题

  • 分析工具集概述
  • 查找地理处理工具

有关此主题的反馈?

在本主题中
  1. 摘要
  2. 使用情况
  3. 参数
  4. 环境
  5. 许可信息