org.geotools.coverage.grid

Class GeneralGridEnvelope

Object

GeneralGridEnvelope

All Implemented Interfaces:

Serializable, GridEnvelope

public class GeneralGridEnvelope
extends Object
implements GridEnvelope, Serializable

Defines a range of grid coverage coordinates.

CAUTION: ISO 19123 defines high coordinates as inclusive. We follow this specification for all getters methods, but keep in mind that this is the opposite of Java2D usage where Rectangle maximal values are exclusive. When the context is ambiguous, an explicit isHighIncluded argument is required.

Since:

2.5

Author:

Martin Desruisseaux (IRD)

See Also:

GridEnvelope2D, Serialized Form

Constructor Summary

Constructors

Constructor and Description
GeneralGridEnvelope(Envelope envelope, PixelInCell anchor) Casts the specified envelope into a grid envelope.
GeneralGridEnvelope(Envelope envelope, PixelInCell anchor, boolean isHighIncluded) Casts the specified envelope into a grid envelope.
GeneralGridEnvelope(GridEnvelope envelope) Creates a new grid envelope as a copy of the given one.
GeneralGridEnvelope(int[] low, int[] high) Constructs a new grid envelope.
GeneralGridEnvelope(int[] low, int[] high, boolean isHighIncluded) Constructs a new grid envelope.
GeneralGridEnvelope(Raster raster, int dimension) Constructs multi-dimensional grid envelope defined by a Raster.
GeneralGridEnvelope(Rectangle rect) Constructs a 2D grid envelope defined by a Rectangle.
GeneralGridEnvelope(Rectangle rect, int dimension) Constructs a multi-dimensional grid envelope defined by a Rectangle.
GeneralGridEnvelope(RenderedImage image, int dimension) Constructs multi-dimensional grid envelope defined by a RenderedImage.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object object) Compares the specified object with this grid envelope for equality.
int	getDimension() Returns the number of dimensions.
GridCoordinates	getHigh() Returns the valid maximum inclusive grid coordinates.
int	getHigh(int dimension) Returns the valid maximum inclusive grid coordinate along the specified dimension.
GridCoordinates	getLow() Returns the valid minimum inclusive grid coordinates.
int	getLow(int dimension) Returns the valid minimum inclusive grid coordinate along the specified dimension.
int	getSpan(int dimension) Returns the number of integer grid coordinates along the specified dimension.
GeneralGridEnvelope	getSubGridEnvelope(int lower, int upper) Returns a new grid envelope that encompass only some dimensions of this grid envelope.
int	hashCode() Returns a hash value for this grid envelope.
Rectangle	toRectangle() Returns a Rectangle with the same bounds as this GeneralGridEnvelope.
String	toString() Returns a string représentation of this grid envelope.

Methods inherited from class Object

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

Constructor Detail

GeneralGridEnvelope

public GeneralGridEnvelope(GridEnvelope envelope)

Creates a new grid envelope as a copy of the given one.

Parameters:

envelope - The grid envelope to copy.

GeneralGridEnvelope

public GeneralGridEnvelope(Rectangle rect,
                           int dimension)

Constructs a multi-dimensional grid envelope defined by a Rectangle. The two first dimensions are set to the [x .. x+width-1] and [y .. y+height-1] inclusive ranges respectively. Extra dimensions (if any) are set to the [0..0] inclusive range.

Notice that this method ensure interoperability between Raster dimensions in Java2D style and GridEnvelope dimensions in ISO 19123 style providing that the user remember to add 1 to the GridEnvelope.getHigh(int) values.

Parameters:

rect - The grid coordinates as a rectangle.

dimension - Number of dimensions for this grid envelope. Must be equals or greater than 2.

GeneralGridEnvelope

public GeneralGridEnvelope(Rectangle rect)

Constructs a 2D grid envelope defined by a Rectangle. The 2 dimensions are set to the [x .. x+width-1] and [y .. y+height-1] inclusive ranges respectively.

Notice that this method ensure interoperability between Raster dimensions in Java2D style and GridEnvelope dimensions in ISO 19123 style providing that the user remember to add 1 to the GridEnvelope.getHigh(int) values.

Parameters:

rect - The grid coordinates as a rectangle.

GeneralGridEnvelope

public GeneralGridEnvelope(Raster raster,
                           int dimension)

Constructs multi-dimensional grid envelope defined by a Raster. The two first dimensions are set to the [x .. x+width-1] and [y .. y+height-1] inclusive ranges respectively. Extra dimensions (if any) are set to the [0..0] inclusive range.

Notice that this method ensure interoperability between Raster dimensions in Java2D style and GridEnvelope dimensions in ISO 19123 style providing that the user remember to add 1 to the GridEnvelope.getHigh(int) values.

Parameters:

raster - The raster for which to construct a grid envelope.

