com.supermap.analyst.networkanalyst

类 FacilityAnalyst

java.lang.Object

com.supermap.analyst.networkanalyst.FacilityAnalyst

public class FacilityAnalyst
extends java.lang.Object

设施网络分析类。

设施网络分析类。它是网络分析功能类之一，主要用于进行各类连通性分析和追踪分析。

设施网络分析属于网络分析功能的一种，所以在进行设施网络分析之前，您需要具备的前提知识是：

1. 了解网络分析中的基本知识：
   • 什么是网络模型，如何创建网络模型；
   • 网络模型中的术语：结点、弧段、障碍点、障碍边、环路等；
   • 了解网络数据集属性表与普通的线数据集属性表的区别，主要是了解网络数据集属性表中的字段信息。
2. 学会建立用于设施网络分析的数据集：

   设施网络是具有方向的网络。即介质（水流、电流等）会根据网络本身的规则在网络中流动。

   设施网络分析的前提是已经建立了用于设施网络分析的数据集，建立用于设施网络分析的数据集的基础是建立网络数据集，详细信息请参见SuperMap iDesktop帮助文档的设施网络分析相关介绍。

3. 了解设施网络分析环境参数的设置：

   在利用设施网络分析类进行分析时，以及上面提到的建立用于设施网络分析的数据集，都要进行设施网络分析环境参数的设置，即使用到 FacilityAnalystSetting 类所做的设置。详细信息请参见 FacilityAnalystSetting 类。

4. 了解追踪分析的相关知识，如上游、下游、源、汇、流向等。

当具备了以上知识，您就可以使用 FacilityAnalyst 类提供的各种方法来实现各种设施网络分析功能。目前，FacilityAnalyst 类提供的设施网络分析功能包括：

1. 根据给定的结点 ID 数组查找与结点连接的环路；
2. 根据给定的弧段 ID 数组查找与弧段连接的环路；
3. 根据给定的结点 ID 数组查找与结点相连通的弧段；
4. 根据给定的弧段 ID 数组查找与弧段相连通的弧段；
5. 根据给定的结点 ID 数组查找与结点不相连通的弧段；
6. 根据给定的弧段 ID 数组查找与弧段不相连通的弧段；
7. 根据给定的结点 ID 数组查找这些结点共同的上游弧段；
8. 根据给定的弧段 ID 数组查找这些弧段共同的上游弧段；
9. 根据给定的结点 ID 数组查找这些结点共同的下游弧段；
10. 根据给定的弧段 ID 数组查找这些弧段共同的下游弧段；
11. 查找某个结点到源之间的所有弧段；
12. 查找某条弧段到源之间的所有弧段；
13. 查找某个结点到汇之间的所有弧段；
14. 查找某条弧段到汇之间的所有弧段；
15. 查找某个结点上游追踪所流经的弧段；
16. 查找某条弧段上游追踪所流经的弧段；
17. 查找某个结点下游追踪所流经的弧段；
18. 查找某条弧段下游追踪所流经的弧段；
19. 设施网络路径分析，包括查找起始结点和终止结点间的最小耗费路径、查找起始弧段和终止弧段间的最小耗费路径、根据给定的结点沿上游或者下游查询最小耗费路径、根据给定的弧段沿上游或者下游查询最小耗费路径。

还可以阅读《设施网络分析》技术文档以便了解更多有关设施网络分析的介绍。

示例:

请参见 findSourceFromNode、traceUpFromNode、findCommonAncestorsFromNodes、findPathFromNodes 以及 findPathDownFromNode 等方法的示例。

构造器概要

构造器

构造器和说明
FacilityAnalyst() 构造一个新的 FacilityAnalyst 对象。

方法概要

限定符和类型	方法和说明
int[]	checkLoops() 检查网络环路，返回构成环路的弧段 ID 数组。
void	dispose() 释放该对象所占用的资源。
int[]	findCommonAncestorsFromEdges(int[] edgeIDs, boolean isUncertainDirectionValid) 根据给定的弧段 ID 数组，查找这些弧段的共同上游弧段，返回弧段 ID 数组。
int[]	findCommonAncestorsFromNodes(int[] nodeIDs, boolean isUncertainDirectionValid) 根据给定的结点 ID 数组，查找这些结点的共同上游弧段，返回弧段 ID 数组。
int[]	findCommonCatchmentsFromEdges(int[] edgeIDs, boolean isUncertainDirectionValid) 根据给定的弧段 ID 数组，查找这些弧段的共同下游弧段，返回弧段 ID 数组。
int[]	findCommonCatchmentsFromNodes(int[] nodeIDs, boolean isUncertainDirectionValid) 根据指定的结点 ID 数组，查找这些结点的共同下游弧段，返回弧段 ID 数组。
int[]	findConnectedEdgesFromEdges(int[] edgeIDs) 根据给定的弧段 ID 数组，查找与这些弧段相连通的弧段，返回弧段 ID 数组。
int[]	findConnectedEdgesFromNodes(int[] nodeIDs) 根据给定的结点 ID 数组，查找与这些结点相连通弧段，返回弧段 ID 数组。
int[]	findLoopsFromEdges(int[] edgeIDs) 根据给定的弧段 ID 数组查找与这些弧段相连接的环路，返回构成环路的弧段 ID 数组。
int[]	findLoopsFromNodes(int[] nodeIDs) 根据给定的结点 ID 数组查找与这些结点相连接的环路，返回构成环路的弧段 ID 数组。
FacilityAnalystResult	findPathDownFromEdge(int edgeID, java.lang.String weightName, boolean isUncertainDirectionValid) 设施网络下游路径分析，根据给定的参与分析的弧段 ID，查询该弧段下游耗费最小的路径，返回该路径包含的弧段、结点及耗费。
FacilityAnalystResult	findPathDownFromNode(int nodeID, java.lang.String weightName, boolean isUncertainDirectionValid) 设施网络下游路径分析，根据给定的参与分析的结点 ID，查询该结点下游耗费最小的路径，返回该路径包含的弧段、结点及耗费。
FacilityAnalystResult	findPathFromEdges(int startEdgeID, int endEdgeID, java.lang.String weightName, boolean isUncertainDirectionValid) 设施网络路径分析，即根据给定的起始和终止弧段 ID，查找其间耗费最小的路径，返回该路径包含的弧段、结点及耗费。
FacilityAnalystResult	findPathFromNodes(int startNodeID, int endNodeID, java.lang.String weightName, boolean isUncertainDirectionValid) 设施网络路径分析，即根据给定的起始和终止结点 ID，查找其间耗费最小的路径，返回该路径包含的弧段、结点及耗费。
FacilityAnalystResult	findPathUpFromEdge(int edgeID, java.lang.String weightName, boolean isUncertainDirectionValid) 设施网络上游路径分析，根据给定的弧段 ID，查询该弧段上游耗费最小的路径，返回该路径包含的弧段、结点及耗费。
FacilityAnalystResult	findPathUpFromNode(int nodeID, java.lang.String weightName, boolean isUncertainDirectionValid) 设施网络上游路径分析，根据给定的结点 ID，查询该结点上游耗费最小的路径，返回该路径包含的弧段、结点及耗费。
FacilityAnalystResult	findSinkFromEdge(int edgeID, java.lang.String weightName, boolean isUncertainDirectionValid) 根据给定的弧段 ID 查找汇，即从给定弧段出发，根据流向查找流出该弧段的下游汇点，并返回给定弧段到达该汇的最小耗费路径所包含的弧段、结点及耗费。
FacilityAnalystResult	findSinkFromNode(int nodeID, java.lang.String weightName, boolean isUncertainDirectionValid) 根据给定的结点 ID 查找汇，即从给定结点出发，根据流向查找流出该结点的下游汇点，并返回给定结点到达该汇的最小耗费路径所包含的弧段、结点及耗费。
FacilityAnalystResult	findSourceFromEdge(int edgeID, java.lang.String weightName, boolean isUncertainDirectionValid) 根据给定的弧段 ID 查找源，即从给定弧段出发，根据流向查找流向该弧段的网络源头，并返回该源到达给定弧段的最小耗费路径所包含的弧段、结点及耗费。
FacilityAnalystResult	findSourceFromNode(int nodeID, java.lang.String weightName, boolean isUncertainDirectionValid) 根据给定的结点 ID 查找源，即从给定结点出发，根据流向查找流向该结点的网络源头，并返回该源到达给定结点的最小耗费路径所包含的弧段、结点及耗费。
int[]	findUnconnectedEdgesFromEdges(int[] edgeIDs) 根据给定的弧段 ID 数组，查找与这些弧段不相连通的弧段，返回弧段 ID 数组。
int[]	findUnconnectedEdgesFromNodes(int[] nodeIDs) 根据给定的结点 ID 数组，查找与这些结点不相连通的弧段，返回弧段 ID 数组。
FacilityAnalystSetting	getAnalystSetting() 返回设施网络分析的环境。
boolean	load() 根据设施网络分析环境设置加载设施网络模型。
void	setAnalystSetting(FacilityAnalystSetting facilityAnalystSetting) 设置设施网络分析的环境。
FacilityAnalystResult	traceDownFromEdge(int edgeID, java.lang.String weightName, boolean isUncertainDirectionValid) 根据给定的弧段 ID 进行下游追踪，即查找给定弧段的下游，返回下游包含的弧段、结点及总耗费。
FacilityAnalystResult	traceDownFromNode(int nodeID, java.lang.String weightName, boolean isUncertainDirectionValid) 根据给定的结点 ID 进行下游追踪，即查找给定结点的下游，返回下游包含的弧段、结点及总耗费。
FacilityAnalystResult	traceUpFromEdge(int edgeID, java.lang.String weightName, boolean isUncertainDirectionValid) 根据给定的弧段 ID 进行上游追踪，即查找给定弧段的上游，返回上游包含的弧段、结点及总耗费。
FacilityAnalystResult	traceUpFromNode(int nodeID, java.lang.String weightName, boolean isUncertainDirectionValid) 根据给定的结点 ID 进行上游追踪，即查找给定结点的上游，返回上游包含的弧段、结点及总耗费。

