Package org.apache.sis.coverage.grid

Class GridExtent

java.lang.Object
org.apache.sis.coverage.grid.GridExtent
All Implemented Interfaces:
Serializable, LenientComparable
Direct Known Subclasses:
CanvasExtent
public class GridExtent extends Object implements Serializable, LenientComparable
A range of grid coverage coordinates, also known as "grid envelope". GridExtent 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.

GridExtent instances are immutable and thread-safe. The same instance can be shared by different GridGeometry instances.

Upcoming API generalization: this class may implement the GridEnvelope interface in a future Apache SIS version. This is pending GeoAPI update.
Since:
1.0
Version:
1.3
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final Map<org.opengis.referencing.cs.AxisDirection,org.opengis.metadata.spatial.DimensionNameType>
    AXIS_DIRECTIONS
    The dimension name types for given coordinate system axis directions.
    private final long[]
    coordinates
    Minimum and maximum grid coordinates.
    private static final org.opengis.metadata.spatial.DimensionNameType[]
    DEFAULT_TYPES
    Default axis types for the two-dimensional cases.
    private static final WeakValueHashMap<org.opengis.metadata.spatial.DimensionNameType[],org.opengis.metadata.spatial.DimensionNameType[]>
    POOL
    A pool of shared DimensionNameType arrays.
    private static final long
    serialVersionUID
    Serial number for inter-operability with different versions.
    private final org.opengis.metadata.spatial.DimensionNameType[]
    types
    Type of each axis (vertical, temporal, …) or null if unspecified.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    (package private)
    GridExtent(int xmin, int ymin, int width, int height)
    Creates a new grid extent for an image of the given size and location.
    private
    GridExtent(int dimension, org.opengis.metadata.spatial.DimensionNameType[] axisTypes)
    Creates an initially empty grid extent with the given number of dimensions.
     
    GridExtent(long width, long height)
    Creates a new grid extent for an image or matrix of the given size.
     
    GridExtent(Rectangle bounds)
    Creates a new grid extent for an image or matrix of the given bounds.
    private
    GridExtent(GridExtent extent)
    Creates a copy of the given grid extent.
    (package private)
    GridExtent(GridExtent enclosing, long[] coordinates)
    Creates a new grid extent with the same axes than the given extent, but different coordinates.
    (package private)
    GridExtent(AbstractEnvelope envelope, GridRoundingMode rounding, GridClippingMode clipping, int[] margin, int[] chunkSize, GridExtent enclosing, int[] modifiedDimensions)
    Creates a new grid extent by rounding the given envelope to (usually) nearest integers.
     
    GridExtent(org.opengis.metadata.spatial.DimensionNameType[] axisTypes, long[] low, long[] high, boolean isHighIncluded)
    Constructs a new grid extent set to the specified coordinates.

  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) static long[]
    allocate(int dimension)
    Creates a new array of coordinates with the given number of dimensions.
    (package private) final void
    appendTo(Appendable out, Vocabulary vocabulary)
    Writes a string representation of this grid extent in the given buffer.
    private GridExtent
    combine(GridExtent other, boolean union)
    Implementation of union(GridExtent) and intersect(GridExtent)
    private void
    complete(GeneralEnvelope envelope, org.opengis.referencing.operation.MathTransform gridToCRS, boolean isCenter, org.opengis.geometry.Envelope fallback)
    If the envelope contains some NaN values, tries to replace them by constant values inferred from the math transform.
    boolean
    contains(long... indices)
    Returns true if this extent contains the given cell indices.
    (package private) final MatrixSIS
    cornerToCRS(org.opengis.geometry.Envelope env, long flippedAxes, int[] sourceDimensions)
    Creates an affine transform from the coordinates of this grid to the coordinates of the given envelope.
    final boolean
    equals(Object object)
    Compares the specified object with this grid extent for equality.
    boolean
    equals(Object object, ComparisonMode mode)
    Compares the specified object with this grid extent for equality.
    GridExtent
    expand(long... margins)
    Returns a grid extent expanded by the given amount of cells on both sides along each dimension.
    private static long
    extremum(long a, long b, boolean max)
    Returns the minimum or maximum value between the given pair of values.
    (package private) final GridExtent
    forChunkSize(int... sizes)
    Returns a grid extent expanded by the minimal amount of cells needed for covering an integer amount of chunks.
    (package private) final Object
    getAxisIdentification(int index, int indexShown)
    Returns the axis number followed by the localized axis type if available.
    Optional<org.opengis.metadata.spatial.DimensionNameType>
    getAxisType(int index)
    Returns the type (vertical, temporal, …) of grid axis at given dimension.
    (package private) final org.opengis.metadata.spatial.DimensionNameType[]
    getAxisTypes()
    Returns the types array or a default array of arbitrary length if types is null.
    final int
    getDimension()
    Returns the number of dimensions.
    (package private) GridCoordinatesView
    getHigh()
    Returns the valid maximum grid coordinates, inclusive.
    long
    getHigh(int index)
    Returns the valid maximum inclusive grid coordinate along the specified dimension.
    (package private) GridCoordinatesView
    getLow()
    Returns the valid minimum grid coordinates, inclusive.
    long
    getLow(int index)
    Returns the valid minimum inclusive grid coordinate along the specified dimension.
    long
    getMedian(int index)
    Returns the average of low and high coordinates, rounded toward positive infinity.
    double[]
    getPointOfInterest()
    Deprecated.
    Replaced by getPointOfInterest(PixelInCell).
    double[]
    getPointOfInterest(org.opengis.referencing.datum.PixelInCell anchor)
    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.
    SortedMap<Integer,Long>
    getSliceCoordinates()
    Returns the grid coordinates for all dimensions where the grid has a size of 1.
    (package private) final int
    getSubDimension()
    Returns the number of dimensions where this grid extent has a size greater than 1.
    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 extent.
    GridExtent
    insertDimension(int offset, org.opengis.metadata.spatial.DimensionNameType axisType, long low, long high, boolean isHighIncluded)
    Returns a new grid extent with the specified dimension inserted at the given index in this grid extent.
    GridExtent
    intersect(GridExtent other)
    Returns the intersection of this grid extent with the given grid extent.
    (package private) final boolean
    isSameSize(GridExtent other)
    Returns whether this grid extent has the same size than the given extent.
    private static boolean
    isZero(long[] vector, int n)
    Returns true if all values in the given vector are zero.
    GridExtent
    reduceDimension(int... dimensions)
    Deprecated.
    Renamed selectDimensions(int...) for clarity.
    (package private) final GridExtent
    reorder(int[] dimensions)
    Changes axis order or reduces the number of dimensions.
    GridExtent
    resize(long... sizes)
    Sets the size of grid extent to the given values by moving low and high coordinates.
    GridExtent
    selectDimensions(int... dimensions)
    Returns a grid extent that encompass only some dimensions of this grid extent.
    (package private) final GridExtent
    slice(org.opengis.geometry.DirectPosition slicePoint, int[] modifiedDimensions)
    Creates a new grid extent which represent a slice of this grid at the given point.
    (package private) final GridExtent
    sliceByRatio(org.opengis.geometry.DirectPosition slicePoint, double sliceRatio, int[] dimensionsToKeep)
    Returns a slice of this grid extent computed by a ratio between 0 and 1 inclusive.
    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.
    (package private) final GeneralEnvelope
    toEnvelope()
    Returns the coordinates of this grid extent in an envelope.
    GeneralEnvelope
    toEnvelope(org.opengis.referencing.operation.MathTransform cornerToCRS)
    Transforms this grid extent to a "real world" envelope using the given transform.
    (package private) final GeneralEnvelope
    toEnvelope(org.opengis.referencing.operation.MathTransform cornerToCRS, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope fallback)
    Transforms this grid extent to a "real world" envelope using the given transform.
    (package private) final GeneralEnvelope[]
    toEnvelopes(org.opengis.referencing.operation.MathTransform cornerToCRS, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope fallback)
    Transforms this grid extent to "real world" envelopes using the given transform.
    (package private) static String
    toSizeString(long size)
    Returns a string representation of the given size, assumed computed by high - low + 1.
    String
    toString()
    Returns a string representation of this grid extent.
    GridExtent
    translate(long... translation)
    Returns an extent translated by the given amount of cells compared to this extent.
    private void
    translate2D(long xmin, long ymin)
    Completes a GridExtent construction with a final translation.
    (package private) static org.opengis.metadata.spatial.DimensionNameType[]
    typeFromAxes(org.opengis.referencing.crs.CoordinateReferenceSystem crs, int dimension)
    Infers the axis types from the given coordinate reference system.
    GridExtent
    union(GridExtent other)
    Returns the union of this grid extent with the given grid extent.
    GridExtent
    upsample(int... periods)
    Creates a new grid extent upsampled by the given amount of cells along each grid dimensions.
    private static org.opengis.metadata.spatial.DimensionNameType[]
    validateAxisTypes(org.opengis.metadata.spatial.DimensionNameType[] types)
    Verifies that the given array (if non-null) contains no duplicated values, then returns a copy of that array.
    private void
    validateCoordinates()
    Checks if coordinate values in the low part are less than or equal to the corresponding coordinate value in the high part.
    (package private) static int[]
    verifyDimensions(int[] dimensions, int limit)
    Verifies the validity of a given dimensions argument.
    GridExtent
    withRange(int index, long low, long high)
    Returns a grid extent identical to this grid extent except for the coordinate values in the specified dimension.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:

    • AXIS_DIRECTIONS

      private static final Map<org.opengis.referencing.cs.AxisDirection,org.opengis.metadata.spatial.DimensionNameType> AXIS_DIRECTIONS
      The dimension name types for given coordinate system axis directions. This map contains only the "positive" axis directions.
      See Also:

    • DEFAULT_TYPES

      private static final org.opengis.metadata.spatial.DimensionNameType[] DEFAULT_TYPES
      Default axis types for the two-dimensional cases.

    • POOL

      private static final WeakValueHashMap<org.opengis.metadata.spatial.DimensionNameType[],org.opengis.metadata.spatial.DimensionNameType[]> POOL
      A pool of shared DimensionNameType arrays. We use a pool because a small amount of arrays is shared by most grid extents.

    • types

      private final org.opengis.metadata.spatial.DimensionNameType[] types
      Type of each axis (vertical, temporal, …) or null if unspecified. If non-null, the array length shall be equal to getDimension(). Any array element may be null if unspecified for that particular axis. The same array may be shared by many GridExtent instances.
      See Also:

    • coordinates

      private final long[] coordinates
      Minimum and maximum grid coordinates. The first half contains minimum coordinates (inclusive), while the last half contains maximum coordinates (inclusive). Note that the later inclusiveness is the opposite of Java2D usage but conforms to ISO specification.

  • Constructor Details

    • GridExtent

      private GridExtent(int dimension, org.opengis.metadata.spatial.DimensionNameType[] axisTypes)
      Creates an initially empty grid extent with the given number of dimensions. All grid coordinate values are initialized to zero. This constructor is private because GridExtent coordinate values cannot be modified by public API.
      Parameters:
      dimension - number of dimensions.
      axisTypes - the axis types, or null if unspecified.
      See Also:

    • GridExtent

      public GridExtent(Rectangle bounds)
      Creates a new grid extent for an image or matrix of the given bounds. The axis types are DimensionNameType.COLUMN and ROW in that order.
      Parameters:
      bounds - the bounds to copy in the new grid extent.
      Throws:
      IllegalArgumentException - if the rectangle is empty.
      Since:
      1.1

    • 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 DimensionNameType.COLUMN and ROW in that order.
      Parameters:
      width - number of pixels in each row.
      height - number of pixels in each column.
      Throws:
      IllegalArgumentException - if the width or the height is not greater than zero.

    • GridExtent

      GridExtent(int xmin, int ymin, int width, int height)
      Creates a new grid extent for an image of the given size and location. This constructor is for internal usage: argument meanings differ from conventions in public constructors.
      Parameters:
      xmin - column index of the first cell.
      ymin - row index of the first cell.
      width - number of pixels in each row.
      height - number of pixels in each column.

    • GridExtent

      public GridExtent(org.opengis.metadata.spatial.DimensionNameType[] axisTypes, long[] low, long[] high, boolean isHighIncluded)
      Constructs a new grid extent 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) axisTypes argument can be used for attaching a label to each grid axis. For example if this GridExtent is four-dimensional, then the axis types may be {column (x), row (y), vertical (z), 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 axisTypes array shall not contain duplicated elements, but may contain null elements if the type of some axes are unknown.

      Parameters:
      axisTypes - 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.
      isHighIncluded - 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:
      IllegalArgumentException - if a coordinate value in the low part is greater than the corresponding coordinate value in the high part.
      See Also:

    • GridExtent

      GridExtent(AbstractEnvelope envelope, GridRoundingMode rounding, GridClippingMode clipping, int[] margin, int[] chunkSize, GridExtent enclosing, int[] modifiedDimensions)
      Creates a new grid extent by rounding the given envelope to (usually) nearest integers. The envelope coordinates shall be cell indices with lower values inclusive and upper values exclusive. Double.NaN envelope coordinates will be set to the corresponding enclosing coordinates (an exception will be thrown if enclosing is null in that situation). Envelopes crossing the anti-meridian shall be simplified. The envelope CRS is ignored, except for identifying dimension names for information purpose. The way floating point values are rounded to integers may be adjusted in any future version.

      API note: this constructor is not public because its contract is a bit approximate.

      Parameters:
      envelope - the envelope containing cell indices to store in a GridExtent.
      rounding - controls behavior of rounding from floating point values to integers.
      clipping - how to clip this extent to the enclosing extent. Ignored if enclosing is null.
      margin - if non-null, expands the extent by that amount of cells on each envelope dimension.
      chunkSize - if non-null, make the grid extent spanning an integer amount of chunks (tiles).
      enclosing - if the new grid is a sub-grid of a larger grid, that larger grid. Otherwise null.
      modifiedDimensions - if enclosing is non-null, the grid dimensions to set from the envelope. The length of this array shall be equal to the envelope dimension. This argument is ignored if enclosing is null.
      Throws:
      DisjointExtentException - if the given envelope does not intersect the enclosing grid extent.
      See Also:

    • GridExtent

      GridExtent(GridExtent enclosing, long[] coordinates)
      Creates a new grid extent with the same axes than the given extent, but different coordinates. This constructor does not invoke validateCoordinates(); we presume that the caller's computation is correct.
      Parameters:
      enclosing - the extent from which to copy axes, or null if none.
      coordinates - the coordinates. This array is not cloned.

    • GridExtent

      private GridExtent(GridExtent extent)
      Creates a copy of the given grid extent. The coordinates array is cloned while the types array is shared between the two instances. This constructor is reserved to methods that modify the coordinates after construction. It must be private because we do not allow coordinates modifications by public API.
      See Also:

  • Method Details

    • allocate

      static long[] allocate(int dimension) throws IllegalArgumentException
      Creates a new array of coordinates with the given number of dimensions.
      Throws:
      IllegalArgumentException - if the given number of dimensions is excessive.

    • validateCoordinates

      private void validateCoordinates() throws IllegalArgumentException
      Checks if coordinate values in the low part are less than or equal to the corresponding coordinate value in the high part.
      Throws:
      IllegalArgumentException - if a coordinate value in the low part is greater than the corresponding coordinate value in the high part.

    • validateAxisTypes

      private static org.opengis.metadata.spatial.DimensionNameType[] validateAxisTypes(org.opengis.metadata.spatial.DimensionNameType[] types) throws IllegalArgumentException
      Verifies that the given array (if non-null) contains no duplicated values, then returns a copy of that array. The returned copy may be shared by many GridExtent instances. Consequently, it shall not be modified.
      Throws:
      IllegalArgumentException - if the given array contains duplicated elements.

    • translate2D

      private void translate2D(long xmin, long ymin)
      Completes a GridExtent construction with a final translation. Shall be invoked for two-dimensional extents only.

    • typeFromAxes

      static org.opengis.metadata.spatial.DimensionNameType[] typeFromAxes(org.opengis.referencing.crs.CoordinateReferenceSystem crs, int dimension)
      Infers the axis types from the given coordinate reference system. This method is the converse of GridExtentCRS.
      Parameters:
      crs - the coordinate reference system, or null.
      dimension - number of name type to infer. Shall not be greater than the CRS dimension.
      Returns:
      axis types, or null if no axis were recognized.

    • getDimension

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

    • getSubDimension

      final int getSubDimension()
      Returns the number of dimensions where this grid extent has a size greater than 1. This is a value between 0 and getDimension() inclusive.
      Returns:
      the number of dimensions where this grid extent has a size greater than 1.
      See Also:

    • 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.
      See Also:

    • isZero

      private static boolean isZero(long[] vector, int n)
      Returns true if all values in the given vector are zero.
      Parameters:
      vector - the vector to verify.
      n - number of elements to verify. All remaining elements are ignored.
      Returns:
      whether the n first elements in the given array are all zero.

    • getLow

      GridCoordinatesView getLow()
      Returns the valid minimum grid coordinates, inclusive. The sequence contains a minimum value for each dimension of the grid coverage.
      Returns:
      the valid minimum grid coordinates, inclusive.
      See Also:

    • getHigh

      GridCoordinatesView getHigh()
      Returns the valid maximum grid coordinates, inclusive. The sequence contains a maximum value for each dimension of the grid coverage.
      Returns:
      the valid maximum grid coordinates, inclusive.
      See Also:

    • 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:
      IndexOutOfBoundsException - if the given index is negative or is equal or greater than the grid dimension.
      See Also:

    • 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:
      IndexOutOfBoundsException - if the given index is negative or is equal or greater than the grid dimension.
      See Also:

    • getMedian

      public long getMedian(int index)
      Returns the average of low and high coordinates, rounded toward positive infinity. This method is equivalent to computing any of the following, except that this method does not overflow even if the sum would overflow:
      • (low + high) / 2 rounded toward positive infinity, or
      • (low + high + 1) / 2 rounded toward negative infinity.
      The two above formulas are equivalent, so the result does not depend on whether the high coordinate should be inclusive or exclusive.
      Parameters:
      index - the dimension for which to obtain the coordinate value.
      Returns:
      the median coordinate value at the given dimension.
      Throws:
      IndexOutOfBoundsException - if the given index is negative or is equal or greater than the grid dimension.
      Since:
      1.3

    • getSize

      public long getSize(int index)
      Returns the number of integer grid coordinates along the specified dimension. This is equal to getHigh(dimension) - getLow(dimension) + 1.
      Parameters:
      index - the dimension for which to obtain the size.
      Returns:
      the number of integer grid coordinates along the given dimension.
      Throws:
      IndexOutOfBoundsException - if the given index is negative or is equal or greater than the grid dimension.
      ArithmeticException - if the size is too large for the long primitive type.
      See Also:

    • 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 getSize(int) and converting the result from long to the double primitive type, except that this method does not overflow (i.e. does not throw ArithmeticException).
      Parameters:
      index - the dimension for which to obtain the size.
      minusOne - true for returning size−1 instead of size.
      Returns:
      the number of integer grid coordinates along the given dimension.

    • getPointOfInterest

      @Deprecated public double[] getPointOfInterest()
      Deprecated.
      Replaced by getPointOfInterest(PixelInCell).
      Returns:
      the grid coordinates of a representative point.

    • getPointOfInterest

      public double[] getPointOfInterest(org.opengis.referencing.datum.PixelInCell anchor)
      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.

      The anchpr argument tells which transform the caller intend to use for converting the grid coordinates to "real world" coordinates. With the default implementation, the coordinate values returned with CELL_CORNER are 0.5 cell units higher than the coordinate values returned with CELL_CENTER. Subclasses are free to ignore this argument.

      Parameters:
      anchor - the convention to be used for conversion to "real world" coordinates.
      Returns:
      the grid coordinates of a representative point.
      Since:
      1.3

    • getSliceCoordinates

      public SortedMap<Integer,Long> getSliceCoordinates()
      Returns the grid coordinates for all dimensions where the grid has a size of 1. Keys are dimensions as values from 0 inclusive to getDimension() exclusive. Values are the low and high coordinates (which are equal) in the associated dimension.
      Returns:
      grid coordinates for all dimensions where the grid has a size of 1.
      Since:
      1.3
      See Also:

    • 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 s ≤ n.
      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. 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 getSubspaceDimensions(2) call will be {1,2}. Note that in this particular example, it would have been more efficient to execute grid.reduce(1,2) directly. This getSubspaceDimensions(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 SubspaceNotSpecifiedException 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. If this grid extent does not have at least s dimensions, then a CannotEvaluateException 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:
      SubspaceNotSpecifiedException - if there is more than s dimensions having a size greater than 1.
      CannotEvaluateException - if this grid extent does not have at least s dimensions.

    • getAxisType

      public Optional<org.opengis.metadata.spatial.DimensionNameType> getAxisType(int index)
      Returns the type (vertical, temporal, …) of grid axis at given dimension. This information is provided because the grid axis type cannot always be inferred from the context. Some examples are:
      • getAxisType(0) may return DimensionNameType.COLUMN, TRACK or LINE.
      • getAxisType(1) may return DimensionNameType.ROW, CROSS_TRACK or SAMPLE.
      • getAxisType(2) may return DimensionNameType.VERTICAL.
      • getAxisType(3) may return DimensionNameType.TIME.
      Above are only examples; there are no constraints on axis order. In particular grid axes do not need to be in the same order than the corresponding coordinate reference system axes.
      Parameters:
      index - the dimension for which to obtain the axis type.
      Returns:
      the axis type at the given dimension. May be absent if the type is unknown.
      Throws:
      IndexOutOfBoundsException - if the given index is negative or is equal or greater than the grid dimension.

    • getAxisTypes

      final org.opengis.metadata.spatial.DimensionNameType[] getAxisTypes()
      Returns the types array or a default array of arbitrary length if types is null. This method returns directly the arrays without cloning; do not modify.

    • getAxisIdentification

      final Object getAxisIdentification(int index, int indexShown)
      Returns the axis number followed by the localized axis type if available. This is used for error messages only.
      Parameters:
      index - index of the dimension as stored in this grid extent.
      indexShown - index to write in the message. Often the same as index.

    • withRange

      public GridExtent withRange(int index, long low, long high)
      Returns a grid extent identical to this grid extent except for the coordinate values in the specified dimension. This grid extent is not modified.
      Parameters:
      index - the dimension for which to set the coordinate values.
      low - the low coordinate value at the given dimension, inclusive.
      high - the high coordinate value at the given dimension, inclusive.
      Returns:
      a grid extent with the specified coordinate values, or this if values are unchanged.
      Throws:
      IllegalArgumentException - if the low coordinate value is greater than the high coordinate value.
      Since:
      1.3
      See Also:

    • toEnvelope

      public GeneralEnvelope toEnvelope(org.opengis.referencing.operation.MathTransform cornerToCRS) throws org.opengis.referencing.operation.TransformException
      Transforms this grid extent to a "real world" envelope using the given transform. The transform shall map cell corner to real world coordinates.
      Parameters:
      cornerToCRS - a transform from cell corners to real world coordinates.
      Returns:
      this grid extent in real world coordinates.
      Throws:
      org.opengis.referencing.operation.TransformException - if the envelope cannot be computed with the given transform.
      Since:
      1.1
      See Also:

    • toEnvelope

      final GeneralEnvelope toEnvelope(org.opengis.referencing.operation.MathTransform cornerToCRS, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope fallback) throws org.opengis.referencing.operation.TransformException
      Transforms this grid extent to a "real world" envelope using the given transform. The transform shall map cell corner to real world coordinates. This method does not set the envelope coordinate reference system.
      Parameters:
      cornerToCRS - a transform from cell corners to real world coordinates.
      gridToCRS - the transform specified by the user. May be the same as cornerToCRS. If different, then this is assumed to map cell centers instead of cell corners.
      fallback - bounds to use if some values are still NaN after conversion, or null if none.
      Returns:
      this grid extent in real world coordinates.
      Throws:
      org.opengis.referencing.operation.TransformException - if the envelope cannot be computed with the given transform.
      See Also:

    • toEnvelope

      final GeneralEnvelope toEnvelope()
      Returns the coordinates of this grid extent in an envelope. The returned envelope has no CRS.

    • toEnvelopes

      final GeneralEnvelope[] toEnvelopes(org.opengis.referencing.operation.MathTransform cornerToCRS, org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.geometry.Envelope fallback) throws org.opengis.referencing.operation.TransformException
      Transforms this grid extent to "real world" envelopes using the given transform. This method usually returns exactly one envelope, but may return more envelopes if the given transform contains at least one WraparoundTransform step.
      Parameters:
      cornerToCRS - a transform from cell corners to real world coordinates.
      gridToCRS - the transform specified by the user. May be the same as cornerToCRS. If different, then this is assumed to map cell centers instead of cell corners.
      fallback - bounds to use if some values are still NaN after conversion, or null if none.
      Returns:
      this grid extent in real world coordinates.
      Throws:
      org.opengis.referencing.operation.TransformException - if the envelope cannot be computed with the given transform.
      See Also:

    • complete

      private void complete(GeneralEnvelope envelope, org.opengis.referencing.operation.MathTransform gridToCRS, boolean isCenter, org.opengis.geometry.Envelope fallback)
      If the envelope contains some NaN values, tries to replace them by constant values inferred from the math transform. We must use the MathTransform specified by the user (gridToCRS), not necessarily cornerToCRS, because inferring a cornerToCRS by translating a centerToCRS by 0.5 cell increase the amount of NaN values in the matrix. For giving a chance to TransformSeparator to perform its work, we need the minimal amount of NaN values.
      Parameters:
      envelope - the envelope to complete if empty.
      gridToCRS - the transform specified by user.
      isCenter - whether the "grid to CRS" transform maps cell center instead of cell corners.
      fallback - bounds to use if some values are still NaN after conversion, or null if none.

    • insertDimension

      public GridExtent insertDimension(int offset, org.opengis.metadata.spatial.DimensionNameType axisType, long low, long high, boolean isHighIncluded)
      Returns a new grid extent with the specified dimension inserted at the given index in this grid extent. To append a new dimension after all existing dimensions, set offset to getDimension().
      Parameters:
      offset - where to insert the new dimension, from 0 to getDimension() inclusive.
      axisType - 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.
      isHighIncluded - 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 extent with the specified dimension added.
      Throws:
      IllegalArgumentException - if the low coordinate value is greater than the high coordinate value.
      Since:
      1.1
      See Also:

    • selectDimensions

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

      This method performs a dimensionality reduction and can be used as the converse of insertDimension(int, DimensionNameType, long, long, boolean). This method cannot 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:
      IndexOutOfBoundsException - if an index is out of bounds.
      Since:
      1.3
      See Also:

    • reduceDimension

      @Deprecated public GridExtent reduceDimension(int... dimensions)
      Deprecated.
      Renamed selectDimensions(int...) for clarity.
      Returns a grid extent that encompass only some dimensions of this grid extent.
      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.
      Since:
      1.1

    • verifyDimensions

      static int[] verifyDimensions(int[] dimensions, int limit)
      Verifies the validity of a given dimensions argument.
      Parameters:
      dimensions - the user supplied argument to validate.
      limit - maximal number of dimensions, exclusive.
      Returns:
      a clone of the given array, or null if the caller can return this.

    • reorder

      final GridExtent reorder(int[] dimensions)
      Changes axis order or reduces the number of dimensions. It is caller responsibility to ensure that the given dimensions are valid.

    • expand

      public GridExtent expand(long... margins)
      Returns a grid extent expanded by the given amount of cells on both sides along each dimension. This method adds the given margins to the high coordinates and subtracts the same margins from the low coordinates. If a negative margin is supplied, the extent size decreases accordingly.

      Number of arguments

      The margins array length should be equal to the number of dimensions. If the array is shorter, missing values default to 0 (i.e. sizes in unspecified dimensions are unchanged). If the array is longer, extraneous values are ignored.
      Parameters:
      margins - amount of cells to add or subtract on both sides for each dimension.
      Returns:
      a grid extent expanded by the given amount, or this if there is no change.
      Throws:
      ArithmeticException - if expanding this extent by the given margins overflows long capacity.
      See Also:

    • forChunkSize

      final GridExtent forChunkSize(int... sizes)
      Returns a grid extent expanded by the minimal amount of cells needed for covering an integer amount of chunks. The grid coordinates (0, 0, …) locate the corner of a chunk.

      Number of arguments

      The sizes array length should be equal to the number of dimensions. If the array is shorter, missing values default to 1. If the array is longer, extraneous values are ignored.
      Parameters:
      sizes - number of cells in all tiles or chunks.
      Returns:
      a grid extent expanded for the given chunk size.
      See Also:

    • resize

      public GridExtent resize(long... sizes)
      Sets the size of grid extent to the given values by moving low and high coordinates. 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.

      Number of arguments

      The sizes array length should be equal to the number of dimensions. If the array is shorter, sizes in unspecified dimensions are unchanged. If the array is longer, extraneous values 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:
      ArithmeticException - if resizing this extent to the given size overflows long capacity.
      See Also:

    • 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: If the "real world" envelope computed from grid extent needs to stay approximately the same, then the grid to CRS transform needs to compensate the subsampling with a pre-multiplication of each grid coordinates by periods. However, the envelope computed that way 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 selectDimensions(int[]).

      Number of arguments

      The periods array length should be equal to the number of dimensions. If the array is shorter, missing values default to 1 (i.e. samplings in unspecified dimensions are unchanged). If the array is longer, extraneous values are ignored.
      Parameters:
      periods - the subsampling. Length shall be equal to the number of dimension and all values shall be greater than zero.
      Returns:
      the subsampled extent, or this if subsampling results in the same extent.
      Throws:
      IllegalArgumentException - if a period is not greater than zero.
      See Also:

    • upsample

      public GridExtent upsample(int... periods)
      Creates a new grid extent upsampled by the given amount of cells along each grid dimensions. This method multiplies low and high coordinates by the given periods. This method does not change the number of dimensions of the grid extent.

      Number of arguments

      The periods array length should be equal to the number of dimensions. If the array is shorter, missing values default to 1 (i.e. samplings in unspecified dimensions are unchanged). If the array is longer, extraneous values are ignored.
      Parameters:
      periods - the upsampling. Length shall be equal to the number of dimension and all values shall be greater than zero.
      Returns:
      the upsampled extent, or this if upsampling results in the same extent.
      Throws:
      IllegalArgumentException - if a period is not greater than zero.
      ArithmeticException - if the upsampled extent overflows the long capacity.
      Since:
      1.3
      See Also:

    • sliceByRatio

      final GridExtent sliceByRatio(org.opengis.geometry.DirectPosition slicePoint, double sliceRatio, int[] dimensionsToKeep)
      Returns a slice of this grid extent computed by a ratio between 0 and 1 inclusive. This is a helper method for GridDerivation.sliceByRatio(double, int...) implementation.
      Parameters:
      slicePoint - a pre-allocated direct position to be overwritten by this method.
      sliceRatio - the ratio to apply on all grid dimensions except the ones to keep.
      dimensionsToKeep - the grid dimension to keep unchanged.

    • slice

      final GridExtent slice(org.opengis.geometry.DirectPosition slicePoint, int[] modifiedDimensions)
      Creates a new grid extent which represent a slice of this grid at the given point. The given point may have less dimensions than this grid extent, in which case the dimensions must be specified in the modifiedDimensions array. Coordinates in the given point will be rounded to nearest integer.

      This method does not reduce the number of dimensions of the grid extent. For dimensionality reduction, see selectDimensions(int[]).

      Parameters:
      slicePoint - where to take a slice. NaN values are handled as if their dimensions were absent.
      modifiedDimensions - mapping from slicePoint dimensions to this GridExtent dimensions, or null if slicePoint contains all grid dimensions in same order.
      Returns:
      a grid extent for the specified slice.
      Throws:
      PointOutsideCoverageException - if the given point is outside the grid extent.

    • cornerToCRS

      final MatrixSIS cornerToCRS(org.opengis.geometry.Envelope env, long flippedAxes, int[] sourceDimensions)
      Creates an affine transform from the coordinates of this grid to the coordinates of the given envelope. This method assumes that all axes are in the same order (no axis swapping) and there is no flipping of axis direction except for those specified in the flips bitmask. The transform maps cell corners.
      Parameters:
      env - the target envelope. Despite this method name, the envelope CRS is ignored.
      flippedAxes - bitmask of target axes to flip (0 if none).
      sourceDimensions - source dimension for each target dimension, or null if dimensions are the same.
      Returns:
      an affine transform from this grid extent to the given envelope, expressed as a matrix.

    • translate

      public GridExtent translate(long... translation)
      Returns an extent translated by the given amount of cells compared to this extent. The returned extent has the same size than this extent, i.e. both low and high grid coordinates are displaced by the same amount of cells.
      Example: for an extent (x: [0…10], y: [2…4], z: [0…1]) and a translation {-2, 2}, the resulting extent would be (x: [-2…8], y: [4…6], z: [0…1]).

      Number of arguments

      The translation array length should be equal to the number of dimensions. If the array is shorter, missing values default to 0 (i.e. no translation in unspecified dimensions). If the array is longer, extraneous values are ignored.
      Parameters:
      translation - translation to apply on each axis in order.
      Returns:
      a grid extent whose coordinates (both low and high ones) have been translated by given amounts. If the given translation is a no-op (no value or only 0 ones), then this extent is returned as is.
      Throws:
      ArithmeticException - if the translation results in coordinates that overflow 64-bits integer.
      Since:
      1.1
      See Also:

    • contains

      public boolean contains(long... indices)
      Returns true if this extent contains the given cell indices. An index is considered inside the grid extent if its value is between low and high bounds, inclusive.

      Number of arguments

      The indices array length should be equal to the number of dimensions. If the array is shorter, missing index values are considered inside the extent. If the array is longer, extraneous values are ignored.
      Parameters:
      indices - indices of the grid cell to check.
      Returns:
      whether the given indices are inside this extent.
      Since:
      1.2

    • intersect

      public GridExtent intersect(GridExtent other)
      Returns the intersection of this grid extent with the given grid extent. The given extent shall have the same number of dimensions than this extent. The axis types (vertical, temporal, …) must be the same in all dimensions, ignoring types that are absent.
      Parameters:
      other - the grid to intersect with.
      Returns:
      the intersection result. May be one of the existing instances.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the two extents do not have the same number of dimensions.
      IllegalArgumentException - if axis types are specified but inconsistent in at least one dimension.
      DisjointExtentException - if the given extent does not intersect this extent.
      Since:
      1.3

    • union

      public GridExtent union(GridExtent other)
      Returns the union of this grid extent with the given grid extent. The given extent shall have the same number of dimensions than this extent. The axis types (vertical, temporal, …) must be the same in all dimensions, ignoring types that are absent.
      Parameters:
      other - the grid to combine with.
      Returns:
      the union result. May be one of the existing instances.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the two extents do not have the same number of dimensions.
      IllegalArgumentException - if axis types are specified but inconsistent in at least one dimension.
      Since:
      1.3

    • combine

      private GridExtent combine(GridExtent other, boolean union)
      Implementation of union(GridExtent) and intersect(GridExtent)
      Parameters:
      other - the grid to combine with.
      Returns:
      the union or intersection result, or null if the intersection gave an empty result.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the two extents do not have the same number of dimensions.
      IllegalArgumentException - if axis types are specified but inconsistent in at least one dimension.

    • extremum

      private static long extremum(long a, long b, boolean max)
      Returns the minimum or maximum value between the given pair of values.

    • isSameSize

      final boolean isSameSize(GridExtent other)
      Returns whether this grid extent has the same size than the given extent. If the given extent is null or has a different number of dimensions, then this method returns false.

      This method is not public because we do not yet have a policy about whether we should verify if axis types match.

      Parameters:
      other - the other extent to compare with this extent. Can be null.
      Returns:
      whether the two extents has the same size.

    • equals

      public final boolean equals(Object object)
      Compares the specified object with this grid extent for equality. This method delegates to equals(object, ComparisonMode.STRICT).
      Specified by:
      equals in interface LenientComparable
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compare with this grid extent for equality.
      Returns:
      true if the given object is equal to this grid extent.
      See Also:

    • equals

      public boolean equals(Object object, ComparisonMode mode)
      Compares the specified object with this grid extent for equality. If the mode is ComparisonMode.IGNORE_METADATA or more flexible, then the axis types are ignored.
      Specified by:
      equals in interface LenientComparable
      Parameters:
      object - the object to compare with this grid extent for equality.
      mode - the strictness level of the comparison.
      Returns:
      true if the given object is equal to this grid extent.
      Since:
      1.1
      See Also:

    • hashCode

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

    • toString

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

    • appendTo

      final void appendTo(Appendable out, Vocabulary vocabulary) throws IOException
      Writes a string representation of this grid extent in the given buffer. This method is provided for allowing caller to recycle the same buffer.
      Parameters:
      out - where to write the string representation.
      vocabulary - resources for some words.
      Throws:
      IOException

    • toSizeString

      static String toSizeString(long size)
      Returns a string representation of the given size, assumed computed by high - low + 1. A value of 0 means that there is an overflow and that the true value os 264.