dimension - Number of dimensions for this grid envelope. Must be equals or greater than 2.

GeneralGridEnvelope

public GeneralGridEnvelope(RenderedImage image,
                           int dimension)

Constructs multi-dimensional grid envelope defined by a RenderedImage. The two first dimensions are set to the [x .. x+width-1] and [y .. y+height-1] inclusive ranges respectively. Extra dimensions (if any) are set to the [0..0] inclusive range.

Notice that this method ensure interoperability between Raster dimensions in Java2D style and GridEnvelope dimensions in ISO 19123 style providing that the user remember to add 1 to the GridEnvelope.getHigh(int) values.

Parameters:

image - The image for which to construct a grid envelope.

dimension - Number of dimensions for this grid envelope. Must be equals or greater than 2.

GeneralGridEnvelope

public GeneralGridEnvelope(Envelope envelope,
                           PixelInCell anchor)
                    throws IllegalArgumentException

Casts the specified envelope into a grid envelope. This is sometime useful after an envelope has been transformed from "real world" coordinates to grid coordinates using the grid to CRS transform. The floating point values are rounded toward the nearest integers.

Notice that highest values are interpreted as non-inclusive

Anchor
According OpenGIS specification, grid geometry maps pixel's center. But envelopes typically encompass all pixels. This means that grid coordinates (0,0) has an envelope starting at (-0.5, -0.5). In order to revert back such envelope to a grid envelope, it is necessary to add 0.5 to every coordinates (including the maximum value since it is exclusive in a grid envelope). This offset is applied only if anchor is PixelInCell.CELL_CENTER. Users who don't want such offset should specify PixelInCell.CELL_CORNER.

The convention is specified as a PixelInCell code instead than the more detailed PixelOrientation because the latter is restricted to the two-dimensional case while the former can be used for any number of dimensions.

Parameters:

envelope - The envelope to use for initializing this grid envelope.

anchor - Whatever envelope coordinates map to pixel center or pixel corner. Should be PixelInCell.CELL_CENTER for OGC convention (an offset of 0.5 will be added to every envelope coordinate values), or PixelInCell.CELL_CORNER for Java2D/JAI convention (no offset will be added).

Throws:

IllegalArgumentException - If anchor is not valid.

See Also:

org.geotools.referencing.GeneralEnvelope#GeneralEnvelope(GridEnvelope, PixelInCell, org.opengis.referencing.operation.MathTransform, org.opengis.referencing.crs.CoordinateReferenceSystem)

GeneralGridEnvelope

public GeneralGridEnvelope(Envelope envelope,
                           PixelInCell anchor,
                           boolean isHighIncluded)
                    throws IllegalArgumentException

Casts the specified envelope into a grid envelope. This is sometime useful after an envelope has been transformed from "real world" coordinates to grid coordinates using the grid to CRS transform. The floating point values are rounded toward the nearest integers.

Note about rounding mode
It would have been possible to round the minimal value toward floor and the maximal value toward ceil in order to make sure that the grid envelope encompass fully the envelope - like what Java2D does when converting Rectangle2D to Rectangle). But this approach may increase by 1 or 2 units the image width or height. For example the range [-0.25 ... 99.75] (which is exactly 101 units wide) would be casted to [-1 ... 100], which is 102 units wide. This leads to unexpected results when using grid envelope with image operations like "Affine". For avoiding such changes in size, it is necessary to use the same rounding mode for both minimal and maximal values. The selected rounding mode is nearest integer in this implementation.

Anchor
According OpenGIS specification, grid geometry maps pixel's center. But envelopes typically encompass all pixels. This means that grid coordinates (0,0) has an envelope starting at (-0.5, -0.5). In order to revert back such envelope to a grid envelope, it is necessary to add 0.5 to every coordinates (including the maximum value since it is exclusive in a grid envelope). This offset is applied only if anchor is PixelInCell.CELL_CENTER. Users who don't want such offset should specify PixelInCell.CELL_CORNER.

The convention is specified as a PixelInCell code instead than the more detailed PixelOrientation because the latter is restricted to the two-dimensional case while the former can be used for any number of dimensions.

Parameters:

envelope - The envelope to use for initializing this grid envelope.

anchor - Whatever envelope coordinates map to pixel center or pixel corner. Should be PixelInCell.CELL_CENTER for OGC convention (an offset of 0.5 will be added to every envelope coordinate values), or PixelInCell.CELL_CORNER for Java2D/JAI convention (no offset will be added).

isHighIncluded - true if the envelope maximal values are inclusive, or false if they are exclusive. This argument does not apply to minimal values, which are always inclusive.

Throws:

IllegalArgumentException - If anchor is not valid.

See Also:

org.geotools.referencing.GeneralEnvelope#GeneralEnvelope(GridEnvelope, PixelInCell, org.opengis.referencing.operation.MathTransform, org.opengis.referencing.crs.CoordinateReferenceSystem)

