Package org.geotools.coverage.grid

Class 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:
    ImageGeometry, GeneralGridGeometry, Serialized Form

    • Constructor Detail

      • 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:
        wrap(org.geotools.api.coverage.grid.GridGeometry)

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

      • 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

      • 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:
        getGridToCRS(org.geotools.api.metadata.spatial.PixelOrientation)

      • 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:
        getGridToCRS(org.geotools.api.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

      • 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