Class GridGeometry2D
 Object

 GeneralGridGeometry

 GridGeometry2D

 All Implemented Interfaces:
Serializable
,GridGeometry
public class GridGeometry2D extends GeneralGridGeometry
Describes the valid range of grid coordinates and the math transform, in the special case where only 2 dimensions are in use. By "in use", we means dimension with more than 1 pixel. For example a grid size of 512×512×1 pixels can be represented by thisGridGeometry2D
class (some peoples said 2.5D) because a twodimensional grid coordinate is enough for referencing a pixel without ambiguity. But a grid size of 512×512×2 pixels can not be represented by thisGridGeometry2D
, because a threedimensional coordinate is mandatory for referencing a pixel without ambiguity. Since:
 2.1
 Author:
 Martin Desruisseaux (IRD)
 See Also:
ImageGeometry
,GeneralGridGeometry
, Serialized Form


Field Summary
Fields Modifier and Type Field Description int
axisDimensionX
The (gridDimensionX
,gridDimensionY
) dimensions in the envelope space.int
axisDimensionY
The (gridDimensionX
,gridDimensionY
) dimensions in the envelope space.int
gridDimensionX
Index of column (gridDimensionX
) and row (gridDimensionY
) ordinates in a grid point.int
gridDimensionY
Index of column (gridDimensionX
) and row (gridDimensionY
) ordinates in a grid point.
Fields inherited from class GeneralGridGeometry
CRS_BITMASK, ENVELOPE_BITMASK, GRID_RANGE_BITMASK, GRID_TO_CRS_BITMASK, gridRange, gridToCRS


Constructor Summary
Constructors Constructor Description GridGeometry2D(Rectangle gridRange, Rectangle2D userRange)
Constructs a new twodimensional grid geometry using java.awt objects.GridGeometry2D(GridEnvelope gridRange, Bounds userRange)
Constructs a new grid geometry from an envelope.GridGeometry2D(GridEnvelope gridRange, PixelOrientation anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs, Hints hints)
Constructs a new grid geometry from a math transform.GridGeometry2D(GridEnvelope gridRange, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs, Hints hints)
Constructs a new grid geometry from a math transform.GridGeometry2D(GridEnvelope gridRange, MathTransform gridToCRS, CoordinateReferenceSystem crs)
Constructs a new grid geometry from a grid range and a math transform.GridGeometry2D(GridGeometry other)
Creates a new grid geometry with the same values than the given grid geometry.GridGeometry2D(PixelInCell anchor, MathTransform gridToCRS, Bounds envelope, Hints hints)
Constructs a new grid geometry from an envelope and a math transform.

Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
equals(Object object)
Compares the specified object with this grid geometry for equality.CoordinateReferenceSystem
getCoordinateReferenceSystem2D()
Returns the twodimensional part of this grid geometry CRS.MathTransform2D
getCRSToGrid2D()
Returns a math transform for the two dimensional part for conversion from world to grid coordinates.MathTransform2D
getCRSToGrid2D(PixelOrientation orientation)
Returns a math transform for the two dimensional part.ReferencedEnvelope
getEnvelope2D()
Returns the twodimensional bounding box for the coverage domain in coordinate reference system coordinates.GridEnvelope2D
getGridRange2D()
Returns the twodimensional part of the grid range as a rectangle.MathTransform
getGridToCRS(PixelOrientation orientation)
Returns a math transform mapping the specified pixel part.MathTransform2D
getGridToCRS2D()
Returns a math transform for the two dimensional part.MathTransform2D
getGridToCRS2D(PixelOrientation orientation)
Returns a math transform for the two dimensional part.Position
gridToWorld(GridCoordinates2D point)
Transforms a point represented by a GridCoordinates2D object from grid to world coordinates.ReferencedEnvelope
gridToWorld(GridEnvelope2D gridEnv)
Transforms an represented by a GridEnvelope2D object from grid to world coordinates.int
hashCode()
Returns a hash value for this grid geometry.ReferencedEnvelope
reduce(Bounds bounds)
Reduces the specified bounds to a twodimensional ReferencedEnvelope.CoordinateReferenceSystem
reduce(CoordinateReferenceSystem crs)
Reduces the specified CRS to a twodimensional one.GridGeometry2D
toCanonical()
Returns a "canonical" representation of the grid geometry, that is, one whose grid range originates in 0,0, but maps to the same real world coordinates.GridEnvelope2D
worldToGrid(BoundingBox envelope)
Transforms a rectangle represented by an Envelope2D object from world to grid coordinates.GridCoordinates2D
worldToGrid(Position point)
Transforms a point represented by a DirectPosition object from world to grid coordinates.GridEnvelope2D
worldToGrid(ReferencedEnvelope envelope)
Transforms a rectangle represented by an ReferencedEnvelope (or BoundingBox) from world to grid coordinates.static GridGeometry2D
wrap(GridGeometry other)
Returns the given grid geometry as aGridGeometry2D
.
Methods inherited from class GeneralGridGeometry
getCoordinateReferenceSystem, getDimension, getEnvelope, getGridRange, getGridToCRS, getGridToCRS, isDefined, toString




