org.geotools.coverage.grid
Class GeneralGridGeometry

java.lang.Object
  org.geotools.coverage.grid.GeneralGridGeometry

All Implemented Interfaces:

org.opengis.coverage.grid.GridGeometry, java.io.Serializable

Direct Known Subclasses:

GridGeometry2D

public class GeneralGridGeometry

extends java.lang.Object

implements org.opengis.coverage.grid.GridGeometry, java.io.Serializable

Describes the valid range of grid coordinates and the math transform to transform grid coordinates to real world coordinates. Grid geometries contains:

• An optional grid range, usually inferred from the rendered image size.
• An optional "grid to CRS" transform, which may be inferred from the grid range and the envelope.
• An optional envelope, which may be inferred from the grid range and the "grid to CRS" transform.
• An optional coordinate reference system to be given to the envelope.

All grid geometry attributes are optional because some of them may be inferred from a wider context. For example a grid geometry know nothing about rendered images, but GridCoverage2D do. Consequently, the later may infer the grid range by itself.

By default, any request for an undefined attribute will thrown an InvalidGridGeometryException. In order to check if an attribute is defined, use isDefined(int).

Since:

2.1

Version:

$Id: GeneralGridGeometry.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux, Alessio Fabiani

See Also:

Serialized Form

Field Summary

static int	CRS A bitmask to specify the validity of the coordinate reference system.
static int	ENVELOPE A bitmask to specify the validity of the envelope.
static int	GRID_RANGE A bitmask to specify the validity of the grid range.
static int	GRID_TO_CRS A bitmask to specify the validity of the grid to CRS transform.
protected org.opengis.coverage.grid.GridRange	gridRange The valid coordinate range of a grid coverage, or if none.
protected org.opengis.referencing.operation.MathTransform	gridToCRS The math transform (usually an affine transform), or if none.

Constructor Summary

GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange, org.opengis.spatialschema.geometry.Envelope userRange)
Constructs a new grid geometry from an envelope.

GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange, org.opengis.spatialschema.geometry.Envelope userRange, boolean[] reverse)
Deprecated. Replaced by . Users just need to append the argument value, so this constructor will be removed in a future version in order to keep the API lighter.

GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange, org.opengis.spatialschema.geometry.Envelope userRange, boolean[] reverse, boolean swapXY)
Constructs a new grid geometry from an envelope.

GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange, org.opengis.referencing.operation.MathTransform gridToCRS)
Deprecated. Replaced by GeneralGridGeometry(gridRange, gridToCRS, null).

GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.referencing.crs.CoordinateReferenceSystem crs)
Constructs a new grid geometry from a math transform.

Method Summary

boolean	equals(java.lang.Object object) Compares the specified object with this grid geometry for equality.
org.opengis.referencing.crs.CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the "real world" coordinate reference system.
int	getDimension() Returns the number of dimensions.
org.opengis.spatialschema.geometry.Envelope	getEnvelope() Returns the bounding box of "real world" coordinates for this grid geometry.
org.opengis.coverage.grid.GridRange	getGridRange() Returns the valid coordinate range of a grid coverage.
org.opengis.referencing.operation.MathTransform	getGridToCoordinateSystem() Returns the math transform which allows for the transformations from grid coordinates to real world earth coordinates.
int	hashCode() Returns a hash value for this grid geometry.
boolean	isDefined(int bitmask) Returns if all the parameters specified by the argument are set.
java.lang.String	toString() Returns a string repr?sentation of this grid geometry.

Methods inherited from class java.lang.Object

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

Field Detail

CRS

public static final int CRS

A bitmask to specify the validity of the coordinate reference system. This is given as an argument to the isDefined(int) method.

Since:

2.2

See Also:

Constant Field Values

ENVELOPE

public static final int ENVELOPE

A bitmask to specify the validity of the envelope. This is given as an argument to the isDefined(int) method.

Since:

2.2

See Also:

Constant Field Values

GRID_RANGE

public static final int GRID_RANGE

A bitmask to specify the validity of the grid range. This is given as an argument to the isDefined(int) method.

Since:

2.2

See Also:

Constant Field Values

GRID_TO_CRS

public static final int GRID_TO_CRS

A bitmask to specify the validity of the grid to CRS transform. This is given as an argument to the isDefined(int) method.

Since:

2.2

See Also:

Constant Field Values

gridRange

protected final org.opengis.coverage.grid.GridRange gridRange

The valid coordinate range of a grid coverage, or 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.

See Also:

RenderedImage.getMinX(), RenderedImage.getMinY(), RenderedImage.getWidth(), RenderedImage.getHeight()

gridToCRS

protected final org.opengis.referencing.operation.MathTransform gridToCRS

The math transform (usually an affine transform), or if none. This math transform maps pixel center to "real world" coordinate using the following line:

gridToCRS.transform(pixels, point);

Constructor Detail

GeneralGridGeometry

public GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange,
                           org.opengis.referencing.operation.MathTransform gridToCRS)

Deprecated. Replaced by GeneralGridGeometry(gridRange, gridToCRS, null).

Constructs a new grid geometry from a math transform.

Parameters:

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

gridToCRS - The math transform which allows for the transformations from grid coordinates (pixel's center) to real world earth coordinates.

GeneralGridGeometry

public GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange,
                           org.opengis.referencing.operation.MathTransform gridToCRS,
                           org.opengis.referencing.crs.CoordinateReferenceSystem crs)
                    throws org.opengis.spatialschema.geometry.MismatchedDimensionException,
                           java.lang.IllegalArgumentException

Constructs a new grid geometry from a math transform. This is the most general constructor, the one that gives the maximal control on the grid geometry to be created.

Parameters:

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

gridToCRS - The math transform which allows for the transformations from grid coordinates (pixel's center) to real world earth coordinates. May be (but this is not recommanded).

crs - The coordinate reference system for the "real world" coordinates, or if unknown. This CRS is given to the envelope.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the math transform or the CRS doesn't have consistent dimensions.

java.lang.IllegalArgumentException - if the math transform can't transform coordinates in the domain of the specified grid range.

Since:

2.2

GeneralGridGeometry

public GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange,
                           org.opengis.spatialschema.geometry.Envelope userRange)
                    throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Constructs a new grid geometry from an envelope. An affine transform will be computed automatically from the specified envelope using heuristic rules described below.

This convenience constructor assumes that axis order in the supplied argument matches exactly axis order in the supplied argument. In other words, if axis order in the underlying image is (column, row) (which is the case for a majority of images), then the envelope given to this constructor should probably have a (longitude, latitude) or (easting, northing) axis order.

An exception to the above rule applies for CRS using exactly the following axis order: (NORTH|SOUTH, EAST|WEST). An example of such CRS is . This convenience constructor will interchange automatically the (y,x) axis for such CRS.

Parameters:

gridRange - The valid coordinate range of a grid coverage.

userRange - The corresponding coordinate range in user coordinate. 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.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the grid range and the CRS doesn't have consistent dimensions.

Since:

2.2

GeneralGridGeometry

public GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange,
                           org.opengis.spatialschema.geometry.Envelope userRange,
                           boolean[] reverse)

Deprecated. Replaced by . Users just need to append the argument value, so this constructor will be removed in a future version in order to keep the API lighter.

Constructs a new grid geometry from an envelope.

GeneralGridGeometry

public GeneralGridGeometry(org.opengis.coverage.grid.GridRange gridRange,
                           org.opengis.spatialschema.geometry.Envelope userRange,
                           boolean[] reverse,
                           boolean swapXY)
                    throws org.opengis.spatialschema.geometry.MismatchedDimensionException

Constructs a new grid geometry from an envelope. An affine transform will be computed automatically from the specified envelope. The two last arguments ( and ) are hints about the affine transform to be created: the argument tells which (if any) axis from user space (not grid space) should have their direction reversed, and the argument tells if the two first axis should be interchanged.

This constructor is convenient when the following conditions are meet:

• Pixels coordinates (usually (x,y) integer values inside the rectangle specified by the argument) are expressed in some coordinate reference system known at compile time. This is often the case; for example the CRS attached to BufferedImage has always (column, row) axis, with the origin (0,0) in the upper left corner, and row values increasing down.

• "Real world" coordinates (inside the envelope specified by the argument) are expressed in arbitrary horizontal coordinate reference system. Axis directions may be (North, West), or (East, North), etc..

In such case (and assuming that the image's CRS has the same characteristics than the BufferedImage's CRS described above):

