com.supermap.analyst.spatialanalyst

类 DistanceAnalyst

java.lang.Object

com.supermap.analyst.spatialanalyst.DistanceAnalyst

public class DistanceAnalyst
extends Object

距离栅格分析类。

距离栅格分析的主要功能主要包含以下三个方面：

1. 生成距离栅格，以及相应的方向栅格和分配栅格；

2. 最短路径分析，该功能是在生成距离栅格的基础上进行分析；

3. 计算两点（源点和目标点）间的最短路径，包括最小耗费路径、最短表面距离路径。

基本概念

1. 源：感兴趣的研究对象或地物，如学校、道路或消防栓等。
2. 源数据集：包含源的数据集，可以为二维点、线、面数据集或栅格数据集。对于栅格数据集，要求除标识源以外的单元格为无值。
3. 距离：包括直线距离、耗费距离和表面距离。直线距离即欧氏距离，是每一个单元格到最近源的直线距离；耗费距离是根据单元格的某个或某几个属性因子的加权得到的实际到达最近源所需的耗费值；表面距离是根据表面栅格的高程值计算出的单元格到达最近源的实际表面距离。
4. 耗费栅格：计算最小耗费路径需要指定耗费栅格。耗费栅格用于确定经过每个单元格所需的成本。单元格的值表示经过此单元格时一个单位的耗费。例如一个表示不同地面环境中汽车前进阻力的耗费栅格，其栅格值代表经过该单元格时每前进1公里的阻力值，那么经过该单元格的总耗费为单位耗费值（即栅格值）乘以单元格大小。耗费栅格的单位可以是任何单位类型，如长度、时间、金钱等，也可以无单位，如重分级后的坡度、坡向、土地利用类型等。通常，一个实际研究涉及到的成本影响因素可能有多个，例如，规划一条新的道路，影响成本的因素可能包括修建的总长度、经过的地区的土地利用类型、坡度、距离人口聚集区的距离等，那么分析时，就需要对这些因素进行加权从而得到一个综合权重作为耗费数据。此外，需注意耗费并不能为负值。

生成距离栅格

生成距离栅格功能用于生成三种类型的距离栅格：

1. 直线距离栅格，以及对应的直线方向栅格和直线分配栅格。直线距离实际上可看作以长短作为耗费，是最简单的一种耗费，例如，翻越一座山的路程耗费较小，但如果考虑时间的耗费，则可能比绕行它的时间耗费要多。详细介绍请参阅 straightDistance 方法。
2. 耗费距离栅格，以及对应的耗费方向栅格和耗费分配栅格。详细介绍请参阅 costDistance 方法。
3. 表面距离栅格，以及对应的表面方向栅格和表面分配栅格。详细介绍请参阅 surfaceDistance 方法。

最短路径分析

最短路径分析是根据目标点数据以及通过“生成距离栅格”功能生成的距离栅格和方向栅格，来计算目标到达最近的源的最短路径。提供两个方法：

1. pathLine 方法：输入耗费距离栅格和耗费方向栅格，生成最小耗费路径；输入表面距离栅格和表面方向栅格，生成最短表面路径栅格。该方法计算出的最短路径为一个矢量线对象。
2. costPath 方法：根据耗费距离栅格和耗费方向栅格，生成最小耗费路径。该方法提供三种不同的计算方式，并返回一个栅格数据集作为最短路径的结果。

两点间的最短路径

提供两种两点间最短路径的计算：

1. 通过 costPathLine 方法依据耗费栅格计算两点间的最小耗费路径。
2. 通过 surfacePathLine 方法依据表面栅格计算两点间的最短表面距离路径。

方法概要

