Class GridEnvelope2D

  • All Implemented Interfaces:
    Shape, Serializable, Cloneable, GridEnvelope, Cloneable

    public class GridEnvelope2D
    extends Rectangle
    implements GridEnvelope, Cloneable
    Defines a range of two-dimensional grid coverage coordinates. This implementation extends Rectangle for interoperability with Java2D. Note that at the opposite of GeneralGridEnvelope, this class is mutable.

    CAUTION: ISO 19123 defines high coordinates as inclusive. We follow this specification for all getters methods, but keep in mind that this is the opposite of Java2D usage where Rectangle maximal values are exclusive.

    Since:
    2.5
    Author:
    Martin Desruisseaux
    See Also:
    GeneralGridEnvelope, Serialized Form
    • Nested Class Summary

      • Nested classes/interfaces inherited from class Rectangle2D

        Rectangle2D.Double, Rectangle2D.Float
    • Field Summary

      • Fields inherited from class Rectangle

        height, width, x, y
      • Fields inherited from class Rectangle2D

        OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      GridEnvelope2D clone()
      Returns a clone of this grid envelope.
      int getDimension()
      Returns the number of dimensions, which is always 2.
      GridCoordinates2D getHigh()
      Returns the valid maximum inclusive grid coordinates.
      int getHigh​(int dimension)
      Returns the valid maximum inclusive grid coordinate along the specified dimension.
      GridCoordinates2D getLow()
      Returns the valid minimum inclusive grid coordinates.
      int getLow​(int dimension)
      Returns the valid minimum inclusive grid coordinate along the specified dimension.
      int getSpan​(int dimension)
      Returns the number of integer grid coordinates along the specified dimension.
      String toString()
      Returns a string représentation of this grid envelope.
      • Methods inherited from class Rectangle

        add, add, add, contains, contains, contains, contains, createIntersection, createUnion, equals, getBounds, getBounds2D, getHeight, getLocation, getSize, getWidth, getX, getY, grow, inside, intersection, intersects, isEmpty, move, outcode, reshape, resize, setBounds, setBounds, setLocation, setLocation, setRect, setSize, setSize, translate, union
      • Methods inherited from class Rectangle2D

        add, add, add, contains, contains, getPathIterator, getPathIterator, hashCode, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, setRect, union
      • Methods inherited from class RectangularShape

        contains, contains, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal
      • Methods inherited from class Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface Shape

        contains, contains, contains, contains, getPathIterator, getPathIterator, intersects, intersects
    • Constructor Detail

      • GridEnvelope2D

        public GridEnvelope2D()
        Creates an initially empty grid envelope.
      • GridEnvelope2D

        public GridEnvelope2D​(Rectangle rectangle)
        Creates a grid envelope initialized to the specified rectangle.
        Parameters:
        rectangle - The rectangle to use for initializing this grid envelope.
      • GridEnvelope2D

        public GridEnvelope2D​(int x,
                              int y,
                              int width,
                              int height)
        Creates a grid envelope initialized to the specified rectangle.
        Parameters:
        x - The minimal x ordinate.
        y - The minimal y ordinate.
        width - The number of valid ordinates along the x axis.
        height - The number of valid ordinates along the y axis.
      • GridEnvelope2D

        public GridEnvelope2D​(Rectangle envelope,
                              PixelInCell anchor)
                       throws IllegalArgumentException
        Casts the specified envelope into a grid envelope. This is sometime useful after an envelope has been transformed from "real world" coordinates to grid coordinates using the grid to CRS transform. The floating point values are rounded toward the nearest integers.

        Notice that highest values are interpreted as non-inclusive

        Anchor
        According OpenGIS specification, grid geometry maps pixel's center. But envelopes typically encompass all pixels. This means that grid coordinates (0,0) has an envelope starting at (-0.5, -0.5). In order to revert back such envelope to a grid envelope, it is necessary to add 0.5 to every coordinates (including the maximum value since it is exclusive in a grid envelope). This offset is applied only if anchor is PixelInCell.CELL_CENTER. Users who don't want such offset should specify PixelInCell.CELL_CORNER.

        The convention is specified as a PixelInCell code instead than the more detailed PixelOrientation because the latter is restricted to the two-dimensional case while the former can be used for any number of dimensions.

        Parameters:
        envelope - The envelope to use for initializing this grid envelope.
        anchor - Whatever envelope coordinates map to pixel center or pixel corner. Should be PixelInCell.CELL_CENTER for OGC convention (an offset of 0.5 will be added to every envelope coordinate values), or PixelInCell.CELL_CORNER for Java2D/JAI convention (no offset will be added).
        Throws:
        IllegalArgumentException - If anchor is not valid.
      • GridEnvelope2D

        public GridEnvelope2D​(ReferencedEnvelope envelope,
                              PixelInCell anchor)
                       throws IllegalArgumentException
        Casts the specified envelope into a grid envelope. This is sometime useful after an envelope has been transformed from "real world" coordinates to grid coordinates using the grid to CRS transform. The floating point values are rounded toward the nearest integers.

        Notice that highest values are interpreted as non-inclusive

        Anchor
        According OpenGIS specification, grid geometry maps pixel's center. But envelopes typically encompass all pixels. This means that grid coordinates (0,0) has an envelope starting at (-0.5, -0.5). In order to revert back such envelope to a grid envelope, it is necessary to add 0.5 to every coordinates (including the maximum value since it is exclusive in a grid envelope). This offset is applied only if anchor is PixelInCell.CELL_CENTER. Users who don't want such offset should specify PixelInCell.CELL_CORNER.

        The convention is specified as a PixelInCell code instead than the more detailed PixelOrientation because the latter is restricted to the two-dimensional case while the former can be used for any number of dimensions.

        Parameters:
        envelope - The envelope to use for initializing this grid envelope.
        anchor - Whatever envelope coordinates map to pixel center or pixel corner. Should be PixelInCell.CELL_CENTER for OGC convention (an offset of 0.5 will be added to every envelope coordinate values), or PixelInCell.CELL_CORNER for Java2D/JAI convention (no offset will be added).
        Throws:
        IllegalArgumentException - If anchor is not valid.
      • GridEnvelope2D

        public GridEnvelope2D​(Rectangle envelope,
                              PixelInCell anchor,
                              boolean isHighIncluded)
                       throws IllegalArgumentException
        Casts the specified envelope into a grid envelope. This is sometime useful after an envelope has been transformed from "real world" coordinates to grid coordinates using the grid to CRS transform. The floating point values are rounded toward the nearest integers.

        Note about rounding mode
        It would have been possible to round the minimal value toward floor and the maximal value toward ceil in order to make sure that the grid envelope encompass fully the envelope - like what Java2D does when converting Rectangle2D to Rectangle). But this approach may increase by 1 or 2 units the image width or height. For example the range [-0.25 ... 99.75] (which is exactly 101 units wide) would be casted to [-1 ... 100], which is 102 units wide. This leads to unexpected results when using grid envelope with image operations like "Affine". For avoiding such changes in size, it is necessary to use the same rounding mode for both minimal and maximal values. The selected rounding mode is nearest integer in this implementation.

        Anchor
        According OpenGIS specification, grid geometry maps pixel's center. But envelopes typically encompass all pixels. This means that grid coordinates (0,0) has an envelope starting at (-0.5, -0.5). In order to revert back such envelope to a grid envelope, it is necessary to add 0.5 to every coordinates (including the maximum value since it is exclusive in a grid envelope). This offset is applied only if anchor is PixelInCell.CELL_CENTER. Users who don't want such offset should specify PixelInCell.CELL_CORNER.

        The convention is specified as a PixelInCell code instead than the more detailed PixelOrientation because the latter is restricted to the two-dimensional case while the former can be used for any number of dimensions.

        Parameters:
        envelope - The envelope to use for initializing this grid envelope.
        anchor - Whatever envelope coordinates map to pixel center or pixel corner. Should be PixelInCell.CELL_CENTER for OGC convention (an offset of 0.5 will be added to every envelope coordinate values), or PixelInCell.CELL_CORNER for Java2D/JAI convention (no offset will be added).
        isHighIncluded - true if the envelope maximal values are inclusive, or false if they are exclusive. This argument does not apply to minimal values, which are always inclusive.
        Throws:
        IllegalArgumentException - If anchor is not valid.
      • GridEnvelope2D

        public GridEnvelope2D​(ReferencedEnvelope envelope,
                              PixelInCell anchor,
                              boolean isHighIncluded)
                       throws IllegalArgumentException
        Casts the specified envelope into a grid envelope. This is sometime useful after an envelope has been transformed from "real world" coordinates to grid coordinates using the grid to CRS transform. The floating point values are rounded toward the nearest integers.

        Note about rounding mode
        It would have been possible to round the minimal value toward floor and the maximal value toward ceil in order to make sure that the grid envelope encompass fully the envelope - like what Java2D does when converting Rectangle2D to Rectangle). But this approach may increase by 1 or 2 units the image width or height. For example the range [-0.25 ... 99.75] (which is exactly 101 units wide) would be casted to [-1 ... 100], which is 102 units wide. This leads to unexpected results when using grid envelope with image operations like "Affine". For avoiding such changes in size, it is necessary to use the same rounding mode for both minimal and maximal values. The selected rounding mode is nearest integer in this implementation.

        Anchor
        According OpenGIS specification, grid geometry maps pixel's center. But envelopes typically encompass all pixels. This means that grid coordinates (0,0) has an envelope starting at (-0.5, -0.5). In order to revert back such envelope to a grid envelope, it is necessary to add 0.5 to every coordinates (including the maximum value since it is exclusive in a grid envelope). This offset is applied only if anchor is PixelInCell.CELL_CENTER. Users who don't want such offset should specify PixelInCell.CELL_CORNER.

        The convention is specified as a PixelInCell code instead than the more detailed PixelOrientation because the latter is restricted to the two-dimensional case while the former can be used for any number of dimensions.

        Parameters:
        envelope - The envelope to use for initializing this grid envelope.
        anchor - Whatever envelope coordinates map to pixel center or pixel corner. Should be PixelInCell.CELL_CENTER for OGC convention (an offset of 0.5 will be added to every envelope coordinate values), or PixelInCell.CELL_CORNER for Java2D/JAI convention (no offset will be added).
        isHighIncluded - true if the envelope maximal values are inclusive, or false if they are exclusive. This argument does not apply to minimal values, which are always inclusive.
        Throws:
        IllegalArgumentException - If anchor is not valid.
    • Method Detail

      • getDimension

        public final int getDimension()
        Returns the number of dimensions, which is always 2.
        Specified by:
        getDimension in interface GridEnvelope
        Returns:
        The number of dimensions.
      • getLow

        public GridCoordinates2D getLow()
        Returns the valid minimum inclusive grid coordinates. The sequence contains a minimum value for each dimension of the grid coverage.
        Specified by:
        getLow in interface GridEnvelope
        Returns:
        The minimal coordinate values for all grid points, inclusive.
      • getHigh

        public GridCoordinates2D getHigh()
        Returns the valid maximum inclusive grid coordinates. The sequence contains a maximum value for each dimension of the grid coverage.
        Specified by:
        getHigh in interface GridEnvelope
        Returns:
        The maximal coordinate values for all grid points, inclusive.
      • getLow

        public int getLow​(int dimension)
        Returns the valid minimum inclusive grid coordinate along the specified dimension.
        Specified by:
        getLow in interface GridEnvelope
        Parameters:
        dimension - The dimension for which to obtain the coordinate value.
        Returns:
        The coordinate value at the given dimension, inclusive.
        See Also:
        getLow()
      • getHigh

        public int getHigh​(int dimension)
        Returns the valid maximum inclusive grid coordinate along the specified dimension.
        Specified by:
        getHigh in interface GridEnvelope
        Parameters:
        dimension - The dimension for which to obtain the coordinate value.
        Returns:
        The coordinate value at the given dimension, inclusive.
        See Also:
        getHigh()
      • getSpan

        public int getSpan​(int dimension)
        Returns the number of integer grid coordinates along the specified dimension. This is equals to getHigh(dimension) - getLow(dimension).
        Specified by:
        getSpan in interface GridEnvelope
        Parameters:
        dimension - The dimension for which to obtain the coordinate value.
        Returns:
        The coordinate value at the given dimension.
        See Also:
        Rectangle.width, Rectangle.height
      • toString

        public String toString()
        Returns a string représentation of this grid envelope. The returned string is implementation dependent. It is usually provided for debugging purposes.
        Overrides:
        toString in class Rectangle
      • clone

        public GridEnvelope2D clone()
        Returns a clone of this grid envelope.
        Specified by:
        clone in interface Cloneable
        Overrides:
        clone in class RectangularShape
        Returns:
        A clone of this grid envelope.
        See Also:
        Object.clone()