com.supermap.analyst.spatialanalyst

类 RasterClip

java.lang.Object

com.supermap.analyst.spatialanalyst.RasterClip

public class RasterClip
extends Object

栅格裁剪类。

对指定区域范围内的栅格/影像地图进行裁剪。

方法概要

限定符和类型	方法和说明
static void	addSteppedListener(SteppedListener l) 添加一个进度条事件（SteppedEvent）的监听器。
static Dataset	clip(Dataset sourceDataset, GeoRegion userRegion, boolean isClipInRegion, boolean isExactClip, Datasource targetDatasource, String targetDatasetName) 已过时。 此方法已废弃，请使用支持进度监听的新方法 RasterClip.clip(Dataset, GeoRegion, boolean, boolean, Datasource, String, SteppedListener...) 替换。
static Dataset	clip(Dataset sourceDataset, GeoRegion userRegion, boolean isClipInRegion, boolean isExactClip, Datasource targetDatasource, String targetDatasetName, SteppedListener... listeners) 对栅格或影像数据集进行裁剪，结果存储为一个新的栅格或影像数据集。
static boolean	clip(DatasetImage sourceDataset, GeoRegion userRegion, boolean isClipInRegion, String targetFileName, RasterClipFileType targetFileType) 对影像数据集进行裁剪，并输出为指定类型的文件。
static Dataset	clipDatasetRaster(Dataset sourceDataset, GeoRegion userRegion, boolean isClipInRegion, boolean isExactClip, Datasource targetDatasource, String targetDatasetName) 已过时。 此方法已废弃，使用clip()替代。 对栅格或影像数据集进行裁剪，结果存储为一个新的栅格或影像数据集。
static Dataset	eraseAndReplace(Dataset sourceDataset, GeoRegion userRegion, Datasource targetDatasource, String targetDatasetName, double replaceValue) 已过时。 此方法已废弃，请使用支持进度监听的新方法 RasterClip.eraseAndReplace(Dataset, GeoRegion, Datasource, String, double, SteppedListener...) 替换。
static Dataset	eraseAndReplace(Dataset sourceDataset, GeoRegion userRegion, Datasource targetDatasource, String targetDatasetName, double replaceValue, SteppedListener... listeners) 对栅格或影像数据集进行擦除与填充。
static void	removeSteppedListener(SteppedListener l) 移除一个进度条事件（SteppedEvent）的监听器。
static boolean	split(Dataset sourceDataset, GeoLine splitLine, Datasource targetDatasource, String targetLeftRasterName, String targetRightDatasetName) 已过时。 此方法已废弃，请使用支持进度监听的新方法 RasterClip.split(Dataset, GeoLine, Datasource, String, String, SteppedListener...) 替换。
static boolean	split(Dataset sourceDataset, GeoLine splitLine, Datasource targetDatasource, String targetLeftRasterName, String targetRightDatasetName, SteppedListener... listeners) 栅格切割，即根据给定的切割线将栅格数据集或影像数据集切割为两部分，分别存储为两个新的数据集。

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

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

方法详细资料

clipDatasetRaster

@Deprecated
public static Dataset clipDatasetRaster(Dataset sourceDataset,
                                                     GeoRegion userRegion,
                                                     boolean isClipInRegion,
                                                     boolean isExactClip,
                                                     Datasource targetDatasource,
                                                     String targetDatasetName)

已过时。 此方法已废弃，使用clip()替代。 对栅格或影像数据集进行裁剪，结果存储为一个新的栅格或影像数据集。

参数:

sourceDataset - 指定的要进行裁剪的数据集，支持栅格数据集和影像数据集。

userRegion - 指定的裁剪区域，可以为矩形、圆形、多边形等。

isClipInRegion - 指定是否对裁剪区内的数据集进行裁剪。若为 true，则对裁剪区域内的数据集进行裁剪，若为 false，则对裁剪区域外的数据集进行裁剪。

isExactClip - 指定是否使用精确裁剪。若为 true，表示使用精确裁剪对栅格或影像数据集进行裁剪。

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