限定符和类型	方法和说明
static void	addSteppedListener(SteppedListener l) 添加一个进度条事件（SteppedEvent）的监听器。
static DistanceAnalystResult	costDistance(Dataset sourceDataset, DatasetGrid costGrid, Datasource targetDatasource, Datasource targetDirDatasource, Datasource targetAllocDatasource, String distanceGridName, String directionGridName, String allocationGridName, double cellSize, double maxDistance, SteppedListener... listeners) 耗费距离
static DistanceAnalystResult	costDistance(Dataset sourceDataset, DatasetGrid costGrid, Datasource targetDatasource, String distanceGridName, String directionGridName, String allocationGridName, double cellSize, double maxDistance) 已过时。 此方法已废弃，请使用支持进度监听的新方法 DistanceAnalyst.costDistance(Dataset, DatasetGrid, Datasource, String, String, String, double, double, SteppedListener...) 替换。
static DistanceAnalystResult	costDistance(Dataset sourceDataset, DatasetGrid costGrid, Datasource targetDatasource, String distanceGridName, String directionGridName, String allocationGridName, double cellSize, double maxDistance, SteppedListener... listeners) 耗费距离
static DistanceAnalystResult	costDistance(DistanceAnalystParameter parameter) 根据给定的参数，生成耗费距离栅格，以及耗费方向栅格和耗费分配栅格。
static DistanceAnalystResult	costDistance(DistanceAnalystParameter parameter, SteppedListener... listeners) 耗费距离
static DatasetGrid	costPath(Dataset sourceDataset, DatasetGrid distanceDataset, DatasetGrid directionDataset, ComputeType computeType, Datasource targetDatasource, String targetDatasetName) 根据耗费距离栅格和耗费方向栅格，分析从目标出发到达最近源的最短路径栅格。
static DatasetGrid	costPath(Dataset sourceDataset, DatasetGrid distanceDataset, DatasetGrid directionDataset, ComputeType computeType, Datasource targetDatasource, String targetDatasetName, SteppedListener... listeners) 计算最短路径
static CostPathLineResult	costPathLine(Point2D sourcePoint, Point2D targetPoint, DatasetGrid costGrid, SmoothMethod smoothMethod, int smoothDegree, Datasource targetDatasource, String targetDatasetName) 已过时。 此方法已废弃，请使用支持进度监听的新方法 DistanceAnalyst.costPathLine(Point2D, Point2D, DatasetGrid, SmoothMethod, int, Datasource, String, SteppedListener...) 替换。
static CostPathLineResult	costPathLine(Point2D sourcePoint, Point2D targetPoint, DatasetGrid costGrid, SmoothMethod smoothMethod, int smoothDegree, Datasource targetDatasource, String targetDatasetName, SteppedListener... listeners) 如下图所示，以对 DEM 栅格计算坡度后重分级的结果栅格作为耗费栅格，指定两点分别作为源点和目标点，进行两点间栅格最短路径分析，得到两点间的最少耗费路线： 根据给定的参数，计算指定源和目标点之间的最少耗费路径。
static PathLineResult	costPathLine(Point2D sourcePoint, Point2D targetPoint, DistanceAnalystParameter parameter) 根据给定的参数，计算源点和目标点之间的最小耗费路径（一个二维矢量线对象）。
static PathLineResult	costPathLine(Point2D sourcePoint, Point2D targetPoint, DistanceAnalystParameter parameter, SteppedListener... listeners) 计算2点间最短路径
static GridAnalystSetting	getAnalystSetting() 返回栅格分析环境设置。
static PathLineResult	pathLine(Point2D targetPoint, DatasetGrid distanceGrid, DatasetGrid directionGrid, SmoothMethod smoothMethod, int smoothDegree) 根据距离栅格和方向栅格，分析从目标点出发到达最近源的最短路径（一个二维矢量线对象）。
static void	removeSteppedListener(SteppedListener l) 移除一个进度条事件（SteppedEvent）的监听器。
static void	setAnalystSetting(GridAnalystSetting gridAnalystSetting) 设置栅格分析环境设置。
static DistanceAnalystResult	straightDistance(Dataset sourceDataset, Datasource targetDatasource, Datasource targetDirDatasource, Datasource targetAllocDatasource, String distanceGridName, String directionGridName, String allocationGridName, double cellSize, double maxDistance, SteppedListener... listeners) 直线距离
static DistanceAnalystResult	straightDistance(Dataset sourceDataset, Datasource targetDatasource, String distanceGridName, String directionGridName, String allocationGridName, double cellSize, double maxDistance) 已过时。 此方法已废弃，请使用支持进度监听的新方法 DistanceAnalyst.straightDistance(Dataset, Datasource, String, String, String, double, double, SteppedListener...) 替换。
static DistanceAnalystResult	straightDistance(Dataset sourceDataset, Datasource targetDatasource, String distanceGridName, String directionGridName, String allocationGridName, double cellSize, double maxDistance, SteppedListener... listeners) 直线距离
static DistanceAnalystResult	straightDistance(DistanceAnalystParameter parameter) 根据给定的参数，生成直线距离栅格，以及直线方向栅格和直线分配栅格。
static DistanceAnalystResult	straightDistance(DistanceAnalystParameter parameter, SteppedListener... listeners) 直线距离
static DistanceAnalystResult	surfaceDistance(DistanceAnalystParameter parameter) 根据给定的参数，生成表面距离栅格，以及表面方向栅格和表面分配栅格。
static DistanceAnalystResult	surfaceDistance(DistanceAnalystParameter parameter, SteppedListener... listeners) 表面距离
static PathLineResult	surfacePathLine(Point2D sourcePoint, Point2D targetPoint, DistanceAnalystParameter parameter) 根据给定的参数，计算源点和目标点之间的最短表面距离路径（一个二维矢量线对象）。
static PathLineResult	surfacePathLine(Point2D sourcePoint, Point2D targetPoint, DistanceAnalystParameter parameter, SteppedListener... listeners) 计算两点间表面最短路径

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

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

方法详细资料

getAnalystSetting

public static GridAnalystSetting getAnalystSetting()

返回栅格分析环境设置。

有关“栅格分析环境设置”请参见 GridAnalystSetting 类的介绍。

返回:

栅格分析环境设置。

setAnalystSetting

public static void setAnalystSetting(GridAnalystSetting gridAnalystSetting)

设置栅格分析环境设置。

有关“栅格分析环境设置”请参见 GridAnalystSetting 类的介绍。

参数:

gridAnalystSetting - 栅格分析环境设置。

straightDistance

public static DistanceAnalystResult straightDistance(Dataset sourceDataset,
                                                     Datasource targetDatasource,
                                                     String distanceGridName,
                                                     String directionGridName,
                                                     String allocationGridName,
                                                     double cellSize,
                                                     double maxDistance,
                                                     SteppedListener... listeners)

直线距离

参数:

sourceDataset - 感兴趣的资源点数据 可以为矢量和栅格

targetDatasource - 输出数据所在数据源。

distanceGridName - 输出距离数据集的名称。

directionGridName - 输出方向数据集的名称。

allocationGridName - 输出分配数据集的名称。

cellSize - 结果栅格的单元格大小

maxDistance - 指定到资源点的最大距离，《0表示无限制

listeners - 用于接收进度条事件的监听器。

返回:

直线距离分析结果

straightDistance

@Deprecated
public static DistanceAnalystResult straightDistance(Dataset sourceDataset,
                                                                  Datasource targetDatasource,
                                                                  String distanceGridName,
                                                                  String directionGridName,
                                                                  String allocationGridName,
                                                                  double cellSize,
                                                                  double maxDistance)