从类继承的方法 java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造器详细资料

FacilityAnalyst

public FacilityAnalyst()

构造一个新的 FacilityAnalyst 对象。

方法详细资料

getAnalystSetting

public FacilityAnalystSetting getAnalystSetting()

返回设施网络分析的环境。

设施网络分析环境参数的设置，直接影响到设施网络分析的结果。设施网络分析所需要的参数包括：用于进行设施网络分析的数据集（即建立了流向的网络数据集或者同时建立了流向和等级的网络数据集，也就是说该方法对应的 FacilityAnalystSetting 类对象的 setNetworkDataset() 方法所指定的网络数据集必须有流向或者流向和等级信息）、结点 ID 字段、弧段 ID 字段、弧段起始结点 ID 字段、弧段终止结点 ID 字段、权值信息、点到弧段的距离容限、障碍结点、障碍弧段、流向等。有关设施网络分析环境参数的设置，请参见 FacilityAnalystSetting 类。

返回:

设施网络分析的环境。

另请参阅:

FacilityAnalystSetting

默认值:

默认值为一个新构造的 FacilityAnalystSetting 对象。

setAnalystSetting

public void setAnalystSetting(FacilityAnalystSetting facilityAnalystSetting)

设置设施网络分析的环境。

设施网络分析环境参数的设置，直接影响到设施网络分析的结果。设施网络分析所需要的参数包括：用于进行设施网络分析的数据集（即建立了流向的网络数据集或者同时建立了流向和等级的网络数据集，也就是说该方法对应的 FacilityAnalystSetting 类对象的 setNetworkDataset() 方法所指定的网络数据集必须有流向或者流向和等级信息）、结点 ID 字段、弧段 ID 字段、弧段起始结点 ID 字段、弧段终止结点 ID 字段、权值信息、点到弧段的距离容限、障碍结点、障碍弧段、流向等。有关设施网络分析环境参数的设置，请参见 FacilityAnalystSetting 类。

参数:

facilityAnalystSetting - 设施网络分析环境参数。

另请参阅:

FacilityAnalystSetting

load

public boolean load()

根据设施网络分析环境设置加载设施网络模型。

该方法根据设施网络分析环境设置（FacilityAnalystSetting）对象中的环境参数，加载网络模型。在设置好设施网络分析环境的参数后，只有调用该方法，所做的设施网络分析环境设置才会在设施网络分析的过程中生效。

注意：

1. 出现以下两种情况都必须重新调用 load 方法来加载网络模型，然后再进行分析，并且在重新调用前，必须先调用 dispose 方法释放 FacilityAnalyst 对象所占用的资源，否则可能出错。
   • 对设施网络分析环境设置对象的参数进行了修改，需要重新调用该方法，否则所作修改不会生效从而导致分析结果错误；
   • 对所使用的网络数据集进行了任何修改，包括修改网络数据集中的数据、替换数据集等，都需要重新加载网络模型，否则分析可能出错。
2. 已经调用 load 方法加载了网络模型，再次调用 load 方法之前，必须先调用 dispose 方法释放资源，否则加载可能失败。

返回:

一个布尔值，用于指示加载设施网络模型是否成功。如果成功返回 true，否则返回 false。

findLoopsFromNodes

public int[] findLoopsFromNodes(int[] nodeIDs)

根据给定的结点 ID 数组查找与这些结点相连接的环路，返回构成环路的弧段 ID 数组。

设施网络中，两条或两条以上流向值为 2（即不确定流向）的弧段构成的闭合路径，称为环路。详细内容请参阅 checkLoops 方法的介绍。

参数:

nodeIDs - 指定的结点 ID 数组。

返回:

与给定结点相连接的环路的弧段 ID 数组。

示例:

请参见 findLoopsFromEdges 方法的示例。

findLoopsFromEdges

public int[] findLoopsFromEdges(int[] edgeIDs)

根据给定的弧段 ID 数组查找与这些弧段相连接的环路，返回构成环路的弧段 ID 数组。

设施网络中，两条或两条以上流向值为 2（即不确定流向）的弧段构成的闭合路径，称为环路。详细内容请参阅 checkLoops 方法的介绍。

参数:

edgeIDs - 指定的弧段 ID 数组。

返回:

与给定弧段相连接的环路的弧段 ID 数组。

示例:

