com.supermap.realspace.networkanalyst

类 FacilityAnalyst3D

java.lang.Object

com.supermap.data.InternalHandle

com.supermap.data.InternalHandleDisposable

com.supermap.realspace.networkanalyst.FacilityAnalyst3D

所有已实现的接口:

IDisposable

public class FacilityAnalyst3D
extends com.supermap.data.InternalHandleDisposable

三维设施网络分析类。该类提供数据检查功能，以及查找结点或弧段到源或汇之间的弧段、上游追踪、下游追踪和上游最近设施查找等分析功能。

设施网络，是对现实世界中的常见网络和基础设施的模拟，如供水网、输电线、通信线路、天然气管道、河流等，其共同的特点是资源的流动具有方向。三维设施网络分析是基于创建了流向的三维网络数据集的分析，是三维网络分析的重要内容，目前提供的主要功能有：查找结点或弧段到源或汇之间的弧段、上下游追踪、上游最近设施查找等。相对于传统的二维设施网络分析，三维设施网络分析由于其真实的三维展现，从而能够更好地为设施网络的设计、施工、突发事故处理等提供指导和决策支持。

三维设施网络分析的一般步骤：

1. 构建三维网络数据集。根据研究需求和已有数据选择合适的网络模型构建方法。SuperMap 提供了三种三维网络数据集的构建方法，具体介绍请参阅 NetworkBuilder3D 类；
2. 为三维网络数据集创建流向（NetworkBuilder3D 类的 buildFacilityNetworkDirections 方法）。由于设施网络是具有方向的网络，因此，进行三维设施网络分析的前提是用于分析的三维网络数据集已经创建了流向；
3. （可选）建议对用于分析的网络数据集进行数据检查（NetworkBuilder3D 类的 NetworkBuilder3D.check(NetworkCheckParameter3D, SteppedListener...) check} 方法）;
4. 设置三维设施网络分析环境（setAnalystSetting 方法）；
5. 加载网络模型（load 方法）；
6. 使用 FacilityAnalyst3D 类提供的各种设施网络分析方法进行相应的分析。

示范代码:

请参见 findSourceFromEdge、traceUpFromEdge、findCriticalFacilitiesUpFromEdge 等方法的示例。

构造器概要

构造器

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

方法概要