已过时。 此方法已废弃，请使用支持进度监听的新方法 DistanceAnalyst.straightDistance(Dataset, Datasource, String, String, String, double, double, SteppedListener...) 替换。

直线距离

参数:

sourceDataset - 感兴趣的资源点数据 可以为矢量和栅格

cellSize - 结果栅格的单元格大小

maxDistance - 指定到资源点的最大距离，《0表示无限制

targetDatasource - 输出数据所在数据源。

distanceGridName - 输出距离数据集的名称。

directionGridName - 输出方向数据集的名称。

allocationGridName - 输出分配数据集的名称。

返回:

直线距离分析结果

straightDistance

public static DistanceAnalystResult straightDistance(Dataset sourceDataset,
                                                     Datasource targetDatasource,
                                                     Datasource targetDirDatasource,
                                                     Datasource targetAllocDatasource,
                                                     String distanceGridName,
                                                     String directionGridName,
                                                     String allocationGridName,
                                                     double cellSize,
                                                     double maxDistance,
                                                     SteppedListener... listeners)

直线距离

参数:

sourceDataset - 感兴趣的资源点数据 可以为矢量和栅格

cellSize - 结果栅格的单元格大小

maxDistance - 指定到资源点的最大距离，《0表示无限制

targetDatasource - 输出数据所在数据源。

distanceGridName - 输出距离数据集的名称。

directionGridName - 输出方向数据集的名称。

allocationGridName - 输出分配数据集的名称。

listeners - 用于接收进度条事件的监听器。

返回:

直线距离分析结果

straightDistance

public static DistanceAnalystResult straightDistance(DistanceAnalystParameter parameter)

根据给定的参数，生成直线距离栅格，以及直线方向栅格和直线分配栅格。

该方法用于对源数据集生成相应的直线距离栅格、直线方向栅格（可选）和直线分配栅格（可选），三个结果数据集的区域范围与源数据集的范围一致。生成直线距离栅格的源数据可以是矢量数据（点、线、面），也可以是栅格数据。对于栅格数据，要求除标识源以外的单元格为无值。

• 直线距离栅格的值代表该单元格到最近的源的欧氏距离（即直线距离）。最近源是当前单元格到达所有源中直线距离最短的一个源。对于每个单元格，它的中心与源的中心相连的直线即为单元格到源的距离，计算的方法是通过二者形成的直角三角形的两条直角边来计算，因此直线距离的计算只与单元格大小（即分辨率）有关。下图为直线距离计算的示意图，其中源栅格的单元格大小（CellSize）为10。



那么第三行第三列的单元格到源的距离L为：



• 直线方向栅格的值表示该单元格到最近的源的方位角，单位为度。以正东方向为90度，正南为180度，正西为270度，正北为360度，顺时针方向旋转，范围为0-360度，并规定对应源的栅格值为0度。
• 直线分配栅格的值为单元格的最近源的值（源为栅格时，为最近源的栅格值；源为矢量对象时，为最近源的 SMID），因此从直线分配栅格中可以得知每个单元格的最近的源是哪个。

下图为生成直线距离的示意图。单元格大小均为2。

直线距离栅格通常用于分析经过的路线没有障碍或等同耗费的情况，例如，救援飞机飞往最近的医院时，空中没有障碍物，因此采用哪条路线的耗费均相同，此时通过直线距离栅格就可以确定从救援飞机所在地点到周围各医院的距离；根据直线分配栅格可以获知离救援飞机所在地点最近的医院；由直线方向栅格可以确定最近的医院在救援飞机所在地点的方位。

然而，在救援汽车开往最近医院的实例中，因为地表有各种类型的障碍物，采用不同的路线的耗费不尽相同，这时，就需要使用耗费距离栅格来进行分析。有关耗费距离栅格请参见 CostDistance 方法。

下图为生成直线距离栅格的一个实例，其中源数据集为点数据集，生成了直线距离栅格、直线方向栅格和直线分配栅格。

通过该方法生成直线距离栅格，以及直线方向栅格和直线分配栅格，需要通过距离栅格分析参数（DistanceAnalystParameter）对象设置相关的参数，需要设置哪些参数请参阅 DistanceAnalystParameter 类。

注意：当数据集的最小外接矩形（getBounds）为某些特殊情形时，结果数据集的 Bounds 按以下规则取值：

1. 当源数据集的 Bounds 的高和宽均为 0 （如只有一个矢量点）时，结果数据集的 Bounds 的高和宽，均取源数据集 Bounds 的左边界值（Left）和下边界值（Right）二者绝对值较小的一个。
2. 当源数据集的 Bounds 的高为 0 而宽不为 0 （如只有一条水平线）时，结果数据集的 Bounds 的高和宽，均等于源数据集 Bounds 的宽。
3. 当源数据集的 Bounds 的宽为 0 而高不为 0 （如只有一条竖直线）时，结果数据集的 Bounds 的高和宽，均等于源数据集 Bounds 的高。

参数:

parameter - 指定的距离栅格分析参数。

返回:

直线距离栅格分析的结果。

示范代码:

以下代码示范了如何生成直线距离栅格。

 private void straightDistanceByParameter(Dataset sourceDataset,
                Datasource targetDatasource) {
        //设置结果栅格数据集（分配栅格数据集、方向栅格数据集、距离栅格数据集）的名称
        //并检查数据源中是否已存在该数据集，如存在则删除
        if (targetDatasource.getDatasets().contains("allocationGrid")) {
                targetDatasource.getDatasets().delete("allocationGrid");
    }
        if (targetDatasource.getDatasets().contains("directionGrid")) {
                targetDatasource.getDatasets().delete("directionGrid");
    }
        if (targetDatasource.getDatasets().contains("distanceGrid")) {
                targetDatasource.getDatasets().delete("distanceGrid");
    }

        //设置栅格距离分析参数
        DistanceAnalystParameter parameter = new DistanceAnalystParameter();
        parameter.setCellSize(0.1);
        parameter.setMaxDistance(100.0);
        parameter.setSourceDataset(sourceDataset);
        parameter.setTargetDatasource(targetDatasource);
        parameter.setAllocationGridName("allocationGrid");
        parameter.setDirectionGridName("directionGrid");
        parameter.setDistanceGridName("distanceGrid");

        //调用straightDistance()方法进行栅格距离分析，并获得距离分析结果对象
        DistanceAnalystResult result = DistanceAnalyst.straightDistance(parameter);

        //从距离栅格分析结果对象中提取距离分析的结果数据集
        DatasetGrid allocationGrid = result.getAllocationDatasetGrid();
        DatasetGrid directionGrid = result.getDirectionDatasetGrid();
        DatasetGrid distanceGrid = result.getDistanceDatasetGrid();
 }
 

straightDistance

public static DistanceAnalystResult straightDistance(DistanceAnalystParameter parameter,
                                                     SteppedListener... listeners)

直线距离

参数:

parameter - 距离分析参数

返回:

直线距离分析结果

costDistance

@Deprecated
public static DistanceAnalystResult costDistance(Dataset sourceDataset,
                                                              DatasetGrid costGrid,
                                                              Datasource targetDatasource,
                                                              String distanceGridName,
                                                              String directionGridName,
                                                              String allocationGridName,
                                                              double cellSize,
                                                              double maxDistance)

已过时。 此方法已废弃，请使用支持进度监听的新方法 DistanceAnalyst.costDistance(Dataset, DatasetGrid, Datasource, String, String, String, double, double, SteppedListener...) 替换。

耗费距离

参数:

sourceDataset - 感兴趣的资源点数据 可以为矢量和栅格

costGrid - 耗费栅格

targetDatasource - 输出数据所在数据源。

distanceGridName - 输出距离数据集的名称。

directionGridName - 输出方向数据集的名称。

allocationGridName - 输出分配数据集的名称。

cellSize - 结果栅格的单元格大小

maxDistance - 指定到资源点的最大距离，《0表示无限制

返回:

耗费距离分析结果

costDistance

public static DistanceAnalystResult costDistance(Dataset sourceDataset,
                                                 DatasetGrid costGrid,
                                                 Datasource targetDatasource,
                                                 String distanceGridName,
                                                 String directionGridName,
                                                 String allocationGridName,
                                                 double cellSize,
                                                 double maxDistance,
                                                 SteppedListener... listeners)

耗费距离

参数:

sourceDataset - 感兴趣的资源点数据 可以为矢量和栅格

costGrid - 耗费栅格

targetDatasource - 输出数据所在数据源。

distanceGridName - 输出距离数据集的名称。

directionGridName - 输出方向数据集的名称。

allocationGridName - 输出分配数据集的名称。

cellSize - 结果栅格的单元格大小

maxDistance - 指定到资源点的最大距离，《0表示无限制

listeners - 用于接收进度条事件的监听器。

返回:

costDistance

public static DistanceAnalystResult costDistance(Dataset sourceDataset,
                                                 DatasetGrid costGrid,
                                                 Datasource targetDatasource,
                                                 Datasource targetDirDatasource,
                                                 Datasource targetAllocDatasource,
                                                 String distanceGridName,
                                                 String directionGridName,
                                                 String allocationGridName,
                                                 double cellSize,
                                                 double maxDistance,
                                                 SteppedListener... listeners)

耗费距离

参数:

sourceDataset - 感兴趣的资源点数据 可以为矢量和栅格

costGrid - 耗费栅格

targetDatasource - 输出距离数据集所在数据源。

targetDirDatasource - 输出方向数据集所在数据源。

targetAllocDatasource - 输出分配数据集所在数据源。

distanceGridName - 输出距离数据集的名称。

directionGridName - 输出方向数据集的名称。

allocationGridName - 输出分配数据集的名称。

cellSize - 结果栅格的单元格大小

maxDistance - 指定到资源点的最大距离，《0表示无限制

listeners - 用于接收进度条事件的监听器。

返回:

costDistance

public static DistanceAnalystResult costDistance(DistanceAnalystParameter parameter)

根据给定的参数，生成耗费距离栅格，以及耗费方向栅格和耗费分配栅格。

实际应用中，直线距离往往不能满足要求。例如，从 B 到最近源 A 的直线距离与从 C 到最近源 A 的直线距离相同，若 BA 路段交通拥堵，而 CA 路段交通畅通，则其时间耗费必然不同；此外，通过直线距离对应的路径到达最近源时常常是不可行的，例如，遇到河流、高山等障碍物就需要绕行，这时就需要考虑其耗费距离。

该方法根据源数据集和耗费栅格生成相应的耗费距离栅格、耗费方向栅格（可选）和耗费分配栅格（可选）。源数据可以是矢量数据（点、线、面），也可以是栅格数据。对于栅格数据，要求除标识源以外的单元格为无值。关于耗费栅格请参阅 DistanceAnlayst 类。

• 耗费距离栅格的值表示该单元格到最近源的最小耗费值（可以是各种类型的耗费因子，也可以是各感兴趣的耗费因子的加权）。最近源是当前单元格到达所有的源中耗费最小的一个源。耗费栅格中为无值的单元格在输出的耗费距离栅格中仍为无值。

单元格到达源的耗费的计算方法是，从待计算单元格的中心出发，到达最近源的最小耗费路径在每个单元格上经过的距离乘以耗费栅格上对应单元格的值，将这些值累加即为单元格到源的耗费值。因此，耗费距离的计算与单元格大小和耗费栅格有关。在下面的示意图中，源栅格和耗费栅格的单元格大小（CellSize）均为2，单元格（2,1）到达源（0,0）的最小耗费路线如右图中红线所示：