以下代码示范了如何查找与给定的弧段或结点相连接的环路。假设下面函数操作的网络数据集为安装目录\SampleData\changchun\下的 changchun.udb 数据源中的名为 RoadNet 的网络数据集，并且已经为该网络数据集建立了流向以及等级。有关建立网络数据集的流向及等级，详细信息请参见SuperMap iDesktop帮助文档的设施网络分析相关介绍。

 public void FindLoopsFrom(DatasetVector networkDataset)
    {
        //设置用于设施网络分析的环境
        FacilityAnalystSetting facilityAnalystSetting = new FacilityAnalystSetting();
        facilityAnalystSetting.setNetworkDataset ( networkDataset);
        facilityAnalystSetting.setDirectionField ("Direction");
        facilityAnalystSetting.setEdgeIDField ("SmID");
        facilityAnalystSetting.setNodeIDField ( "SmNodeID");
        facilityAnalystSetting.setFNodeIDField ( "SmFNode");
        facilityAnalystSetting.setTNodeIDField ("SmTNode");
        facilityAnalystSetting.setTolerance ( 0.0015);
        WeightFieldInfo weightFieldInfo = new WeightFieldInfo();
        weightFieldInfo.setName ( "Length");
        weightFieldInfo.setFTWeightField ( "SmLength");
        weightFieldInfo.setTFWeightField ("SmLength");
        WeightFieldInfos weightFieldInfos = new WeightFieldInfos();
        weightFieldInfos.add(weightFieldInfo);
        facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);
        FacilityAnalyst facilityAnalyst = new FacilityAnalyst();
        facilityAnalyst.setAnalystSetting ( facilityAnalystSetting);
        facilityAnalyst.load();

        //获取参与分析的弧段或结点
        int[] edgeIDs = new int[] { 3855, 9073 };
        int[] nodeIDs = new int[] { 2996, 2682 };

        //查找与给定弧段相连接的环路
        int[] loopsFromEdges = facilityAnalyst.findLoopsFromEdges(edgeIDs);

        //查找与给定结点相连接的环路
        int[] loopsFromNodes = facilityAnalyst.findLoopsFromNodes(nodeIDs);
    }

findConnectedEdgesFromNodes

public int[] findConnectedEdgesFromNodes(int[] nodeIDs)

根据给定的结点 ID 数组，查找与这些结点相连通弧段，返回弧段 ID 数组。

参数:

nodeIDs - 给定的结点 ID 数组。

返回:

弧段 ID 数组。

另请参阅:

findConnectedEdgesFromEdges() 方法的示例。

findConnectedEdgesFromEdges

public int[] findConnectedEdgesFromEdges(int[] edgeIDs)

根据给定的弧段 ID 数组，查找与这些弧段相连通的弧段，返回弧段 ID 数组。

参数:

edgeIDs - 给定的弧段 ID 数组。

返回:

弧段 ID 数组。

示例:

以下代码示范了如何查找与给定结点或弧段相连通或不相连通的弧段。假设下面函数操作的网络数据集为安装目录\SampleData\changchun\下的 changchun.udb 数据源中的名为 RoadNet 的网络数据集，并且已经为该网络数据集建立了流向以及等级。 有关建立网络数据集的流向及等级，详细信息请参见SuperMap iDesktop帮助文档的设施网络分析相关介绍。

 public void TestFindConnectedandUnconnectedEdges(DatasetVector networkDataset)
    {
        //设置用于设施网络分析的环境
        FacilityAnalystSetting facilityAnalystSetting = new FacilityAnalystSetting();
        facilityAnalystSetting.setNetworkDataset ( networkDataset);
        facilityAnalystSetting.setDirectionField ("Direction");
        facilityAnalystSetting.setEdgeIDField ("SmID");
        facilityAnalystSetting.setNodeIDField ( "SmNodeID");
        facilityAnalystSetting.setFNodeIDField ( "SmFNode");
        facilityAnalystSetting.setTNodeIDField ("SmTNode");
        facilityAnalystSetting.setTolerance ( 0.0015);
        WeightFieldInfo weightFieldInfo = new WeightFieldInfo();
        weightFieldInfo.setName ( "Length");
        weightFieldInfo.setFTWeightField ( "SmLength");
        weightFieldInfo.setTFWeightField ("SmLength");
        WeightFieldInfos weightFieldInfos = new WeightFieldInfos();
        weightFieldInfos.add(weightFieldInfo);
        facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);
        FacilityAnalyst facilityAnalyst = new FacilityAnalyst();
        facilityAnalyst.setAnalystSetting ( facilityAnalystSetting);
        facilityAnalyst.load();

        //获取参与分析的弧段或结点
        int[] edgeIDs = new int[] { 3855, 9073 };
        int[] nodeIDs = new int[] { 2996, 2682 };

        //查找与给定弧段相连通和不相连通的弧段
        int[] connectEdges = facilityAnalyst.findConnectedEdgesFromEdges(edgeIDs);
        int[] unconnectEdges = facilityAnalyst.findUnconnectedEdgesFromEdges(edgeIDs);

        //查找与给定的结点相连通和不相连通的弧段
        int[] connectNodes = facilityAnalyst.findConnectedEdgesFromNodes(nodeIDs);
        int[] unconnectNodes = facilityAnalyst.findUnconnectedEdgesFromNodes(nodeIDs);
    }

findUnconnectedEdgesFromNodes

public int[] findUnconnectedEdgesFromNodes(int[] nodeIDs)

根据给定的结点 ID 数组，查找与这些结点不相连通的弧段，返回弧段 ID 数组。

参数:

nodeIDs - 给定的结点 ID 数组。

返回:

弧段 ID 数组。

另请参阅:

findConnectedEdgesFromEdges()方法的示例。

findUnconnectedEdgesFromEdges

public int[] findUnconnectedEdgesFromEdges(int[] edgeIDs)

根据给定的弧段 ID 数组，查找与这些弧段不相连通的弧段，返回弧段 ID 数组。

参数:

edgeIDs - 给定的弧段 ID 数组。

返回:

弧段 ID 数组。

另请参阅:

findConnectedEdgesFromEdges()方法的示例。

findCommonAncestorsFromNodes

public int[] findCommonAncestorsFromNodes(int[] nodeIDs,
                                          boolean isUncertainDirectionValid)

根据给定的结点 ID 数组，查找这些结点的共同上游弧段，返回弧段 ID 数组。

有关“上游”的介绍，请参阅 traceUpFromNode 方法。

共同上游是指多个结点（或弧段）的公共上游网络。该方法用于查找多个结点的共同上游弧段，即取这些结点的各自上游弧段的交集部分，结果返回这些弧段的弧段 ID。

如下图所示，流向如图中的箭头所示的方向，前两幅图分别是对结点 1 和结点 2 进行上游追踪的结果，查找出各自的上游弧段（绿色），第三幅图则是对结点 1 和结点 2 查找共同上游弧段（橙色），容易看出，结点 1 和结点 2 的共同上游弧段，就是它们各自的上游弧段的交集。

参数:

nodeIDs - 给定的结点 ID 数组。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

弧段 ID 数组。

示例:

以下代码示范了如何查找给定弧段或结点的共同上游或共同下游。假设下面函数操作的网络数据集为安装目录\SampleData\changchun\下的 changchun.udb 数据源中的名为 RoadNet 的网络数据集，并且已经为该网络数据集建立了流向以及等级。有关建立网络数据集的流向及等级，详细信息请参见SuperMap iDesktop帮助文档的设施网络分析相关介绍。

 public void FindCommonAncestorsandCatchementsEdges(DatasetVector networkDataset)
    {
        //设置用于设施网络分析的环境
        FacilityAnalystSetting facilityAnalystSetting = new FacilityAnalystSetting();
        facilityAnalystSetting.setNetworkDataset ( networkDataset);
        facilityAnalystSetting.setDirectionField ("Direction");
        facilityAnalystSetting.setEdgeIDField ("SmID");
        facilityAnalystSetting.setNodeIDField ( "SmNodeID");
        facilityAnalystSetting.setFNodeIDField ( "SmFNode");
        facilityAnalystSetting.setTNodeIDField ("SmTNode");
        facilityAnalystSetting.setTolerance ( 0.0015);
        WeightFieldInfo weightFieldInfo = new WeightFieldInfo();
        weightFieldInfo.setName ( "Length");
        weightFieldInfo.setFTWeightField ( "SmLength");
        weightFieldInfo.setTFWeightField ("SmLength");
        WeightFieldInfos weightFieldInfos = new WeightFieldInfos();
        weightFieldInfos.add(weightFieldInfo);
        facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);
        FacilityAnalyst facilityAnalyst = new FacilityAnalyst();
        facilityAnalyst.setAnalystSetting ( facilityAnalystSetting);
        facilityAnalyst.load();

        //获取参与分析的弧段或结点
        int[] edgeIDs = new int[] { 3855,9073};
        int[] nodeIDs = new int[] { 2996,2682};

        //查找给定弧段的共同上游弧段和共同上游弧段
        int[] commonAncestorsofEdges = facilityAnalyst.findCommonAncestorsFromEdges(edgeIDs,false);
        int[] commonCatchmentsofEdges = facilityAnalyst.findCommonCatchmentsFromEdges(edgeIDs, false);

        //查找给定结点的共同上游弧段和共同上游弧段
        int[] commonAncestorsofNodes = facilityAnalyst.findCommonAncestorsFromNodes(nodeIDs, false);
        int[] commonCatchementsofNodes = facilityAnalyst.findCommonCatchementsFromNodes(nodeIDs, false);
    }