GeneralGridEnvelope

public GeneralGridEnvelope(int[] low,
                           int[] high,
                           boolean isHighIncluded)

Constructs a new grid envelope.

Parameters:

low - The valid minimum inclusive grid coordinate. The array contains a minimum value (inclusive) for each dimension of the grid coverage. The lowest valid grid coordinate is often zero, but this is not mandatory.

high - The valid maximum grid coordinate. The array contains a maximum value for each dimension of the grid coverage.

isHighIncluded - true if the high values are inclusive (as in ISO 19123 specification), or false if they are exclusive (as in Java usage). This argument does not apply to low values, which are always inclusive.

See Also:

getLow(), getHigh()

GeneralGridEnvelope

public GeneralGridEnvelope(int[] low,
                           int[] high)

Constructs a new grid envelope.

Notice that this constructor has been added for compatibility with JAVA2D, which means that the high coords are intepreted as EXCLUSIVE

Parameters:

low - The valid minimum inclusive grid coordinate. The array contains a minimum value (inclusive) for each dimension of the grid coverage. The lowest valid grid coordinate is often zero, but this is not mandatory.

high - The valid maximum grid coordinate. The array contains a maximum value for each dimension of the grid coverage.

isHighIncluded - true if the high values are inclusive (as in ISO 19123 specification), or false if they are exclusive (as in Java usage). This argument does not apply to low values, which are always inclusive.

See Also:

getLow(), getHigh()

Method Detail

getDimension

public int getDimension()

Returns the number of dimensions.

Specified by:

getDimension in interface GridEnvelope

Returns:

The number of dimensions.

getLow

public GridCoordinates getLow()

Returns the valid minimum inclusive grid coordinates. The sequence contains a minimum value for each dimension of the grid coverage.

Specified by:

getLow in interface GridEnvelope

Returns:

The minimal coordinate values for all grid points, inclusive.

getHigh

public GridCoordinates getHigh()

Returns the valid maximum inclusive grid coordinates. The sequence contains a maximum value for each dimension of the grid coverage.

Specified by:

getHigh in interface GridEnvelope

Returns:

The maximal coordinate values for all grid points, inclusive.

getLow

public int getLow(int dimension)

Returns the valid minimum inclusive grid coordinate along the specified dimension.

Specified by:

getLow in interface GridEnvelope

Parameters:

dimension - The dimension for which to obtain the coordinate value.

Returns:

The coordinate value at the given dimension, inclusive.

See Also:

getLow()

getHigh

public int getHigh(int dimension)

Returns the valid maximum inclusive grid coordinate along the specified dimension.

Specified by:

getHigh in interface GridEnvelope

Parameters:

dimension - The dimension for which to obtain the coordinate value.

Returns:

The coordinate value at the given dimension, inclusive.

See Also:

getHigh()

getSpan

public int getSpan(int dimension)

Returns the number of integer grid coordinates along the specified dimension. This is equals to getHigh(dimension) - getLow(dimension).

Specified by:

getSpan in interface GridEnvelope

Parameters:

dimension - The dimension for which to obtain the coordinate value.

Returns:

The coordinate value at the given dimension.

See Also:

Rectangle.width, Rectangle.height

getSubGridEnvelope

public GeneralGridEnvelope getSubGridEnvelope(int lower,
                                              int upper)
                                       throws IndexOutOfBoundsException

Returns a new grid envelope that encompass only some dimensions of this grid envelope. This method copies this grid range into a new grid envelope, beginning at dimension lower and extending to dimension upper-1 inclusive. Thus the dimension of the sub grid envelope is upper - lower.

Parameters:

lower - The first dimension to copy, inclusive.

upper - The last dimension to copy, exclusive.

Returns:

The sub grid envelope.

Throws:

IndexOutOfBoundsException - if an index is out of bounds.

toRectangle

public Rectangle toRectangle()
                      throws IllegalStateException

Returns a Rectangle with the same bounds as this GeneralGridEnvelope. This is a convenience method for interoperability with Java2D.

Returns:

A rectangle with the same bounds than this grid envelope.

Throws:

IllegalStateException - if this grid envelope is not two-dimensional.

hashCode

public int hashCode()

Returns a hash value for this grid envelope. This value need not remain consistent between different implementations of the same class.

Overrides:

hashCode in class Object

equals

public boolean equals(Object object)

Compares the specified object with this grid envelope for equality.

Overrides:

equals in class Object

Parameters:

object - The object to compare with this grid envelope for equality.

Returns:

true if the given object is equals to this grid envelope.

toString

public String toString()

Returns a string représentation of this grid envelope. The returned string is implementation dependent. It is usually provided for debugging purposes.

Overrides:

toString in class Object