com.supermap.analyst.networkanalyst
类 PathGuideItem

java.lang.Object
  com.supermap.analyst.networkanalyst.PathGuideItem

public class PathGuideItem
extends java.lang.Object

行驶导引子项类。

行驶导引（PathGuide）记录了如何从一条路径的起点一步步行驶到终点，其中路径上的每一个关键要素对应一个行驶导引子项。这些关键要素包括站点（用户输入的用于分析的点，可以为普通点或结点），经过的弧段和网络结点。通过行驶导引子项对象，可以获取路径中关键要素的 ID、名称、序号、权值、长度，还可以判断是弧段还是站点，以及行驶方向、转弯方向、花费等信息。按照行驶导引子项的序号对其存储的关键要素信息进行提取并组织，就可以描绘出如何从路径起点到达终点。

在交通网络分析中，行驶导引子项可以归纳为以下几类：

1. 站点：即用户选择的用于分析的点，如进行最佳路径分析时指定的要经过的各个点。

2. 站点到网络的线段：当站点为普通的坐标点时，需要首先将站点归结到网络上，才能基于网络进行分析。请参见 setTolerance 方法的介绍。

   如下图所示，红色虚线即为站点到网络的最短直线距离。注意，当站点在网络弧段的边缘附近时，如右图所示，这段距离是指站点与弧段端点的连线距离。



3. 站点在网络上的对应点：与“站点到网络的线段”对应，这个点就是将站点（普通坐标点）归结到网络上时，网络上相应的点。上面左图所示的情形，这个点就是站点在对应弧段上的垂足点；上面右图所示的情形，这个点则为弧段的端点。
4. 路段：也就是行驶经过的一段道路。交通网络中用弧段模拟道路，因此行驶路段都位于弧段上。注意，多个弧段可能被合并为一个行驶导引子项，合并的条件是它们的弧段名称相同，并且相邻弧段间的转角小于 30 度。需要强调，到达站点前的最后一个行驶路段和到达站点后的第一个行驶路段，仅包含一条弧段或弧段的一部分，即使满足上述条件也不会与相邻弧段合并为一个行驶导引。

如下图所示，使用不同的颜色标示出了两个站点之间的行驶路段。其中，站点 1 之后的第一条路段（红色），虽然其所在弧段的名称与后面几条弧段的名称相同，且转向角度都小于 30 度，但由于它是站点后的第一条路段，因此并未将它们合并。而蓝色路段所覆盖的三条弧段，由于弧段名称相同且转角小于 30 度，故将它们合并为一个行驶导引子项；粉色路段由于与之前的路段具有不同的弧段名称，故成为另一个行驶导引子项；绿色路段由于是到达站点前的最后一条路段，因此也单独作为一个行驶导引子项。



5. 转向点：两个相邻的行驶路段之间的路口。路口是指有可能发生方向改变的实际道路的路口（如十字路口或丁字路口）。在转向点处行驶方向可能发生改变。如上图中的结点 2783、2786 和 2691 都是转向点。转向点一定是网络结点。

通过 PathGuideItem 的各个方法返回的值，可以判断行驶导引子项属于哪种类型，下表总结了五种行驶导引子项的各个方法返回值的对照表，方便用户理解和使用行驶导引。

通过下面的实例，可以帮助用户理解行驶导引和行驶导引子项的内容和作用。

下图中的蓝色虚线为最近设施查找分析的结果中的一条路径，在最近设施查找的返回结果中，可以获得这条路径对应的行驶导引。

用于描述这条路径的行驶导引共包含7个子项。这7个行驶导引子项包含2个站点（即起点和终点，对应序号为0和6）、3个弧段（即路段，序号分别为1、3、5）和2个网络结点（即转向点，序号分别为2、4）。下表列出了这7个行驶导引子项的信息，包括是否为站点（IsStop）、是否为弧段（IsEdge）、序号（Index）、行驶方向（DirectionType）、转弯方向（TurnType）及弧段名称（Name）等信息。

将行驶导引子项记录的信息进行组织，可以得到如下表所示的该路径的导引描述。

方法摘要

Rectangle2D	getBounds() 返回该行驶导引子项的范围。
DirectionType	getDirectionType() 返回该行驶导引子项的行驶方向，仅当行驶导引子项为线类型（即 isEdge 返回 true）时有意义，可以为东、南、西、北。
double	getDistance() 返回站点到网络的距离，仅当行驶导引子项为站点时有效。
GeoLine	getGuideLine() 返回该行驶导引子项为线类型（即 isEdge 返回 true）时，对应的行驶导引线段。
int	getID() 返回该行驶导引子项的 ID。
int	getIndex() 返回该行驶导引子项的序号。
double	getLength() 返回该行驶导引子项为线类型（即 isEdge 返回 true}）时，对应线段的长度。
java.lang.String	getName() 返回该行驶导引子项的名称。
SideType	getSideType() 返回该行驶导引子项为站点时，站点在道路的左侧、右侧还是在路上。
double	getTurnAngle() 返回该行驶导引子项为点类型（即 isEdge 返回 false）时，该点处下一步行进的转弯角度。
TurnType	getTurnType() 返回该行驶导引子项为点类型（即 isEdge 返回 false）时，该点处下一步行进的转弯方向。
double	getWeight() 返回该行驶导引子项的权值，即行使导引对象子项的花费。
boolean	isEdge() 返回该行驶导引子项是线还是点类型。
boolean	isStop() 返回该行驶导引子项是否为站点，或站点被归结到网络上的对应点。

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

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

方法详细信息

getID

public int getID()

返回该行驶导引子项的 ID。