Field Detail

gridDimensionX
public final int gridDimensionX
Index of column (gridDimensionX
) and row (gridDimensionY
) ordinates in a grid point. They are the index of the first two dimensions with a span greater than 1 in the grid range. Their values are usually 0 and 1 respectively.It is garanteed that
gridDimensionX
<gridDimensionY
.

gridDimensionY
public final int gridDimensionY
Index of column (gridDimensionX
) and row (gridDimensionY
) ordinates in a grid point. They are the index of the first two dimensions with a span greater than 1 in the grid range. Their values are usually 0 and 1 respectively.It is garanteed that
gridDimensionX
<gridDimensionY
.

axisDimensionX
public final int axisDimensionX
The (gridDimensionX
,gridDimensionY
) dimensions in the envelope space. They are index of (x, y) ordinates in a direct position after the grid to CRS transform.There is no garantee that
gridDimensionX
maps toaxisDimensionX
andgridDimensionY
maps toaxisDimensionY
, since axis may be interchanged.It is garanteed that
axisDimensionX
<axisDimensionY
.

axisDimensionY
public final int axisDimensionY
The (gridDimensionX
,gridDimensionY
) dimensions in the envelope space. They are index of (x, y) ordinates in a direct position after the grid to CRS transform.There is no garantee that
gridDimensionX
maps toaxisDimensionX
andgridDimensionY
maps toaxisDimensionY
, since axis may be interchanged.It is garanteed that
axisDimensionX
<axisDimensionY
.


Constructor Detail

GridGeometry2D
public GridGeometry2D(GridGeometry other)
Creates a new grid geometry with the same values than the given grid geometry. This is a copy constructor useful when the instance must be aGridGeometry2D
. Parameters:
other
 The other grid geometry to copy. Since:
 2.5
 See Also:
wrap(org.geotools.api.coverage.grid.GridGeometry)

GridGeometry2D
public GridGeometry2D(GridEnvelope gridRange, MathTransform gridToCRS, CoordinateReferenceSystem crs) throws IllegalArgumentException, MismatchedDimensionException
Constructs a new grid geometry from a grid range and a math transform. The arguments are passed unchanged to the superclass constructor. However, they must obey to the following additional constraints: Only two dimensions in the grid range can have a span larger than 1.
 Parameters:
gridRange
 The valid coordinate range of a grid coverage, ornull