findCommonAncestorsFromEdges

public int[] findCommonAncestorsFromEdges(int[] edgeIDs,
                                          boolean isUncertainDirectionValid)

根据给定的弧段 ID 数组，查找这些弧段的共同上游弧段，返回弧段 ID 数组。

有关“上游”的介绍，请参阅 traceUpFromNode 方法。

共同上游是指多个结点（或弧段）的公共上游网络。该方法用于查找多条弧段的共同上游弧段，即取这些弧段的各自上游弧段的交集部分，结果返回这些弧段的弧段 ID。

请参阅 findCommonAncestorsFromNodes 方法获得更多关于“查找共同上游弧段”的介绍。

参数:

edgeIDs - 指定的弧段 ID 数组。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

给定弧段的共同上游的弧段 ID 数组。

示例:

请参见 findCommonAncestorsFromNodes 方法的示例。

findCommonCatchmentsFromNodes

public int[] findCommonCatchmentsFromNodes(int[] nodeIDs,
                                           boolean isUncertainDirectionValid)

根据指定的结点 ID 数组，查找这些结点的共同下游弧段，返回弧段 ID 数组。

有关“下游”的介绍，请参阅 traceUpFromNode 方法。

共同下游是指多个结点（或弧段）的公共下游网络。该方法用于查找多个结点的共同下游弧段，即取这些结点的各自下游弧段的交集部分，结果返回这些弧段的弧段 ID。

如下图所示，流向如图中的箭头所示的方向，前两幅图分别是对结点 1 和结点 2 进行下游追踪的结果，查找出各自的下游弧段（绿色），第三幅图则是对结点 1 和结点 2 查找共同下游弧段（橙色），容易看出，结点 1 和结点 2 的共同下游弧段，就是它们各自的下游弧段的交集。

参数:

nodeIDs - 指定的结点 ID 数组。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

给定结点的共同下游的弧段 ID 数组。

示例:

请参见 findCommonAncestorsFromNodes 方法的示例。

findCommonCatchmentsFromEdges

public int[] findCommonCatchmentsFromEdges(int[] edgeIDs,
                                           boolean isUncertainDirectionValid)

根据给定的弧段 ID 数组，查找这些弧段的共同下游弧段，返回弧段 ID 数组。

有关“下游”的介绍，请参阅 traceUpFromNode 方法。

共同下游是指多个结点（或弧段）的公共下游网络。该方法用于查找多条弧段的共同下游弧段，即取这些弧段的各自下游弧段的交集部分，结果返回这些弧段的弧段 ID。

请参阅 findCommonCatchmentsFromNodes 方法获得更多关于“查找共同下游弧段”的介绍。

参数:

edgeIDs - 指定的弧段 ID 数组。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

给定弧段的共同下游的弧段 ID 数组。

示例:

请参见 findCommonAncestorsFromNodes 方法的示例。

findSourceFromNode

public FacilityAnalystResult findSourceFromNode(int nodeID,
                                                java.lang.String weightName,
                                                boolean isUncertainDirectionValid)

根据给定的结点 ID 查找源，即从给定结点出发，根据流向查找流向该结点的网络源头，并返回该源到达给定结点的最小耗费路径所包含的弧段、结点及耗费。

该方法从给定结点出发，按照流向，查找流向该结点的网络源头结点（即源点），分析的结果为查找到的源到达给定结点的最小耗费路径所包含的弧段、结点及耗费。如果网络中有多个源，将查找最远的也就是到达给定结点的最小耗费最大的那个源。为了便于理解，可将该功能的实现过程分为三步：

1. 从给定结点出发，根据流向，找到该结点上游所有的源点；
2. 分析每个源到达给定结点的最小耗费路径并计算耗费；
3. 选择上一步中计算出的耗费中的最大值所对应的路径作为结果，给出该路径上的弧段 ID 数组、结点 ID 数组以及该路径的耗费。

注意：分析结果中的结点 ID 数组不包括分析结点本身。

下图是一个简单的设施网络，在网络弧段上使用箭头标示了网络的流向，在弧段旁标注了权值。对于分析结点 M 进行查找源分析。可以知道，从 结点 M 出发，根据流向向上回溯，共有 7 个源，从源到结点 M 的最小耗费路径分别为：C-H-M、A-E-H-M、B-D-E-H-M、F-D-E-H-M、J-N-M、I-N-M 和 P-N-M，根据网络阻力，也就是弧段权值，可以计算得出 B-D-E-H-M 这条路径的耗费最大，为 18.4，因此，结点 B 就是查找到的源。

参数:

nodeID - 指定的结点 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

以下代码示范了如何根据给定的结点或弧段查找源和汇。本例使用示范数据中的“FacilityNet.udb”数据源进行分析，该数据源中存在一个名为“WaterNet”的网络数据集，以弧段 ID 为 336 的弧段和结点 ID 为 311 的结点为例，示范如何查找源和汇。

        /**
         * 根据给定的弧段 ID 或结点 ID 来查找源或汇。
         * @param datasource 指定的网络数据集所在的数据源。
         */
        private void findSourceOrSinkExample(Datasource datasource) {
                //获取用于分析的网络数据集
                DatasetVector network = (DatasetVector)datasource.getDatasets().get("WaterNet");

                //构造一个设施网络分析环境设置对象，并设置相关参数
                FacilityAnalystSetting facilityAnalystSetting = new FacilityAnalystSetting();
                facilityAnalystSetting.setNetworkDataset(network);
                facilityAnalystSetting.setDirectionField("direction");
                facilityAnalystSetting.setEdgeIDField("SMEDGEID");
                facilityAnalystSetting.setNodeIDField("SMNODEID");
                facilityAnalystSetting.setFNodeIDField("SMFNODE");
                facilityAnalystSetting.setTNodeIDField("SMTNODE");
                facilityAnalystSetting.setTolerance(0.001);

                WeightFieldInfo weightFieldInfo = new WeightFieldInfo();
                weightFieldInfo.setName("Length");
                weightFieldInfo.setFTWeightField("SMLENGTH");
                weightFieldInfo.setTFWeightField("SMLENGTH");
                WeightFieldInfos weightFieldInfos = new WeightFieldInfos();
                weightFieldInfos.add(weightFieldInfo);
                facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);

                //障碍结点和障碍弧段的设置对查找源/汇是有效的
                facilityAnalystSetting.setBarrierEdges(new int[] { 8, 199 });
                facilityAnalystSetting.setBarrierNodes(new int[] { 372 });

                //构造一个设施网络分析对象，并设置设施网络分析环境
                FacilityAnalyst facilityAnalyst = new FacilityAnalyst();
                facilityAnalyst.setAnalystSetting(facilityAnalystSetting);

                //加载网络模型
                Boolean isLoad = facilityAnalyst.load();

                if (isLoad)     {
                        //获取参与分析的弧段或结点 ID
                        int edgeID = 336;
                        int nodeID = 311;

                        //根据给定弧段查找源
                        FacilityAnalystResult resultSourceFromEdge = facilityAnalyst.findSourceFromEdge(edgeID, "Length", true);
                        if (resultSourceFromEdge != null) {
                                System.out.println("从弧段" + edgeID + "到源的耗费为" + resultSourceFromEdge.Cost);
                                System.out.println("从弧段" + edgeID + "到源的弧段 ID 包括：");
                                for (int i = 0; i < resultSourceFromEdge.Edges.Length; i++) {
                                        System.out.println(resultSourceFromEdge.Edges[i]);
                                }
                                System.out.println("从弧段" + edgeID + "到源的结点 ID 包括：");
                                for (int i = 0; i < resultSourceFromEdge.Nodes.Length; i++)     {
                                        System.out.println(resultSourceFromEdge.Nodes[i]);
                                }
                        }
                        //根据给定结点查找源（略，参考“根据给定弧段查找源”）

                        //根据给定结点查找汇
                        FacilityAnalystResult resultSinkFromNode = facilityAnalyst.findSinkFromNode(nodeID, "Length", true);
                        if (resultSinkFromNode != null) {
                                System.out.println("从结点" + nodeID + "到汇的耗费为" + resultSinkFromNode.Cost);
                                System.out.println("从结点" + nodeID + "到汇的弧段 ID 包括：");
                                for (int i = 0; i < resultSinkFromNode.Edges.Length; i++) {
                                        System.out.println(resultSinkFromNode.Edges[i]);
                                }
                                System.out.println("从结点" + nodeID + "到汇的结点 ID 包括：");
                                for (int i = 0; i < resultSinkFromNode.Nodes.Length; i++) {
                                        System.out.println(resultSinkFromNode.Nodes[i]);
                                }
                        }
                        //根据给定弧段查找汇（略，参考“根据给定结点查找汇”）
                }

                //分析完毕，释放设施网络分析对象所占的资源
                facilityAnalyst.dispose();
        }
 