targetDatasetName - 指定的存储结果数据集的名称。

返回:

裁剪的结果数据集。

eraseAndReplace

@Deprecated
public static Dataset eraseAndReplace(Dataset sourceDataset,
                                                   GeoRegion userRegion,
                                                   Datasource targetDatasource,
                                                   String targetDatasetName,
                                                   double replaceValue)

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

对栅格或影像数据集进行擦除与填充。即可以修改指定区域的栅格值。

参数:

sourceDataset - 指定的要进行裁剪的栅格或影像数据集。

userRegion - 指定的裁剪区域，可以为矩形、圆形、多边形等。

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

targetDatasetName - 指定的存储结果数据集的名称。

replaceValue - 被擦除区域的替换值。

返回:

裁剪的结果数据集。

eraseAndReplace

public static Dataset eraseAndReplace(Dataset sourceDataset,
                                      GeoRegion userRegion,
                                      Datasource targetDatasource,
                                      String targetDatasetName,
                                      double replaceValue,
                                      SteppedListener... listeners)

对栅格或影像数据集进行擦除与填充。即可以修改指定区域的栅格值。

参数:

sourceDataset - 指定的要进行裁剪的栅格或影像数据集。

userRegion - 指定的裁剪区域，可以为矩形、圆形、多边形等。

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

targetDatasetName - 指定的存储结果数据集的名称。

replaceValue - 被擦除区域的替换值。

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

返回:

裁剪的结果数据集。

clip

@Deprecated
public static Dataset clip(Dataset sourceDataset,
                                        GeoRegion userRegion,
                                        boolean isClipInRegion,
                                        boolean isExactClip,
                                        Datasource targetDatasource,
                                        String targetDatasetName)

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

对栅格或影像数据集进行裁剪，结果存储为一个新的栅格或影像数据集。

有时，我们的研究范围或者感兴趣区域较小，仅涉及当前栅格数据的一部分，这时可以对栅格数据进行裁剪，即通过一个 GeoRegion 对象作为裁剪区域对栅格数据进行裁剪，提取该区域内（外）的栅格数据生成一个新的数据集，此外，还可以选择进行精确裁剪或显示裁剪。

• 区域内与区域外裁剪

选择区域内裁剪，则被裁剪的栅格数据在裁剪区范围内的部分被保留到结果数据集中；相反，使用区域外裁剪，则保留不在裁剪区范围内的那部分数据到结果数据集中。



• 精确裁剪与显示裁剪

请结合下图来理解显示裁剪和精确裁剪的区别。注意，下图的示例采用的是区域内裁剪方式。



采用显示裁剪时，系统会按照像素分块的大小，对栅格或影像数据集进行裁剪。此时只有裁剪区域内的数据被保留，即如果裁剪区的边界没有恰好与单元格的边界重合，那么单元格将被分割，位于裁剪区的部分会保留下来；位于裁剪区域外，且在被裁剪的那部分栅格所在块的总范围内（即图 2 中灰色区域）的栅格仍有栅格值，但不显示。此种方式适用于大数据的裁剪。

采用精确裁剪时，系统在裁剪区域边界，会根据裁剪区域压盖的单元格的中心点的位置确定是否保留该单元格。如果使用区域内裁剪方式，单元格的中心点位于裁剪区内则保留，反之不保留。

参数:

sourceDataset - 指定的要进行裁剪的数据集，支持栅格数据集和影像数据集。

userRegion - 指定的裁剪区域，可以为矩形、圆形、多边形等。

isClipInRegion - 指定是否对裁剪区内的数据集进行裁剪。若为 true，则对裁剪区域内的数据集进行裁剪，若为 false，则对裁剪区域外的数据集进行裁剪。

isExactClip - 指定是否使用精确裁剪。若为 true，表示使用精确裁剪对栅格或影像数据集进行裁剪，false 表示使用显示裁剪。详见备注部分。

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

targetDatasetName - 指定的存储结果数据集的名称。

返回:

裁剪的结果数据集。

clip

