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 explicitisHighIncluded
argument is required. Since:
 2.5
 Author:
 Martin Desruisseaux (IRD)
 See Also:
GridEnvelope2D
, Serialized Form


Constructor Summary
Constructors Constructor Description 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 multidimensional grid envelope defined by aRaster
.GeneralGridEnvelope(RenderedImage image, int dimension)
Constructs multidimensional grid envelope defined by aRenderedImage
.GeneralGridEnvelope(Rectangle rect)
Constructs a 2D grid envelope defined by aRectangle
.GeneralGridEnvelope(Rectangle rect, int dimension)
Constructs a multidimensional grid envelope defined by aRectangle
.GeneralGridEnvelope(GridEnvelope envelope)
Creates a new grid envelope as a copy of the given one.GeneralGridEnvelope(Bounds envelope, PixelInCell anchor)
Casts the specified envelope into a grid envelope.GeneralGridEnvelope(Bounds envelope, PixelInCell anchor, boolean isHighIncluded)
Casts the specified envelope into a grid envelope.

Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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 aRectangle
with the same bounds as thisGeneralGridEnvelope
.String
toString()
Returns a string représentation of this grid envelope.



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 multidimensional grid envelope defined by aRectangle
. The two first dimensions are set to the [x .. x+width1] and [y .. y+height1] 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 andGridEnvelope
dimensions in ISO 19123 style providing that the user remember to add 1 to theGridEnvelope.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 aRectangle
. The 2 dimensions are set to the [x .. x+width1] and [y .. y+height1] inclusive ranges respectively.Notice that this method ensure interoperability between
Raster
dimensions in Java2D style andGridEnvelope
dimensions in ISO 19123 style providing that the user remember to add 1 to theGridEnvelope.getHigh(int)
values. Parameters:
rect
 The grid coordinates as a rectangle.

GeneralGridEnvelope
public GeneralGridEnvelope(Raster raster, int dimension)
Constructs multidimensional grid envelope defined by aRaster
. The two first dimensions are set to the [x .. x+width1] and [y .. y+height1] 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 andGridEnvelope
dimensions in ISO 19123 style providing that the user remember to add 1 to theGridEnvelope.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 multidimensional grid envelope defined by aRenderedImage
. The two first dimensions are set to the [x .. x+width1] and [y .. y+height1] 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 andGridEnvelope
dimensions in ISO 19123 style providing that the user remember to add 1 to theGridEnvelope.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(Bounds 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 noninclusive
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 ifanchor
isPixelInCell.CELL_CENTER
. Users who don't want such offset should specifyPixelInCell.CELL_CORNER
.The convention is specified as a
PixelInCell
code instead than the more detailedPixelOrientation
because the latter is restricted to the twodimensional 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 bePixelInCell.CELL_CENTER
for OGC convention (an offset of 0.5 will be added to every envelope coordinate values), orPixelInCell.CELL_CORNER
for Java2D/JAI convention (no offset will be added). Throws:
IllegalArgumentException
 Ifanchor
is not valid. See Also:
org.geotools.referencing.GeneralEnvelope#GeneralEnvelope(GridEnvelope, PixelInCell, org.geotools.api.referencing.operation.MathTransform, org.geotools.api.referencing.crs.CoordinateReferenceSystem)

GeneralGridEnvelope
public GeneralGridEnvelope(Bounds 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 convertingRectangle2D
toRectangle
). 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 ifanchor
isPixelInCell.CELL_CENTER
. Users who don't want such offset should specifyPixelInCell.CELL_CORNER
.The convention is specified as a
PixelInCell
code instead than the more detailedPixelOrientation
because the latter is restricted to the twodimensional 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 bePixelInCell.CELL_CENTER
for OGC convention (an offset of 0.5 will be added to every envelope coordinate values), orPixelInCell.CELL_CORNER
for Java2D/JAI convention (no offset will be added).isHighIncluded
true
if the envelope maximal values are inclusive, orfalse
if they are exclusive. This argument does not apply to minimal values, which are always inclusive. Throws:
IllegalArgumentException
 Ifanchor
is not valid. See Also:
org.geotools.referencing.GeneralEnvelope#GeneralEnvelope(GridEnvelope, PixelInCell, org.geotools.api.referencing.operation.MathTransform, org.geotools.api.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 thehigh
values are inclusive (as in ISO 19123 specification), orfalse
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. See Also:
getLow()
,getHigh()


Method Detail

getDimension
public int getDimension()
Returns the number of dimensions. Specified by:
getDimension
in interfaceGridEnvelope
 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 interfaceGridEnvelope
 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 interfaceGridEnvelope
 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 interfaceGridEnvelope
 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 interfaceGridEnvelope
 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 togetHigh(dimension)  getLow(dimension)
. Specified by:
getSpan
in interfaceGridEnvelope
 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 dimensionlower
and extending to dimensionupper1
inclusive. Thus the dimension of the sub grid envelope isupper  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 aRectangle
with the same bounds as thisGeneralGridEnvelope
. 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 twodimensional.

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 classObject

equals
public boolean equals(Object object)
Compares the specified object with this grid envelope for equality. Overrides:
equals
in classObject
 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 classObject