findSourceFromEdge

public FacilityAnalystResult findSourceFromEdge(int edgeID,
                                                java.lang.String weightName,
                                                boolean isUncertainDirectionValid)

根据给定的弧段 ID 查找源，即从给定弧段出发，根据流向查找流向该弧段的网络源头，并返回该源到达给定弧段的最小耗费路径所包含的弧段、结点及耗费。

该方法从给定弧段出发，按照流向，查找流向该弧段的网络源头结点（即源点），分析的结果为查找到的源到达给定弧段的最小耗费路径所包含的弧段、结点及耗费。如果网络中有多个源，将查找最远的也就是到达给定弧段的最小耗费最大的那个源。为了便于理解，可将该功能的实现过程分为三步：

1. 从给定弧段出发，根据流向，找到该弧段上游所有的源点；
2. 分析每个源到达给定弧段的最小耗费路径并计算耗费；
3. 选择上一步中计算出的耗费中的最大值所对应的路径作为结果，给出该路径上的弧段 ID 数组、结点 ID 数组以及该路径的耗费。

注意：分析结果中的弧段 ID 数组不包括分析弧段本身。

更多介绍还可参阅 findSourceFromNode 方法，该方法根据给定的结点 ID 查找源。

参数:

edgeID - 指定的弧段 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 findSourceFromNode 方法的示例。

findSinkFromNode

public FacilityAnalystResult findSinkFromNode(int nodeID,
                                              java.lang.String weightName,
                                              boolean isUncertainDirectionValid)

根据给定的结点 ID 查找汇，即从给定结点出发，根据流向查找流出该结点的下游汇点，并返回给定结点到达该汇的最小耗费路径所包含的弧段、结点及耗费。

该方法从给定结点出发，按照流向，查找流出该结点的下游汇点，分析的结果为该结点到达查找到的汇的最小耗费路径所包含的弧段、结点及耗费。如果网络中有多个汇，将查找最远的也就是从给定结点出发最小耗费最大的那个汇。为了便于理解，可将该功能的实现过程分为三步：

1. 从给定结点出发，根据流向，找到该结点下游所有的汇点；
2. 分析给定结点到每个汇的最小耗费路径并计算耗费；
3. 选择上一步中计算出的耗费中的最大值所对应的路径作为结果，给出该路径上的弧段 ID 数组、结点 ID 数组以及该路径的耗费。

注意：分析结果中的结点 ID 数组不包括分析结点本身。

下图是一个简单的设施网络，在网络弧段上使用箭头标示了网络的流向，在弧段旁标注了权值。对于分析结点 D 进行查找汇分析。可以知道，从 结点 D 出发，根据流向向下查找，共有 4 个汇，从结点 D 到达汇的最小耗费路径分别为：E-H-L-G、E-H-L-K、E-H-M-S 和 E-H-M-Q-R，根据网络阻力，也就是弧段权值，可以计算得出 E-H-M-Q-R 这条路径的耗费最大，为 16.6，因此，结点 R 就是查找到的汇。

参数:

nodeID - 指定的参与分析的结点 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 findSourceFromNode 方法的示例。

findSinkFromEdge

public FacilityAnalystResult findSinkFromEdge(int edgeID,
                                              java.lang.String weightName,
                                              boolean isUncertainDirectionValid)

根据给定的弧段 ID 查找汇，即从给定弧段出发，根据流向查找流出该弧段的下游汇点，并返回给定弧段到达该汇的最小耗费路径所包含的弧段、结点及耗费。

该方法从给定弧段出发，按照流向，查找流出该弧段的下游汇点，分析的结果为该弧段到达查找到的汇的最小耗费路径所包含的弧段、结点及耗费。如果网络中有多个汇，将查找最远的也就是从给定弧段出发最小耗费最大的那个汇。为了便于理解，可将该功能的实现过程分为三步：

1. 从给定弧段出发，根据流向，找到该弧段下游所有的汇点；
2. 分析给定弧段到每个汇的最小耗费路径并计算耗费；
3. 选择上一步中计算出的耗费中的最大值所对应的路径作为结果，给出该路径上的弧段 ID 数组、结点 ID 数组以及该路径的耗费。

注意：分析结果中的弧段 ID 数组不包括分析弧段本身。

更多介绍还可参阅 findSinkFromNode 方法，该方法根据给定的结点 ID 查找汇。

参数:

edgeID - 指定的弧段 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 findSourceFromNode 方法的示例。

traceUpFromNode

public FacilityAnalystResult traceUpFromNode(int nodeID,
                                             java.lang.String weightName,
                                             boolean isUncertainDirectionValid)

根据给定的结点 ID 进行上游追踪，即查找给定结点的上游，返回上游包含的弧段、结点及总耗费。

• 上游和下游

• 对于设施网络的某个结点（或弧段）来说，网络中的资源最终流入该结点（或弧段）所经过的弧段和结点称为它的上游；从该结点（或弧段）流出最终流入汇点所经过的弧段和网络称为它的下游。

  下面以结点的上游和下游为例。下图是一个简单的设施网络的示意图，使用箭头标出了网络的流向。根据流向，可以看出，资源流经结点 2、4、3、7、8 以及弧段 10、9、3、4、8 最终流入结点 10，因此这些结点和弧段称为结点 10 的上游，其中的结点称为它的上游结点，弧段称为它的上游弧段。同样的，资源从结点 10 流出，流经结点9、11、12 以及弧段 5、7、11 最终流出网络，因此，这些结点和弧段称为结点 10 的下游，其中的结点称为它的下游结点，弧段称为它的下游弧段。

  

• 上游追踪与下游追踪