限定符和类型	方法和说明
BurstAnalyse3DResult	burstAnalyseFromEdge(int[] sourceNodeIDs, int edgeID, boolean isUncertainDirectionValid) 双向爆管分析，通过指定爆管弧段，查找爆管弧段上下游中对爆管位置产生直接影响的结点以及受爆管位置直接影响的结点。
BurstAnalyse3DResult	burstAnalyseFromNode(int[] sourceNodeIDs, int nodeID, boolean isUncertainDirectionValid) 双向爆管分析，通过指定爆管结点，查找爆管结点上下游中对爆管位置产生直接影响的结点以及受爆管位置直接影响的结点。
FacilityAnalystCheckResult3D	check() 已过时。
void	dispose() 释放该对象所占用的资源。
FacilityAnalystResult3D	findCriticalFacilitiesDownFromEdge(int[] sourceNodeIDs, int edgeID, boolean isUncertainDirectionValid) 下游关键设施查找，即查找给定弧段的关键下游设施结点，返回关键设施结点 ID 数组及给定弧段影响到的下游弧段 ID 数组。
FacilityAnalystResult3D	findCriticalFacilitiesDownFromNode(int[] sourceNodeIDs, int nodeID, boolean isUncertainDirectionValid) 下游关键设施查找，即查找给定结点的下游关键设施结点，返回关键结点 ID 数组及给定结点影响到的下游弧段 ID 数组。
FacilityAnalystResult3D	findCriticalFacilitiesUpFromEdge(int[] sourceNodeIDs, int edgeID, boolean isUncertainDirectionValid) 上游关键设施查找，即查找给定弧段的上游中的关键设施结点，返回关键结点 ID 数组及其下游弧段 ID 数组。
FacilityAnalystResult3D	findCriticalFacilitiesUpFromNode(int[] sourceNodeIDs, int nodeID, boolean isUncertainDirectionValid) 上游关键设施查找，即查找给定结点的上游中的关键设施结点，返回关键结点 ID 数组及其影响到的下游弧段 ID 数组。
FacilityAnalystResult3D	findSinkFromEdge(int edgeID, String weightName, boolean isUncertainDirectionValid) 根据给定的弧段 ID 查找汇，即从给定弧段出发，根据流向查找流出该弧段的下游汇点，并返回给定弧段到达该汇的最小耗费路径所包含的弧段、结点及耗费。
FacilityAnalystResult3D	findSinkFromNode(int nodeID, String weightName, boolean isUncertainDirectionValid) 根据给定的结点 ID 查找汇，即从给定结点出发，根据流向查找流出该结点的下游汇点，并返回给定结点到达该汇的最小耗费路径所包含的弧段、结点及耗费。
FacilityAnalystResult3D	findSourceFromEdge(int edgeID, String weightName, boolean isUncertainDirectionValid) 根据给定的弧段 ID 查找源，即从给定弧段出发，根据流向查找流向该弧段的网络源头，并返回该源到达给定弧段的最小耗费路径所包含的弧段、结点及耗费。
FacilityAnalystResult3D	findSourceFromNode(int nodeID, String weightName, boolean isUncertainDirectionValid) 根据给定的结点 ID 查找源，即从给定结点出发，根据流向查找流向该结点的网络源头，并返回该源到达给定结点的最小耗费路径所包含的弧段、结点及耗费。
FacilityAnalystSetting3D	getAnalystSetting() 返回三维设施网络分析环境。
boolean	load() 根据三维设施网络分析环境设置对象中的环境参数，加载网络模型。
void	setAnalystSetting(FacilityAnalystSetting3D value) 设置三维设施网络分析环境。
FacilityAnalystResult3D	traceDownFromEdge(int edgeID, String weightName, boolean isUncertainDirectionValid) 根据给定的弧段 ID 进行下游追踪，即查找给定弧段的下游，返回下游包含的弧段、结点及总耗费。
FacilityAnalystResult3D	traceDownFromNode(int nodeID, String weightName, boolean isUncertainDirectionValid) 根据给定的结点 ID 进行下游追踪，即查找给定结点的下游，返回下游包含的弧段、结点及总耗费。
FacilityAnalystResult3D	traceUpFromEdge(int edgeID, String weightName, boolean isUncertainDirectionValid) 根据给定的弧段 ID 进行上游追踪，即查找给定弧段的上游，返回上游包含的弧段、结点及总耗费。
FacilityAnalystResult3D	traceUpFromNode(int nodeID, String weightName, boolean isUncertainDirectionValid) 根据给定的结点 ID 进行上游追踪，即查找给定结点的上游，返回上游包含的弧段、结点及总耗费。

从类继承的方法 com.supermap.data.InternalHandleDisposable

makeSureNativeObjectLive

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

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

构造器详细资料

FacilityAnalyst3D

public FacilityAnalyst3D()

构造一个新的 FacilityAnalyst3D 对象。

方法详细资料

getAnalystSetting

public FacilityAnalystSetting3D getAnalystSetting()

返回三维设施网络分析环境。

返回:

三维设施网络分析的环境。

默认值:

默认值为一个初始化的 FacilityAnalystSetting3D 对象。

setAnalystSetting

public void setAnalystSetting(FacilityAnalystSetting3D value)

设置三维设施网络分析环境。

三维设施网络分析环境用于设置三维设施网络分析所需的相关参数，包括三维网络数据集、弧段和结点的 ID 字段、权值信息、障碍信息等。详见 FacilityAnalystSetting3D 类。三维设施网络分析环境参数的设置，直接影响到设施网络分析的结果。

参数:

value - 三维设施网络分析环境参数。 请参见 findSourceFromEdge、traceUpFromEdge、findCriticalFacilitiesUpFromEdge 等方法的示例。

load

public boolean load()

根据三维设施网络分析环境设置对象中的环境参数，加载网络模型。

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

注意：

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

返回:

一个布尔值，代表网络模型是否加载成功。如果成功，返回 true，否则返回 false。 请参见 findSourceFromEdge、traceUpFromEdge、findCriticalFacilitiesUpFromEdge 等方法的示例。

check

@Deprecated
public FacilityAnalystCheckResult3D check()

已过时。

对三维设施网络数据集进行数据检查，返回三维设施网络分析数据检查结果对象。

