Package org.apache.sis.storage

## Interface GridCoverageResource

- All Superinterfaces:
    `DataSet`, `Resource`

      public interface GridCoverageResource
      extends DataSet

  Access to data values in a n-dimensional grid. A coverage is a kind of function with the following properties:
  - The function input is a position valid in the coverage domain. In the particular case of `GridCoverage`, the domain is described by a grid geometry.
  - The function output is a record of values in the coverage range. In the particular case of `GridCoverage`, the range is described by a list of sample dimensions.
  A coverage resource may be a member of `Aggregate` if a single file can provide many rasters.
  Since:
    1.0

  Defined in the `sis-storage` module

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `GridGeometry` | `getGridGeometry()` | Returns the valid extent of grid coordinates together with the conversion from those grid coordinates to real world coordinates.
    `List<SampleDimension>` | `getSampleDimensions()` | Returns the ranges of sample values together with the conversion from samples to real values.
    `GridCoverage` | `read​(GridGeometry domain, int... range)` | Loads a subset of the grid coverage represented by this resource.

    - ### Methods inherited from interface DataSet

      `getEnvelope`

    - ### Methods inherited from interface Resource

      `addListener, getIdentifier, getMetadata, removeListener`

- - ### Method Detail

    - #### getGridGeometry

          GridGeometry getGridGeometry()
                                throws DataStoreException

      Returns the valid extent of grid coordinates together with the conversion from those grid coordinates to real world coordinates. A grid geometry contains the following information:
      - The minimum and maximum grid coordinates as integers (the Grid Extent). The minimum coordinates are typically (0,0, …, 0) but not necessarily.
      - The minimum and maximum "real world" coordinates (the Envelope). Those coordinates are typically, but not necessarily, latitudes and longitudes or projected coordinates, together with altitudes and dates.
      - A description of the datum and axes of above "real world" coordinates (the Coordinate Reference System).
      - The conversion from grid coordinates to "real world" coordinates. This conversion is often, but not necessarily, a linear relationship. Axis order or direction may be changed by the conversion. For example row indices may be increasing toward down while latitude coordinates are increasing toward up.
      - An estimation of grid resolution for each "real world" axis.
      The grid returned by this method should be equal to the grid returned by `read(null).getGridGeometry()`. However the grid geometry returned by this method is allowed to be only approximate if computing accurate information would be prohibitively expensive, or if the grid geometry depends on the exact argument value given to the `read(…)` method. At least, the number of dimensions should match.
      Returns:
        extent of grid coordinates together with their mapping to "real world" coordinates.
      Throws:
        `DataStoreException` - if an error occurred while reading definitions from the underlying data store.
      See Also:
        `GridCoverage​.getGridGeometry()`

    - #### getSampleDimensions

          List<SampleDimension> getSampleDimensions()
                                             throws DataStoreException

      Returns the ranges of sample values together with the conversion from samples to real values. Sample dimensions contain the following information:
      - The range of valid sample values, typically but not necessarily as positive integers.
      - A transfer function for converting sample values to real values, for example measurements of a geophysics phenomenon. The transfer function is typically defined by a scale factor and an offset, but is not restricted to such linear equations.
      - The units of measurement of "real world" values after their conversions from sample values.
      - The sample values reserved for missing values.
      The returned list should never be empty. If the coverage is an image to be used only for visualization purposes (i.e. the image does not contain any classification data or any measurement of physical phenomenon), then list size should be equal to the number of bands in the image and sample dimension names may be "Red", "Green" and "Blue" for instance. Those sample dimensions do not need to contain any category.

      The list returned by this method should be equal to the list returned by `read(null).getSampleDimensions()`. However the sample dimensions returned by this method is allowed to be only approximate if computing accurate information would be prohibitively expensive, or if the sample dimensions depend on the `domain` argument (area of interest) given to the `read(…)` method. At least, the number of sample dimensions should match.

      Returns:
        ranges of sample values together with their mapping to "real values".
      Throws:
        `DataStoreException` - if an error occurred while reading definitions from the underlying data store.
      See Also:
        `GridCoverage​.getSampleDimensions()`

    - #### read

          GridCoverage read​(GridGeometry domain,
                            int... range)
                     throws DataStoreException

      Loads a subset of the grid coverage represented by this resource. If a non-null grid geometry is specified, then this method will try to return a grid coverage matching the given grid geometry on a best-effort basis; the coverage actually returned may have a different resolution, cover a different area in a different CRS, etc. The general contract is that the returned coverage should not contain less data than a coverage matching exactly the given geometry.

      The returned coverage shall contain the exact set of sample dimensions specified by the `range` argument, in the specified order (the "best-effort basis" flexibility applies only to the grid geometry, not to the range). All `range` values shall be between 0 inclusive and `getSampleDimensions().size()` exclusive, without duplicated values.

      While this method name suggests an immediate reading, some implementations may defer the actual reading at a later stage.

      Parameters:
        `domain` - desired grid extent and resolution, or `null` for reading the whole domain.
        `range` - 0-based indices of sample dimensions to read, or `null` or an empty sequence for reading them all.
      Returns:
        the grid coverage for the specified domain and range.
      Throws:
        `DataStoreException` - if an error occurred while reading the grid coverage data.