Class GeneralGridGeometry
- Object
-
- GeneralGridGeometry
-
- All Implemented Interfaces:
Serializable
,GridGeometry
- Direct Known Subclasses:
GridGeometry2D
public class GeneralGridGeometry extends Object implements GridGeometry, 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 envelope (a.k.a. "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, useisDefined(int)
.- Since:
- 2.1
- Author:
- Martin Desruisseaux (IRD), Simone Giannecchini, GeoSolutions SAS
- See Also:
GridGeometry2D
,ImageGeometry
, Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description 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 GridEnvelope
gridRange
The valid coordinate range of a grid coverage, ornull
if none.protected MathTransform
gridToCRS
The math transform (usually an affine transform), ornull
if none.
-
Constructor Summary
Constructors Constructor Description GeneralGridGeometry(GridEnvelope gridRange, Bounds userRange)
Constructs a new grid geometry from an envelope.GeneralGridGeometry(GridEnvelope gridRange, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs)
Constructs a new grid geometry from a grid range and a math transform mapping pixel center or corner.GeneralGridGeometry(GridEnvelope gridRange, MathTransform gridToCRS, CoordinateReferenceSystem crs)
Constructs a new grid geometry from a grid range and a math transform mapping pixel center.GeneralGridGeometry(GridGeometry other)
Creates a new grid geometry with the same values than the given grid geometry.GeneralGridGeometry(PixelInCell anchor, MathTransform gridToCRS, Bounds envelope)
Constructs a new grid geometry from an envelope and a math transform.GeneralGridGeometry(PixelInCell anchor, MathTransform gridToCRS, Bounds envelope, boolean gridMaxInclusive, boolean preserveGridToCRS)
Constructs a new grid geometry from an envelope and a math transform.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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.Bounds
getEnvelope()
Returns the bounding box of "real world" coordinates for this grid geometry.GridEnvelope
getGridRange()
Returns the valid coordinate range of a grid coverage.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.int
hashCode()
Returns a hash value for this grid geometry.boolean
isDefined(int bitmask)
Returnstrue
if all the parameters specified by the argument are set.String
toString()
Returns a string representation of this grid geometry.
-
-
-
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 theisDefined(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 theisDefined(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 theisDefined(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 theisDefined(int)
method.- Since:
- 2.2
- See Also:
- Constant Field Values
-
gridRange
protected final GridEnvelope gridRange
The valid coordinate range of a grid coverage, ornull
if none. The lowest valid grid coordinate is zero forBufferedImage
, but may be non-zero for arbitraryRenderedImage
. A grid with 512 cells can have a minimum coordinate of 0 and maximum of 512, with 511 as the highest valid index.
-
gridToCRS
protected MathTransform gridToCRS
The math transform (usually an affine transform), ornull
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(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 aGeneralGridGeometry
.- Parameters:
other
- The other grid geometry to copy.- Since:
- 2.5
-
GeneralGridGeometry
public GeneralGridGeometry(GridEnvelope gridRange, MathTransform gridToCRS, CoordinateReferenceSystem crs) throws MismatchedDimensionException, 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, ornull
if none.gridToCRS
- The math transform which allows for the transformations from grid coordinates (pixel's center) to real world earth coordinates. May benull
, but this is not recommanded.crs
- The coordinate reference system for the "real world" coordinates, ornull
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 range.- Since:
- 2.2
-
GeneralGridGeometry
public GeneralGridGeometry(GridEnvelope gridRange, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs) throws MismatchedDimensionException, 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, ornull
if none.anchor
-CELL_CENTER
for OGC conventions orCELL_CORNER
for Java2D/JAI conventions.gridToCRS
- The math transform which allows for the transformations from grid coordinates to real world earth coordinates. May benull
, but this is not recommended.crs
- The coordinate reference system for the "real world" coordinates, ornull
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 range.- Since:
- 2.5
-
GeneralGridGeometry
public GeneralGridGeometry(PixelInCell anchor, MathTransform gridToCRS, Bounds envelope, boolean gridMaxInclusive, boolean preserveGridToCRS) 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 theanchor
argument.It is worth to point a few guidelines for the usage of the gridMaxInclusive parameter. In case we are using this contructor for a reprojection it might be worth using a
false
value for this parameter since we would not force to create a new raster that might be slightly bigger than the original one, causing problems with black or nodata collars appearing after a resample. In case we are trying to build a source raster area to be used at reading time, in that case we may want to providetrue
for gridMaxInclusive since we may want to read an area that is slightly bigger than what we need to be sure we actually reading something.- Parameters:
anchor
-CELL_CENTER
for OGC conventions orCELL_CORNER
for Java2D/JAI conventions.gridToCRS
- The math transform which allows for the transformations from grid coordinates to real world earth coordinates. May benull
, but this is not recommended.envelope
- The envelope (including CRS) of a grid coverage, ornull
if none.gridMaxInclusive
- Tells us whether or not the resulting gridRange max values should be inclusive or not. See notes above.preserveGridToCRS
- Tells us whether we should try to preserve the the gridToCRS or the envelope most part of the time we won't be able to preserve both for our purposes.- 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.7
-
GeneralGridGeometry
public GeneralGridGeometry(PixelInCell anchor, MathTransform gridToCRS, Bounds 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 theanchor
argument.- Parameters:
anchor
-CELL_CENTER
for OGC conventions orCELL_CORNER
for Java2D/JAI conventions.gridToCRS
- The math transform which allows for the transformations from grid coordinates to real world earth coordinates. May benull
, but this is not recommended.envelope
- The envelope (including CRS) of a grid coverage, ornull
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 range.- Since:
- 2.5
-
GeneralGridGeometry
public GeneralGridGeometry(GridEnvelope gridRange, Bounds userRange) 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 inGridToEnvelopeMapper
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:
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 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)
returnedfalse
).- Since:
- 2.2
- See Also:
GridGeometry2D.getCoordinateReferenceSystem2D()
-
getEnvelope
public Bounds 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)
returnedfalse
).- See Also:
GridGeometry2D.getEnvelope2D()
-
getGridRange
public GridEnvelope getGridRange() throws InvalidGridGeometryException
Returns the valid coordinate range of a grid coverage. The lowest valid grid coordinate is zero forBufferedImage
, but may be non-zero for arbitraryRenderedImage
. 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 interfaceGridGeometry
- Returns:
- The grid range (never
null
). - Throws:
InvalidGridGeometryException
- if this grid geometry has no grid range (i.e.isDefined(GRID_RANGE_BITMASK)
returnedfalse
).- See Also:
GridGeometry2D.getGridRange2D()
-
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 byCoverage.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 interfaceGridGeometry
- Returns:
- The transform (never
null
). - Throws:
InvalidGridGeometryException
- if this grid geometry has no transform (i.e.isDefined(GRID_TO_CRS_BITMASK)
returnedfalse
).- 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 togetGridToCRS()
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)
returnedfalse
).- Since:
- 2.3
- See Also:
getGridToCRS(org.geotools.api.referencing.datum.PixelInCell)
-
isDefined
public boolean isDefined(int bitmask) throws IllegalArgumentException
Returnstrue
if all the parameters specified by the argument are set.- Parameters:
bitmask
- Any combination ofCRS_BITMASK
,ENVELOPE_BITMASK
,GRID_RANGE_BITMASK
andGRID_TO_CRS_BITMASK
.- Returns:
true
if all specified attributes are defined (i.e. invoking the corresponding method will not thrown anInvalidGridGeometryException
).- 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.
-
equals
public boolean equals(Object object)
Compares the specified object with this grid geometry for equality.
-
-