public static Dataset clip(Dataset sourceDataset,
                           GeoRegion userRegion,
                           boolean isClipInRegion,
                           boolean isExactClip,
                           Datasource targetDatasource,
                           String targetDatasetName,
                           SteppedListener... listeners)

对栅格或影像数据集进行裁剪，结果存储为一个新的栅格或影像数据集。

有时，我们的研究范围或者感兴趣区域较小，仅涉及当前栅格数据的一部分，这时可以对栅格数据进行裁剪，即通过一个 GeoRegion 对象作为裁剪区域对栅格数据进行裁剪，提取该区域内（外）的栅格数据生成一个新的数据集，此外，还可以选择进行精确裁剪或显示裁剪。

• 区域内与区域外裁剪

选择区域内裁剪，则被裁剪的栅格数据在裁剪区范围内的部分被保留到结果数据集中；相反，使用区域外裁剪，则保留不在裁剪区范围内的那部分数据到结果数据集中。



• 精确裁剪与显示裁剪

请结合下图来理解显示裁剪和精确裁剪的区别。注意，下图的示例采用的是区域内裁剪方式。



采用显示裁剪时，系统会按照像素分块的大小，对栅格或影像数据集进行裁剪。此时只有裁剪区域内的数据被保留，即如果裁剪区的边界没有恰好与单元格的边界重合，那么单元格将被分割，位于裁剪区的部分会保留下来；位于裁剪区域外，且在被裁剪的那部分栅格所在块的总范围内（即图 2 中灰色区域）的栅格仍有栅格值，但不显示。此种方式适用于大数据的裁剪。

采用精确裁剪时，系统在裁剪区域边界，会根据裁剪区域压盖的单元格的中心点的位置确定是否保留该单元格。如果使用区域内裁剪方式，单元格的中心点位于裁剪区内则保留，反之不保留。

参数:

sourceDataset - 指定的要进行裁剪的数据集，支持栅格数据集和影像数据集。

userRegion - 指定的裁剪区域，可以为矩形、圆形、多边形等。

isClipInRegion - 指定是否对裁剪区内的数据集进行裁剪。若为 true，则对裁剪区域内的数据集进行裁剪，若为 false，则对裁剪区域外的数据集进行裁剪。

isExactClip - 指定是否使用精确裁剪。若为 true，表示使用精确裁剪对栅格或影像数据集进行裁剪，false 表示使用显示裁剪。详见备注部分。

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

targetDatasetName - 指定的存储结果数据集的名称。

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

返回:

裁剪的结果数据集。

clip

public static boolean clip(DatasetImage sourceDataset,
                           GeoRegion userRegion,
                           boolean isClipInRegion,
                           String targetFileName,
                           RasterClipFileType targetFileType)

对影像数据集进行裁剪，并输出为指定类型的文件。目前只支持将裁剪结果并输出为 TIF 格式的文件。

参数:

sourceDataset - 指定的要进行裁剪的影像数据集。

userRegion - 指定的裁剪区域，可以为矩形、圆形、多边形等。

isClipInRegion - 指定是否对裁剪区内的数据集进行裁剪。若为 true，则对裁剪区域内的数据集进行裁剪，若为 false，则对裁剪区域外的数据集进行裁剪。

targetFileName - 指定的输出文件路径和名称。

targetFileType - 指定的输出文件类型。目前仅支持输出为 TIF 格式文件，即只当指定为 RasterClipFileType.TIF 时有效。

返回:

一个布尔值，代表裁剪是否成功。如果成功，返回 true，否则返回 false。

split

@Deprecated
public static boolean split(Dataset sourceDataset,
                                         GeoLine splitLine,
                                         Datasource targetDatasource,
                                         String targetLeftRasterName,
                                         String targetRightDatasetName)

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

栅格切割，即根据给定的切割线将栅格数据集或影像数据集切割为两部分，分别存储为两个新的数据集。

当需要将已有栅格数据的一部分作为研究范围，且希望保持原有栅格数据的空间范围时，可以对栅格进行切割。

