org.geotools.coverage.grid
Class GeneralGridGeometry

java.lang.Object
  extended by org.geotools.coverage.grid.GeneralGridGeometry
All Implemented Interfaces:
java.io.Serializable, org.opengis.coverage.grid.GridGeometry
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:

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 33828 2009-09-03 06:44:06Z mbedward $
Author:
Martin Desruisseaux (IRD), Alessio Fabiani
See Also:
GridGeometry2D, ImageGeometry, Serialized Form

Field Summary
static int CRS_BITMASK
          A bitmask to specify the validity of the coordinate reference system.
static int ENVELOPE_BITMASK
          A bitmask to specify the validity of the envelope.
static int GRID_RANGE_BITMASK
          A bitmask to specify the validity of the grid range.
static int GRID_TO_CRS_BITMASK
          A bitmask to specify the validity of the grid to CRS transform.
protected  org.opengis.coverage.grid.GridEnvelope gridRange
          The valid coordinate range of a grid coverage, or null if none.
protected  org.opengis.referencing.operation.MathTransform gridToCRS
          The math transform (usually an affine transform), or null if none.
 
Constructor Summary
GeneralGridGeometry(org.opengis.coverage.grid.GridEnvelope gridRange, org.opengis.geometry.Envelope userRange)
          Constructs a new grid geometry from an envelope.
GeneralGridGeometry(org.opengis.coverage.grid.GridEnvelope gridRange, org.opengis.geometry.Envelope userRange, boolean[] reverse, boolean swapXY)
          Deprecated. Use GridToEnvelopeMapper instead, which provides more control.
GeneralGridGeometry(org.opengis.coverage.grid.GridEnvelope gridRange, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.referencing.crs.CoordinateReferenceSystem crs)
          Constructs a new grid geometry from a grid range and a math transform mapping pixel center.
GeneralGridGeometry(org.opengis.coverage.grid.GridEnvelope gridRange, org.opengis.referencing.datum.PixelInCell anchor, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.referencing.crs.CoordinateReferenceSystem crs)
          Constructs a new grid geometry from a grid range and a math transform mapping pixel center or corner.
GeneralGridGeometry(org.opengis.coverage.grid.GridGeometry other)
          Creates a new grid geometry with the same values than the given grid geometry.
GeneralGridGeometry(org.opengis.referencing.datum.PixelInCell anchor, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope envelope)
          Constructs a new grid geometry from an envelope and 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.geometry.Envelope getEnvelope()
          Returns the bounding box of "real world" coordinates for this grid geometry.
 org.opengis.coverage.grid.GridEnvelope getGridRange()
          Returns the valid coordinate range of a grid coverage.
 org.opengis.referencing.operation.MathTransform getGridToCRS()
          Returns the transform from grid coordinates to real world earth coordinates.
 org.opengis.referencing.operation.MathTransform getGridToCRS(org.opengis.referencing.datum.PixelInCell anchor)
          Returns the transform from grid coordinates to real world earth coordinates.
 int hashCode()
          Returns a hash value for this grid geometry.
 boolean isDefined(int bitmask)
          Returns true if all the parameters specified by the argument are set.
 java.lang.String toString()
          Returns a string representation of this grid geometry.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

CRS_BITMASK

public static final int CRS_BITMASK
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_BITMASK

public static final int ENVELOPE_BITMASK
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_BITMASK

public static final int GRID_RANGE_BITMASK
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_BITMASK

public static final int GRID_TO_CRS_BITMASK
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.GridEnvelope 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.

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 null 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.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 GeneralGridGeometry.

Parameters:
other - The other grid geometry to copy.
Since:
2.5

GeneralGridGeometry

public GeneralGridGeometry(org.opengis.coverage.grid.GridEnvelope gridRange,
                           org.opengis.referencing.operation.MathTransform gridToCRS,
                           org.opengis.referencing.crs.CoordinateReferenceSystem crs)
                    throws org.opengis.geometry.MismatchedDimensionException,
                           java.lang.IllegalArgumentException
Constructs a new grid geometry from a grid range and a math transform mapping pixel center.

Parameters:
gridRange - The valid coordinate range of a grid coverage, or null if none.
gridToCRS - The math transform which allows for the transformations from grid coordinates (pixel's center) to real world earth coordinates. May be null, but this is not recommanded.
crs - The coordinate reference system for the "real world" coordinates, or null if unknown. This CRS is given to the envelope.
Throws:
org.opengis.geometry.MismatchedDimensionException - if the math transform and the CRS don'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.GridEnvelope gridRange,
                           org.opengis.referencing.datum.PixelInCell anchor,
                           org.opengis.referencing.operation.MathTransform gridToCRS,
                           org.opengis.referencing.crs.CoordinateReferenceSystem crs)
                    throws org.opengis.geometry.MismatchedDimensionException,
                           java.lang.IllegalArgumentException
Constructs a new grid geometry from a grid range and a math transform mapping pixel center or corner. This is the most general constructor, the one that gives the maximal control over the grid geometry to be created.