if none. The lowest valid grid coordinate is zero forBufferedImage
, but may be nonzero for arbitraryRenderedImage
. A grid with 512 cells can have a minimum coordinate of 0 and maximum of 512, with 511 as the highest valid index.gridToCRS
 The math transform which allows for the transformations from grid coordinates (pixel's center) to real world earth coordinates.crs
 The coordinate reference system for the "real world" coordinates, ornull
if unknown. This CRS is given to the envelope. Throws:
MismatchedDimensionException
 if the math transform and the CRS don't have consistent dimensions.IllegalArgumentException
 ifgridRange
has more than 2 dimensions with a span larger than 1, or if the math transform can't transform coordinates in the domain of the specified grid range. Since:
 2.2

GridGeometry2D
public GridGeometry2D(GridEnvelope gridRange, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs, Hints hints) throws MismatchedDimensionException, IllegalArgumentException
Constructs a new grid geometry from a math transform. This constructor is similar toGridGeometry2D(gridRange, gridToCRS, crs)
with the addition of an explicit anchor and an optional set of hints giving more control on theMathTransform2D
to be inferred from the ndimensional transform.The
anchor
argument tells whatever thegridToCRS
transform maps cell center (OGC convention) or cell corner (Java2D/JAI convention). At the opposite of the constructor expecting aPixelOrientation
argument, the translation (if any) applies to every dimensions, not just the ones mapping the 2D part. Parameters:
gridRange
 The valid coordinate range of a grid coverage, ornull
if none.anchor
 Whatever thegridToCRS
transform maps cell center (OGC convention) or cell corner (Java2D/JAI convention).gridToCRS
 The math transform which allows for the transformations from grid coordinates to real world earth coordinates.crs
 The coordinate reference system for the "real world" coordinates, ornull
if unknown. This CRS is given to the envelope.hints
 An optional set of hints controlling theDimensionFilter
to be used for deriving theMathTransform2D
instance from the givengridToCRS
transform. Throws:
MismatchedDimensionException
 if the math transform and the CRS don't have consistent dimensions.IllegalArgumentException
 if the math transform can't transform coordinates in the domain of the specified grid range. Since:
 2.5

GridGeometry2D
public GridGeometry2D(GridEnvelope gridRange, PixelOrientation anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs, Hints hints) throws IllegalArgumentException, MismatchedDimensionException
Constructs a new grid geometry from a math transform. This constructor is similar toGridGeometry2D(gridRange, gridToCRS, crs)
with the addition of an explicit anchor and an optional set of hints giving more control on theMathTransform2D
to be inferred from the ndimensional transform.The
anchor
argument tells whatever thegridToCRS
transform maps pixel center or some corner. UseCENTER
for OGC conventions orUPPER_LEFT
for Java2D/JAI conventions. A translation (if needed) is applied only on thegridDimensionX
andgridDimensionY
parts of the transform  all other dimensions are assumed mapping pixel center. Parameters:
gridRange
 The valid coordinate range of a grid coverage, ornull
if none.anchor
 Whatever the twodimensional part of thegridToCRS
transform maps pixel center or some corner.gridToCRS
 The math transform from grid coordinates to real world earth coordinates.crs
 The coordinate reference system for the "real world" coordinates, ornull
if unknown.hints
 An optional set of hints controlling theDimensionFilter
to be used for deriving theMathTransform2D
instance from the givengridToCRS
transform. Throws:
MismatchedDimensionException
 if the math transform and the CRS don't have consistent dimensions.IllegalArgumentException
 ifgridRange
has more than 2 dimensions with a span larger than 1, or if the math transform can't transform coordinates in the domain of the specified grid range. Since:
 2.5

GridGeometry2D
public GridGeometry2D(PixelInCell anchor, MathTransform gridToCRS, Bounds envelope, Hints hints) throws MismatchedDimensionException, IllegalArgumentException
Constructs a new grid geometry from an envelope and a math transform. According OGC specification, the math transform should map pixel center. But in Java2D/JAI conventions, the transform is rather expected to maps pixel corner. The convention to follow can be specified by theanchor
argument. Parameters:
anchor
CELL_CENTER
for OGC conventions orCELL_CORNER
for Java2D/JAI conventions.gridToCRS
 The math transform which allows for the transformations from grid coordinates to real world earth coordinates. May benull
, but this is not recommended.envelope
 The envelope (including CRS) of a grid coverage, ornull
if none.hints
 An optional set of hints controlling theDimensionFilter
to be used for deriving theMathTransform2D
instance from the givengridToCRS
transform. Throws:
MismatchedDimensionException
 if the math transform and the envelope doesn't have consistent dimensions.IllegalArgumentException
 if the math transform can't transform coordinates in the domain of the grid range. Since:
 2.5

GridGeometry2D
public GridGeometry2D(GridEnvelope gridRange, Bounds userRange) throws IllegalArgumentException, MismatchedDimensionException
Constructs a new grid geometry from an envelope. This constructors applies the same heuristic rules than the superclass constructor. However, they must obey to the same additional constraints than the main constructor. Parameters:
gridRange
 The valid coordinate range of a grid coverage.userRange
 The corresponding coordinate range in user coordinate. Throws:
IllegalArgumentException
 ifgridRange
has more than 2 dimensions with a length larger than 1.MismatchedDimensionException
 if the grid range and the CRS doesn't have consistent dimensions. Since:
 2.2

GridGeometry2D
public GridGeometry2D(Rectangle gridRange, Rectangle2D userRange)
Constructs a new twodimensional grid geometry using java.awt objects. Initialising corresponding GeoTools objects if necessary, and calls GridGeometry2D(GridEnvelope, Bounds) Parameters:
gridRange
 The valid coordinate range of a grid coverage. Increasing x values goes right and increasing y values goes down.userRange
 The corresponding coordinate range in user coordinate.


Method Detail

wrap
public static GridGeometry2D wrap(GridGeometry other)
Returns the given grid geometry as aGridGeometry2D
. If the given object is already an instance ofGridGeometry2D
, then it is returned unchanged. Otherwise a newGridGeometry2D
instance is created using the copy constructor. Parameters:
other
 The grid geometry to wrap. Returns:
 The wrapped geometry, or
null
ifother
was null.  Since:
 2.5

reduce
public ReferencedEnvelope reduce(Bounds bounds)
Reduces the specified bounds to a twodimensional ReferencedEnvelope. If the given bounds has more than two dimensions, then a new one is created using only the coordinates at (axisDimensionX
,axisDimensionY
) index.The
coordinate reference system
of the source envelope is ignored. The coordinate reference system of the target envelope will begetCoordinateReferenceSystem2D()
ornull
. Parameters:
bounds
 The bounds to reduce, ornull
. This envelope will not be modified. Returns:
 An ReferencedEnvelope with exactly 2 dimensions, or
null
ifbounds
was null. The returned ReferencedEnvelope is always a new instance, so it can be modified safely.  Since:
 2.5

reduce
public CoordinateReferenceSystem reduce(CoordinateReferenceSystem crs) throws FactoryException
Reduces the specified CRS to a twodimensional one. If the given CRS has more than two dimensions, then a new one is created using only the axis at (axisDimensionX
,axisDimensionY
) index. Parameters:
crs
 The coordinate reference system to reduce, ornull
. Returns:
 A coordinate reference system with no more than 2 dimensions, or
null
ifcrs
was null.  Throws:
FactoryException
 if the given CRS can't be reduced to two dimensions. Since:
 2.5

getCoordinateReferenceSystem2D
public CoordinateReferenceSystem getCoordinateReferenceSystem2D() throws InvalidGridGeometryException
Returns the twodimensional part of this grid geometry CRS. If the complete CRS is twodimensional, then this method returns the same CRS. Otherwise it returns a CRS for (axisDimensionX
,axisDimensionY
) axis. Note that those axis are garanteed to appears in the same order than in the complete CRS. Returns:
 The coordinate reference system (never
null
).  Throws:
InvalidGridGeometryException
 if this grid geometry has no CRS (i.e.isDefined(CRS)
returnedfalse
). Since:
 2.2
 See Also:
GeneralGridGeometry.getCoordinateReferenceSystem()

getEnvelope2D
public ReferencedEnvelope getEnvelope2D() throws InvalidGridGeometryException
Returns the twodimensional bounding box for the coverage domain in coordinate reference system coordinates. If the coverage envelope has more than two dimensions, only the dimensions used in the underlying rendered image are returned. Returns:
 The bounding box in "real world" coordinates (never
null
).  Throws:
InvalidGridGeometryException
 if this grid geometry has no envelope (i.e.isDefined(ENVELOPE_BITMASK)
returnedfalse
). See Also:
GeneralGridGeometry.getEnvelope()

getGridRange2D
public GridEnvelope2D getGridRange2D() throws InvalidGridGeometryException
Returns the twodimensional part of the grid range as a rectangle. Note that the returned object is aRectangle
subclass. Returns:
 The grid range (never
null
).  Throws:
InvalidGridGeometryException
 if this grid geometry has no grid range (i.e.isDefined(GRID_RANGE_BITMASK)
returnedfalse
). See Also:
GeneralGridGeometry.getGridRange()

getGridToCRS2D
public MathTransform2D getGridToCRS2D() throws InvalidGridGeometryException
Returns a math transform for the two dimensional part. This is a convenience method for working on horizontal data while ignoring vertical or temporal dimensions. Returns:
 The transform which allows for the transformations from grid coordinates to real
world earth coordinates, operating only on two dimensions. The returned transform is
often an instance of
AffineTransform
, which make it convenient for interoperability with Java2D.  Throws:
InvalidGridGeometryException
 if a twodimensional transform is not available for this grid geometry. Since:
 2.3
 See Also:
getGridToCRS(org.geotools.api.metadata.spatial.PixelOrientation)

getCRSToGrid2D
public MathTransform2D getCRSToGrid2D() throws InvalidGridGeometryException
Returns a math transform for the two dimensional part for conversion from world to grid coordinates. This is a convenience method for working on horizontal data while ignoring vertical or temporal dimensions. Returns:
 The transform which allows for the transformations from real world earth coordinates
to grid coordinates, operating only on two dimensions. The returned transform is often an
instance of
AffineTransform
, which makes it convenient for interoperability with Java2D.  Throws:
InvalidGridGeometryException
 if a twodimensional transform is not available for this grid geometry. Since:
 2.6
 See Also:
getGridToCRS(org.geotools.api.metadata.spatial.PixelOrientation)

getGridToCRS2D
public MathTransform2D getGridToCRS2D(PixelOrientation orientation)
Returns a math transform for the two dimensional part. This method is similar togetGridToCRS2D()
except that the transform may maps a pixel corner instead of pixel center. Parameters:
orientation
 The pixel part to map. The default value isCENTER
. Returns:
 The transform which allows for the transformations from grid coordinates to real world earth coordinates.
 Throws:
InvalidGridGeometryException
 if a twodimensional transform is not available for this grid geometry. Since:
 2.3

getCRSToGrid2D
public MathTransform2D getCRSToGrid2D(PixelOrientation orientation)
Returns a math transform for the two dimensional part. This method is similar togetCRSToGrid2D()
except that the transform may map a pixel corner instead of pixel center. Parameters:
orientation
 The pixel part to map. The default value isCENTER
. Returns:
 The transform which allows for the transformations from world coordinates to grid coordinates.
 Throws:
InvalidGridGeometryException
 if a twodimensional transform is not available for this grid geometry. Since:
 2.6

getGridToCRS
public MathTransform getGridToCRS(PixelOrientation orientation)
Returns a math transform mapping the specified pixel part. A translation (if needed) is applied on thegridDimensionX
andgridDimensionY
parts of the transform; all other dimensions are assumed mapping pixel center. For applying a translation on all dimensions, useGeneralGridGeometry.getGridToCRS(PixelInCell)
instead. Parameters:
orientation
 The pixel part to map. The default value isCENTER
. Returns:
 The transform which allows for the transformations from grid coordinates to real world earth coordinates.
 Throws:
InvalidGridGeometryException
 if a transform is not available for this grid geometry. Since:
 2.3

worldToGrid
public final GridCoordinates2D worldToGrid(Position point) throws InvalidGridGeometryException, TransformException
Transforms a point represented by a DirectPosition object from world to grid coordinates. If the point contains aCoordinateReferenceSystem
, and it differs from that of the coverage, it will be reprojected on the fly. The the nearest grid cell centre to the input point is found.Users needing more control over the nature of the conversion can access the MathsTransform provided by getCRSToGrid2D(PixelOrientation) which is accessed via #getGridGeometry().
 Parameters:
point
 The point in world coordinate system. Returns:
 A new point in the grid coordinate system as a GridCoordinates2D object
 Throws:
InvalidGridGeometryException
 if a twodimensional inverse transform is not available.TransformException
 if the transformation failed. Since:
 2.6

worldToGrid
public final GridEnvelope2D worldToGrid(BoundingBox envelope) throws TransformException, InvalidGridGeometryException
Transforms a rectangle represented by an Envelope2D object from world to grid coordinates. If the envelope contains aCoordinateReferenceSystem
, it must be the same as that of this coverage, otherwise an exception is thrown.The
GridEnvelope2D
returned contains the range of cells whose centers lie inside the inputEnvelope2D
Users needing more control over the nature of the conversion can access the MathsTransform provided by getCRSToGrid2D(PixelOrientation) which is accessed via #getGridGeometry().
 Parameters:
envelope
 The envelope in world coordinate system. Returns:
 The corresponding rectangle in the grid coordinate system as a new
GridEnvelope2D
object  Throws:
IllegalArgumentException
 if the coordinate reference system of the envelope is notnull
and does not match that of the coverageInvalidGridGeometryException
 if a twodimensional inverse transform is not available for this grid geometry.TransformException
 if the transformation failed. Since:
 2.6

worldToGrid
public final GridEnvelope2D worldToGrid(ReferencedEnvelope envelope) throws TransformException, InvalidGridGeometryException
Transforms a rectangle represented by an ReferencedEnvelope (or BoundingBox) from world to grid coordinates. If the envelope contains aCoordinateReferenceSystem
, it must be the same as that of this coverage, otherwise an exception is thrown.The
GridEnvelope2D
returned contains the range of cells whose centers lie inside the inputEnvelope2D
Users needing more control over the nature of the conversion can access the MathsTransform provided by getCRSToGrid2D(PixelOrientation) which is accessed via #getGridGeometry().
 Parameters:
envelope
 The envelope in world coordinate system. Returns:
 The corresponding rectangle in the grid coordinate system as a new
ReferencedEnvelope
object  Throws:
IllegalArgumentException
 if the coordinate reference system of the envelope is notnull
and does not match that of the coverageInvalidGridGeometryException
 if a twodimensional inverse transform is not available for this grid geometry.TransformException
 if the transformation failed. Since:
 2.6

gridToWorld
public final Position gridToWorld(GridCoordinates2D point) throws TransformException
Transforms a point represented by a GridCoordinates2D object from grid to world coordinates. The coordinates returned are those of the centre of the grid cell in which the point lies.Users needing more control over the nature of the conversion (e.g. calculating cell corner coordinates) can use the
MathsTransform
provided by getGridToCRS2D(PixelOrientation) which is accessed via #getGridGeometry(). Parameters:
point
 The point in world coordinate system. Returns:
 A new point in the grid coordinate system as a GridCoordinates2D object
 Throws:
TransformException
 if the transformation failed.IllegalArgumentException
 if the point lies outside the coverage Since:
 2.6

gridToWorld
public final ReferencedEnvelope gridToWorld(GridEnvelope2D gridEnv) throws TransformException
Transforms an represented by a GridEnvelope2D object from grid to world coordinates. The bounds of the Envelope2D object returned correspond to the outer edges of the grid cells within the input envelope.Users needing more control over the nature of the conversion can use the
MathsTransform
provided by getGridToCRS2D(PixelOrientation) which is accessed via #getGridGeometry(). Parameters:
gridEnv
 The rectangle of grid coordinates to convert Returns:
 World coordinates of the rectangle as a new Envelope2D object
 Throws:
TransformException
 if the transformation failed.IllegalArgumentException
 if the input rectangle lies outside the coverage Since:
 2.6

equals
public boolean equals(Object object)
Compares the specified object with this grid geometry for equality. Overrides:
equals
in classGeneralGridGeometry
 Parameters:
object
 The object to compare with. Returns:
true
if the given object is equals to this grid geometry.

hashCode
public int hashCode()
Description copied from class:GeneralGridGeometry
Returns a hash value for this grid geometry. This value need not remain consistent between different implementations of the same class. Overrides:
hashCode
in classGeneralGridGeometry

toCanonical
public GridGeometry2D toCanonical()
Returns a "canonical" representation of the grid geometry, that is, one whose grid range originates in 0,0, but maps to the same real world coordinates. This setup helps in image processing, as JAI is not meant to be used for images whose ordinates are in the range of the millions and starts to exhibit numerical issues when used there. Since:
 13.3

