Class GridEnvelope2D
 Object

 RectangularShape

 Rectangle2D

 Rectangle

 GridEnvelope2D

 All Implemented Interfaces:
Shape
,Serializable
,Cloneable
,GridEnvelope
,Cloneable
public class GridEnvelope2D extends Rectangle implements GridEnvelope, Cloneable
Defines a range of twodimensional grid coverage coordinates. This implementation extendsRectangle
for interoperability with Java2D. Note that at the opposite ofGeneralGridEnvelope
, this class is mutable.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. Since:
 2.5
 Author:
 Martin Desruisseaux
 See Also:
GeneralGridEnvelope
, Serialized Form


Nested Class Summary

Nested classes/interfaces inherited from class Rectangle2D
Rectangle2D.Double, Rectangle2D.Float


Field Summary

Fields inherited from class Rectangle2D
OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP


Constructor Summary
Constructors Constructor Description GridEnvelope2D()
Creates an initially empty grid envelope.GridEnvelope2D(int x, int y, int width, int height)
Creates a grid envelope initialized to the specified rectangle.GridEnvelope2D(Rectangle rectangle)
Creates a grid envelope initialized to the specified rectangle.GridEnvelope2D(Rectangle envelope, PixelInCell anchor)
Casts the specified envelope into a grid envelope.GridEnvelope2D(Rectangle envelope, PixelInCell anchor, boolean isHighIncluded)
Casts the specified envelope into a grid envelope.GridEnvelope2D(ReferencedEnvelope envelope, PixelInCell anchor)
Casts the specified envelope into a grid envelope.GridEnvelope2D(ReferencedEnvelope 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 GridEnvelope2D
clone()
Returns a clone of this grid envelope.int
getDimension()
Returns the number of dimensions, which is always 2.GridCoordinates2D
getHigh()
Returns the valid maximum inclusive grid coordinates.int
getHigh(int dimension)
Returns the valid maximum inclusive grid coordinate along the specified dimension.GridCoordinates2D
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.String
toString()
Returns a string représentation of this grid envelope.
Methods inherited from class Rectangle
add, add, add, contains, contains, contains, contains, createIntersection, createUnion, equals, getBounds, getBounds2D, getHeight, getLocation, getSize, getWidth, getX, getY, grow, inside, intersection, intersects, isEmpty, move, outcode, reshape, resize, setBounds, setBounds, setLocation, setLocation, setRect, setSize, setSize, translate, union

Methods inherited from class Rectangle2D
add, add, add, contains, contains, getPathIterator, getPathIterator, hashCode, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, setRect, union

Methods inherited from class RectangularShape
contains, contains, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal

Methods inherited from interface Shape
contains, contains, contains, contains, getPathIterator, getPathIterator, intersects, intersects




Constructor Detail

GridEnvelope2D
public GridEnvelope2D()
Creates an initially empty grid envelope.

GridEnvelope2D
public GridEnvelope2D(Rectangle rectangle)
Creates a grid envelope initialized to the specified rectangle. Parameters:
rectangle
 The rectangle to use for initializing this grid envelope.

GridEnvelope2D
public GridEnvelope2D(int x, int y, int width, int height)
Creates a grid envelope initialized to the specified rectangle. Parameters:
x
 The minimal x ordinate.y
 The minimal y ordinate.width
 The number of valid ordinates along the x axis.height
 The number of valid ordinates along the y axis.

GridEnvelope2D
public GridEnvelope2D(Rectangle 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.

GridEnvelope2D
public GridEnvelope2D(ReferencedEnvelope 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.

GridEnvelope2D
public GridEnvelope2D(Rectangle 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.

GridEnvelope2D
public GridEnvelope2D(ReferencedEnvelope 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.


Method Detail

getDimension
public final int getDimension()
Returns the number of dimensions, which is always 2. Specified by:
getDimension
in interfaceGridEnvelope
 Returns:
 The number of dimensions.

getLow
public GridCoordinates2D 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 GridCoordinates2D 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

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.

clone
public GridEnvelope2D clone()
Returns a clone of this grid envelope. Specified by:
clone
in interfaceCloneable
 Overrides:
clone
in classRectangularShape
 Returns:
 A clone of this grid envelope.
 See Also:
Object.clone()

