Class GridExtent

  • All Implemented Interfaces:
    Serializable

    public class GridExtent
    extends Object
    implements Serializable
    A range of grid coverage coordinates, also known as "grid envelope". Grid­Extent are defined by low coordinates (often all zeros) and high coordinates, inclusive. For example a grid with a width of 512 cells can have a low coordinate of 0 and high coordinate of 511.
    Note: The inclusiveness of high coordinates come from ISO 19123. We follow this specification for all getters methods, but developers should keep in mind that this is the opposite of Java2D usage where Rectangle maximal values are exclusive.

    Grid­Extent instances are immutable and thread-safe. The same instance can be shared by different Grid­Geometry instances.

    Upcoming API generalization: this class may implement the Grid­Envelope interface in a future Apache SIS version. This is pending GeoAPI update.
    Since:
    1.0
    See Also:
    Serialized Form

    Defined in the sis-feature module

    • Constructor Summary

      Constructors 
      Constructor Description
      GridExtent​(long width, long height)
      Creates a new grid extent for an image or matrix of the given size.
      GridExtent​(DimensionNameType[] axisTypes, long[] low, long[] high, boolean isHighIncluded)
      Constructs a new grid envelope set to the specified coordinates.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(Object object)
      Compares the specified object with this grid envelope for equality.
      GridExtent expand​(long... margins)
      Expands or shrinks this grid extent by the given amount of cells along each dimension.
      Optional<DimensionNameType> getAxisType​(int index)
      Returns the type (vertical, temporal, …) of grid axis at given dimension.
      int getDimension()
      Returns the number of dimensions.
      long getHigh​(int index)
      Returns the valid maximum inclusive grid coordinate along the specified dimension.
      long getLow​(int index)
      Returns the valid minimum inclusive grid coordinate along the specified dimension.
      double[] getPointOfInterest()
      Returns the grid coordinates of a representative point.
      long getSize​(int index)
      Returns the number of integer grid coordinates along the specified dimension.
      double getSize​(int index, boolean minusOne)
      Returns the number of grid coordinates as a double precision floating point value.
      int[] getSubspaceDimensions​(int s)
      Returns indices of all dimensions where this grid extent has a size greater than 1.
      int hashCode()
      Returns a hash value for this grid envelope.
      GridExtent insert​(int offset, DimensionNameType axisType, long low, long high, boolean isHighIncluded)
      Returns a new grid envelope with the specified dimension inserted at the given index in this grid envelope.
      GridExtent reduce​(int... dimensions)
      Returns a grid envelope that encompass only some dimensions of this grid envelope.
      GridExtent resize​(long... sizes)
      Sets the size of this grid extent to the given values.
      boolean startsAtZero()
      Returns true if all low coordinates are zero.
      GridExtent subsample​(int... periods)
      Creates a new grid extent subsampled by the given amount of cells along each grid dimensions.
      String toString()
      Returns a string representation of this grid envelope.
    • Constructor Detail

      • GridExtent

        public GridExtent​(long width,
                          long height)
        Creates a new grid extent for an image or matrix of the given size. The low grid coordinates are zeros and the axis types are Dimension­Name­Type​.COLUMN and ROW in that order.
        Parameters:
        width - number of pixels in each row.
        height - number of pixels in each column.
      • GridExtent

        public GridExtent​(DimensionNameType[] axisTypes,
                          long[] low,
                          long[] high,
                          boolean isHighIncluded)
        Constructs a new grid envelope set to the specified coordinates. The given arrays contain a minimum (inclusive) and maximum value for each dimension of the grid coverage. The lowest valid grid coordinates are often zero, but this is not mandatory. As a convenience for this common case, a null low array means that all low coordinates are zero.

        An optional (nullable) axis­Types argument can be used for attaching a label to each grid axis. For example if this Grid­Extent is four-dimensional, then the axis types may be {column (x), row (y), vertical (z), {@linkplain DimensionNameType#TIME time} (t), which means that the last axis is for the temporal dimension, the third axis is for the vertical dimension, etc. This information is related to the "real world" coordinate reference system axes, but not necessarily in the same order; it is caller responsibility to ensure that the grid axes are consistent with the CRS axes. The axis­Types array shall not contain duplicated elements, but may contain null elements if the type of some axes are unknown.

        Parameters:
        axis­Types - the type of each grid axis, or null if unspecified.
        low - the valid minimum grid coordinates (always inclusive), or null for all zeros.
        high - the valid maximum grid coordinates, inclusive or exclusive depending on the next argument.
        is­High­Included - true if the high values are inclusive (as in ISO 19123 specification), or false if they are exclusive (as in Java2D usage). This argument does not apply to low values, which are always inclusive.
        Throws:
        Illegal­Argument­Exception - if a coordinate value in the low part is greater than the corresponding coordinate value in the high part.
        See Also:
        get­Low(), get­High(), insert(int, Dimension­Name­Type, long, long, boolean)
    • Method Detail

      • getDimension

        public final int getDimension()
        Returns the number of dimensions.
        Returns:
        the number of dimensions.
        See Also:
        reduce(int...)
      • startsAtZero

        public boolean startsAtZero()
        Returns true if all low coordinates are zero. This is a very common case since many grids start their cell numbering at zero.
        Returns:
        whether all low coordinates are zero.
      • getLow

        public long getLow​(int index)
        Returns the valid minimum inclusive grid coordinate along the specified dimension.
        Parameters:
        index - the dimension for which to obtain the coordinate value.
        Returns:
        the low coordinate value at the given dimension, inclusive.
        Throws:
        Index­Out­Of­Bounds­Exception - if the given index is negative or is equals or greater than the grid dimension.
        See Also:
        get­High(int)
      • getHigh

        public long getHigh​(int index)
        Returns the valid maximum inclusive grid coordinate along the specified dimension.
        Parameters:
        index - the dimension for which to obtain the coordinate value.
        Returns:
        the high coordinate value at the given dimension, inclusive.
        Throws:
        Index­Out­Of­Bounds­Exception - if the given index is negative or is equals or greater than the grid dimension.
        See Also:
        get­Low(int)
      • getSize

        public long getSize​(int index)
        Returns the number of integer grid coordinates along the specified dimension. This is equal to get­High(dimension) - get­Low(dimension) + 1.
        Parameters:
        index - the dimension for which to obtain the size.
        Returns:
        the number of integer grid coordinates along the given dimension.
        Throws:
        Index­Out­Of­Bounds­Exception - if the given index is negative or is equals or greater than the grid dimension.
        Arithmetic­Exception - if the size is too large for the long primitive type.
        See Also:
        get­Low(int), get­High(int)
      • getSize

        public double getSize​(int index,
                              boolean minusOne)
        Returns the number of grid coordinates as a double precision floating point value. Invoking this method is equivalent to invoking get­Size(int) and converting the result from long to the double primitive type, except that this method does not overflow.
        Parameters:
        index - the dimension for which to obtain the size.
        minus­One - true for returning size−1 instead of size.
        Returns:
        the number of integer grid coordinates along the given dimension.
      • getPointOfInterest

        public double[] getPointOfInterest()
        Returns the grid coordinates of a representative point. This point may be used for estimating a grid resolution. The default implementation returns the median (or center) coordinates of this grid extent, but subclasses can override this method if another point is considered more representative.
        Returns:
        the grid coordinates of a representative point.
      • getSubspaceDimensions

        public int[] getSubspaceDimensions​(int s)
        Returns indices of all dimensions where this grid extent has a size greater than 1. This method can be used for getting the grid extent of a s-dimensional slice in a n-dimensional cube where sn.
        Example: suppose that we want to get a two-dimensional slice (y,z) in a four-dimensional data cube (x,y,z,t). The first step is to specify the x and t coordinates of the slice. In this example we set x to 5 and t to 8.
        GridGeometry grid = ...;             // Geometry of the (x,y,z,t) grid.
        GridGeometry slice4D = grid.slice(new GeneralDirectPosition(5, NaN, NaN, 8));
        Above code created a slice at the requested position, but that slice still have 4 dimensions. It is a "slice" because the x and t dimensions of slice4D have only one cell. If a two-dimensional slice is desired, then above operations can be completed as below. In this example, the result of get­Subspace­Dimensions(2) call will be {1,2}.
        int[]  subDimensions = slice4D.getExtent().getSubspaceDimensions(2);
        GridGeometry slice2D = slice4D.reduce(subDimensions);
        Note that in this particular example, it would have been more efficient to execute grid​.reduce(1,2) directly. This get­Subspace­Dimensions(int) method is more useful for inferring a slice2D from a slice4D which has been created elsewhere, or when we do not really want the slice2D but only its dimension indices.
        This method returns exactly s indices. If there is more than s dimensions having a size greater than 1, then a Subspace­Not­Specified­Exception is thrown. If there is less than s dimensions having a size greater than 1, then the returned list of dimensions is completed with some dimensions of size 1, starting with the first dimensions in this grid extent, until there is exactly s dimensions. This this grid extent does not have s dimensions, then a Cannot­Evaluate­Exception is thrown.
        Parameters:
        s - number of dimensions of the sub-space.
        Returns:
        indices of sub-space dimensions, in increasing order in an array of length s.
        Throws:
        Subspace­Not­Specified­Exception - if there is more than s dimensions having a size greater than 1.
        Runtime­Exception - if this grid extent does not have at least s dimensions.
      • insert

        public GridExtent insert​(int offset,
                                 DimensionNameType axisType,
                                 long low,
                                 long high,
                                 boolean isHighIncluded)
        Returns a new grid envelope with the specified dimension inserted at the given index in this grid envelope. To append a new dimension after all existing dimensions, set offset to get­Dimension().
        Parameters:
        offset - where to insert the new dimension, from 0 to get­Dimension() inclusive.
        axis­Type - the type of the grid axis to add, or null if unspecified.
        low - the valid minimum grid coordinate (always inclusive).
        high - the valid maximum grid coordinate, inclusive or exclusive depending on the next argument.
        is­High­Included - true if the high value is inclusive (as in ISO 19123 specification), or false if it is exclusive (as in Java2D usage). This argument does not apply to low value, which is always inclusive.
        Returns:
        a new grid envelope with the specified dimension added.
        Throws:
        Illegal­Argument­Exception - if the low coordinate value is greater than the high coordinate value.
      • expand

        public GridExtent expand​(long... margins)
        Expands or shrinks this grid extent by the given amount of cells along each dimension. This method adds the given margins to the high coordinates and subtracts the same margins to the low coordinates.
        Parameters:
        margins - amount of cells to add or subtract.
        Returns:
        a grid extent expanded by the given amount, or this if there is no change.
        Throws:
        Arithmetic­Exception - if expanding this extent by the given margins overflows long capacity.
      • resize

        public GridExtent resize​(long... sizes)
        Sets the size of this grid extent to the given values. This method modifies grid coordinates as if they were multiplied by (given size) / (current size), rounded toward zero and with the value farthest from zero adjusted by ±1 for having a size exactly equals to the specified value. In the common case where the low value is zero, this is equivalent to setting the high value to size - 1.

        The length of the given array should be equal to get­Dimension(). If the array is shorter, missing dimensions have their size unchanged. If the array is longer, extra sizes are ignored.

        Parameters:
        sizes - the new grid sizes for each dimension.
        Returns:
        a grid extent having the given sizes, or this if there is no change.
        Throws:
        Arithmetic­Exception - if resizing this extent to the given size overflows long capacity.
        See Also:
        Grid­Derivation​.resize(Grid­Extent, double...)
      • reduce

        public GridExtent reduce​(int... dimensions)
        Returns a grid envelope that encompass only some dimensions of this grid envelope. This method copies the specified dimensions of this grid envelope into a new grid envelope. The given dimensions must be in strictly ascending order without duplicated values. The number of dimensions of the sub grid envelope will be dimensions​.length.

        This method performs a dimensionality reduction and can be used as the converse of insert(int, Dimension­Name­Type, long, long, boolean). This method can not be used for changing dimension order.

        Parameters:
        dimensions - the dimensions to select, in strictly increasing order.
        Returns:
        the sub-envelope, or this if the given array contains all dimensions of this grid extent.
        Throws:
        Index­Out­Of­Bounds­Exception - if an index is out of bounds.
        See Also:
        get­Subspace­Dimensions(int), Grid­Geometry​.reduce(int...)
      • subsample

        public GridExtent subsample​(int... periods)
        Creates a new grid extent subsampled by the given amount of cells along each grid dimensions. This method divides low coordinates and grid sizes by the given periods, rounding toward zero. The high coordinates are adjusted accordingly (this is often equivalent to dividing high coordinates by the periods too, but a difference of one cell may exist).
        Note: The envelope computed from a grid extent may become larger after subsampling, not smaller. This effect can be understood intuitively if we consider that cells become larger after subsampling, which implies that accurate representation of the same envelope may require fractional cells on some grid borders.
        This method does not reduce the number of dimensions of the grid extent. For dimensionality reduction, see reduce(int...).
        Parameters:
        periods - the subsamplings. Length shall be equal to the number of dimension and all values shall be greater than zero.
        Returns:
        the subsampled extent, or this is subsampling results in the same extent.
        Throws:
        Illegal­Argument­Exception - if a period is not greater than zero.
        See Also:
        Grid­Derivation​.subsample(int...)
      • hashCode

        public int hashCode()
        Returns a hash value for this grid envelope. This value needs not to remain consistent between different implementations of the same class.
        Overrides:
        hash­Code in class Object
        Returns:
        a hash value for this grid envelope.
      • equals

        public boolean equals​(Object object)
        Compares the specified object with this grid envelope for equality.
        Overrides:
        equals in class Object
        Parameters:
        object - the object to compare with this grid envelope for equality.
        Returns:
        true if the given object is equal to this grid envelope.
      • toString

        public String toString()
        Returns a string representation of this grid envelope. The returned string is implementation dependent and is provided for debugging purposes only.
        Overrides:
        to­String in class Object