org.geotoolkit.coverage.grid
Class GridGeometry2D

Object
  GeneralGridGeometry
      GridGeometry2D

All Implemented Interfaces:

Serializable, GridGeometry

@Immutable
public class GridGeometry2D
extends GeneralGridGeometry

A GeneralGridGeometry where only 2 dimensions have more than 1 cell. 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.

Constructors
The most complete way to create a GridGeometry2D instance is to provide all the following information:

• An optional grid envelope - See the constraints documented below.
• An optional "grid to CRS" transform.
• An optional PixelInCell or PixelOrientation code, which specify whatever the source of the "grid to CRS" transform maps a pixel corner or the pixel center.
• An optional coordinate reference system (CRS) which is the target of the grid to CRS transform.

This class defines also some convenience constructors for inferring the math transform from a geodetic envelope. However those convenience constructors use heuristic rules which try to guess whatever an axis should be reversed according common practice. Users should alway prefer the above listed argument types when possible.

Constraints
The above-listed arguments shall comply with the following constraints:

• Only two dimensions in the grid envelope can have a span larger than 1.
• If the grid geometry describes a BufferedImage, then the lowest valid grid ordinates shall be zero. For other kind of RenderedImage, the lowest ordinates may be non-zero.

Since:

2.1

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

ImageGeometry, GeneralGridGeometry, Serialized Form

Module:

coverage/geotk-coverage (download)

View source code for this class

Field Summary

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, envelope, ENVELOPE, extent, EXTENT, GRID_RANGE, GRID_TO_CRS, gridToCRS

Constructor Summary

GridGeometry2D(GridEnvelope extent, Envelope envelope)
Constructs a new grid geometry from an envelope.

GridGeometry2D(GridEnvelope extent, MathTransform gridToCRS, CoordinateReferenceSystem crs)
Constructs a new grid geometry from a grid envelope and a math transform.

GridGeometry2D(GridEnvelope extent, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs, Hints hints)
Constructs a new grid geometry from a math transform.

GridGeometry2D(GridEnvelope extent, 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 extent, Rectangle2D envelope)
Constructs a new two-dimensional grid geometry.

Method Summary

static GridGeometry2D	castOrCopy(GridGeometry other) Returns the given grid geometry as a GridGeometry2D.
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.
Envelope2D	getEnvelope2D() Returns the two-dimensional bounding box for the coverage domain in coordinate reference system coordinates.
GridEnvelope2D	getExtent2D() Returns the two-dimensional part of the grid envelope as a rectangle.
GridEnvelope2D	getGridRange2D() Deprecated. Renamed getGridRange2D().
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.
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.

Methods inherited from class GeneralGridGeometry

getCoordinateReferenceSystem, getDimension, getEnvelope, getExtent, getGridRange, getGridToCRS, getGridToCRS, getResolution, hashCode, 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 extent. Their values are usually 0 and 1 respectively.

Notes:

• It is guaranteed 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 extent. Their values are usually 0 and 1 respectively.

Notes:

• It is guaranteed 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.

Notes:

• It is guaranteed that axisDimensionX < axisDimensionY.
• There is no guarantee that gridDimensionX maps to axisDimensionX and gridDimensionY maps to axisDimensionY, since axis may be interchanged.

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.

Notes:

• It is guaranteed that axisDimensionX < axisDimensionY.
• There is no guarantee that gridDimensionX maps to axisDimensionX and gridDimensionY maps to axisDimensionY, since axis may be interchanged.

Constructor Detail

GridGeometry2D

public GridGeometry2D(GridGeometry other)
               throws IllegalArgumentException

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.

Throws:

IllegalArgumentException - If the given grid geometry does not comply to the constraints documented in the class javadoc.

Since:

2.5

See Also:

castOrCopy(GridGeometry)

GridGeometry2D

public GridGeometry2D(GridEnvelope extent,
                      MathTransform gridToCRS,
                      CoordinateReferenceSystem crs)
               throws IllegalArgumentException,
                      MismatchedDimensionException

Constructs a new grid geometry from a grid envelope and a math transform. The arguments are passed unchanged to the super-class constructor. However, they must obey to the additional constraints documented in the class javadoc.

Parameters:

extent - The extent of grid coordinates in 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.

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 extent 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 envelope.

Since:

2.2

See Also:

GridGeometry2D(GridEnvelope, PixelInCell, MathTransform, CoordinateReferenceSystem, Hints), GridGeometry2D(GridEnvelope, PixelOrientation, MathTransform, CoordinateReferenceSystem, Hints)

GridGeometry2D

public GridGeometry2D(GridEnvelope extent,
                      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(extent, 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:

extent - The extent of grid coordinates in 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 envelope.

Since:

2.5

GridGeometry2D

public GridGeometry2D(GridEnvelope extent,
                      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(extent, 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:

extent - The extent of grid coordinates in 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 extent 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 envelope.

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 envelope.

Since:

2.5

GridGeometry2D

public GridGeometry2D(GridEnvelope extent,
                      Envelope envelope)
               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:

extent - The valid coordinate range of a grid coverage.

envelope - The corresponding coordinate range in user coordinate.

Throws:

IllegalArgumentException - if extent has more than 2 dimensions with a span larger than 1.

MismatchedDimensionException - if the grid envelope and the CRS doesn't have consistent dimensions.

Since:

2.2

GridGeometry2D

public GridGeometry2D(Rectangle extent,
                      Rectangle2D envelope)

Constructs a new two-dimensional grid geometry. A math transform will be computed automatically with an inverted y axis (i.e. extent and userRange are assumed to have y axis in opposite direction).

Parameters:

extent - The valid domain of grid coordinates. Increasing x values goes right and increasing y values goes down.

envelope - 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

castOrCopy

public static GridGeometry2D castOrCopy(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 cast or copy.

Returns:

The wrapped geometry, or null if other was null.

Since:

3.19 (derived from 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 guaranteed 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) returned false).

See Also:

GeneralGridGeometry.getEnvelope()

getExtent2D

public GridEnvelope2D getExtent2D()
                           throws InvalidGridGeometryException

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

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 2.1)

See Also:

GeneralGridGeometry.getExtent()

getGridRange2D

@Deprecated
public GridEnvelope2D getGridRange2D()
                              throws InvalidGridGeometryException

Deprecated. Renamed getGridRange2D().

Throws:

InvalidGridGeometryException

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 inter-operability 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)

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

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

See Also:

GeneralGridGeometry.getGridToCRS(PixelInCell), PixelTranslation

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.