Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.geotoolkit.coverage.grid
Class GeneralGridGeometry

Object
  extended by GeneralGridGeometry
All Implemented Interfaces:
Serializable, GridGeometry
Direct Known Subclasses:
GridGeometry2D
@Immutable
public class GeneralGridGeometry
extends Object
implements GridGeometry, Serializable

Describes the valid range of grid coordinates and the transform from those 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 envelope 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:
1.2
Version:
3.20
Author:
Martin Desruisseaux (IRD, Geomatys), Alessio Fabiani (Geosolutions)
See Also:
GridGeometry2D, ImageGeometry, Serialized Form
Module:
coverage/geotk-coverage (download)    View source code for this class

Field Summary
static int CRS
          A bitmask to specify the validity of the coordinate reference system.
protected  ImmutableEnvelope envelope
          The geodetic envelope, or null if none.
static int ENVELOPE
          A bitmask to specify the validity of the geodetic envelope.
protected  GridEnvelope extent
          The valid domain of a grid coverage, or null if none.
static int EXTENT
          A bitmask to specify the validity of the grid envelope.
static int GRID_RANGE
          Deprecated. Renamed EXTENT.
static int GRID_TO_CRS
          A bitmask to specify the validity of the grid to CRS transform.
protected  MathTransform gridToCRS
          The math transform from grid indices to "real world" coordinates, or null if none.
 
Constructor Summary
GeneralGridGeometry(GridEnvelope extent, Envelope envelope)
          Constructs a new grid geometry from an envelope.
GeneralGridGeometry(GridEnvelope extent, MathTransform gridToCRS, CoordinateReferenceSystem crs)
          Constructs a new grid geometry from a grid envelope and a math transform mapping pixel center.
GeneralGridGeometry(GridEnvelope extent, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs)
          Constructs a new grid geometry from a grid envelope and a math transform mapping pixel center or corner.
GeneralGridGeometry(GridGeometry other)
          Creates a new grid geometry with the same values than the given grid geometry.
GeneralGridGeometry(PixelInCell anchor, MathTransform gridToCRS, Envelope envelope)
          Constructs a new grid geometry from an envelope and a math transform.
 
Method Summary
 boolean equals(Object object)
          Compares the specified object with this grid geometry for equality.
 CoordinateReferenceSystem getCoordinateReferenceSystem()
          Returns the "real world" coordinate reference system.
 int getDimension()
          Returns the number of dimensions of the grid.
 Envelope getEnvelope()
          Returns the bounding box of "real world" coordinates for this grid geometry.
 GridEnvelope getExtent()
          Returns the valid coordinate range of a grid coverage.
 GridEnvelope getGridRange()
          Deprecated. Renamed getExtent().
 MathTransform getGridToCRS()
          Returns the transform from grid coordinates to real world earth coordinates.
 MathTransform getGridToCRS(PixelInCell anchor)
          Returns the transform from grid coordinates to real world earth coordinates.
 double[] getResolution()
          Returns the grid resolution in units of the Coordinate Reference System axes, or null if it can't be computed.
 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.
 String toString()
          Returns a string representation of this grid geometry.
 
Methods inherited from class 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 in 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 geodetic envelope. This is given in argument to the isDefined(int) method.

Since:
2.2
See Also:
Constant Field Values

EXTENT

public static final int EXTENT
A bitmask to specify the validity of the grid envelope. This is given in argument to the isDefined(int) method.

Since:
3.20 (derived from 2.2)
See Also:
Constant Field Values

GRID_RANGE

@Deprecated
public static final int GRID_RANGE
Deprecated. Renamed EXTENT.
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 in argument to the isDefined(int) method.

Since:
2.2
See Also:
Constant Field Values

extent

protected final GridEnvelope extent
The valid domain 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.
Note: This field name was gridRange in all Geotk versions prior 3.20. The grid range name was defined in the legacy OGC 01-004 specification, while extent is defined in the ISO 19123 specification. This field has been renamed in order to avoid confusion with coverage range, which has a totally different meaning in ISO 19123.

See Also:
RenderedImage.getMinX(), RenderedImage.getMinY(), RenderedImage.getWidth(), RenderedImage.getHeight()

envelope

protected final ImmutableEnvelope envelope
The geodetic envelope, or null if none. If non-null, this envelope is usually the grid envelope transformed to real world coordinates. The coordinate reference system (CRS) of this envelope defines the "real world" CRS of this grid geometry.

Since:
3.20

gridToCRS