Parameters:
gridRange - The valid coordinate range of a grid coverage, or null if none.
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 recommanded.
crs - The coordinate reference system for the "real world" coordinates, or null if unknown. This CRS is given to the envelope.
Throws:
org.opengis.geometry.MismatchedDimensionException - if the math transform and the CRS don'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.5

GeneralGridGeometry

public GeneralGridGeometry(org.opengis.referencing.datum.PixelInCell anchor,
                           org.opengis.referencing.operation.MathTransform gridToCRS,
                           org.opengis.geometry.Envelope envelope)
                    throws org.opengis.geometry.MismatchedDimensionException,
                           java.lang.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.
Throws:
org.opengis.geometry.MismatchedDimensionException - if the math transform and the envelope doesn't have consistent dimensions.
java.lang.IllegalArgumentException - if the math transform can't transform coordinates in the domain of the grid range.
Since:
2.5

GeneralGridGeometry

public GeneralGridGeometry(org.opengis.coverage.grid.GridEnvelope gridRange,
                           org.opengis.geometry.Envelope userRange)
                    throws org.opengis.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 in GridToEnvelopeMapper javadoc. More specifically, heuristic rules are applied for:

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.geometry.MismatchedDimensionException - if the grid range and the envelope doesn't have consistent dimensions.
Since:
2.2

GeneralGridGeometry

@Deprecated
public GeneralGridGeometry(org.opengis.coverage.grid.GridEnvelope gridRange,
                                      org.opengis.geometry.Envelope userRange,
                                      boolean[] reverse,
                                      boolean swapXY)
                    throws org.opengis.geometry.MismatchedDimensionException
Deprecated. Use GridToEnvelopeMapper instead, which provides more control.

Constructs a new grid geometry from an envelope. This convenience constructor delegates the work to GridToEnvelopeMapper; see its javadoc for details.

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 null value reverse no axis. Callers will typically set reverse[1] to true in order to reverse the y axis direction.
swapXY - If true, then the two first axis will be interchanged. Callers will typically set this argument to true when the geographic coordinate system has axis in the (y,x) order. The reverse parameter then apply to axis after the swap.
Throws:
org.opengis.geometry.MismatchedDimensionException - if the grid range and the envelope doesn't have consistent dimensions.
Since:
2.2
Method Detail

getDimension

public int getDimension()
Returns the number of dimensions.

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 null).
Throws:
InvalidGridGeometryException - if this grid geometry has no CRS (i.e. isDefined(CRS_BITMASK) returned false).
Since:
2.2
See Also:
GridGeometry2D.getCoordinateReferenceSystem2D()

getEnvelope

public org.opengis.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 null).
Throws:
InvalidGridGeometryException - if this grid geometry has no envelope (i.e. isDefined(ENVELOPE_BITMASK) returned false).
See Also:
GridGeometry2D.getEnvelope2D()

getGridRange

public org.opengis.coverage.grid.GridEnvelope 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 null).
Throws:
InvalidGridGeometryException - if this grid geometry has no grid range (i.e. isDefined(GRID_RANGE_BITMASK) returned false).
See Also:
GridGeometry2D.getGridRange2D()

getGridToCRS

public org.opengis.referencing.operation.MathTransform getGridToCRS()
                                                             throws InvalidGridGeometryException
Returns the transform from grid coordinates to real world earth coordinates. The transform is often an affine transform. 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:
getGridToCRS in interface org.opengis.coverage.grid.GridGeometry
Returns:
The transform (never null).
Throws:
InvalidGridGeometryException - if this grid geometry has no transform (i.e. isDefined(GRID_TO_CRS_BITMASK) returned false).
Since:
2.3
See Also:
GridGeometry2D.getGridToCRS2D()

getGridToCRS

public org.opengis.referencing.operation.MathTransform getGridToCRS(org.opengis.referencing.datum.PixelInCell anchor)
                                                             throws InvalidGridGeometryException
Returns the transform from grid coordinates to real world earth coordinates. This is similar to getGridToCRS() except that the transform may maps other parts than pixel center.

Parameters:
anchor - The pixel part to map.
Returns:
The transform (never null).
Throws:
InvalidGridGeometryException - if this grid geometry has no transform (i.e. isDefined(GRID_TO_CRS_BITMASK) returned false).
Since:
2.3
See Also:
getGridToCRS(org.opengis.referencing.datum.PixelInCell)

isDefined

public boolean isDefined(int bitmask)
                  throws java.lang.IllegalArgumentException
Returns true if all the parameters specified by the argument are set.

Parameters:
bitmask - Any combinaison of CRS_BITMASK, ENVELOPE_BITMASK, GRID_RANGE_BITMASK and GRID_TO_CRS_BITMASK.
Returns:
true 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
See Also:
ImageLayout.isValid(int)

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.

Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object object)
Compares the specified object with this grid geometry for equality.

Overrides:
equals in class java.lang.Object
Parameters:
object - The object to compare with.
Returns:
true if the given object is equals to this grid geometry.

toString

public java.lang.String toString()
Returns a string representation of this grid geometry. The returned string is implementation dependent. It is usually provided for debugging purposes.

Overrides:
toString in class java.lang.Object


Copyright © 1996-2010 Geotools. All Rights Reserved.