org.geotools.coverage.grid

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 this GridGeometry2D class (some peoples said 2.5D) because a two-dimensional grid coordinate is enough for referencing a pixel without ambiguity. But a grid size of 512×512×2 pixels can not be represented by this GridGeometry2D, because a three-dimensional 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 and 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 and Description
GridGeometry2D(GridEnvelope gridRange, Envelope userRange) Constructs a new grid geometry from an envelope.
GridGeometry2D(GridEnvelope gridRange, MathTransform gridToCRS, CoordinateReferenceSystem crs) Constructs a new grid geometry from a grid range and 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, PixelOrientation anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs, Hints hints) Constructs a new grid geometry from 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, Envelope envelope, Hints hints) Constructs a new grid geometry from an envelope and a math transform.
GridGeometry2D(Rectangle gridRange, Rectangle2D userRange) Constructs a new two-dimensional grid geometry.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object object) Compares the specified object with this grid geometry for equality.
CoordinateReferenceSystem	getCoordinateReferenceSystem2D() Returns the two-dimensional 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.
Envelope2D	getEnvelope2D() Returns the two-dimensional bounding box for the coverage domain in coordinate reference system coordinates.
GridEnvelope2D	getGridRange2D() Returns the two-dimensional 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.
DirectPosition	gridToWorld(GridCoordinates2D point) Transforms a point represented by a GridCoordinates2D object from grid to world coordinates.
Envelope2D	gridToWorld(GridEnvelope2D gridEnv) Transforms a rectangle represented by a GridEnvelope2D object from grid to world coordinates.
int	hashCode() Returns a hash value for this grid geometry.
CoordinateReferenceSystem	reduce(CoordinateReferenceSystem crs) Reduces the specified CRS to a two-dimensional one.
Envelope2D	reduce(Envelope envelope) Reduces the specified envelope to a two-dimensional 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.
GridCoordinates2D	worldToGrid(DirectPosition point) Transforms a point represented by a DirectPosition object from world to grid coordinates.
GridEnvelope2D	worldToGrid(Envelope2D envelope) Transforms a rectangle represented by an Envelope2D object from world to grid coordinates.
static GridGeometry2D	wrap(GridGeometry other) Returns the given grid geometry as a GridGeometry2D.

Methods inherited from class GeneralGridGeometry

getCoordinateReferenceSystem, getDimension, getEnvelope, getGridRange, getGridToCRS, getGridToCRS, isDefined, toString

Methods inherited from class Object

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

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 to axisDimensionX and gridDimensionY maps to axisDimensionY, 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 to axisDimensionX and gridDimensionY maps to axisDimensionY, 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 a GridGeometry2D.

Parameters:

other - The other grid geometry to copy.

Since:

2.5

See Also:

wrap(org.opengis.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 super-class 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, or null if none. The lowest valid grid coordinate is zero for BufferedImage, but may be non-zero for arbitrary RenderedImage. 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, or null if unknown. This CRS is given to the envelope.

Throws:

MismatchedDimensionException - if the math transform and the CRS don't have consistent dimensions.

IllegalArgumentException - if gridRange 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 to GridGeometry2D(gridRange, gridToCRS, crs) with the addition of an explicit anchor and an optional set of hints giving more control on the MathTransform2D to be inferred from the n-dimensional transform.

The anchor argument tells whatever the gridToCRS transform maps cell center (OGC convention) or cell corner (Java2D/JAI convention). At the opposite of the constructor expecting a PixelOrientation 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, or null if none.

anchor - Whatever the gridToCRS 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, or null if unknown. This CRS is given to the envelope.

hints - An optional set of hints controlling the DimensionFilter to be used for deriving the MathTransform2D instance from the given gridToCRS 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 to GridGeometry2D(gridRange, gridToCRS, crs) with the addition of an explicit anchor and an optional set of hints giving more control on the MathTransform2D to be inferred from the n-dimensional transform.

The anchor argument tells whatever the gridToCRS transform maps pixel center or some corner. Use CENTER for OGC conventions or UPPER_LEFT for Java2D/JAI conventions. A translation (if needed) is applied only on the gridDimensionX and gridDimensionY parts of the transform - all other dimensions are assumed mapping pixel center.

Parameters:

gridRange - The valid coordinate range of a grid coverage, or null if none.

anchor - Whatever the two-dimensional part of the gridToCRS 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, or null if unknown.

hints - An optional set of hints controlling the DimensionFilter to be used for deriving the MathTransform2D instance from the given gridToCRS transform.

Throws:

MismatchedDimensionException - if the math transform and the CRS don't have consistent dimensions.

IllegalArgumentException - if gridRange 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,
                      Envelope 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 the anchor argument.

Parameters:

anchor - CELL_CENTER for OGC conventions or CELL_CORNER for Java2D/JAI conventions.

gridToCRS - The math transform which allows for the transformations from grid coordinates to real world earth coordinates. May be null, but this is not recommended.

envelope - The envelope (including CRS) of a grid coverage, or null if none.

hints - An optional set of hints controlling the DimensionFilter to be used for deriving the MathTransform2D instance from the given gridToCRS 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,
                      Envelope userRange)
               throws IllegalArgumentException,
                      MismatchedDimensionException

