Package org.apache.sis.coverage.grid

## Class GridCoverage

- Object
- - GridCoverage

-     public abstract class GridCoverage
      extends Object

  Base class of coverages with domains defined as a set of grid points. The essential property of coverage is to be able to generate a value for any point within its domain. Since a grid coverage is represented by a grid of values, the value returned by the coverage for a point is that of the grid value whose location is nearest the point.
  Since:
    1.0

  Defined in the `sis-feature` module

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `GridCoverage​(GridGeometry grid, Collection<? extends SampleDimension> bands)` | Constructs a grid coverage using the specified grid geometry and sample dimensions.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract GridCoverage` | `forConvertedValues​(boolean converted)` | Returns a grid coverage that contains real values or sample values, depending if `converted` is `true` or `false` respectively.
    `CoordinateReferenceSystem` | `getCoordinateReferenceSystem()` | Returns the coordinate reference system to which the values in grid domain are referenced.
    `GridGeometry` | `getGridGeometry()` | Returns information about the domain of this grid coverage.
    `List<SampleDimension>` | `getSampleDimensions()` | Returns information about the range of this grid coverage.
    `abstract RenderedImage` | `render​(GridExtent sliceExtent)` | Returns a two-dimensional slice of grid data as a rendered image.
    `String` | `toString()` | Returns a string representation of this grid coverage for debugging purpose.
    `TreeTable` | `toTree​(Locale locale, int bitmask)` | Returns a tree representation of some elements of this grid coverage.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### GridCoverage

          protected GridCoverage​(GridGeometry grid,
                                 Collection<? extends SampleDimension> bands)

      Constructs a grid coverage using the specified grid geometry and sample dimensions.
      Parameters:
        `grid` - the grid extent, CRS and conversion from cell indices to CRS.
        `bands` - sample dimensions for each image band.

  - ### Method Detail

    - #### getCoordinateReferenceSystem

          public CoordinateReferenceSystem getCoordinateReferenceSystem()

      Returns the coordinate reference system to which the values in grid domain are referenced. This is the CRS used when accessing a coverage with the `evaluate(…)` methods. This coordinate reference system is usually different than the coordinate system of the grid. It is the target coordinate reference system of the `gridToCRS` math transform.

      The default implementation delegates to `GridGeometry​.getCoordinateReferenceSystem()`.

      Returns:
        the CRS used when accessing a coverage with the `evaluate(…)` methods.
      Throws:
        `IncompleteGridGeometryException` - if the grid geometry has no CRS.

    - #### getGridGeometry

          public GridGeometry getGridGeometry()

      Returns information about the domain of this grid coverage. Information includes the grid extent, CRS and conversion from cell indices to CRS. `GridGeometry` can also provide derived information like bounding box and resolution.
      Returns:
        grid extent, CRS and conversion from cell indices to CRS.
      See Also:
        `GridCoverageResource​.getGridGeometry()`

    - #### getSampleDimensions

          public List<SampleDimension> getSampleDimensions()

      Returns information about the range of this grid coverage. Information include names, sample value ranges, fill values and transfer functions for all bands in this grid coverage. The length of the returned list should be equal to the number of bands in the rendered image.
      Returns:
        names, value ranges, fill values and transfer functions for all bands in this grid coverage.
      See Also:
        `GridCoverageResource​.getSampleDimensions()`

    - #### forConvertedValues

          public abstract GridCoverage forConvertedValues​(boolean converted)

      Returns a grid coverage that contains real values or sample values, depending if `converted` is `true` or `false` respectively. If there is no transfer function defined by the sample dimensions, then this method returns `this`. In all cases, the returned grid coverage r has the following properties:
      - The list returned by `r​.getSampleDimensions()` is equal to the list returned by `this.getSampleDimensions()` with each element e replaced by `e.forConvertedValues(converted)`.
      - The `RenderedImage` produced by `r​.render(extent)` is equivalent to the image returned by `this.render(extent)` with all sample values converted using the transfer function if `converted` is `true`, or the inverse of transfer function if `converted` is `false`.
      Parameters:
        `converted` - `true` for a coverage containing converted values, or `false` for a coverage containing packed values.
      Returns:
        a coverage containing converted or packed values, depending on `converted` argument value. May be `this` but never `null`.
      See Also:
        `SampleDimension​.forConvertedValues(boolean)`

    - #### render

          public abstract RenderedImage render​(GridExtent sliceExtent)

      Returns a two-dimensional slice of grid data as a rendered image. The given `sliceExtent` argument specifies the coordinates of the slice in all dimensions that are not in the two-dimensional image. For example if this grid coverage has (x,y,z,t) dimensions and we want to render an image of data in the (x,y) dimensions, then the given `sliceExtent` shall contain the (z,t) coordinates of the desired slice. Those coordinates are specified in a grid extent where low coordinate = high coordinate in the z and t dimensions. The two dimensions of the data to be shown (x and y in our example) shall be the only dimensions having a size greater than 1 cell.

      If the `sliceExtent` argument is `null`, then the default value is `getGridGeometry().getExtent()`. This means that `gridExtent` is optional for two-dimensional grid coverages or grid coverages where all dimensions except two have a size of 1 cell. If the grid extent contains more than 2 dimensions with a size greater than one cell, then a `SubspaceNotSpecifiedException` is thrown.

      How to compute a slice extent from a slice point in "real world" coordinates

      The `sliceExtent` is specified to this method as grid indices. If the z and t values are not grid indices but are relative to some Coordinate Reference System (CRS) instead, then the slice extent can be computed as below. First, a slice point containing the z and t coordinates should be constructed as a `DirectPosition` in one of the following ways:
      - The `slicePoint` has a CRS with two dimensions less than this grid coverage CRS.
      - The `slicePoint` has the same CRS than this grid coverage, but the two coordinates to exclude are set to `Double​.NaN`.
      Then:

      > `sliceExtent = getGridGeometry().`derive()`.slice(slicePoint).getIntersection();`

      If the `slicePoint` CRS is different than this grid coverage CRS (except for the number of dimensions), a coordinate transformation will be applied as needed.
      Characteristics of the returned image
      Image dimensions x and y map to the first and second dimension respectively of the two-dimensional `sliceExtent` subspace. The coordinates given by `RenderedImage​.getMinX()` and `getMinY()` will be the image location relative to the location specified in `sliceExtent` low coordinates. For example in the case of image minimum X coordinate:
      - A value of 0 means that the image left border is exactly where requested by `sliceExtent​.getLow(xDimension)`.
      - A positive value means that the returned image is shifted to the right compared to specified extent. This implies that the image has less data than requested on left side. It may happen if the specified extent is partially outside grid coverage extent.
      - A negative value means that the returned image is shifted to the left compared to specified extent. This implies that the image has more data than requested on left side. It may happen if the image is tiled, the specified `sliceExtent` covers many tiles, and expanding the specified extent is necessary for returning an integer amount of tiles.
      Similar discussion applies to the minimum Y coordinate. The image width and height will be the `sliceExtent` sizes if this method can honor exactly the request, or otherwise may be adjusted for the same reasons than x and y location discussed above.

      Implementations should return a view as much as possible, without copying sample values. `GridCoverage` subclasses can use the `ImageRenderer` class as a helper tool for that purpose. This method does not mandate any behavior regarding tiling (size of tiles, their numbering system, etc.). Some implementations may defer data loading until a tile is requested.

      Parameters:
        `sliceExtent` - a subspace of this grid coverage extent where all dimensions except two have a size of 1 cell. May be `null` if this grid coverage has only two dimensions with a size greater than 1 cell.
      Returns:
        the grid slice as a rendered image. Image location is relative to `sliceExtent`.
      Throws:
        `SubspaceNotSpecifiedException` - if the given argument is not sufficient for reducing the grid to a two-dimensional slice.
        `DisjointExtentException` - if the given extent does not intersect this grid coverage.
        `RuntimeException` - if this method can not produce the rendered image for another reason.

    - #### toString

          public String toString()

      Returns a string representation of this grid coverage for debugging purpose. The returned string is implementation dependent and may change in any future version. Current implementation is equivalent to the following, where `<default flags>` is the same set of flags than `GridGeometry​.toString()`.

      >     return toTree(Locale.getDefault(), <default flags>).toString();

      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this grid coverage for debugging purpose.

    - #### toTree

          @Debug
          public TreeTable toTree​(Locale locale,
                                  int bitmask)

      Returns a tree representation of some elements of this grid coverage. The tree representation is for debugging purpose only and may change in any future SIS version.
      Parameters:
        `locale` - the locale to use for textual labels.
        `bitmask` - combination of `GridGeometry` flags.
      Returns:
        a tree representation of the specified elements.
      See Also:
        `GridGeometry​.toTree(Locale, int)`