Package org.apache.sis.coverage.grid

# Class BufferedGridCoverage

Object
BandedCoverage
GridCoverage
BufferedGridCoverage

public class BufferedGridCoverage extends GridCoverage
Basic access to grid data values backed by a n-dimensional `DataBuffer`. Those data can be shown as an untiled `RenderedImage`. Images are created when `render(GridExtent)` is invoked instead of at construction time. This delayed construction makes this class better suited to n-dimensional grids since those grids can not be wrapped into a single `RenderedImage`.
Comparison with alternatives: this class expects all data to reside in-memory and does not support tiling. Pixels are stored in a row-major fashion with all bands in a single array or one array per band. By contrast, `GridCoverage2D` allows more flexibility in data layout and supports tiling with data loaded or computed on-the-fly, but is restricted to two-dimensional images (which may be slices in a n-dimensional grid).
The number of bands is determined by the number of `SampleDimension`s specified at construction time. The number of banks is either 1 or the number of bands.

- If the number of banks is 1, all data are packed in a single array with band indices varying fastest, then column indices (x), then row indices (y), then other dimensions.
- If the number of banks is greater than 1, then each band is stored in a separated array. In each array, sample values are stored with column indices (x) varying fastest, then row indices (y), then other dimensions. In the two-dimensional case, this layout is also known as row-major.

The number of cells in each dimension is specified by the `GridExtent` of the geometry given at construction time. By default the extent size in the two first dimensions will define the image width and height, but different dimensions may be used depending on which dimensions are identified as the subspace dimensions.

Since:
  1.1

Defined in the `sis-feature` module

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class BandedCoverage

  `BandedCoverage​.Evaluator`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final DataBuffer`
  `data`
  The sample values, potentially multi-banded.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BufferedGridCoverage(GridGeometry grid, List<? extends SampleDimension> bands, int dataType)`
  Constructs a grid coverage using the specified grid geometry, sample dimensions and data type.
  `BufferedGridCoverage(GridGeometry domain, List<? extends SampleDimension> range, DataBuffer data)`
  Constructs a grid coverage using the specified grid geometry, sample dimensions and data buffer.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GridEvaluator`
  `evaluator()`
  Creates a new function for computing or interpolating sample values at given locations.
  `RenderedImage`
  `render(GridExtent sliceExtent)`
  Returns a two-dimensional slice of grid data as a rendered image.

  ### Methods inherited from class GridCoverage

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

  ### Methods inherited from class Object

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

- ## Field Details

  - ### data

    protected final DataBuffer data
    The sample values, potentially multi-banded. The bands may be stored either in a single bank (pixel interleaved image) or in different banks (banded image). This class detects automatically which of those two sample models is used when `render(GridExtent)` is invoked.

    Sample values in this buffer shall not be packed.

- ## Constructor Details

  - ### BufferedGridCoverage

    public BufferedGridCoverage(GridGeometry domain, List<? extends SampleDimension> range, DataBuffer data)
    Constructs a grid coverage using the specified grid geometry, sample dimensions and data buffer. This method stores the given buffer by reference (no copy). The bands in the given buffer can be stored either in a single bank (pixel interleaved image) or in different banks (banded image). This class detects automatically which of those two sample models is used (see class javadoc for more information).

    Note that `DataBuffer` does not contain any information about image size. Consequently `render(GridExtent)` depends on the domain `GridExtent`, which must be accurate. If the extent size does not reflect accurately the image size, then the image will not be rendered properly.

    Parameters:
      `domain` - the grid extent, CRS and conversion from cell indices to CRS.
      `range` - sample dimensions for each image band.
      `data` - the sample values, potentially multi-banded.
    Throws:
      `NullPointerException` - if an argument is `null`.
      `IllegalArgumentException` - if the data buffer has an incompatible number of banks.
      `IllegalGridGeometryException` - if the grid extent is larger than the data buffer capacity.
      `ArithmeticException` - if the number of cells is larger than 64 bits integer capacity.

  - ### BufferedGridCoverage

    public BufferedGridCoverage(GridGeometry grid, List<? extends SampleDimension> bands, int dataType)
    Constructs a grid coverage using the specified grid geometry, sample dimensions and data type. This constructor creates a single-bank `DataBuffer` (pixel interleaved sample model) with all sample values initialized to zero.
    Parameters:
      `grid` - the grid extent, CRS and conversion from cell indices to CRS.
      `bands` - sample dimensions for each image band.
      `dataType` - one of `DataBuffer​.TYPE_*` constants, the native data type used to store the coverage values.
    Throws:
      `ArithmeticException` - if the grid size is too large.

- ## Method Details

  - ### evaluator

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

    #### Multi-threading

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

  - ### render

    public RenderedImage render(GridExtent sliceExtent)
    Returns a two-dimensional slice of grid data as a rendered image. This method returns a view; sample values are not copied.
    Specified by:
      `render` in class `GridCoverage`
    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.