• 上游追踪，是从给定结点（或弧段）出发，根据流向，查找其上游的过程。类似的，下游追踪是从给定结点（或弧段）出发，根据流向，查找其下游的过程。FacilityAnalyst 类分别提供了从结点或弧段出发，进行上游或下游追踪的方法，分析的结果为查找到的上游或下游所包含的弧段 ID 数组、结点 ID 数组，以及流经整个上游或者下游的耗费。本方法用于查找给定弧段的上游。

• 应用实例

• 上游追踪的一个常用应用是辅助定位河流水污染物来源。河流不仅是地球水循环的重要路径，也是人类最主要的淡水资源，一旦河流发生污染而没有及时发现污染源并消除，很可能影响人们的正常饮水和健康。由于河流受重力影响从高处向低处流动，因此当河流发生污染时，应考虑其上游可能出现了污染源，如工业废水排放、生活污水排放、农药化肥污染等。河流水污染物来源追踪的大致步骤一般为：

  1. 当水质监测站的监测数据显示水质发生异常，首先确定发生异常的位置，从而在河流网络（网络数据集）上找出该位置所在（或最近）的弧段或结点，作为上游追踪的起点；
  2. 如果知道在起点的上游中距离起点最近的水质监测正常的位置，可以将这些位置或其所在的河段设置为障碍，可以帮助进一步缩小分析的范围。因为可以认为，水质监测正常的位置的上游，不可能存在此次调查的污染源。设置为障碍后，进行上游追踪分析，追踪到该位置后，将不会继续追踪该位置的上游；
  3. 进行上游追踪分析，查找到向发生水质异常位置所在河段汇流的所有河段；
  4. 使用空间查询、分析找出位于这些河段附近的所有可能的污染源，如化工厂、垃圾处理厂等；
  5. 根据发生水质异常的监测数据对污染源进行进一步筛选；
  6. 分析筛选出的污染源的排污负荷，按照其造成污染的可能性进行排序；
  7. 对可能的污染源按照顺序进行实地调查与研究，最终确定污染物来源。

参数:

nodeID - 指定的结点 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

弧段 ID 数组。

示例:

以下代码示范了如何根据给定的结点或弧段进行上下游追踪。本例使用示范数据中的“FacilityNet.udb”数据源进行分析，该数据源中存在一个名为“WaterNet”的网络数据集，以弧段 ID 为 336 的弧段和结点 ID 为 311 的结点为例，示范如何进行上游追踪和下游追踪。

        /**
         * 根据给定的弧段 ID 或结点 ID 进行上游追踪或下游追踪。
         * @param datasource 指定的网络数据集所在的数据源。
         */
        private void traceUpOrDownExample(Datasource datasource) {
                //获取用于分析的网络数据集
                DatasetVector network = (DatasetVector)datasource.getDatasets().get("WaterNet");

                //构造一个设施网络分析环境设置对象，并设置相关参数
                FacilityAnalystSetting facilityAnalystSetting = new FacilityAnalystSetting();
                facilityAnalystSetting.setNetworkDataset(network);
                facilityAnalystSetting.setDirectionField("direction");
                facilityAnalystSetting.setEdgeIDField("SMEDGEID");
                facilityAnalystSetting.setNodeIDField("SMNODEID");
                facilityAnalystSetting.setFNodeIDField("SMFNODE");
                facilityAnalystSetting.setTNodeIDField("SMTNODE");
                facilityAnalystSetting.setTolerance(0.001);

                WeightFieldInfo weightFieldInfo = new WeightFieldInfo();
                weightFieldInfo.setName("Length");
                weightFieldInfo.setFTWeightField("SMLENGTH");
                weightFieldInfo.setTFWeightField("SMLENGTH");
                WeightFieldInfos weightFieldInfos = new WeightFieldInfos();
                weightFieldInfos.add(weightFieldInfo);
                facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);

                //障碍结点和障碍弧段的设置对查找源/汇是有效的
                facilityAnalystSetting.setBarrierEdges(new int[] { 8, 199 });
                facilityAnalystSetting.setBarrierNodes(new int[] { 372 });

                //构造一个设施网络分析对象，并设置设施网络分析环境
                FacilityAnalyst facilityAnalyst = new FacilityAnalyst();
                facilityAnalyst.setAnalystSetting(facilityAnalystSetting);

                //加载网络模型
                Boolean isLoad = facilityAnalyst.load();

                if (isLoad)     {
                        //获取参与分析的弧段或结点 ID
                        int edgeID = 336;
                        int nodeID = 311;

                        //对给定的弧段进行上游追踪
                        FacilityAnalystResult resultTraceUpFromEdge = facilityAnalyst.TraceUpFromEdge(edgeID, "Length", true);
                        System.out.println("从弧段" + edgeID + "进行上游追踪的耗费为" + resultTraceUpFromEdge.Cost);
                        System.out.println("从弧段" + edgeID + "进行上游追踪，弧段 ID 包括：");
                        for (int i = 0; i < resultTraceUpFromEdge.Edges.Length; i++) {
                                System.out.println(resultTraceUpFromEdge.Edges[i]);
                        }
                        System.out.println("从弧段" + edgeID + "进行上游追踪，结点 ID 包括：");
                        for (int i = 0; i < resultTraceUpFromEdge.Nodes.Length; i++) {
                                System.out.println(resultTraceUpFromEdge.Nodes[i]);
                        }
                        //对给定的结点进行上游追踪（略，参考"对给定的弧段进行上游追踪"）

                        //对给定的结点进行下游追踪
                        FacilityAnalystResult resultTraceDownFromNode = facilityAnalyst.traceDownFromNode(nodeID, "Length", true);
                        System.out.println("从结点" + nodeID + "进行下游追踪的耗费为" + resultTraceDownFromNode.Cost);
                        System.out.println("从结点" + nodeID + "进行下游追踪，弧段 ID 包括：");
                        for (int i = 0; i < resultTraceDownFromNode.Edges.Length; i++) {
                                System.out.println(resultTraceDownFromNode.Edges[i]);
                        }
                        System.out.println("从结点" + nodeID + "进行下游追踪，结点 ID 包括：");
                        for (int i = 0; i < resultTraceDownFromNode.Nodes.Length; i++) {
                                System.out.println(resultTraceDownFromNode.Nodes[i]);
                        }
                        //对给定的弧段进行下游追踪（略，参考"对给定的结点进行下游追踪"）
                }

                //分析完毕，释放设施网络分析对象所占的资源
                facilityAnalyst.dispose();
        }
 

traceUpFromEdge

public FacilityAnalystResult traceUpFromEdge(int edgeID,
                                             java.lang.String weightName,
                                             boolean isUncertainDirectionValid)

根据给定的弧段 ID 进行上游追踪，即查找给定弧段的上游，返回上游包含的弧段、结点及总耗费。

上游追踪，是从给定结点（或弧段）出发，根据流向，查找其上游的过程。该方法用于查找给定弧段的下游，分析结果为其上游所包含的弧段、结点，及流经整个下游的耗费。

有关“上下游”和“上下游追踪”的详细介绍，请参阅 traceUpFromNode 方法。

参数:

edgeID - 指定的弧段 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 traceUpFromNode 方法的示例。

traceDownFromNode

public FacilityAnalystResult traceDownFromNode(int nodeID,
                                               java.lang.String weightName,
                                               boolean isUncertainDirectionValid)

根据给定的结点 ID 进行下游追踪，即查找给定结点的下游，返回下游包含的弧段、结点及总耗费。

下游追踪，是从给定结点（或弧段）出发，根据流向，查找其下游的过程。该方法用于查找给定弧段的下游，分析结果为其下游所包含的弧段、结点，及流经整个下游的耗费。

有关“上下游”和“上下游追踪”的详细介绍，请参阅 traceUpFromNode 方法。

下游追踪常用于影响范围的分析。例如：