那么单元格（2,1）到达源的最小耗费（即耗费距离）为：



• 耗费方向栅格的值表达的是从该单元格到达最近的源的最小耗费路径的行进方向。在耗费方向栅格中，可能的行进方向共有八个（正北、正南、正西、正东、西北、西南、东南、东北），使用1到8八个整数对这八个方向进行编码，如下图所示。注意，源所在的单元格在耗费方向栅格中的值为0，耗费栅格中为无值的单元格在输出的耗费方向栅格中将被赋值为15。



• 耗费分配栅格的值为单元格的最近源的值（源为栅格时，为最近源的栅格值；源为矢量对象时，为最近源的 SMID），单元格到达最近的源具有最小耗费距离。耗费栅格中为无值的单元格在输出的耗费分配栅格中仍为无值。

下图为生成耗费距离的示意图。其中，在耗费栅格上，使用蓝色箭头标识了单元格到达最近源的行进路线，耗费方向栅格的值即标示了当前单元格到达最近源的最小耗费路线的行进方向。

下图为生成耗费距离栅格的一个实例，其中源数据集为点数据集，耗费栅格为对应区域的坡度栅格的重分级结果，生成了耗费距离栅格、耗费方向栅格和耗费分配栅格。

通过该方法生成耗费距离栅格，以及耗费方向栅格和耗费分配栅格，需要通过距离栅格分析参数（DistanceAnalystParameter）对象设置相关的参数，需要设置哪些参数请参阅 DistanceAnalystParameter 类。

参数:

parameter - 指定的耗费距离栅格分析参数。

返回:

耗费距离栅格分析的结果。

示范代码:

以下代码示范了如何生成耗费距离栅格。本示例中使用的耗费栅格是将栅格数据集生成坡度图后重分级的结果。

 private void costDistanceByParameter(Dataset sourceDataset,
                DatasetGrid costGrid, Datasource targetDatasource) {
        //设置结果栅格数据集（分配栅格数据集、方向栅格数据集、距离栅格数据集）的名称
        //并检查数据源中是否已存在该数据集，如存在则删除
        if (targetDatasource.getDatasets().contains("costAllocationGrid")) {
                targetDatasource.getDatasets().delete("costAllocationGrid");
    }
        if (targetDatasource.getDatasets().contains("costDirectionGrid")) {
                targetDatasource.getDatasets().delete("costDirectionGrid");
    }
        if (targetDatasource.getDatasets().contains("costDistanceGrid")) {
                targetDatasource.getDatasets().delete("costDistanceGrid");
    }

        //设置耗费距离栅格分析参数
        DistanceAnalystParameter parameter = new DistanceAnalystParameter();
        parameter.setSourceDataset(sourceDataset);
        parameter.setCostGrid(costGrid);
        parameter.setTargetDatasource(targetDatasource);
        parameter.setAllocationGridName("costAllocationGrid");
        parameter.setDirectionGridName("costDirectionGrid");
        parameter.setDistanceGridName("costDistanceGrid");
        parameter.setMaxDistance(100.0);
        parameter.setCellSize(0.1);

        //调用costDistance()方法进行栅格距离分析，并获得距离分析结果对象
        DistanceAnalystResult result = DistanceAnalyst.costDistance(parameter);

        //从耗费距离栅格分析结果对象中提取耗费距离栅格分析的结果数据集
        DatasetGrid allocationGrid = result.getAllocationDatasetGrid();
        DatasetGrid directionGrid = result.getDirectionDatasetGrid();
        DatasetGrid distanceGrid = result.getDistanceDatasetGrid();
 }
 

costDistance

public static DistanceAnalystResult costDistance(DistanceAnalystParameter parameter,
                                                 SteppedListener... listeners)

耗费距离

参数:

parameter - 距离分析参数

返回:

耗费距离分析结果

surfaceDistance

public static DistanceAnalystResult surfaceDistance(DistanceAnalystParameter parameter)

根据给定的参数，生成表面距离栅格，以及表面方向栅格和表面分配栅格。

该方法根据源数据集和表面栅格生成相应的表面距离栅格、表面方向栅格（可选）和表面分配栅格（可选）。源数据可以是矢量数据（点、线、面），也可以是栅格数据。对于栅格数据，要求除标识源以外的单元格为无值。

• 表面距离栅格的值表示表面栅格上该单元格到最近源的表面最短距离。最近源是指当前单元格到达所有的源中表面距离最短的一个源。表面栅格中为无值的单元格在输出的表面距离栅格中仍为无值。

从当前单元格（设为 g1）到达下一个单元格（设为 g2）的表面距离 d 的计算方法为：



其中，b 为 g1 的栅格值（即高程）与 g2 的栅格值的差；a 为 g1 与 g2 的中心点之间的直线距离，其值考虑两种情况，当 g2 是与 g1 相邻的上、下、左、右四个单元格之一时，a 的值等于单元格大小；当 g2 是与 g1 对角相邻的四个单元格之一时，a 的值为单元格大小乘以根号 2。

当前单元格到达最近源的距离值就是沿着最短路径的表面距离值。在下面的示意图中，源栅格和表面栅格的单元格大小（CellSize）均为 1，单元格（2,1）到达源（0,0）的表面最短路径如右图中红线所示：



那么单元格（2,1）到达源的最短表面距离为：



