org.geotools.coverage.processing.operation

Class Crop

Object

AbstractOperation

Operation2D

Crop

All Implemented Interfaces:

Serializable, Operation

public class Crop
extends Operation2D

The crop operation is responsible for selecting geographic subarea of the source coverage. The CoverageCrop operation does not merely wrap the JAI Crop operation but it goes beyond that as far as capabilities.

The key point is that the CoverageCrop operation aims to perform a spatial crop, i.e. cropping the underlying raster by providing a spatial Envelope (if the envelope is not 2D only the 2D part of it will be used). This means that, depending on the grid-to-world transformation existing for the raster we want to crop, the crop area in the raster space might not be a rectangle, hence JAI's crop may not suffice in order to shrink the raster area we would obtain. For this purpose this operation make use of either the JAI's Crop or Mosaic operations depending on the conditions in which we are working.

Meaning of the ROI_OPTIMISATION_TOLERANCE parameter
In general if the grid-to-world transform is a simple scale and translate using JAI's crop should suffice, but when the g2w transform contains rotations or skew then we need something more elaborate since a rectangle in model space may not map to a rectangle in raster space. We would still be able to crop using JAI's crop on this polygon bounds but, depending on how this rectangle is built, we would be highly inefficient. In order to overcome this problems we use a combination of JAI's crop and mosaic since the mosaic can be used to crop a raster using a general ROI instead of a simple rectangle. There is a negative effect though. Crop would not create a new raster but simply forwards requests back to the original one (it basically create a viewport on the source raster) while the mosaic operation creates a new raster. We try to address this trade-off by providing the parameter ROI_OPTIMISATION_TOLERANCE, which basically tells this operation "Use the mosaic operation only if the area that we would load with the Mosaic is strictly smaller then (ROI_OPTIMISATION_TOLERANCE)* A' where A' is the area of the polygon resulting from converting the crop area from the model space to the raster space.

ROI
By providing a ROI parameter, the coverage can be cropped by any set of polygons, even disjuncted ones. When the ROI is provided, the JAI's Mosaic operation will be used.
At least one between Envelope and ROI must be provided. If both of them are provided, the resulting area will be the intersection of them.
ROI geometries must be in the same CRS as the source coverage.
ROI must be any among a Polygon, a MultiPolygon, or a GeometryCollection of the two.

NOTE that in case we will use the Mosaic operation with a ROI, such a ROI will be added as a synthetic property to the resulting coverage. The key for this property will be GC_ROI and the type of the object Polygon.

Since:

2.3

Author:

Simone Giannecchini (GeoSolutions), Emanuele Tajariol (GeoSolutions)

See Also:

CropDescriptor, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static ParameterDescriptor<Envelope>	CROP_ENVELOPE The parameter descriptor used to pass this operation the envelope to use when doing the spatial crop.
static ParameterDescriptor<Geometry>	CROP_ROI The parameter descriptor used to pass this operation the polygons(s) to use when doing the spatial crop.
static ParameterDescriptor<double[]>	DEST_NODATA The parameter descriptor used to tell this operation to set destinationNoData
static double	EPS
static ParameterDescriptor<Boolean>	FORCE_MOSAIC The parameter descriptor used to tell this operation to force the usage of a mosaic by avoiding any kind of optimization
static ParameterDescriptor<Range>	NODATA The parameter descriptor used to tell this operation to check NoData
static String	PARAMNAME_DEST_NODATA
static String	PARAMNAME_ENVELOPE
static String	PARAMNAME_FORCEMOSAIC
static String	PARAMNAME_NODATA
static String	PARAMNAME_ROI
static String	PARAMNAME_ROITOLERANCE
static ParameterDescriptor<Double>	ROI_OPTIMISATION_TOLERANCE The parameter descriptor used to tell this operation to optimize the crop using a Mosaic in where the area of the image we would not load is smaller than ROI_OPTIMISATION_TOLERANCE*FULL_CROP.

Fields inherited from class Operation2D

PRIMARY_SOURCE_INDEX, SOURCE_0

Fields inherited from class AbstractOperation

descriptor

Constructor Summary

Constructors

Constructor and Description
Crop() Constructs a default "Crop" operation.

Method Summary

Modifier and Type	Method and Description
Coverage	doOperation(ParameterValueGroup parameters, Hints hints) Applies a crop operation to a coverage.
static Polygon	rectangleToPolygon(Rectangle rect) Converts the rectangle into a java.awt.Polygon.

Methods inherited from class Operation2D

extractSources, getFactory

Methods inherited from class AbstractOperation

equals, getDescription, getDocURL, getName, getNumSources, getParameters, getVendor, getVersion, hashCode, toString

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EPS

public static final double EPS

See Also:

Constant Field Values

PARAMNAME_ENVELOPE

public static final String PARAMNAME_ENVELOPE

See Also:

Constant Field Values

PARAMNAME_ROI

public static final String PARAMNAME_ROI

See Also:

Constant Field Values

PARAMNAME_ROITOLERANCE

public static final String PARAMNAME_ROITOLERANCE

See Also:

Constant Field Values

PARAMNAME_FORCEMOSAIC

public static final String PARAMNAME_FORCEMOSAIC

See Also:

Constant Field Values

PARAMNAME_NODATA

public static final String PARAMNAME_NODATA

See Also:

Constant Field Values

PARAMNAME_DEST_NODATA

public static final String PARAMNAME_DEST_NODATA

See Also:

Constant Field Values

CROP_ENVELOPE

public static final ParameterDescriptor<Envelope> CROP_ENVELOPE

The parameter descriptor used to pass this operation the envelope to use when doing the spatial crop.

CROP_ROI

public static final ParameterDescriptor<Geometry> CROP_ROI

The parameter descriptor used to pass this operation the polygons(s) to use when doing the spatial crop.

If set, the intersection of Envelope and ROI must not be empty. The final output area will contain area inside the Envelope AND the ROI.

The parameter shall be a Polygon instance, or a GeometryCollection holding Polygons

ROI_OPTIMISATION_TOLERANCE

public static final ParameterDescriptor<Double> ROI_OPTIMISATION_TOLERANCE

The parameter descriptor used to tell this operation to optimize the crop using a Mosaic in where the area of the image we would not load is smaller than ROI_OPTIMISATION_TOLERANCE*FULL_CROP.

FORCE_MOSAIC

public static final ParameterDescriptor<Boolean> FORCE_MOSAIC

The parameter descriptor used to tell this operation to force the usage of a mosaic by avoiding any kind of optimization

NODATA

public static final ParameterDescriptor<Range> NODATA

The parameter descriptor used to tell this operation to check NoData

DEST_NODATA

public static final ParameterDescriptor<double[]> DEST_NODATA

The parameter descriptor used to tell this operation to set destinationNoData

Constructor Detail

Crop

public Crop()

Constructs a default "Crop" operation.

Method Detail

doOperation

public Coverage doOperation(ParameterValueGroup parameters,
                            Hints hints)

Applies a crop operation to a coverage.

Specified by:

doOperation in class AbstractOperation

Parameters:

parameters - List of name value pairs for the parameters required for the operation.

hints - A set of rendering hints, or null if none. The DefaultProcessor may provides hints for the following keys: Hints.COORDINATE_OPERATION_FACTORY and Hints.JAI_INSTANCE.

Returns:

The result as a coverage.

See Also:

AbstractOperation.doOperation(org.opengis.parameter.ParameterValueGroup, org.geotools.util.factory.Hints)

rectangleToPolygon

public static Polygon rectangleToPolygon(Rectangle rect)

Converts the rectangle into a java.awt.Polygon.