除以下三种情形外，该方法均返回 -1：

• 当行驶导引子项为结点模式下的站点时，站点为结点，返回该结点的结点 ID；
• 当行驶导引子项为转向点时，转向点为结点，返回该结点的结点 ID；
• 当行驶导引子项为路段时，返回路段对应的弧段的弧段 ID。如果该路段由多条弧段合并而成，则返回第一条弧段的 ID。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引子项的 ID。

getName

public java.lang.String getName()

返回该行驶导引子项的名称。

除以下两种情形外，该方法均返回空字符串：

• 当行驶导引子项为站点（结点模式）或转向点时，该值根据交通网络分析环境中指定的结点名称字段（setNodeNameField）的值给出，如未设置则为空字符串；
• 当行驶导引子项为路段或站点到网络的线段时，该值根据交通网络分析环境中指定的结点名称字段（setEdgeNameField）的值给出，如未设置则为空字符串。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引子项的名称。

getIndex

public int getIndex()

返回该行驶导引子项的序号。

除以下两种情形外，该方法均返回 -1：

• 当行驶导引子项为站点时，该值为该站点在所有站点中的序号，从 1 开始。例如某个站点是行驶路线经过的第 2 个站点，则此站点的 Index 值为 2；
• 当行驶导引子项为转向点时，该值为该点距离上一个转向点或站点的路口数。例如某个转向点之前的两个路口是最近的一个站点，则这个转向点的 Index 值为 2；当某个点同时为站点和转向点时，Index 为在整个行驶过程的所有站点中该站点的位置。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引对象子项的序号。

getWeight

public double getWeight()

返回该行驶导引子项的权值，即行使导引对象子项的花费。单位与交通网络分析参数（TransportationAnalystParameter）对象的 setWeightName 方法所指定的权值字段信息（WeightFieldInfo）对象的权值字段的单位相同。

当行驶导引子项为路段、转向点或结点模式下的站点时，得到的花费才有意义，否则均为 0.0。

• 当行驶导引子项为路段时，根据弧段权值和转向权值计算得出相应的花费。如果未设置转向表，则转向权值为 0；
• 当行驶导引子项为转向点或结点模式下的站点时（二者均为结点），为相应的转向权值。如果未设置转向表，则为 0.0。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引子项的权值。

getLength

public double getLength()

返回该行驶导引子项为线类型（即 isEdge 返回 true}）时，对应线段的长度。单位为米。

仅当 isEdge 返回 true 时，也就是行驶导引子项为路段或站点到网络的线段时，Length 有意义，否则均为 0.0。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引子项的长度。

getDistance

public double getDistance()

返回站点到网络的距离，仅当行驶导引子项为站点时有效。单位为米。

站点可能不在网络上（既不在弧段上也不在结点上），必须将站点归结到网络上，才能基于网络进行分析。该距离是指站点到最近一条弧段的距离。如下图所示，桔色点代表网络结点，蓝色代表弧段，灰色点为站点，红色线段代表距离。

当行驶导引子项是站点以外的其他类型时，该值为 0.0。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

站点到网络的距离。

getDirectionType

public DirectionType getDirectionType()

返回该行驶导引子项的行驶方向，仅当行驶导引子项为线类型（即 isEdge 返回 true）时有意义，可以为东、南、西、北。

当 isEdge 返回 false 时，该方法返回 NONE，即无方向。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引子项的行驶方向。

getTurnType

public TurnType getTurnType()

返回该行驶导引子项为点类型（即 isEdge 返回 false）时，该点处下一步行进的转弯方向。

当 isEdge 返回 true 时，该方法返回 NONE。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引子项的转弯方向。

getSideType

public SideType getSideType()

返回该行驶导引子项为站点时，站点在道路的左侧、右侧还是在路上。

当行驶导引子项为站点以外的类型时，该方法返回 NONE。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

站点的道路的哪一侧。

getTurnAngle

public double getTurnAngle()

返回该行驶导引子项为点类型（即 isEdge 返回 false）时，该点处下一步行进的转弯角度。单位为度，精确到 0.1 度。 当 isEdge 返回 true 时，该方法返回 -1。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引子项的转弯角度。

isEdge

public boolean isEdge()

返回该行驶导引子项是线还是点类型。若为 true，表示为线类型，如站点到网络的线段、路段；若为 false，表示为点类型，如站点、转向点或站点被归结到网络上的对应点。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

一个布尔值指示该行驶导引子项是线还是点类型。true 代表该行驶导引子项为线类型，否则为点类型。

isStop

public boolean isStop()

返回该行驶导引子项是否为站点，或站点被归结到网络上的对应点。

当 isStop 返回 true 时，对应的行驶导引子项可能是站点，或当站点为坐标点时，被归结到网络上的对应点，具体介绍请参阅 PathGuideItem 类对行驶导引子项类型的介绍。

返回：

一个布尔值指示该行驶导引子项是否为站点或站点在网络上的对应点。true 代表该行驶导引子项为站点或站点在网络上的对应点，否则不是。

getBounds

public Rectangle2D getBounds()

返回该行驶导引子项的范围。仅当行驶导引子项为线类型（即 isEdge 返回 true）时，为线的最小外接矩形；为点类型（即 isEdge 返回 false）时，则为点本身。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引子项的范围。

getGuideLine

public GeoLine getGuideLine()

返回该行驶导引子项为线类型（即 isEdge 返回 true）时，对应的行驶导引线段。

当 isEdge 返回 false 时，该方法返回 null。

有关行驶导引子项的类型，请参阅 PathGuideItem 类的介绍。

返回：

行驶导引线段。