• 表面方向栅格的值表达的是从该单元格到达最近源的最短表面距离路径的行进方向。在表面方向栅格中，可能的行进方向共有八个（正北、正南、正西、正东、西北、西南、东南、东北），使用 1 到 8 八个整数对这八个方向进行编码，如下图所示。注意，源所在的单元格在表面方向栅格中的值为 0，表面栅格中为无值的单元格在输出的表面方向栅格中将被赋值为 15。



• 表面分配栅格的值为单元格的最近源的值（源为栅格时，为最近源的栅格值；源为矢量对象时，为最近源的 SMID），单元格到达最近的源具有最短表面距离。表面栅格中为无值的单元格在输出的表面分配栅格中仍为无值。

下图为生成表面距离的示意图。其中，在表面栅格上，根据结果表面方向栅格，使用蓝色箭头标识了单元格到达最近源的行进方向。

通过上面的介绍，可以了解到，结合表面距离栅格及对应的方向、分配栅格，可以知道表面栅格上每个单元格最近的源是哪个，表面距离是多少以及如何到达该最近源。

通过该方法生成表面距离栅格，以及表面方向栅格和表面分配栅格，需要通过距离栅格分析参数（DistanceAnalystParameter）对象设置相关的参数，需要设置哪些参数请参阅 DistanceAnalystParameter 类。

注意，生成表面距离时可以指定最大上坡角度（setMaxUpslopeDegree）和最大下坡角度（setMaxDownslopeDegree），从而在寻找最近源时避免经过上下坡角度超过指定值的单元格。从当前单元格行进到下一个高程更高的单元格为上坡，上坡角度即上坡方向与水平面的夹角，如果上坡角度大于给定值，则不会考虑此行进方向；从当前单元格行进到下一个高程小于当前高程的单元格为下坡，下坡角度即下坡方向与水平面的夹角，同样的，如果下坡角度大于给定值，则不会考虑此行进方向。如果由于上下坡角度限制，使得当前单元格没能找到最近源，那么在表面距离栅格中该单元格的值为无值，在方向栅格和分配栅格中也为无值。

下图为生成表面距离栅格的一个实例，其中源数据集为点数据集，表面栅格为对应区域的 DEM 栅格，生成了表面距离栅格、表面方向栅格和表面分配栅格。

参数:

parameter - 指定的距离栅格分析参数。

返回:

表面距离栅格分析的结果。

surfaceDistance

public static DistanceAnalystResult surfaceDistance(DistanceAnalystParameter parameter,
                                                    SteppedListener... listeners)

表面距离

参数:

parameter - 距离分析参数

返回:

表面距离分析结果

costPath

public static DatasetGrid costPath(Dataset sourceDataset,
                                   DatasetGrid distanceDataset,
                                   DatasetGrid directionDataset,
                                   ComputeType computeType,
                                   Datasource targetDatasource,
                                   String targetDatasetName)

根据耗费距离栅格和耗费方向栅格，分析从目标出发到达最近源的最短路径栅格。

该方法根据给定的目标数据集，以及通过“生成耗费距离栅格”功能得到的耗费距离栅格和耗费方向栅格，来计算每个目标对象到达最近的源的最短路径，也就是最小耗费路径。该方法不需要指定源所在的数据集，因为源的位置在距离栅格和方向栅格中能够体现出来，即栅格值为 0 的单元格。生成的最短路径栅格是一个二值栅格，值为 1 的单元格表示路径，其他单元格的值为 0。

例如，将购物商场（一个点数据集）作为源，各居民小区（一个面数据集）作为目标，分析从各居民小区出发，如何到达距其最近的购物商场。实现的过程是，首先针对源（购物商场）生成距离栅格和方向栅格，然后将居民小区作为目标区域，通过最短路径分析，得到各居民小区（目标）到最近购物商场（源）的最短路径。该最短路径包含两种含义：通过直线距离栅格与直线方向栅格，将得到最小直线距离路径；通过耗费距离栅格与耗费方向栅格，则得到最小耗费路径。

注意，该方法中要求输入的耗费距离栅格和耗费方向栅格必须是匹配的，也就是说二者应是同一次使用“生成耗费距离栅格”功能生成的。此外，有三种计算最短路径的方式：像元路径、区域路径和单一路径，具体含义请参见 ComputeType 类。

参数:

sourceDataset - 指定的目标所在的数据集。可以为点、线、面或栅格数据集。如果是栅格数据，要求除标识目标以外的单元格为无值。

distanceDataset - 指定的耗费距离栅格数据集。

directionDataset - 指定的耗费方向栅格数据集。

computeType - 指定的栅格距离最短路径分析的计算方式。

targetDatasource - 指定的用于存储结果数据集的数据源。

targetDatasetName - 指定的结果最短路径所在的数据集的名称。

返回:

最短路径结果数据集，为栅格数据集。

示范代码:

以下代码示范了如何实现距离栅格最短路径分析，并返回结果栅格数据集。

 private DatasetGrid costPathAnalyst(Dataset sourceDataset,
                DatasetGrid distanceDataset, DatasetGrid directionDataset,
                Datasource targetDatasource) {
        //设置结果栅格数据集的名称，并检查数据源中是否已存在该数据集，如存在则删除
        String targetDatasetName = "costPathGrid";
        if (targetDatasource.getDatasets().contains(targetDatasetName)) {
                targetDatasource.getDatasets().delete(targetDatasetName);
    }

        //调用costPath()方法进行距离栅格最短路径分析，并获取结果栅格数据集
        DatasetGrid resultDatasetGrid = DistanceAnalyst.costPath(sourceDataset,
                        distanceDataset, directionDataset, ComputeType.CELL,
                        targetDatasource, targetDatasetName);

        return resultDatasetGrid;
 }
 

costPath

