Package org.apache.sis.coverage.grid

## Class GridDerivation

- Object
- - GridDerivation

-     public class GridDerivation
      extends Object

  Creates a new grid geometry derived from a base grid geometry with different extent or resolution. `GridDerivation` are created by calls to `GridGeometry​.derive()`. Properties of the desired grid geometry can be specified by calls to the following methods, in that order (each method is optional):
  1. `rounding(GridRoundingMode)` and/or `margin(int...)` in any order
  2. `resize(GridExtent, double...)`, `subgrid(Envelope, double...)` or `subgrid(GridGeometry)`
  3. `subsample(int...)` (if not set indirectly by above methods)
  4. `slice(DirectPosition)` and/or `sliceByRatio(double, int...)`
  Then the grid geometry is created by a call to `build()`. Alternatively, `getIntersection()` can be invoked if only the `GridExtent` is desired instead than the full `GridGeometry` and no subsampling is applied.

  All methods in this class preserve the number of dimensions. For example the `slice(DirectPosition)` method sets the grid size to 1 in all dimensions specified by the slice point, but does not remove those dimensions from the grid geometry. For dimensionality reduction, see `GridGeometry​.reduce(int...)`.

  Since:
    1.0
  See Also:
    `GridGeometry​.derive()`, `GridGeometry​.reduce(int...)`

  Defined in the `sis-feature` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected GridGeometry` | `base` | The base grid geometry from which to derive a new grid geometry.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `GridDerivation​(GridGeometry base)` | Creates a new builder for deriving a grid geometry from the specified base.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `GridGeometry` | `build()` | Builds a grid geometry with the configuration specified by the other methods in this `GridDerivation` class.
    `double` | `getGlobalScale()` | Returns an estimation of the scale factor when converting sub-grid coordinates to `base` grid coordinates.
    `GridExtent` | `getIntersection()` | Returns the extent of the modified grid geometry, ignoring subsamplings or changes in resolution.
    `int[]` | `getSubsamplings()` | Returns an estimation of the strides for accessing cells along each axis of base grid.
    `GridDerivation` | `margin​(int... cellCounts)` | Specifies an amount of cells by which to expand `GridExtent` after rounding.
    `GridDerivation` | `resize​(GridExtent extent, double... scales)` | Requests a grid geometry where cell sizes have been scaled by the given factors, which result in a change of grid size.
    `GridDerivation` | `rounding​(GridRoundingMode mode)` | Controls behavior of rounding from floating point values to integers.
    `GridDerivation` | `slice​(DirectPosition slicePoint)` | Requests a grid geometry for a slice at the given "real world" position.
    `GridDerivation` | `sliceByRatio​(double sliceRatio, int... dimensionsToKeep)` | Requests a grid geometry for a slice at the given relative position.
    `GridDerivation` | `subgrid​(GridGeometry gridOfInterest)` | Adapts the base grid for the geographic area and resolution of the given grid geometry.
    `GridDerivation` | `subgrid​(Envelope areaOfInterest, double... resolution)` | Requests a grid geometry over a sub-region of the base grid geometry and optionally with subsampling.
    `GridDerivation` | `subsample​(int... subsamplings)` | Applies a subsampling on the grid geometry to build.
    `String` | `toString()` | Returns a string representation of this `GridDerivation` for debugging purpose.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### base

          protected final GridGeometry base

      The base grid geometry from which to derive a new grid geometry.

  - ### Constructor Detail

    - #### GridDerivation

          protected GridDerivation​(GridGeometry base)

      Creates a new builder for deriving a grid geometry from the specified base.
      Parameters:
        `base` - the base to use as a template for deriving a new grid geometry.
      See Also:
        `GridGeometry​.derive()`

  - ### Method Detail

    - #### rounding

          public GridDerivation rounding​(GridRoundingMode mode)

      Controls behavior of rounding from floating point values to integers. This setting modifies computations performed by the following methods (it has no effect on other methods in this `GridDerivation` class):
      - `slice(DirectPosition)`
      - `subgrid(Envelope, double...)`
      If this method is never invoked, the default value is `GridRoundingMode​.NEAREST`. If this method is invoked too late, an `IllegalStateException` is thrown.
      Parameters:
        `mode` - the new rounding mode.
      Returns:
        `this` for method call chaining.
      Throws:
        `IllegalStateException` - if `subgrid(Envelope, double...)` or `slice(DirectPosition)` has already been invoked.

    - #### margin

          public GridDerivation margin​(int... cellCounts)

      Specifies an amount of cells by which to expand `GridExtent` after rounding. This setting modifies computations performed by the following methods (it has no effect on other methods in this `GridDerivation` class):
      - `subgrid(GridGeometry)`
      - `subgrid(Envelope, double...)`
      - `resize(GridExtent, double...)`
      For each dimension i of the grid computed by above methods, the low grid coordinate is subtracted by `cellCount[i]` and the high grid coordinate is increased by `cellCount[i]`. The result is intersected with the extent of the `base` grid geometry given to the constructor.
      Use case: if the caller wants to apply bilinear interpolations in an image, (s)he will need 1 more pixel on each image border. If the caller wants to apply bi-cubic interpolations, (s)he will need 2 more pixels on each image border.
      If this method is never invoked, the default value is zero for all dimensions. If this method is invoked too late, an `IllegalStateException` is thrown. If the `count` array length is shorter than the grid dimension, then zero is assumed for all missing dimensions.
      Parameters:
        `cellCounts` - number of cells by which to expand the grid extent.
      Returns:
        `this` for method call chaining.
      Throws:
        `IllegalArgumentException` - if a value is negative.
        `IllegalStateException` - if `subgrid(Envelope, double...)` or `slice(DirectPosition)` has already been invoked.

    - #### resize

          public GridDerivation resize​(GridExtent extent,
                                       double... scales)

      Requests a grid geometry where cell sizes have been scaled by the given factors, which result in a change of grid size. The new grid geometry is given a "grid to CRS" transform computed as the concatenation of given scale factors (applied on grid indices) followed by the grid to CRS transform of the grid geometry specified at construction time. The resulting grid extent can be specified explicitly (typically as an extent computed by `GridExtent​.resize(long...)`) or computed automatically by this method.
      Example: if the original grid geometry had an extent of [0 … 5] in x and [0 … 8] in y, then a call to `resize(null, 0.1, 0.1)` will build a grid geometry with an extent of [0 … 50] in x and [0 … 80] in y. This new extent covers the same geographic area than the old extent but with pixels having a size of 0.1 times the old pixels size. The grid to CRS transform of the new grid geometry will be pre-concatenated with scale factors of 0.1 in compensation for the shrink in pixels size.

      Notes:

      - This method can be invoked only once.
      - This method can not be used together with a `subgrid(…)` method.
      - If a non-default rounding mode is desired, it should be specified before to invoke this method.
      - This method does not reduce the number of dimensions of the grid geometry. For dimensionality reduction, see `GridGeometry​.reduce(int...)`.
      This method can be seen as a complement of `subgrid(Envelope, double...)` working in grid coordinates space instead of CRS coordinates space.
      Parameters:
        `extent` - the grid extent to set as a result of the given scale, or `null` for computing it automatically. In non-null, then this given extent is used as-is without checking intersection with the base grid geometry.
        `scales` - the scale factors to apply on grid indices. If the length of this array is smaller than the number of grid dimension, then a scale of 1 is assumed for all missing dimensions.
      Returns:
        `this` for method call chaining.
      Throws:
        `IllegalStateException` - if a `subgrid(…)` or `slice(…)` method has already been invoked.
      See Also:
        `subsample(int...)`, `GridExtent​.resize(long...)`

    - #### subgrid

          public GridDerivation subgrid​(GridGeometry gridOfInterest)

      Adapts the base grid for the geographic area and resolution of the given grid geometry. The new grid geometry will cover the spatiotemporal region given by `gridOfInterest` envelope (coordinate operations are applied as needed if the Coordinate Reference Systems are not the same). The new grid geometry resolution will be integer multiples of the `base` grid geometry resolution.
      Usage: This method can be helpful for implementation of `GridCoverageResource​.read(GridGeometry, int...)`. Example:

      >     class MyDataStorage extends GridCoverageResource {
      >         @Override
      >         public GridCoverage read(GridGeometry domain, int... range) throws DataStoreException {
      >             GridDerivation change = getGridGeometry().derive().subgrid(domain);
      >             GridExtent toRead = change.buildExtent();
      >             int[] subsampling = change.getSubsamplings());
      >             // Do reading here.
      >         }
      >     }

      The following information are mandatory:
      - Extent in `gridOfInterest`.
      - Grid to CRS conversion in `gridOfInterest`.
      - Grid to CRS conversion in `base` grid.
      The following information are optional but recommended:
      - Coordinate reference system in `gridOfInterest`.
      - Coordinate reference system in `base` grid.
      - Extent in `base` grid.
      An optional margin can be specified for increasing the size of the grid extent computed by this method. For example if the caller wants to apply bilinear interpolations in an image, (s)he will need 1 more pixel on each image border. If the caller wants to apply bi-cubic interpolations, (s)he will need 2 more pixels on each image border.

      Notes:

      - This method can be invoked only once.
      - This method can not be used together with `subgrid(Envelope, double...)` or `resize(GridExtent, double...)`.
      - If a non-default rounding mode is desired, it should be specified before to invoke this method.
      - This method does not reduce the number of dimensions of the grid geometry. For dimensionality reduction, see `GridGeometry​.reduce(int...)`.
      Parameters:
        `gridOfInterest` - the area of interest and desired resolution as a grid geometry.
      Returns:
        `this` for method call chaining.
      Throws:
        `DisjointExtentException` - if the given grid of interest does not intersect the grid extent.
        `IncompleteGridGeometryException` - if a mandatory property of a grid geometry is absent.
        `IllegalGridGeometryException` - if an error occurred while converting the envelope coordinates to grid coordinates.
        `IllegalStateException` - if a `subgrid(…)` or `slice(…)` method has already been invoked.
      See Also:
        `getIntersection()`, `getSubsamplings()`

    - #### subgrid

          public GridDerivation subgrid​(Envelope areaOfInterest,
                                        double... resolution)

      Requests a grid geometry over a sub-region of the base grid geometry and optionally with subsampling. The given envelope does not need to be expressed in the same coordinate reference system (CRS) than the CRS of the base grid geometry; coordinate conversions or transformations will be applied as needed. That envelope CRS may have fewer dimensions than the base grid geometry CRS, in which case grid dimensions not mapped to envelope dimensions will be returned unchanged. The target resolution, if provided, shall be in same units and same order than the given envelope axes. If the length of `resolution` array is less than the number of dimensions of `areaOfInterest`, then no subsampling will be applied on the missing dimensions.

      Notes:

      - This method can be invoked only once.
      - This method can not be used together with `subgrid(GridGeometry)` or `resize(GridExtent, double...)`.
      - If a non-default rounding mode is desired, it should be specified before to invoke this method.
      - This method does not reduce the number of dimensions of the grid geometry. For dimensionality reduction, see `GridGeometry​.reduce(int...)`.
      - If the given envelope is known to be expressed in the same CRS than the grid geometry, then the CRS of the envelope can be left unspecified (`null`). It may give a slight performance improvement by avoiding the check for coordinate transformation.
      Parameters:
        `areaOfInterest` - the desired spatiotemporal region in any CRS (transformations will be applied as needed), or `null` for not restricting the sub-grid to a sub-area.
        `resolution` - the desired resolution in the same units and order than the axes of the given envelope, or `null` or an empty array if no subsampling is desired. The array length should be equal to the `areaOfInterest` dimension, but this is not mandatory (zero or missing values mean no sub-sampling, extraneous values are ignored).
      Returns:
        `this` for method call chaining.
      Throws:
        `DisjointExtentException` - if the given area of interest does not intersect the grid extent.
        `IncompleteGridGeometryException` - if the base grid geometry has no extent, no "grid to CRS" transform, or no CRS (unless `areaOfInterest` has no CRS neither, in which case the CRS are assumed the same).
        `IllegalGridGeometryException` - if an error occurred while converting the envelope coordinates to grid coordinates.
        `IllegalStateException` - if a `subgrid(…)` or `slice(…)` method has already been invoked.
      See Also:
        `getIntersection()`, `getSubsamplings()`

    - #### subsample

          public GridDerivation subsample​(int... subsamplings)

      Applies a subsampling on the grid geometry to build. This method can be invoked as an alternative to `subgrid(…)` methods if only the resolution needs to be changed. The extent of the built grid geometry will be derived from `getIntersection()` as below for each dimension i:
      - The low is divided by `subsamplings[i]`, rounded toward zero.
      - The size is divided by `subsamplings[i]`, rounded toward zero.
      - The high is recomputed from above low and size.
      The grid to CRS transform is scaled accordingly in order to map approximately to the same envelope.
      Parameters:
        `subsamplings` - the subsampling to apply on each grid dimension. All values shall be greater than zero. If the array length is shorter than the number of dimensions, missing values are assumed to be 1.
      Returns:
        `this` for method call chaining.
      Throws:
        `IllegalStateException` - if a subsampling has already been set, for example by a call to `subgrid(…)`.
      See Also:
        `subgrid(GridGeometry)`, `getSubsamplings()`, `GridExtent​.subsample(int...)`

    - #### slice

          public GridDerivation slice​(DirectPosition slicePoint)

      Requests a grid geometry for a slice at the given "real world" position. The given position can be expressed in any coordinate reference system (CRS). The position should not define a coordinate for all dimensions, otherwise the slice would degenerate to a single point. Dimensions can be left unspecified either by assigning to `slicePoint` a CRS without those dimensions, or by assigning the NaN value to some coordinates.
      Example: if the coordinate reference system of base grid geometry has (longitude, latitude, time) axes, then a (longitude, latitude) slice at time t can be created with one of the following two positions:
      - A three-dimensional position with (`Double​.NaN`, `Double​.NaN`, t) coordinates.
      - A one-dimensional position with (t) coordinate and the coordinate reference system set to the temporal component of the grid geometry CRS.

      Notes:

      - This method can be invoked after `subgrid(Envelope, double...)`, but not before.
      - If a non-default rounding mode is desired, it should be specified before to invoke this method.
      - This method does not reduce the number of dimensions of the grid geometry. For dimensionality reduction, see `GridGeometry​.reduce(int...)`.
      - If the given point is known to be expressed in the same CRS than the grid geometry, then the CRS of the point can be left unspecified (`null`). It may give a slight performance improvement by avoiding the check for coordinate transformation.
      Parameters:
        `slicePoint` - the coordinates where to get a slice. If no coordinate reference system is attached to it, we consider it's the same as base grid geometry.
      Returns:
        `this` for method call chaining.
      Throws:
        `IncompleteGridGeometryException` - if the base grid geometry has no extent, no "grid to CRS" transform, or no CRS (unless `slicePoint` has no CRS neither, in which case the CRS are assumed the same).
        `IllegalGridGeometryException` - if an error occurred while converting the point coordinates to grid coordinates.
        `RuntimeException` - if the given point is outside the grid extent.

    - #### sliceByRatio

          public GridDerivation sliceByRatio​(double sliceRatio,
                                             int... dimensionsToKeep)

      Requests a grid geometry for a slice at the given relative position. The relative position is specified by a ratio between 0 and 1 where 0 maps to low grid coordinates, 1 maps to high grid coordinates and 0.5 maps to the median position. The slicing is applied on all dimensions except the specified dimensions to keep.
      Example: given a n-dimensional cube, the following call creates a slice of the two first dimensions (numbered 0 and 1, typically the dimensions of x and y axes) located at the center (ratio 0.5) of all other dimensions (typically z and/or t axes):

      >     gridGeometry.derive().sliceByRatio(0.5, 0, 1).build();

      Parameters:
        `sliceRatio` - the ratio to apply on all grid dimensions except the ones to keep.
        `dimensionsToKeep` - the grid dimension to keep unchanged.
      Returns:
        `this` for method call chaining.
      Throws:
        `IncompleteGridGeometryException` - if the base grid geometry has no extent.
        `IndexOutOfBoundsException` - if a `dimensionsToKeep` value is out of bounds.

    - #### build

          public GridGeometry build()

      Builds a grid geometry with the configuration specified by the other methods in this `GridDerivation` class.
      Returns:
        the modified grid geometry. May be the `base` grid geometry if no change apply.
      See Also:
        `getIntersection()`

    - #### getIntersection

          public GridExtent getIntersection()

      Returns the extent of the modified grid geometry, ignoring subsamplings or changes in resolution. This is the intersection of the `base` grid geometry with the (grid or geospatial) envelope given to a `subgrid(…)` method, expanded by the specified margin (if any) and potentially with some grid sizes set to 1 if a `slice(…)` method has been invoked. The returned extent is in units of the `base` grid cells, i.e. subsamplings are ignored.
      Returns:
        intersection of grid geometry extents in units of `base` grid cells.

    - #### getSubsamplings

          public int[] getSubsamplings()

      Returns an estimation of the strides for accessing cells along each axis of base grid. If `subsample(int...)` has been invoked, then this method returns the argument values given to that method. Otherwise if a `subgrid(…)` method has been invoked, then this method computes the subsamplings as below: Given a conversion from `gridOfInterest` grid coordinates (x, y, z) to `base` grid coordinates (x′, y′, z′) defined as below (generalize to as many dimensions as needed):
      - x′ = s₀⋅x
      - y′ = s₁⋅y
      - z′ = s₂⋅z
      Then this method returns {|s₀|, |s₁|, |s₂|} rounded toward zero or nearest integer (depending on the grid rounding mode) and clamped to 1 (i.e. all values in the returned array are strictly positive, no zero values). It means that an iteration over `gridOfInterest` grid coordinates with a stride Δx=1 corresponds approximately to an iteration in `base` grid coordinates with a stride of Δx′=s₀, a stride Δy=1 corresponds approximately to a stride Δy′=s₁, etc. If the conversion changes grid axis order, then the order of elements in the returned array is the order of axes in the `base` grid.
      Returns:
        an estimation of the strides for accessing cells along each axis of `base` grid.
      See Also:
        `subgrid(GridGeometry)`, `subgrid(Envelope, double...)`, `subsample(int...)`

    - #### getGlobalScale

          public double getGlobalScale()

      Returns an estimation of the scale factor when converting sub-grid coordinates to `base` grid coordinates. This is for information purpose only since this method combines potentially different scale factors for all dimensions.
      Returns:
        an estimation of the scale factor for all dimensions.
      See Also:
        `subgrid(GridGeometry)`, `subgrid(Envelope, double...)`

    - #### toString

          public String toString()

      Returns a string representation of this `GridDerivation` for debugging purpose. The returned string is implementation dependent and may change in any future version.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this `GridDerivation` for debugging purpose.