• 自来水供水管道爆管后，通过下游追踪分析事故位置的所有下游管道，然后通过空间查询，确定受影响的供水区域，从而及时发放通知，并采取应急措施，如由消防车或自来水公司安排车辆为停水小区送水。
• 当发现河流的某个位置发生污染时，可以通过下游追踪，分析出可能受到影响的所有下游河段，如下图所示。在分析前，还可以根据污染物的种类、排放量等结合恰当的水质管理模型，分析出在污染清除前不会遭到污染的下游河段或位置，设置为障碍（在 FacilityAnalystSetting 中设置），下游追踪时，到达障碍即追踪停止，这样可以缩小分析的范围。确定了可能受影响的河段后，通过空间查询和分析标记出位于结果河段附近的所有用水单位和居民区，及时下发通知，并采取紧急措施，防止污染的危害进一步扩大。

参数:

nodeID - 指定的结点 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 traceUpFromNode 方法的示例。

traceDownFromEdge

public FacilityAnalystResult traceDownFromEdge(int edgeID,
                                               java.lang.String weightName,
                                               boolean isUncertainDirectionValid)

根据给定的弧段 ID 进行下游追踪，即查找给定弧段的下游，返回下游包含的弧段、结点及总耗费。

下游追踪，是从给定结点（或弧段）出发，根据流向，查找其下游的过程。该方法用于查找给定弧段的下游，分析结果为其下游所包含的弧段、结点，及流经整个下游的耗费。

有关“上下游”和“上下游追踪”的详细介绍，请参阅 traceDownFromNode 和 traceUpFromNode 方法。

参数:

edgeID - 指定的弧段 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 traceUpFromNode 方法的示例。

checkLoops

public int[] checkLoops()

检查网络环路，返回构成环路的弧段 ID 数组。

设施网络中，环路是指两条或两条以上流向值为 2（即不确定流向）的弧段构成的闭合路径。这意味着环路必须同时满足以下两个条件：

1. 是由至少两条弧段构成的闭合路径；
2. 构成环路的弧段的流向均为 2，即不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

下图是设施网络的一部分，使用不同的符号显示网络弧段的流向。对该网络进行环路检查，检查出两个环路，即图中的红色闭合路径。而右上方有一条流向为 2 的弧段，由于它未与其他流向同样为 2 的弧段构成闭合路径，因此不是环路。

返回:

构成环路的弧段 ID 数组。

示例:

以下代码示范了如何查找网络环路。假设下面函数操作的网络数据集为安装目录\SampleData\City\下的 Changchun.udb 数据源中的名为 RoadNet 的网络数据集，并且已经为该网络数据集建立了流向。 有关建立网络数据集的流向及等级，详细信息请参见SuperMap iDesktop帮助文档的设施网络分析相关介绍。

 public void TestCheckLoops(DatasetVector networkDataset)
     {
        //设置用于设施网络分析的环境
        FacilityAnalystSetting facilityAnalystSetting = new FacilityAnalystSetting();
        facilityAnalystSetting.setNetworkDataset ( networkDataset);
        facilityAnalystSetting.setDirectionField ("Direction");
        facilityAnalystSetting.setEdgeIDField ("SmID");
        facilityAnalystSetting.setNodeIDField ( "SmNodeID");
        facilityAnalystSetting.setFNodeIDField ( "SmFNode");
        facilityAnalystSetting.setTNodeIDField ("SmTNode");
        facilityAnalystSetting.setTolerance ( 0.0015);
        WeightFieldInfo weightFieldInfo = new WeightFieldInfo();
        weightFieldInfo.setName ( "Length");
        weightFieldInfo.setFTWeightField ( "SmLength");
        weightFieldInfo.setTFWeightField ("SmLength");
        WeightFieldInfos weightFieldInfos = new WeightFieldInfos();
        weightFieldInfos.add(weightFieldInfo);
        facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);
        FacilityAnalyst facilityAnalyst = new FacilityAnalyst();
        facilityAnalyst.setAnalystSetting ( facilityAnalystSetting);
        facilityAnalyst.load();

        //调用方法查找网络环路
        int[] edgeIDs = facilityAnalyst.checkLoops();

        //输出构成环路的弧段ID
        System.out.println("构成环路的弧段ID数组如下：");
        for (int i = 0; i < edgeIDs.length; i++)
        {
            System.out.println(edgeIDs[i]);
        }
    }

findPathFromNodes

public FacilityAnalystResult findPathFromNodes(int startNodeID,
                                               int endNodeID,
                                               java.lang.String weightName,
                                               boolean isUncertainDirectionValid)

设施网络路径分析，即根据给定的起始和终止结点 ID，查找其间耗费最小的路径，返回该路径包含的弧段、结点及耗费。

两结点间的最小耗费路径的查找过程为：从给定的起始结点出发，根据流向，查找到给定的终止结点的所有路径，然后从其中找出耗费最小的一条返回。

下图是两结点最小耗费路径的示意图。从起始结点 B 出发，沿着网络流向，有三条路径能够到达终止结点 P，分别为 B-D-L-P、B-C-G-I-J-K-P 和 E-E-F-H-M-N-O-P，其中路径 B-C-G-I-J-K-P 的耗费最小，为 105，因此该路径是结点 B 到 P 的最小耗费路径。

参数:

startNodeID - 指定的起始结点 ID。

endNodeID - 指定的终止结点 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

以下代码示范了如何查找两个结点或弧段之间的最小耗费路径。假设下面函数操作的网络数据集为安装目录\SampleData\changchun\下的 changchun.udb 数据源中的名为 RoadNet 的网络数据集，并且已经为该网络数据集建立了流向以及等级。 有关建立网络数据集的流向及等级，详细信息请参见SuperMap iDesktop帮助文档的设施网络分析相关介绍。

 public void findPathBetween(DatasetVector networkDataset)
    {
        //设置用于设施网络分析的环境
        FacilityAnalystSetting facilityAnalystSetting = new FacilityAnalystSetting();
        facilityAnalystSetting.setNetworkDataset ( networkDataset);
        facilityAnalystSetting.setDirectionField ("Direction");
        facilityAnalystSetting.setEdgeIDField ("SmID");
        facilityAnalystSetting.setNodeIDField ( "SmNodeID");
        facilityAnalystSetting.setFNodeIDField ( "SmFNode");
        facilityAnalystSetting.setTNodeIDField ("SmTNode");
        facilityAnalystSetting.setTolerance ( 0.0015);
        WeightFieldInfo weightFieldInfo = new WeightFieldInfo();
        weightFieldInfo.setName ( "Length");
        weightFieldInfo.setFTWeightField ( "SmLength");
        weightFieldInfo.setTFWeightField ("SmLength");
        WeightFieldInfos weightFieldInfos = new WeightFieldInfos();
        weightFieldInfos.add(weightFieldInfo);
        facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);
        FacilityAnalyst facilityAnalyst = new FacilityAnalyst();
        facilityAnalyst.setAnalystSetting ( facilityAnalystSetting);
        facilityAnalyst.load();

        //获取参与分析的弧段或结点
        int startEdgeID = 3855;
        int32 endEdgeID = 7887;
        int startNodeID = 2996;
        int endNodeID = 4239;

                //查找两个弧段间的最小耗费路径
        FacilityAnalystResult PathLeastE = facilityAnalyst.findPathFromEdges( startEdgeID, endEdgeID, "Length", true);
        //查找两个结点间的最小耗费路径
        FacilityAnalystResult PathLeastN = facilityAnalyst.findPathFromNodes( startNodeID, endNodeID, "Length", true);
    }
 

findPathFromEdges

public FacilityAnalystResult findPathFromEdges(int startEdgeID,
                                               int endEdgeID,
                                               java.lang.String weightName,
                                               boolean isUncertainDirectionValid)