该方法用于对三维设施网络数据集进行检查，给出错误信息，便于用户针对错误信息对数据进行修改，以避免由于数据错误导致设施网络分析错误。

注意，该方法需要在设置三维设施网络分析环境（setAnalystSetting 方法）之后调用，但不需要加载网络模型（load 方法）。

该方法返回一个三维设施网络分析数据检查结果（FacilityAnalystCheckResult3D）对象，通过该对象的 getArcErrorInfos 方法和 getNodeErrorInfos 方法可以获取弧段错误信息和结点错误信息。错误信息存储在字典中，键代表错误弧段或结点的 SMID，值代表错误类型。错误类型以数字表示，代表的具体错误含义如下表所示。

返回:

三维设施网络分析数据检查结果。

findSourceFromNode

public FacilityAnalystResult3D findSourceFromNode(int nodeID,
                                                  String weightName,
                                                  boolean isUncertainDirectionValid)

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

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

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

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

参数:

nodeID - 指定的结点 ID。

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

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。

示范代码:

请参见 findSourceFromEdge 方法的示例。

findSourceFromEdge

public FacilityAnalystResult3D findSourceFromEdge(int edgeID,
                                                  String weightName,
                                                  boolean isUncertainDirectionValid)

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

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

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

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

参数:

edgeID - 指定的弧段 ID。

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

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。

示范代码:

以下代码示范了如何根据给定的结点或弧段查找源和汇。假设在数据源“datasource”中存在一个名为“FacilityNet”的三维网络数据集，以弧段 ID 为 102 的弧段和结点 ID 为 45 的结点为例，示范如何查找源和汇。

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

                // 构造一个三维设施网络分析环境设置对象，并设置相关参数
                FacilityAnalystSetting3D facilityAnalystSetting = new FacilityAnalystSetting3D();
                facilityAnalystSetting.setNetworkDataset(network3D);
                facilityAnalystSetting.setDirectionField("direction");
                facilityAnalystSetting.setEdgeIDField("SMEDGEID");
                facilityAnalystSetting.setNodeIDField("SMNODEID");
                facilityAnalystSetting.setFNodeIDField("SMFNODE");
                facilityAnalystSetting.setTNodeIDField("SMTNODE");
                facilityAnalystSetting.setTolerance(0.001);
                WeightFieldInfo3D weightFieldInfo = new WeightFieldInfo3D();
                weightFieldInfo.setName("Length");
                weightFieldInfo.setFTWeightField("SMLENGTH");
                weightFieldInfo.setTFWeightField("SMLENGTH");
                WeightFieldInfos3D weightFieldInfos = new WeightFieldInfos3D();
                weightFieldInfos.add(weightFieldInfo);
                facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);

                facilityAnalystSetting.setBarrierEdges(new int[] { 8 });
                facilityAnalystSetting.setBarrierNodes(new int[] { 79 });

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

                // 加载三维网络模型
                boolean isLoad = facilityAnalyst.load();

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

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

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

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

findSinkFromNode

public FacilityAnalystResult3D findSinkFromNode(int nodeID,
                                                String weightName,
                                                boolean isUncertainDirectionValid)

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

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

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

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

参数:

nodeID - 指定的结点 ID。

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

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。

示范代码:

请参见 findSourceFromEdge 方法的示例。

findSinkFromEdge

public FacilityAnalystResult3D findSinkFromEdge(int edgeID,
                                                String weightName,
                                                boolean isUncertainDirectionValid)

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

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

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

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

参数:

edgeID - 指定的弧段 ID。

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

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。

示范代码:

请参见 findSourceFromEdge 方法的示例。

traceUpFromNode

public FacilityAnalystResult3D traceUpFromNode(int nodeID,
                                               String weightName,
                                               boolean isUncertainDirectionValid)

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

下图为一个简单的设施网络的示意图，其中结点 Q 为汇点，即资源流入 Q 点，图中的箭头标出了网络的流向。根据流向可以看出，资源流经结点 A、B、C、L、E、F、G 最终流入结点 Q，因此这些结点称为结点 Q 的上游结点，同样，资源流经弧段 AB、BC、CL、LQ、EB、FG、GL 最终流入结点 Q，故这些弧段称为结点 Q 的上游弧段。