栅格切割功能根据给定的一条二维线（称为“切割线”）对栅格（影像）数据集进行切割，切割的结果为两个新的栅格（影像）数据集，分别为切割线左侧和右侧的部分。切割线可以是直线、折线或多边形等。

该方法通过判断每一个单元格是位于距离它最近的线段（注意不是线对象）的左侧还是右侧，将该单元格分配到左侧结果数据集或右侧结果数据集，因此对于自相交的线对象，切割的效果可能与预期不符。对于位于数据集范围内部的线对象，同样依据该方式来切割。左侧和右侧是指线段的节点序列方向的左侧和右侧。对于切割线所经过的那些单元格，与栅格裁剪中的“精确裁剪”方式相同，即如果单元格的中心点位于最近线段的左侧（或右侧），则该单元格分配到该侧。

值得注意的是，与栅格裁剪不同，栅格切割得到的两个结果数据集的空间范围与原栅格数据的空间范围一致，无数据的部分被赋予“无值”，而栅格裁剪的结果为一个数据集，并且空间范围即为裁剪出来的区域的范围，比原数据的范围要小。

下图为栅格切割的一个实例。

参数:

sourceDataset - 指定的待切割的数据集。支持栅格数据集和影像数据集。

splitLine - 指定的用于切割数据集的二维线。注意，不支持复杂线对象。

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

targetLeftRasterName - 指定的位于切割线左侧的结果数据集的名称。

targetRightDatasetName - 指定的位于切割线右侧的结果数据集的名称。

返回:

一个布尔值，代表是否切割成功。如果成功，返回 true，否则返回 false。

抛出:

IllegalArgumentException - 如果 sourceDataset 指定的数据集的类型为矢量

split

public static boolean split(Dataset sourceDataset,
                            GeoLine splitLine,
                            Datasource targetDatasource,
                            String targetLeftRasterName,
                            String targetRightDatasetName,
                            SteppedListener... listeners)

栅格切割，即根据给定的切割线将栅格数据集或影像数据集切割为两部分，分别存储为两个新的数据集。

当需要将已有栅格数据的一部分作为研究范围，且希望保持原有栅格数据的空间范围时，可以对栅格进行切割。

栅格切割功能根据给定的一条二维线（称为“切割线”）对栅格（影像）数据集进行切割，切割的结果为两个新的栅格（影像）数据集，分别为切割线左侧和右侧的部分。切割线可以是直线、折线或多边形等。

该方法通过判断每一个单元格是位于距离它最近的线段（注意不是线对象）的左侧还是右侧，将该单元格分配到左侧结果数据集或右侧结果数据集，因此对于自相交的线对象，切割的效果可能与预期不符。对于位于数据集范围内部的线对象，同样依据该方式来切割。左侧和右侧是指线段的节点序列方向的左侧和右侧。对于切割线所经过的那些单元格，与栅格裁剪中的“精确裁剪”方式相同，即如果单元格的中心点位于最近线段的左侧（或右侧），则该单元格分配到该侧。

值得注意的是，与栅格裁剪不同，栅格切割得到的两个结果数据集的空间范围与原栅格数据的空间范围一致，无数据的部分被赋予“无值”，而栅格裁剪的结果为一个数据集，并且空间范围即为裁剪出来的区域的范围，比原数据的范围要小。

下图为栅格切割的一个实例。

参数:

sourceDataset - 指定的待切割的数据集。支持栅格数据集和影像数据集。

splitLine - 指定的用于切割数据集的二维线。注意，不支持复杂线对象。

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

targetLeftRasterName - 指定的位于切割线左侧的结果数据集的名称。

targetRightDatasetName - 指定的位于切割线右侧的结果数据集的名称。

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

返回:

一个布尔值，代表是否切割成功。如果成功，返回 true，否则返回 false。

抛出:

IllegalArgumentException - 如果 sourceDataset 指定的数据集的类型为矢量

addSteppedListener

public static void addSteppedListener(SteppedListener l)

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

参数:

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

removeSteppedListener

public static void removeSteppedListener(SteppedListener l)

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

参数:

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