• shall be set to if the "real world" axis order is (North, East) instead of (East, North). This axis swapping is necessary for mapping the (column, row) axis order associated to the image CRS.

• In addition, the "real world" axis directions shall be reversed (by setting to ) if their direction is WEST (x axis) or NORTH (y axis), in order to get them oriented toward the EAST or SOUTH direction respectively. The later may seems unatural, but it reflects the fact that row values are increasing down in an BufferedImage's CRS.

If this convenience constructor do not provides suffisient control on axis order or reversal, then an affine transform shall be created explicitly and the grid geometry shall be created using the constructor expecting a math transform argument.

Parameters:

gridRange - The valid coordinate range of a grid coverage.

userRange - The corresponding coordinate range in user coordinate. This envelope must contains entirely all pixels, i.e. the envelope's upper left corner must coincide with the upper left corner of the first pixel and the envelope's lower right corner must coincide with the lower right corner of the last pixel.

reverse - Tells for each axis in user space whatever or not its direction should be reversed. A value reverse no axis. Callers will typically set to in order to reverse the y axis direction.

swapXY - If , then the two first axis will be interchanged. Callers will typically set this argument to when the geographic coordinate system has axis in the (y,x) order. The parameter then apply to axis after the swap.

Throws:

org.opengis.spatialschema.geometry.MismatchedDimensionException - if the grid range and the CRS doesn't have consistent dimensions.

Since:

2.2

Method Detail

getDimension

public int getDimension()

Returns the number of dimensions.

getCoordinateReferenceSystem

public org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateReferenceSystem()
                                                                                   throws InvalidGridGeometryException

Returns the "real world" coordinate reference system.

Returns:

The coordinate reference system (never ).

Throws:

InvalidGridGeometryException - if this grid geometry has no CRS (i.e. isDefined(CRS) returned ).

Since:

2.2

See Also:

GridGeometry2D.getCoordinateReferenceSystem2D()

getEnvelope

public org.opengis.spatialschema.geometry.Envelope getEnvelope()
                                                        throws InvalidGridGeometryException

Returns the bounding box of "real world" coordinates for this grid geometry. This envelope is the grid range transformed to the "real world" coordinate system.

Returns:

The bounding box in "real world" coordinates (never ).

Throws:

InvalidGridGeometryException - if this grid geometry has no envelope (i.e. isDefined(ENVELOPE) returned ).

See Also:

GridGeometry2D.getEnvelope2D()

getGridRange

public org.opengis.coverage.grid.GridRange getGridRange()
                                                 throws InvalidGridGeometryException

Returns the valid coordinate range of a grid coverage. 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.

Specified by:

getGridRange in interface org.opengis.coverage.grid.GridGeometry

Returns:

The grid range (never ).

Throws:

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

See Also:

GridGeometry2D.getGridRange2D()

getGridToCoordinateSystem

public org.opengis.referencing.operation.MathTransform getGridToCoordinateSystem()
                                                                          throws InvalidGridGeometryException

Returns the math transform which allows for the transformations from grid coordinates to real world earth coordinates. The transform is often an affine transformation. The coordinate reference system of the real world coordinates is given by Coverage.getCoordinateReferenceSystem().

Note: OpenGIS requires that the transform maps pixel centers to real world coordinates. This is different from some other systems that map pixel's upper left corner.

Specified by:

getGridToCoordinateSystem in interface org.opengis.coverage.grid.GridGeometry

Returns:

The transform (never ).

Throws:

InvalidGridGeometryException - if this grid geometry has no transform (i.e. isDefined(GRID_TO_CRS) returned ).

See Also:

GridGeometry2D.getGridToCoordinateSystem2D()

isDefined

public boolean isDefined(int bitmask)
                  throws java.lang.IllegalArgumentException

Returns if all the parameters specified by the argument are set.

Parameters:

bitmask - Any combinaison of CRS, ENVELOPE, GRID_RANGE and GRID_TO_CRS.

Returns:

if all specified attributes are defined (i.e. invoking the corresponding method will not thrown an InvalidGridGeometryException).

Throws:

java.lang.IllegalArgumentException - if the specified bitmask is not a combinaison of known masks.

Since:

2.2

hashCode

public int hashCode()

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

equals

public boolean equals(java.lang.Object object)

Compares the specified object with this grid geometry for equality.

toString

public java.lang.String toString()

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