上游追踪的目的就是找出某个结点或弧段的上游所流经的所有弧段。上图中，对于结点 Q ，上游追踪的结果为弧段 AB、BC、CL、LQ、EB、FG、GL 的 ID 的数组。

关于上游追踪的更多介绍，请参见 traceUpFromEdge 方法。

参数:

nodeID - 指定的结点 ID。

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

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。

示范代码:

请参见 FacilityAnalyst3D 类的示例。

traceUpFromEdge

public FacilityAnalystResult3D traceUpFromEdge(int edgeID,
                                               String weightName,
                                               boolean isUncertainDirectionValid)

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

下图为一个简单的设施网络的示意图，其中结点 Q 为汇点，即资源流入 Q 点，图中的箭头标出了网络的流向。根据流向可以看出，资源流经结点 A、B、C、L、E、F、G 最终流入结点 Q，因此这些结点称为结点 Q 的上游结点，同样，资源流经弧段 AB、BC、CL、LQ、EB、FG、GL 最终流入结点 Q，故这些弧段称为结点 Q 的上游弧段。同理，对于弧段 LQ 来说，结点 A、B、C、L、E、F、G 是它的上游结点，弧段 AB、BC、CL、EB、FG、GL 是它的上游弧段。

上游追踪的目的就是找出某个结点或弧段的上游所流经的所有弧段。上图中，对于弧段 LQ，上游追踪的结果为弧段 AB、BC、CL、EB、FG、GL 的 ID 数组。

河流（水系）网络是最常见的设施网络之一。上游追踪可以用于分析某条河段的上游河段有哪些，并且上游追踪在遇到障碍（包括障碍点、障碍弧段和障碍结点）时停止搜索。障碍信息在三维设施网络分析环境设置（FacilityAnalystSetting3D）中指定。如下图所示，黄色弧段为要进行上游追踪的河段，红色弧段为障碍，蓝色弧段为分析出的上游弧段。

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

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

参数:

edgeID - 指定的弧段 ID。

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

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。

示范代码:

以下代码示范了如何根据给定的结点或弧段进行上下游追踪。假设在数据源“datasource”中存在一个名为“FacilityNet”的三维网络数据集，以弧段 ID 为 102 的弧段和结点 ID 为 45 的结点为例，示范如何进行上游追踪和下游追踪。

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

                // 构造一个三维设施网络分析环境设置对象，并设置相关参数
                FacilityAnalystSetting3D facilityAnalystSetting = new FacilityAnalystSetting3D();
                facilityAnalystSetting.setNetworkDataset(network3D);
                facilityAnalystSetting.setDirectionField("direction");
                facilityAnalystSetting.setEdgeIDField("SMEDGEID");
                facilityAnalystSetting.setNodeIDField("SMNODEID");
                facilityAnalystSetting.setFNodeIDField("SMFNODE");
                facilityAnalystSetting.setTNodeIDField("SMTNODE");
                facilityAnalystSetting.setTolerance(0.001);
                WeightFieldInfo3D weightFieldInfo = new WeightFieldInfo3D();
                weightFieldInfo.setName("Length");
                weightFieldInfo.setFTWeightField("SMLENGTH");
                weightFieldInfo.setTFWeightField("SMLENGTH");
                WeightFieldInfos3D weightFieldInfos = new WeightFieldInfos3D();
                weightFieldInfos.add(weightFieldInfo);
                facilityAnalystSetting.setWeightFieldInfos(weightFieldInfos);

                facilityAnalystSetting.setBarrierEdges(new int[] { 8 });
                facilityAnalystSetting.setBarrierNodes(new int[] { 79 });

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

                // 加载三维网络模型
                boolean isLoad = facilityAnalyst.load();

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

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

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

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

traceDownFromNode

public FacilityAnalystResult3D traceDownFromNode(int nodeID,
                                                 String weightName,
                                                 boolean isUncertainDirectionValid)

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

下图为一个简单的设施网络的示意图，其中结点 Q 为源点，即资源从 Q 点流出，图中的箭头标出了网络的流向。根据流向可以看出，结点 A、B、C、L、E、F、G 都接收了从结点 Q 流出的资源，因此这些结点称为结点 Q 的下游结点，同样，资源从结点 Q 流出，流经弧段 BA、CB、LC、QL、BE、GF、LG，故这些弧段称为结点 Q 的下游弧段。