public static DatasetGrid costPath(Dataset sourceDataset,
                                   DatasetGrid distanceDataset,
                                   DatasetGrid directionDataset,
                                   ComputeType computeType,
                                   Datasource targetDatasource,
                                   String targetDatasetName,
                                   SteppedListener... listeners)

计算最短路径

参数:

sourceDataset - [in] 感兴趣的资源点数据 可以为矢量和栅格

distanceDataset - 距离栅格数据集

directionDataset - 方向栅格数据集

computeType - 路径计算方式

targetDatasource - 输出数据所在数据源。

targetDatasetName - 输出数据集的名称。

返回:

耗费距离分析结果

costPathLine

@Deprecated
public static CostPathLineResult costPathLine(Point2D sourcePoint,
                                                           Point2D targetPoint,
                                                           DatasetGrid costGrid,
                                                           SmoothMethod smoothMethod,
                                                           int smoothDegree,
                                                           Datasource targetDatasource,
                                                           String targetDatasetName)

已过时。 此方法已废弃，请使用支持进度监听的新方法 DistanceAnalyst.costPathLine(Point2D, Point2D, DatasetGrid, SmoothMethod, int, Datasource, String, SteppedListener...) 替换。

如下图所示，以对 DEM 栅格计算坡度后重分级的结果栅格作为耗费栅格，指定两点分别作为源点和目标点，进行两点间栅格最短路径分析，得到两点间的最少耗费路线：

根据给定的参数，计算指定源和目标点之间的最少耗费路径。

参数:

sourcePoint - 指定的源点。

targetPoint - 指定的目标点。

costGrid - 指定的耗费栅格。耗费栅格用于确定经过每个单元格所需的成本。详见 DistanceAnalyst 类的介绍。

smoothMethod - 指定的对最少耗费路径进行光滑处理所使用的光滑方法。

smoothDegree - 指定的光滑度。光滑度的取值与光滑方法有关，具体内容可参阅 ConversionAnalystParameter 类的 setSmoothDegree 方法。

targetDatasource - 指定的用于存储结果数据集的数据源。

targetDatasetName - 指定的最短耗费路径结果所在的数据集的名称。

返回:

最短路径分析结果。

示范代码:

以下代码示范了如何实现距离栅格最短路径分析。示例中通过指定源点、目标点以及耗费栅格，计算两点之间的最少耗费线路。

 private void costPathLineAnalyst(Point2D sourcePoint, Point2D targetPoint,
                DatasetGrid costGrid, Datasource targetDatasource) {
        //设置结果数据集的名称，并检查数据源中是否已存在该数据集，如存在则删除
        String targetDatasetName = "costPathLineDataset";
        if (targetDatasource.getDatasets().contains(targetDatasetName)) {
                targetDatasource.getDatasets().delete(targetDatasetName);
    }

        //调用costPathLine()方法进行距离栅格最短路径分析，并获取距离栅格最短路径分析结果对象
        CostPathLineResult result = DistanceAnalyst.costPathLine(sourcePoint,
                        targetPoint, costGrid, SmoothMethod.NONE, 0, targetDatasource,
                        targetDatasetName);

        //从距离栅格最短路径分析结果对象中提取结果
        double cost = result.getCost();
        DatasetVector costPathLineDataset = result.getCostPathLineDataset();
 }
 

costPathLine

public static CostPathLineResult costPathLine(Point2D sourcePoint,
                                              Point2D targetPoint,
                                              DatasetGrid costGrid,
                                              SmoothMethod smoothMethod,
                                              int smoothDegree,
                                              Datasource targetDatasource,
                                              String targetDatasetName,
                                              SteppedListener... listeners)

如下图所示，以对 DEM 栅格计算坡度后重分级的结果栅格作为耗费栅格，指定两点分别作为源点和目标点，进行两点间栅格最短路径分析，得到两点间的最少耗费路线：

根据给定的参数，计算指定源和目标点之间的最少耗费路径。

参数:

sourcePoint - 指定的源点。

targetPoint - 指定的目标点。

costGrid - 指定的耗费栅格。耗费栅格用于确定经过每个单元格所需的成本。详见 DistanceAnalyst 类的介绍。

smoothMethod - 指定的对最少耗费路径进行光滑处理所使用的光滑方法。

smoothDegree - 指定的光滑度。光滑度的取值与光滑方法有关，具体内容可参阅 ConversionAnalystParameter 类的 setSmoothDegree 方法。

targetDatasource - 指定的用于存储结果数据集的数据源。

targetDatasetName - 指定的最短耗费路径结果所在的数据集的名称。

listeners - 用于接收进度条事件的监听器。

返回:

最短路径分析结果。

示范代码:

以下代码示范了如何实现距离栅格最短路径分析。示例中通过指定源点、目标点以及耗费栅格，计算两点之间的最少耗费线路。

 private void costPathLineAnalyst(Point2D sourcePoint, Point2D targetPoint,
                DatasetGrid costGrid, Datasource targetDatasource) {
        //设置结果数据集的名称，并检查数据源中是否已存在该数据集，如存在则删除
        String targetDatasetName = "costPathLineDataset";
        if (targetDatasource.getDatasets().contains(targetDatasetName)) {
                targetDatasource.getDatasets().delete(targetDatasetName);
    }

        //调用costPathLine()方法进行距离栅格最短路径分析，并获取距离栅格最短路径分析结果对象
        CostPathLineResult result = DistanceAnalyst.costPathLine(sourcePoint,
                        targetPoint, costGrid, SmoothMethod.NONE, 0, targetDatasource,
                        targetDatasetName);

        //从距离栅格最短路径分析结果对象中提取结果
        double cost = result.getCost();
        DatasetVector costPathLineDataset = result.getCostPathLineDataset();
 }
 

costPathLine