protected final MathTransform gridToCRS
The math transform from grid indices to "real world" coordinates, or null if none. This math transform is usually affine. It maps pixel center to "real world" coordinate using the following line: 
DirectPosition aCellIndices = ...:
DirectPosition aPixelCenter = gridToCRS.transform(pixels, aCellIndices);

Constructor Detail

GeneralGridGeometry

public GeneralGridGeometry(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(GridEnvelope extent,
                           MathTransform gridToCRS,
                           CoordinateReferenceSystem crs)
                    throws MismatchedDimensionException,
                           IllegalArgumentException
Constructs a new grid geometry from a grid envelope and a math transform mapping pixel center.

Parameters:
extent - The valid extent of grid coordinates, or null if none.
gridToCRS - The math transform which allows for the transformations from grid coordinates (pixel center) to real world earth coordinates. May be null, but this is not recommended.
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 the math transform can't transform coordinates in the domain of the specified grid envelope.
Since:
2.2

GeneralGridGeometry

public GeneralGridGeometry(GridEnvelope extent,
                           PixelInCell anchor,
                           MathTransform gridToCRS,
                           CoordinateReferenceSystem crs)
                    throws MismatchedDimensionException,
                           IllegalArgumentException
Constructs a new grid geometry from a grid envelope 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:
extent - The valid extent of grid coordinates, 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 recommended.
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 the math transform can't transform coordinates in the domain of the specified grid envelope.
Since:
2.5

GeneralGridGeometry

public GeneralGridGeometry(PixelInCell anchor,
                           MathTransform gridToCRS,
                           Envelope envelope)
                    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.
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 envelope.
Since:
2.5

GeneralGridGeometry

public GeneralGridGeometry(GridEnvelope extent,
                           Envelope envelope)
                    throws 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:
extent - The valid extent of grid coordinates, or null if none.
envelope - The corresponding domain in "real world" coordinates. 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:
MismatchedDimensionException - if the grid envelope and the georeferenced envelope doesn't have consistent dimensions.
Since:
2.2
Method Detail

getDimension

public int getDimension()
Returns the number of dimensions of the grid. This is typically the same than the number of dimension of the envelope or the CRS, but not necessarily.

Returns:
The number of grid dimensions.

getCoordinateReferenceSystem

public 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) returned false).
Since:
2.2
See Also:
GridGeometry2D.getCoordinateReferenceSystem2D()

getEnvelope

public Envelope getEnvelope()
                     throws InvalidGridGeometryException
Returns the bounding box of "real world" coordinates for this grid geometry. This envelope is the grid extent 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) returned false).
See Also:
GridGeometry2D.getEnvelope2D()

getExtent

public GridEnvelope getExtent()
                       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:
getExtent in interface GridGeometry
Returns:
The grid envelope (never null).
Throws:
InvalidGridGeometryException - if this grid geometry has no extent (i.e. isDefined(EXTENT) returned false).
Since:
3.20 (derived from 1.2)
See Also:
GridGeometry2D.getGridRange2D()

getGridRange

@Deprecated
public GridEnvelope getGridRange()
                          throws InvalidGridGeometryException
Deprecated. Renamed getExtent().

Specified by:
getGridRange in interface GridGeometry
Throws:
InvalidGridGeometryException

getGridToCRS

public 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 GridGeometry
Returns:
The transform (never null).
Throws:
InvalidGridGeometryException - if this grid geometry has no transform (i.e. isDefined(GRID_TO_CRS) returned false).
Since:
2.3
See Also:
GridGeometry2D.getGridToCRS2D()

getGridToCRS

public MathTransform getGridToCRS(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) returned false).
Since:
2.3
See Also:
GridGeometry2D.getGridToCRS(PixelOrientation), DiscreteReferencingFactory.getAffineTransform(GridGeometry, PixelInCell), PixelTranslation

getResolution

public double[] getResolution()
Returns the grid resolution in units of the Coordinate Reference System axes, or null if it can't be computed. If non-null, the length of the returned array is the number of CRS dimension.

Returns:
The grid resolution, or null if unknown.
Since:
3.10

isDefined

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

Parameters:
bitmask - Any combination of CRS, ENVELOPE, EXTENT and GRID_TO_CRS.
Returns:
true if all specified attributes are defined (i.e. invoking the corresponding method will not thrown an InvalidGridGeometryException).
Throws:
IllegalArgumentException - if the specified bitmask is not a combination 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 Object

equals

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

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

toString

public 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 Object
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2009-2012 Geotoolkit.org. All Rights Reserved.