下游追踪的目的就是找出某个结点或弧段的下游所流经的所有弧段。上图中，对于结点 Q ，下游追踪的结果为弧段 BA、CB、LC、QL、BE、GF、LG 的 ID 数组。

下游追踪常用于影响范围的分析。详细介绍请参见 traceDownFromEdge 方法。

参数:

nodeID - 指定的结点 ID。

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

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。

示范代码:

请参见 FacilityAnalyst3D 类的示例。

traceDownFromEdge

public FacilityAnalystResult3D traceDownFromEdge(int edgeID,
                                                 String weightName,
                                                 boolean isUncertainDirectionValid)

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

下图为一个简单的设施网络的示意图，其中结点 Q 为源点，即资源从 Q 点流出，图中的箭头标出了网络的流向。根据流向可以看出，结点 A、B、C、L、E、F、G 都接收了从结点 Q 流出的资源，因此这些结点称为结点 Q 的下游结点，同样，资源从结点 Q 流出，流经弧段 BA、CB、LC、QL、BE、GF、LG，故这些弧段称为结点 Q 的下游弧段。同理，对于弧段 QL 来说，结点 A、B、C、L、E、F、G 是它的下游结点，弧段 BA、CB、LC、BE、GF、LG 是它的下游弧段。

下游追踪的目的就是找出某个结点或弧段的下游所流经的所有弧段。上图中，对于弧段 QL，下游追踪的结果为弧段 BA、CB、LC、BE、GF、LG 的 ID 数组。

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

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

参数:

edgeID - 指定的弧段 ID。

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

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。

示范代码:

请参见 FacilityAnalyst3D 类的示例。

findCriticalFacilitiesUpFromNode

public FacilityAnalystResult3D findCriticalFacilitiesUpFromNode(int[] sourceNodeIDs,
                                                                int nodeID,
                                                                boolean isUncertainDirectionValid)

上游关键设施查找，即查找给定结点的上游中的关键设施结点，返回关键结点 ID 数组及其影响到的下游弧段 ID 数组。

此方法根据给定的结点 ID 和设施结点的 ID 数组，查找该结点的上游中的关键设施结点。有关上游关键设施查找的详细介绍，请参阅另一重载方法 findCriticalFacilitiesUpFromEdge，该方法用来查找给定弧段的上游中的关键设施结点。

参数:

sourceNodeIDs - 指定的设施结点 ID 数组。不能为空。

nodeID - 指定的分析结点 ID。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。设施网络分析结果。未查找到关键设施结点返回 null。

示范代码:

请参见 findCriticalFacilitiesUpFromEdge 方法的示例。

findCriticalFacilitiesUpFromEdge

public FacilityAnalystResult3D findCriticalFacilitiesUpFromEdge(int[] sourceNodeIDs,
                                                                int edgeID,
                                                                boolean isUncertainDirectionValid)

上游关键设施查找，即查找给定弧段的上游中的关键设施结点，返回关键结点 ID 数组及其下游弧段 ID 数组。

在进行上游关键设施查找分析时，我们将设施网络的结点划分为普通结点和设施结点两类，其中设施结点认为是能够影响网络连通性的结点，例如供水管网中的阀门；普通结点是不影响网络连通性的结点，如供水管网中的消防栓或三通等。上游关键设施查找分析需要指定设施结点和分析结点，其中分析结点可以是设施结点也可以是普通结点。

上游关键设施查找分析将从给定的设施结点中筛选出关键结点，这些关键结点是分析弧段与其上游保持连通性的最基本的结点，也就是说，关闭这些关键结点后，分析结点与上游无法连通。同时，该分析的结果还包含查找出的关键结点的下游弧段的并集。关键设施结点和它们的下游分别通过设施网络分析结果（FacilityAnalystResult3D）类的 getNodes 和 getEdges 方法返回。

关键设施结点的查找方式可以归纳为：从分析弧段出发，向它的上游回溯，每个方向上遇到的第一个设施结点，就是要查找的关键设施结点。如下图所示，从分析弧段（红色）出发，查找到的关键设施结点包括：2、8、9 和 7。而结点 4 和 11 不是回溯方向上遇到的第一个设施结点，因此不是关键设施结点。作为示意，这里仅给出了分析弧段的上游部分，但注意分析结果还会给出关键设施结点 2、8、9 和 7 的下游弧段。