设施网络路径分析，即根据给定的起始和终止弧段 ID，查找其间耗费最小的路径，返回该路径包含的弧段、结点及耗费。

两弧段间的最小耗费路径的查找过程为：从给定的起始弧段出发，根据流向，查找到给定的终止弧段的所有路径，然后从其中找出耗费最小的一条返回。请参阅 findPathFromNodes 方法以获得更多有关“设施网络路径分析”的介绍，该方法用于查找两结点间的最小耗费路径。

注意：如果指定的待分析弧段的流向值为 2，即不确定流向，则分析结果返回 null。

参数:

startEdgeID - 指定的起始弧段 ID。

endEdgeID - 指定的终止弧段 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 findPathFromNodes 方法的示例。

findPathUpFromNode

public FacilityAnalystResult findPathUpFromNode(int nodeID,
                                                java.lang.String weightName,
                                                boolean isUncertainDirectionValid)

设施网络上游路径分析，根据给定的结点 ID，查询该结点上游耗费最小的路径，返回该路径包含的弧段、结点及耗费。

有关“上游”的介绍，请参阅 traceUpFromNode 方法。

上游最小耗费路径的查找过程可以理解为：从给定结点（或弧段）出发，根据流向，查找出该结点（或弧段）的所有上游路径，然后从其中找出耗费最小的一条返回。该方法用于查找给定结点的上游最小耗费路径。

下图是一个简单的设施网络，在网络弧段上使用箭头标示了网络的流向，在弧段旁标注了权值。对于分析结点 I 进行上游最小耗费路径分析。首先从结点 I 出发，根据流向向上回溯，找出结点 I 的所有上游路径，共有 6 条，包括：E-F-I、A-F-I、B-G-J-I、D-G-J-I、C-G-J-I 和 H-J-I，然后根据网络阻力（即权值）计算这些路径的耗费，可以得出 E-F-I 这条路径的耗费最小，为 8.2，因此，结点 I 的上游最小耗费路径就是 E-F-I。

参数:

nodeID - 指定的结点 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 findPathDownFromNode 方法的示例。

findPathUpFromEdge

public FacilityAnalystResult findPathUpFromEdge(int edgeID,
                                                java.lang.String weightName,
                                                boolean isUncertainDirectionValid)

设施网络上游路径分析，根据给定的弧段 ID，查询该弧段上游耗费最小的路径，返回该路径包含的弧段、结点及耗费。

有关“上游”的介绍，请参阅 traceUpFromNode 方法。

上游最小耗费路径的查找过程可以理解为：从给定结点（或弧段）出发，根据流向，查找出该结点（或弧段）的所有上游路径，然后从其中找出耗费最小的一条返回。该方法用于查找给定弧段的上游最小耗费路径。

请参阅 findPathUpFromNode 方法，以获得更多关于“上游最小耗费路径”的介绍。

注意：如果指定的待分析弧段的流向值为 2，即不确定流向，则分析结果返回 null。

参数:

edgeID - 指定的弧段 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

请参见 findPathDownFromNode 方法的示例。

findPathDownFromNode

public FacilityAnalystResult findPathDownFromNode(int nodeID,
                                                  java.lang.String weightName,
                                                  boolean isUncertainDirectionValid)

设施网络下游路径分析，根据给定的参与分析的结点 ID，查询该结点下游耗费最小的路径，返回该路径包含的弧段、结点及耗费。

有关“下游”的介绍，请参阅 traceUpFromNode 方法。

下游最小耗费路径的查找过程可以理解为：从给定结点（或弧段）出发，根据流向，查找出该结点（或弧段）的所有下游路径，然后从其中找出耗费最小的一条返回。该方法用于查找给定结点的下游最小耗费路径。

下图是一个简单的设施网络，在网络弧段上使用箭头标示了网络的流向，在弧段旁标注了权值。对于分析结点 H 进行下游最小耗费路径分析。首先从结点 H 出发，根据流向向下查找，找出结点 H 的所有下游路径，共有 4 条，包括：H-L-G、H-L-K、H-M-S 和 H-M-Q-R，然后根据网络阻力（即权值）计算这些路径的耗费，可以得出 H-L-K 这条路径的耗费最小，为 11.1，因此，结点 H 的下最小耗费路径就是 H-L-K。

参数:

nodeID - 指定的结点 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

示例:

以下代码示范了如何查找给定弧段或结点的下游或上游耗费最小的路径。假设下面函数操作的网络数据集为安装目录\SampleData\changchun\下的 changchun.udb 数据源中的名为 RoadNet 的网络数据集，并且已经为该网络数据集建立了流向以及等级。 有关建立网络数据集的流向及等级，详细信息请参见SuperMap iDesktop帮助文档的设施网络分析相关介绍。

public void findPathDownandUp(DatasetVector networkDataset)
    {
        //设置用于设施网络分析的环境
        FacilityAnalystSetting facilityAnalystSetting = new FacilityAnalystSetting();
        facilityAnalystSetting.setNetworkDataset ( networkDataset);
        facilityAnalystSetting.setDirectionField ("Direction");
        facilityAnalystSetting.setEdgeIDField ("SmID");
        facilityAnalystSetting.setNodeIDField ( "SmNodeID");
        facilityAnalystSetting.setFNodeIDField ( "SmFNode");
        facilityAnalystSetting.setTNodeIDField ("SmTNode");
        facilityAnalystSetting.setTolerance ( 0.0015);
        WeightFieldInfo weightFieldInfo = new WeightFieldInfo();
        weightFieldInfo.setName ( "Length");
        weightFieldInfo.setFTWeightField ( "SmLength");
        weightFieldInfo.setTFWeightField ("SmLength");
        WeightFieldInfos weightFieldInfos = new WeightFieldInfos();
        weightFieldInfos.add(weightFieldInfo);
        facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);
        FacilityAnalyst facilityAnalyst = new FacilityAnalyst();
        facilityAnalyst.setAnalystSetting ( facilityAnalystSetting);
        facilityAnalyst.load();

        //获取参与分析的结点
        int nodeID =2996;

        //查找给定结点的上游和下游弧段数最小耗费路径
        FacilityAnalystResult PathUpLeast = facilityAnalyst.findPathUpFromNode( nodeID, "Length", true);
        FacilityAnalystResult PathDownLeast = facilityAnalyst .findPathDownFromNode(nodeID, "Length", true);
    }

findPathDownFromEdge

public FacilityAnalystResult findPathDownFromEdge(int edgeID,
                                                  java.lang.String weightName,
                                                  boolean isUncertainDirectionValid)

设施网络下游路径分析，根据给定的参与分析的弧段 ID，查询该弧段下游耗费最小的路径，返回该路径包含的弧段、结点及耗费。

有关“下游”的介绍，请参阅 traceUpFromNode 方法。

下游最小耗费路径的查找过程可以理解为：从给定结点（或弧段）出发，根据流向，查找出该结点（或弧段）的所有下游路径，然后从其中找出耗费最小的一条返回。该方法用于查找给定弧段的下游最小耗费路径。

请参阅 findPathDownFromNode 方法，以获得更多关于“下游最小耗费路径”的介绍。

注意：如果指定的待分析弧段的流向值为 2，即不确定流向，则分析结果返回 null。

参数:

edgeID - 指定的弧段 ID。

weightName - 指定的权值字段信息对象的名称，即设施网络分析环境中指定的权值字段信息集合（setWeightFieldInfos）中某一个权值信息对象（WeightFieldInfo） 的名称（getName）。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。有关流向请参阅SuperMap iDesktop帮助文档的设施网络分析相关介绍。

返回:

设施网络分析结果。

dispose

public void dispose()

释放该对象所占用的资源。当调用该方法之后，此对象不再可用。