Constructs a new grid geometry from an envelope. This constructors applies the same heuristic rules than the super-class 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 - if gridRange 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 two-dimensional grid geometry. A math transform will be computed automatically with an inverted y axis (i.e. gridRange and userRange are assumed to have y axis in opposite direction).

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. Increasing x values goes right and increasing y values goes up. This rectangle must contains entirely all pixels, i.e. the rectangle's upper left corner must coincide with the upper left corner of the first pixel and the rectangle's lower right corner must coincide with the lower right corner of the last pixel.

Method Detail

wrap

public static GridGeometry2D wrap(GridGeometry other)

Returns the given grid geometry as a GridGeometry2D. If the given object is already an instance of GridGeometry2D, then it is returned unchanged. Otherwise a new GridGeometry2D instance is created using the copy constructor.

Parameters:

other - The grid geometry to wrap.

Returns:

The wrapped geometry, or null if other was null.

Since:

2.5

reduce

public Envelope2D reduce(Envelope envelope)

Reduces the specified envelope to a two-dimensional one. If the given envelope 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 be getCoordinateReferenceSystem2D() or null.

Parameters:

envelope - The envelope to reduce, or null. This envelope will not be modified.

Returns:

An envelope with exactly 2 dimensions, or null if envelope was null. The returned envelope 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 two-dimensional 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, or null.

Returns:

A coordinate reference system with no more than 2 dimensions, or null if crs 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 two-dimensional part of this grid geometry CRS. If the complete CRS is two-dimensional, 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) returned false).

Since:

2.2

See Also:

GeneralGridGeometry.getCoordinateReferenceSystem()

getEnvelope2D

public Envelope2D getEnvelope2D()
                         throws InvalidGridGeometryException

Returns the two-dimensional 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) returned false).

See Also:

GeneralGridGeometry.getEnvelope()

getGridRange2D

public GridEnvelope2D getGridRange2D()
                              throws InvalidGridGeometryException

Returns the two-dimensional part of the grid range as a rectangle. Note that the returned object is a Rectangle subclass.

Returns:

The grid range (never null).

Throws:

InvalidGridGeometryException - if this grid geometry has no grid range (i.e. isDefined(GRID_RANGE_BITMASK) returned false).

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 two-dimensional transform is not available for this grid geometry.

Since:

2.3

See Also:

getGridToCRS(org.opengis.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 two-dimensional transform is not available for this grid geometry.

Since:

2.6

See Also:

getGridToCRS(org.opengis.metadata.spatial.PixelOrientation)

getGridToCRS2D

public MathTransform2D getGridToCRS2D(PixelOrientation orientation)

Returns a math transform for the two dimensional part. This method is similar to getGridToCRS2D() except that the transform may maps a pixel corner instead of pixel center.

Parameters:

orientation - The pixel part to map. The default value is CENTER.

Returns:

The transform which allows for the transformations from grid coordinates to real world earth coordinates.

Throws:

InvalidGridGeometryException - if a two-dimensional 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 to getCRSToGrid2D() except that the transform may map a pixel corner instead of pixel center.

Parameters:

orientation - The pixel part to map. The default value is CENTER.

Returns:

The transform which allows for the transformations from world coordinates to grid coordinates.

Throws:

InvalidGridGeometryException - if a two-dimensional 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 the gridDimensionX and gridDimensionY parts of the transform; all other dimensions are assumed mapping pixel center. For applying a translation on all dimensions, use GeneralGridGeometry.getGridToCRS(PixelInCell) instead.

Parameters:

orientation - The pixel part to map. The default value is CENTER.

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(DirectPosition point)
                                    throws InvalidGridGeometryException,
                                           TransformException

Transforms a point represented by a DirectPosition object from world to grid coordinates. If the point contains a CoordinateReferenceSystem, 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 two-dimensional inverse transform is not available.

TransformException - if the transformation failed.

Since:

2.6

worldToGrid

public final GridEnvelope2D worldToGrid(Envelope2D envelope)
                                 throws TransformException,
                                        InvalidGridGeometryException

Transforms a rectangle represented by an Envelope2D object from world to grid coordinates. If the envelope contains a CoordinateReferenceSystem, 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 input Envelope2D

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 not null and does not match that of the coverage

InvalidGridGeometryException - if a two-dimensional inverse transform is not available for this grid geometry.

TransformException - if the transformation failed.

Since:

2.6

gridToWorld

public final DirectPosition 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 Envelope2D gridToWorld(GridEnvelope2D gridEnv)
                             throws TransformException

Transforms a rectangle 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 class GeneralGridGeometry

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 class GeneralGridGeometry

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