此方法根据给定的弧段 ID 和设施结点的 ID 数组，查找该弧段的上游中的关键设施结点。还可以通过 findCriticalFacilitiesUpFromNode 方法来查找给定结点的上游的关键设施结点。

应用实例

供水管网发生爆管后，可以将所有的阀门作为设施结点，将发生爆裂的管段或管点作为分析弧段或分析结点，进行上游关键设施查找分析，迅速找到上游中需要关闭的最少数量的阀门。关闭这些阀门后，爆裂管段或管点与它的上游不再连通，从而阻止水的流出，防止灾情加重和资源浪费。同时，分析得出需要关闭的阀门的下游弧段的并集，也就是关闭阀门后的影响范围，从而确定停水区域，及时做好通知工作和应急措施。

参数:

sourceNodeIDs - 指定的设施结点 ID 数组。不能为空。

edgeID - 指定的分析弧段 ID。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。未查找到关键设施结点返回 null。

示范代码:

以下代码示范了如何进行上游关键设施查找分析。

假设在数据源“datasource”中存在一个名为“FacilityNet”的三维网络数据集，查找弧段 ID 为 16 的弧段的上游中的关键设施结点有哪些。

        /**
         * 根据给定的弧段 ID 和设施结点 ID 数组进行上游关键设施查找分析。
         * @param datasource 指定的三维网络数据集所在的数据源。
         */
        private void findCriticalFacilitiesUpExample(Datasource datasource)
        {
                //获取用于分析的三维网络数据集
                DatasetVector network3D = (DatasetVector)datasource.getDatasets().get("FacilityNet");
                //构造一个三维设施网络分析环境设置对象，并设置相关参数
                FacilityAnalystSetting3D facilityAnalystSetting = new FacilityAnalystSetting3D();
                facilityAnalystSetting.setNetworkDataset(network3D);
                facilityAnalystSetting.setDirectionField("direction");
                facilityAnalystSetting.setEdgeIDField("SMEDGEID");
                facilityAnalystSetting.setNodeIDField("SMNODEID");
                facilityAnalystSetting.setFNodeIDField("SMFNODE");
                facilityAnalystSetting.setTNodeIDField("SMTNODE");
                facilityAnalystSetting.setTolerance(0.001);
                //由于上游关键设施查找不需要权值信息，因此不需要设置WeightFieldInfos
                //是否设置WeightFieldInfos需要根据具体的分析功能确定

                //构造一个三维设施网络分析对象，并设置三维设施网络分析环境
                FacilityAnalyst3D facilityAnalyst = new FacilityAnalyst3D();
                facilityAnalyst.setAnalystSetting(facilityAnalystSetting);
                
                //加载三维网络模型
                boolean isLoad = facilityAnalyst.load();
                
                if (isLoad) {
                        // 指定待分析弧段
                        int edgeID = 16;
                        // 指定网络中的设施结点
                        int[] facilitiyNodeIDs = new int[] { 1, 9, 10, 13, 17, 20, 21, 29,
                                        30, 35, 35, 37 };
                        //对给定弧段进行上游关键设施查找分析
                        FacilityAnalystResult3D result = facilityAnalyst.findCriticalFacilitiesUpFromEdge(facilitiyNodeIDs, edgeID, true);
                        if (result != null)     {
                                //从设施网络分析结果中获取查找到的关键设施结点数组
                                int[] criticalFacilities = result.getNodes();
                                //从设施网络分析结果中获取关键设施结点的下游弧段数组
                                int[] catchmentEdges = result.getEdges();
                        }
                        //对给定结点进行上游关键设施查找分析（略，参考“对给定弧段进行上游关键设施查找分析”）
                }
                
                // 分析完毕，释放三维设施网络分析对象所占的资源
                facilityAnalyst.dispose();      
        }
 

findCriticalFacilitiesDownFromNode

public FacilityAnalystResult3D findCriticalFacilitiesDownFromNode(int[] sourceNodeIDs,
                                                                  int nodeID,
                                                                  boolean isUncertainDirectionValid)

下游关键设施查找，即查找给定结点的下游关键设施结点，返回关键结点 ID 数组及给定结点影响到的下游弧段 ID 数组。