public static PathLineResult costPathLine(Point2D sourcePoint,
                                          Point2D targetPoint,
                                          DistanceAnalystParameter parameter)

根据给定的参数，计算源点和目标点之间的最小耗费路径（一个二维矢量线对象）。

该方法用于根据给定的源点、目标点和耗费栅格，计算源点与目标点之间的最小耗费路径。除源点和目标点之外，耗费栅格及其他参数需要通过通过距离栅格分析参数（DistanceAnalystParameter）对象设置。需要设置哪些参数请参阅 DistanceAnalystParameter 类的介绍。有关耗费栅格，请参阅 DistanceAnalyst 类的相关介绍。

下图为计算两点间最小耗费路径的实例。该例以 DEM 栅格的坡度的重分级结果作为耗费栅格，分析给定的源点和目标点之间的最小耗费路径。

参数:

sourcePoint - 指定的源点。

targetPoint - 指定的目标点。

parameter - 指定的距离栅格分析参数。

返回:

最小耗费路径分析结果。

costPathLine

public static PathLineResult costPathLine(Point2D sourcePoint,
                                          Point2D targetPoint,
                                          DistanceAnalystParameter parameter,
                                          SteppedListener... listeners)

计算2点间最短路径

参数:

sourcePoint - 出发点坐标

targetPoint - 目标点坐标

parameter - 分析参数

surfacePathLine

public static PathLineResult surfacePathLine(Point2D sourcePoint,
                                             Point2D targetPoint,
                                             DistanceAnalystParameter parameter)

根据给定的参数，计算源点和目标点之间的最短表面距离路径（一个二维矢量线对象）。

该方法用于根据给定的源点、目标点和表面栅格，计算源点与目标点之间的最短表面距离路径。除源点和目标点之外，表面栅格及其他参数需要通过通过距离栅格分析参数（DistanceAnalystParameter）对象设置。需要设置哪些参数请参阅 DistanceAnalystParameter 类的介绍。

设置最大上坡角度（setMaxUpslopeDegree）和最大下坡角度（setMaxDownslopeDegree）可以使分析得出的路线不经过过于陡峭的地形。但注意，如果指定了上下坡角度限制，也可能得不到分析结果，这与最大上下坡角度的值和表面栅格所表达的地形有关。下图展示了将最大上坡角度和最大下坡角度分别均设置为 5 度、10 度和 90 度（即不限制上下坡角度）时的表面距离最短路径，由于对上下坡角度做出了限制，因此表面距离最短路径是以不超过最大上下坡角度为前提而得出的。

参数:

sourcePoint - 指定的源点。

targetPoint - 指定的目标点。

parameter - 指定的距离栅格分析参数。

返回:

最短路径分析结果。

surfacePathLine

public static PathLineResult surfacePathLine(Point2D sourcePoint,
                                             Point2D targetPoint,
                                             DistanceAnalystParameter parameter,
                                             SteppedListener... listeners)

计算两点间表面最短路径

参数:

sourcePoint - 出发点坐标

targetPoint - 目标点坐标

parameter - 分析参数

pathLine

public static PathLineResult pathLine(Point2D targetPoint,
                                      DatasetGrid distanceGrid,
                                      DatasetGrid directionGrid,
                                      SmoothMethod smoothMethod,
                                      int smoothDegree)

根据距离栅格和方向栅格，分析从目标点出发到达最近源的最短路径（一个二维矢量线对象）。

该方法根据距离栅格和方向栅格，分析给定的目标点到达最近源的最短路径。其中距离栅格和方向栅格可以是耗费距离栅格和耗费方向栅格，也可以是表面距离栅格和表面方向栅格。

• 当距离栅格为耗费距离栅格，方向栅格为耗费方向栅格时，该方法计算得出的是最小耗费路径。耗费距离栅格和耗费方向栅格可以通过 costDistance 方法生成。注意，此方法要求二者是同一次生成的结果。
• 当距离栅格为表面距离栅格，方向栅格为表面方向栅格时，该方法计算得出的是最短表面距离路径。表面距离栅格和表面方向栅格可以通过 surfaceDistance 方法生成。同样，此方法要求二者是同一次生成的结果。

源的位置在距离栅格和方向栅格中能够体现出来，即栅格值为 0 的单元格。源可以是一个，也可以有多个。当有多个源时，最短路径是目标点到达其最近的源的路径。

下图为源、表面栅格、耗费栅格和目标点，其中耗费栅格是对表面栅格计算坡度后重分级的结果。

使用如上图所示的源和表面栅格生成表面距离栅格和表面方向栅格，然后计算目标点到最近源的最短表面距离路径；使用源和耗费栅格生成耗费距离栅格和耗费方向栅格，然后计算目标点到最近源的最小耗费路径。得到的结果路径如下图所示：

参数:

targetPoint - 指定的目标点。

distanceGrid - 指定的距离栅格。可以是耗费距离栅格或表面距离栅格。

directionGrid - 指定的方向栅格。与距离栅格对应，可以是耗费方向栅格或表面方向栅格。

smoothMethod - 指定的对最短路径进行光滑处理所使用的光滑方法。

smoothDegree - 指定的光滑度。光滑度的取值与光滑方法有关，具体内容可参阅 ConversionAnalystParameter 类的 setSmoothDegree 方法。

返回:

最短路径分析结果。

addSteppedListener

public static void addSteppedListener(SteppedListener l)

添加一个进度条事件（SteppedEvent）的监听器。

参数:

l - 一个用于接收进度条事件的监听器。

removeSteppedListener

public static void removeSteppedListener(SteppedListener l)

移除一个进度条事件（SteppedEvent）的监听器。

参数:

l - 一个用于接收进度条事件的监听器。