Package org.geotools.coverage.grid

Class GridGeometry2D

Object
GeneralGridGeometry
GridGeometry2D
All Implemented Interfaces:
Serializable, GridGeometry
public class GridGeometry2D extends GeneralGridGeometry
Describes the valid range of grid coordinates and the math transform, in the special case where only 2 dimensions are in use. By "in use", we means dimension with more than 1 pixel. 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.
Since:
2.1
Author:
Martin Desruisseaux (IRD)
See Also:

  • Field Details

  • Constructor Details

    • GridGeometry2D

      public GridGeometry2D(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 GridGeometry2D.
      Parameters:
      other - The other grid geometry to copy.
      Since:
      2.5
      See Also:

    • GridGeometry2D

      public GridGeometry2D(GridEnvelope gridRange, MathTransform gridToCRS, CoordinateReferenceSystem crs) throws IllegalArgumentException, MismatchedDimensionException
      Constructs a new grid geometry from a grid range and a math transform. The arguments are passed unchanged to the super-class constructor. However, they must obey to the following additional constraints:

      • Only two dimensions in the grid range can have a span larger than 1.
      Parameters:
      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.
      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 gridRange 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 range.
      Since:
      2.2

    • GridGeometry2D

      public GridGeometry2D(GridEnvelope gridRange, 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(gridRange, 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:
      gridRange - The valid coordinate range of 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 range.
      Since:
      2.5

    • GridGeometry2D

      public GridGeometry2D(GridEnvelope gridRange, 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(gridRange, 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:
      gridRange - The valid coordinate range of 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 gridRange 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 range.
      Since:
      2.5

    • GridGeometry2D

      public GridGeometry2D(PixelInCell anchor, MathTransform gridToCRS, Bounds 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 range.
      Since:
      2.5

    • GridGeometry2D

      public GridGeometry2D(GridEnvelope gridRange, Bounds userRange) 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:
      gridRange - The valid coordinate range of a grid coverage.
      userRange - The corresponding coordinate range in user coordinate.
      Throws:
      IllegalArgumentException - if gridRange has more than 2 dimensions with a length larger than 1.
      MismatchedDimensionException - if the grid range and the CRS doesn't have consistent dimensions.
      Since:
      2.2

    • GridGeometry2D

      public GridGeometry2D(Rectangle gridRange, Rectangle2D userRange)
      Constructs a new two-dimensional grid geometry using java.awt objects. Initialising corresponding GeoTools objects if necessary, and calls GridGeometry2D(GridEnvelope, Bounds)
      Parameters:
      gridRange - The valid coordinate range of a grid coverage. Increasing x values goes right and increasing y values goes down.
      userRange - The corresponding coordinate range in user coordinate.

  • Method Details

    • wrap

      public static GridGeometry2D wrap(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 wrap.
      Returns:
      The wrapped geometry, or null if other was null.
      Since:
      2.5

    • reduce

      public ReferencedEnvelope reduce(Bounds bounds)
      Reduces the specified bounds to a two-dimensional ReferencedEnvelope. If the given bounds 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:
      bounds - The bounds to reduce, or null. This envelope will not be modified.
      Returns:
      An ReferencedEnvelope with exactly 2 dimensions, or null if bounds was null. The returned ReferencedEnvelope 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 garanteed 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:

    • getEnvelope2D

      public ReferencedEnvelope 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_BITMASK) returned false).
      See Also:

    • getGridRange2D

      public GridEnvelope2D getGridRange2D() throws InvalidGridGeometryException
      Returns the two-dimensional part of the grid range as a rectangle. Note that the returned object is a Rectangle subclass.
      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:

    • 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 interoperability with Java2D.
      Throws:
      InvalidGridGeometryException - if a two-dimensional transform is not available for this grid geometry.
      Since:
      2.3
      See Also:

    • getCRSToGrid2D

      public MathTransform2D getCRSToGrid2D() throws InvalidGridGeometryException
      Returns a math transform for the two dimensional part for conversion from world to grid coordinates. 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 real world earth coordinates to grid coordinates, operating only on two dimensions. The returned transform is often an instance of AffineTransform, which makes it convenient for interoperability with Java2D.
      Throws:
      InvalidGridGeometryException - if a two-dimensional transform is not available for this grid geometry.
      Since:
      2.6
      See Also:

    • 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

    • getCRSToGrid2D

      public MathTransform2D getCRSToGrid2D(PixelOrientation orientation)
      Returns a math transform for the two dimensional part. This method is similar to getCRSToGrid2D() except that the transform may map 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 world coordinates to grid coordinates.
      Throws:
      InvalidGridGeometryException - if a two-dimensional transform is not available for this grid geometry.
      Since:
      2.6

    • 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

    • worldToGrid

      public final GridCoordinates2D worldToGrid(Position point) throws InvalidGridGeometryException, TransformException
      Transforms a point represented by a DirectPosition object from world to grid coordinates. If the point contains a CoordinateReferenceSystem, and it differs from that of the coverage, it will be reprojected on the fly. The the nearest grid cell centre to the input point is found.

      Users needing more control over the nature of the conversion can access the MathsTransform provided by getCRSToGrid2D(PixelOrientation) which is accessed via #getGridGeometry().

      Parameters:
      point - The point in world coordinate system.
      Returns:
      A new point in the grid coordinate system as a GridCoordinates2D object
      Throws:
      InvalidGridGeometryException - if a two-dimensional inverse transform is not available.
      TransformException - if the transformation failed.
      Since:
      2.6

    • worldToGrid

      public final GridEnvelope2D worldToGrid(BoundingBox envelope) throws TransformException, InvalidGridGeometryException
      Transforms a rectangle represented by an Envelope2D object from world to grid coordinates. If the envelope contains a CoordinateReferenceSystem, it must be the same as that of this coverage, otherwise an exception is thrown.

      The GridEnvelope2D returned contains the range of cells whose centers lie inside the input Envelope2D

      Users needing more control over the nature of the conversion can access the MathsTransform provided by getCRSToGrid2D(PixelOrientation) which is accessed via #getGridGeometry().

      Parameters:
      envelope - The envelope in world coordinate system.
      Returns:
      The corresponding rectangle in the grid coordinate system as a new GridEnvelope2D object
      Throws:
      IllegalArgumentException - if the coordinate reference system of the envelope is not null and does not match that of the coverage
      InvalidGridGeometryException - if a two-dimensional inverse transform is not available for this grid geometry.
      TransformException - if the transformation failed.
      Since:
      2.6

    • worldToGrid

      public final GridEnvelope2D worldToGrid(ReferencedEnvelope envelope) throws TransformException, InvalidGridGeometryException
      Transforms a rectangle represented by an ReferencedEnvelope (or BoundingBox) from world to grid coordinates. If the envelope contains a CoordinateReferenceSystem, it must be the same as that of this coverage, otherwise an exception is thrown.

      The GridEnvelope2D returned contains the range of cells whose centers lie inside the input Envelope2D

      Users needing more control over the nature of the conversion can access the MathsTransform provided by getCRSToGrid2D(PixelOrientation) which is accessed via #getGridGeometry().

      Parameters:
      envelope - The envelope in world coordinate system.
      Returns:
      The corresponding rectangle in the grid coordinate system as a new ReferencedEnvelope object
      Throws:
      IllegalArgumentException - if the coordinate reference system of the envelope is not null and does not match that of the coverage
      InvalidGridGeometryException - if a two-dimensional inverse transform is not available for this grid geometry.
      TransformException - if the transformation failed.
      Since:
      2.6

    • gridToWorld

      public final Position gridToWorld(GridCoordinates2D point) throws TransformException
      Transforms a point represented by a GridCoordinates2D object from grid to world coordinates. The coordinates returned are those of the centre of the grid cell in which the point lies.

      Users needing more control over the nature of the conversion (e.g. calculating cell corner coordinates) can use the MathsTransform provided by getGridToCRS2D(PixelOrientation) which is accessed via #getGridGeometry().

      Parameters:
      point - The point in world coordinate system.
      Returns:
      A new point in the grid coordinate system as a GridCoordinates2D object
      Throws:
      TransformException - if the transformation failed.
      IllegalArgumentException - if the point lies outside the coverage
      Since:
      2.6

    • gridToWorld

      public final ReferencedEnvelope gridToWorld(GridEnvelope2D gridEnv) throws TransformException
      Transforms an represented by a GridEnvelope2D object from grid to world coordinates. The bounds of the Envelope2D object returned correspond to the outer edges of the grid cells within the input envelope.

      Users needing more control over the nature of the conversion can use the MathsTransform provided by getGridToCRS2D(PixelOrientation) which is accessed via #getGridGeometry().

      Parameters:
      gridEnv - The rectangle of grid coordinates to convert
      Returns:
      World coordinates of the rectangle as a new Envelope2D object
      Throws:
      TransformException - if the transformation failed.
      IllegalArgumentException - if the input rectangle lies outside the coverage
      Since:
      2.6

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

    • hashCode

      public int hashCode()
      Description copied from class: GeneralGridGeometry
      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 GeneralGridGeometry

    • toCanonical

      public GridGeometry2D toCanonical()
      Returns a "canonical" representation of the grid geometry, that is, one whose grid range originates in 0,0, but maps to the same real world coordinates. This setup helps in image processing, as JAI is not meant to be used for images whose ordinates are in the range of the millions and starts to exhibit numerical issues when used there.
      Since:
      13.3