此方法根据给定的结点 ID 和设施结点的 ID 数组，查找该结点的下游中的关键设施结点。有关下游关键设施查找的详细介绍，请参阅另一重载方法FacilityAnalyst3D.findCriticalFacilitiesDownFromEdge(int[], int, boolean)，该方法用来查找给定弧段的下游中的关键设施结点。

参数:

sourceNodeIDs - 指定的设施结点 ID 数组。不能为空。

nodeID - 指定的分析结点 ID。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，具有不确定流向的弧段仍然参与分析；指定为 false，分析时遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

施网络分析结果。未查找到关键设施结点返回 null。

findCriticalFacilitiesDownFromEdge

public FacilityAnalystResult3D findCriticalFacilitiesDownFromEdge(int[] sourceNodeIDs,
                                                                  int edgeID,
                                                                  boolean isUncertainDirectionValid)

下游关键设施查找，即查找给定弧段的关键下游设施结点，返回关键设施结点 ID 数组及给定弧段影响到的下游弧段 ID 数组。

在进行下游关键设施查找分析时，我们将设施网络的结点划分为普通结点和设施结点两类，其中设施结点认为是能够影响网络连通性的结点，例如供水管网中的阀门；普通结点是不影响网络连通性的结点，如供水管网中的消防栓或三通等。

下游关键设施查找分析将从给定的设施结点中筛选出关键结点，这些关键结点是分析弧段与其下游保持连通性的最基本的结点，也就是说，关闭这些关键结点后，分析结点与下游无法连通。同时，该分析的结果还包含给定弧段影响的下游弧段并集。关键设施结点和下游弧段分别通过设施网络分析结果类的 getNodes() 和 getEdges() 方法返回。

关键设施结点的查找方式可以归纳为：从分析弧段出发，向它的下游查找，每个方向上遇到的第一个设施结点，就是要查找的关键设施结点。

此方法根据给定的弧段 ID 和设施结点的 ID 数组，查找该弧段的下游中的关键设施结点。还可以通过 FacilityAnalyst3D.findCriticalFacilitiesDownFromNode(int[], int, boolean)方法来查找给定结点的下游关键设施结点。

参数:

sourceNodeIDs - 指定的设施结点 ID 数组。不能为空。

edgeID - 指定的分析弧段 ID。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，具有不确定流向的弧段仍然参与分析；指定为 false，分析时遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅 buildFacilityNetworkDirections 方法的介绍。

返回:

设施网络分析结果。未查找到关键设施结点返回 null。

dispose

public void dispose()

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

burstAnalyseFromNode

public BurstAnalyse3DResult burstAnalyseFromNode(int[] sourceNodeIDs,
                                                 int nodeID,
                                                 boolean isUncertainDirectionValid)

双向爆管分析，通过指定爆管结点，查找爆管结点上下游中对爆管位置产生直接影响的结点以及受爆管位置直接影响的结点。

参数:

sourceNodeIDs - 指定的设施结点 ID 数组。不能为空。

nodeID - 指定的分析结点 ID。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅NetworkBuilder.buildFacilityNetworkDirections方法的介绍。

返回:

爆管分析结果。

从以下版本开始:

SuperMap iObjects Java 8.0.2

burstAnalyseFromEdge

public BurstAnalyse3DResult burstAnalyseFromEdge(int[] sourceNodeIDs,
                                                 int edgeID,
                                                 boolean isUncertainDirectionValid)

双向爆管分析，通过指定爆管弧段，查找爆管弧段上下游中对爆管位置产生直接影响的结点以及受爆管位置直接影响的结点。

参数:

sourceNodeIDs - 指定的设施结点 ID 数组。不能为空。

edgeID - 指定的弧段结点 ID。

isUncertainDirectionValid - 指定不确定流向是否有效。指定为 true，表示不确定流向有效，遇到不确定流向时分析继续进行；指定为 false，表示不确定流向无效，遇到不确定流向将停止在该方向上继续查找。流向字段的值为 2 时代表该弧段的流向为不确定流向。详细介绍请参阅NetworkBuilder.buildFacilityNetworkDirections方法的介绍。

返回:

爆管分析结果。

从以下版本开始:

SuperMap iObjects Java 8.0.2