Module org.apache.sis.feature
Package org.apache.sis.coverage.grid

# Class GridCoverage2D

Object
BandedCoverage
GridCoverage
GridCoverage2D

public class GridCoverage2D extends GridCoverage
Basic access to grid data values backed by a two-dimensional `RenderedImage`. While images are two-dimensional, the coverage envelope may have more dimensions. In other words the rendered image can be a two-dimensional slice in a n-dimensional space. The only restriction is that the grid extent has a size equals to 1 in all dimensions except two of them.

## Example

A remote sensing image may be valid only over some time range (the temporal period of the satellite passing over observed area). Envelopes for such grid coverage can have three dimensions: the two usual ones (horizontal extent along x and y), and a third dimension for start time and end time (temporal extent along t). This "two-dimensional" grid coverage can have any number of columns along x axis and any number of rows along y axis, but only one plan along t axis. This single plan can have a lower bound (the start time) and an upper bound (the end time).

## Image size and location

The image width and height must be equal to the grid extent size in the two dimensions of the slice. However, the image origin (minimal x and y values) does not need to be equal to the grid extent low values; a translation will be applied as needed.

## Image bands

Each band in an image is represented as a `SampleDimension`.

Since:
  1.1

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class GridCoverage

  `GridCoverage​.Evaluator`

- ## Field Summary

  ### Fields inherited from class GridCoverage

  `gridGeometry`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GridCoverage2D(GridCoverage source, RenderedImage data)`
  Constructs a grid coverage using the same domain and range than the given coverage, but different data.
  `GridCoverage2D(GridGeometry domain, List<? extends SampleDimension> range, RenderedImage data)`
  Constructs a grid coverage using the specified domain, range and data.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected GridCoverage`
  `createConvertedValues(boolean converted)`
  Creates a grid coverage that contains real values or sample values, depending if `converted` is `true` or `false` respectively.
  `GridCoverage​.Evaluator`
  `evaluator()`
  Creates a new function for computing or interpolating sample values at given locations.
  `GridGeometry`
  `getGridGeometry2D()`
  Returns the two-dimensional part of this grid geometry.
  `RenderedImage`
  `render(GridExtent sliceExtent)`
  Returns a grid data region as a rendered image.

  ### Methods inherited from class GridCoverage

  `forConvertedValues, getCoordinateReferenceSystem, getEnvelope, getGridGeometry, getSampleDimensions, toString, toTree`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### GridCoverage2D

    public GridCoverage2D(GridCoverage source, RenderedImage data)
    Constructs a grid coverage using the same domain and range than the given coverage, but different data. This constructor can be used when new data have been computed by an image processing operation, but each pixel of the result have the same coordinates and the same units of measurement than in the source coverage.
    Parameters:
      `source` - the coverage from which to copy grid geometry and sample dimensions.
      `data` - the sample values as a `RenderedImage`, with one band for each sample dimension.
    Throws:
      `IllegalGridGeometryException` - if the image size is not consistent with the grid geometry.
      `IllegalArgumentException` - if the image number of bands is not the same than the number of sample dimensions.
    Since:
      1.2

  - ### GridCoverage2D

    public GridCoverage2D(GridGeometry domain, List<? extends SampleDimension> range, RenderedImage data)
    Constructs a grid coverage using the specified domain, range and data. If the given domain does not have an extent, then a default `GridExtent` will be computed from given image. Otherwise the image width and height must be equal to the grid extent size in the two dimensions of the slice.

    The image origin (minimal x and y values) can be anywhere; it does not need to be the same as the grid extent low values. Translations will be applied automatically when needed.

    This constructor throws an `IllegalGridGeometryException` if one of the following errors is detected in the `domain` argument:

    - The given domain has less than two dimensions.
    - The given domain has more than two dimensions having an extent size greater than 1.
    - The extent size along x and y axes is not equal to the image width and height.
    Parameters:
      `domain` - the grid extent (may be absent), CRS and conversion from cell indices. If `null` a default grid geometry will be created with no CRS and identity conversion.
      `range` - sample dimensions for each image band. The size of this list must be equal to the number of bands. If `null`, default sample dimensions will be created with no transfer function.
      `data` - the sample values as a `RenderedImage`, with one band for each sample dimension.
    Throws:
      `IllegalGridGeometryException` - if the `domain` does not met the above-documented conditions.
      `IllegalArgumentException` - if the image number of bands is not the same than the number of sample dimensions.
      `ArithmeticException` - if the distance between grid location and image location exceeds the `long` capacity.
    See Also:
      - `GridCoverageBuilder`

- ## Method Details

  - ### getGridGeometry2D

    public GridGeometry getGridGeometry2D()
    Returns the two-dimensional part of this grid geometry. If the complete geometry is already two-dimensional, then this method returns the same geometry. Otherwise it returns a geometry for the two first axes having a size greater than 1 in the grid envelope. Note that those axes are guaranteed to appear in the same order than in the complete geometry.
    Returns:
      the two-dimensional part of the grid geometry.
    See Also:
      - `GridCoverage​.getGridGeometry()`
      - `GridGeometry​.selectDimensions(int[])`

  - ### createConvertedValues

    protected GridCoverage createConvertedValues(boolean converted)
    Creates a grid coverage that contains real values or sample values, depending if `converted` is `true` or `false` respectively. This method is invoked by the default implementation of `GridCoverage​.forConvertedValues(boolean)` when first needed.
    Overrides:
      `createConvertedValues` in class `GridCoverage`
    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.

  - ### evaluator

    public GridCoverage.Evaluator evaluator()
    Creates a new function for computing or interpolating sample values at given locations.

    #### Multi-threading

    `Evaluator`s are not thread-safe. For computing sample values concurrently, a new `Evaluator` instance should be created for each thread.
    Overrides:
      `evaluator` in class `GridCoverage`
    Returns:
      a new function for computing or interpolating sample values.
    Since:
      1.1

  - ### render

    public RenderedImage render(GridExtent sliceExtent) throws CannotEvaluateException
    Returns a grid data region as a rendered image. The `sliceExtent` argument specifies the area of interest and may be `null` for requesting the whole image. The coordinates given by `RenderedImage​.getMinX()` and `getMinY()` will be the image location relative to the location specified in `sliceExtent` low coordinates (see super-class javadoc for more discussion). The image width and height will be the `sliceExtent` sizes if this method can honor exactly the request, but this method is free to return a smaller or larger image if doing so reduce the amount of data to create or copy. This implementation returns a view as much as possible, without copying sample values.
    Specified by:
      `render` in class `GridCoverage`
    Parameters:
      `sliceExtent` - area of interest, or `null` for the whole image.
    Returns:
      the grid slice as a rendered image. Image location is relative to `sliceExtent`.
    Throws:
      `MismatchedDimensionException` - if the given extent does not have the same number of dimensions than this coverage.
      `DisjointExtentException` - if the given extent does not intersect this grid coverage.
      `CannotEvaluateException` - if this method cannot produce the rendered image for another reason.
    See Also:
      - `BufferedImage​.getSubimage(int, int, int, int)`