## org.opengis.coverage.grid
Interface GridCoverage

All Superinterfaces:
  Coverage

All Known Subinterfaces:
  GridAnalysis

    @UML(identifier="CV_GridCoverage",
         specification=OGC_01004)
    public interface GridCoverage

extends Coverage

Represent the basic implementation which provides access to grid coverage data. A `GridCoverage` implementation may provide the ability to update grid values.

WARNING: THIS CLASS WILL CHANGE. Current API is derived from OGC Grid Coverages Implementation specification 1.0. We plan to replace it by new interfaces derived from ISO 19123 (Schema for coverage geometry and functions). Current interfaces should be considered as legacy and are included in this distribution only because they were part of GeoAPI 1.0 release. We will try to preserve as much compatibility as possible, but no migration plan has been determined yet.

Since:
  GeoAPI 1.0
Version:
  Grid Coverage specification 1.0
See Also:
  `RenderedImage`, `PixelAccessor`

Method Summary
`boolean[]` `getDataBlock(GridRange gridRange, boolean[] destination)` Return a sequence of boolean values for a block.
`byte[]` `getDataBlock(GridRange gridRange, byte[] destination)` Return a sequence of 8 bits values for a block.
`double[]` `getDataBlock(GridRange gridRange, double[] destination)` Return a sequence of double values for a block.
`float[]` `getDataBlock(GridRange gridRange, float[] destination)` Return a sequence of float values for a block.
`int[]` `getDataBlock(GridRange gridRange, int[] destination)` Return a sequence of 32 bits values for a block.
`short[]` `getDataBlock(GridRange gridRange, short[] destination)` Return a sequence of 16 bits values for a block.
`GridGeometry` `getGridGeometry()` Information for the grid coverage geometry.
`GridPacking` `getGridPacking()` Information for the packing of grid coverage values.
`int` `getNumOverviews()` Number of predetermined overviews for the grid.
`int[]` `getOptimalDataBlockSizes()` Optimal size to use for each dimension when accessing grid values.
`GridCoverage` `getOverview(int overviewIndex)` Returns a pre-calculated overview for a grid coverage.
`GridGeometry` `getOverviewGridGeometry(int overviewIndex)` Returns the grid geometry for an overview.
`byte[]` `getPackedDataBlock(GridRange gridRange)` Return a block of grid coverage data for all sample dimensions.
`boolean` `isDataEditable()` Returns `true` if grid data can be edited.
`void` `setDataBlock(GridRange gridRange, boolean[] values)` Set a block of boolean values for all sample dimensions.
`void` `setDataBlock(GridRange gridRange, byte[] values)` Set a block of 8 bits values for all sample dimensions.
`void` `setDataBlock(GridRange gridRange, double[] values)` Set a block of double values for all sample dimensions.
`void` `setDataBlock(GridRange gridRange, float[] values)` Set a block of float values for all sample dimensions.
`void` `setDataBlock(GridRange gridRange, int[] values)` Set a block of 32 bits values for all sample dimensions.
`void` `setDataBlock(GridRange gridRange, short[] values)` Set a block of 16 bits values for all sample dimensions.
`void` `setPackedDataBlock(GridRange gridRange, byte[] values)` Deprecated. This operation can hardly be implemented efficiently in Java with a `byte[]` argument type, since we can't easily cast an array of `byte[]` to an array of arbitrary type.

Methods inherited from interface Coverage
`evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluateInverse, find, find, getCommonPointRule, getCoordinateReferenceSystem, getDimensionNames, getDomainElements, getDomainExtents, getEnvelope, getMetadataNames, getMetadataValue, getNumSampleDimensions, getRangeElements, getRangeType, getRenderableImage, getSampleDimension, getSources, list, select`

Method Detail

### isDataEditable

    @UML(identifier="dataEditable",
         obligation=MANDATORY,
         specification=OGC_01004)
    boolean isDataEditable()

  Returns `true` if grid data can be edited.

  Returns:
    `true` if grid data can be edited.

### getGridPacking

    @UML(identifier="gridPacking",
         obligation=MANDATORY,
         specification=OGC_01004)
    GridPacking getGridPacking()

  Information for the packing of grid coverage values.

  Returns:
    The information for the packing of grid coverage values.

### getGridGeometry

    @UML(identifier="gridGeometry",
         obligation=MANDATORY,
         specification=OGC_01004)
    GridGeometry getGridGeometry()

  Information for the grid coverage geometry. Grid geometry includes the valid range of grid coordinates and the georeferencing.

  Returns:
    The information for the grid coverage geometry.

### getOptimalDataBlockSizes

    @UML(identifier="optimalDataBlockSizes",
         obligation=OPTIONAL,
         specification=OGC_01004)
    int[] getOptimalDataBlockSizes()

  Optimal size to use for each dimension when accessing grid values. These values together give the optimal block size to use when retrieving grid coverage values. For example, a client application can achieve better performance for a 2-D grid coverage by reading blocks of 128 by 128 if the grid is tiled into blocks of this size. The sequence is ordered by dimension. If the implementation does not have optimal sizes, the sequence will be `null`.

  Returns:
    The optimal size to use for each dimension when accessing grid values, or `null` if none.

### getNumOverviews

    @UML(identifier="numOverviews",
         obligation=MANDATORY,
         specification=OGC_01004)
    int getNumOverviews()

  Number of predetermined overviews for the grid.

  Returns:
    The number of predetermined overviews for the grid.

### getOverviewGridGeometry

    @UML(identifier="getOverviewGridGeometry",
         obligation=MANDATORY,
         specification=OGC_01004)
    GridGeometry getOverviewGridGeometry(int overviewIndex)
                                         throws IndexOutOfBoundsException

  Returns the grid geometry for an overview.

  Parameters:
    `overviewIndex` - Overview index for which to retrieve grid geometry. Indices start at 0.
  Returns:
    The grid geometry for an overview.
  Throws:
    `IndexOutOfBoundsException` - if `overviewIndex` is out of bounds.

### getOverview

    @UML(identifier="getOverview",
         obligation=MANDATORY,
         specification=OGC_01004)
    GridCoverage getOverview(int overviewIndex)
                             throws IndexOutOfBoundsException

  Returns a pre-calculated overview for a grid coverage. The overview indices are numbered from 0 to `numberOverviews-1`. The overviews are ordered from highest (index 0) to lowest (`numberOverviews-1`) resolution. Overview grid coverages will have overviews which are the overviews for the grid coverage with lower resolution than the overview. For example, a 1 meter grid coverage with 3, 9, and 27 meter overviews will be ordered as in the left side below. The 3 meter overview will have 2 overviews as in the right side below:

  > 1 meter GC |  | 3 meter overview
  > --- | --- | ---

  > Index | resolution
  > --- | ---
  > 0 | 3
  > 1 | 9
  > 2 | 27

  > Index | resolution
  > --- | ---
  > 0 | 9
  > 1 | 27

  Parameters:
    `overviewIndex` - Index of grid coverage overview to retrieve. Indexes start at 0.
  Returns:
    a pre-calculated overview for a grid coverage.
  Throws:
    `IndexOutOfBoundsException` - if `overviewIndex` is out of bounds.

### getDataBlock

    @UML(identifier="getDataBlockAsBoolean",
         obligation=MANDATORY,
         specification=OGC_01004)
    boolean[] getDataBlock(GridRange gridRange,
                                                                                  boolean[] destination)
                           throws InvalidRangeException,
                                  ArrayIndexOutOfBoundsException

  Return a sequence of boolean values for a block. A value for each sample dimension will be returned. The semantic is the same as `getDataBlock(GridRange, double[])` except for the return type.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `destination` - An optionally preallocated array in which to store the values, or `null` if none.
  Returns:
    A sequence of boolean values for a given block in the coverage. If `destination` was non-null, then it is returned. Otherwise, a new array is allocated and returned.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `ArrayIndexOutOfBoundsException` - if the `destination` array is not null and too small to hold the output.
  See Also:
    `setDataBlock(GridRange, boolean[])`

### getDataBlock

    @UML(identifier="getDataBlockAsByte",
         obligation=MANDATORY,
         specification=OGC_01004)
    byte[] getDataBlock(GridRange gridRange,
                                                                               byte[] destination)
                        throws InvalidRangeException,
                               ArrayIndexOutOfBoundsException

  Return a sequence of 8 bits values for a block. A value for each sample dimension will be returned. The semantic is the same as `getDataBlock(GridRange, double[])` except for the return type.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `destination` - An optionally preallocated array in which to store the values, or `null` if none.
  Returns:
    A sequence of 8 bits values for a given block in the coverage. If `destination` was non-null, then it is returned. Otherwise, a new array is allocated and returned.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `ArrayIndexOutOfBoundsException` - if the `destination` array is not null and too small to hold the output.
  See Also:
    `setDataBlock(GridRange, byte[])`, `UnpackedImageData`

### getDataBlock

    @UML(identifier="getDataBlockAsInteger",
         obligation=MANDATORY,
         specification=OGC_01004)
    short[] getDataBlock(GridRange gridRange,
                                                                                short[] destination)
                         throws InvalidRangeException,
                                ArrayIndexOutOfBoundsException

  Return a sequence of 16 bits values for a block. A value for each sample dimension will be returned. The semantic is the same as `getDataBlock(GridRange, double[])` except for the return type.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `destination` - An optionally preallocated array in which to store the values, or `null` if none.
  Returns:
    A sequence of 16 bits values for a given block in the coverage. If `destination` was non-null, then it is returned. Otherwise, a new array is allocated and returned.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `ArrayIndexOutOfBoundsException` - if the `destination` array is not null and too small to hold the output.
  See Also:
    `setDataBlock(GridRange, int[])`, `UnpackedImageData`

### getDataBlock

    @UML(identifier="getDataBlockAsInteger",
         obligation=MANDATORY,
         specification=OGC_01004)
    int[] getDataBlock(GridRange gridRange,
                                                                              int[] destination)
                       throws InvalidRangeException,
                              ArrayIndexOutOfBoundsException

  Return a sequence of 32 bits values for a block. A value for each sample dimension will be returned. The semantic is the same as `getDataBlock(GridRange, double[])` except for the return type.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `destination` - An optionally preallocated array in which to store the values, or `null` if none.
  Returns:
    A sequence of 32 bits values for a given block in the coverage. If `destination` was non-null, then it is returned. Otherwise, a new array is allocated and returned.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `ArrayIndexOutOfBoundsException` - if the `destination` array is not null and too small to hold the output.
  See Also:
    `setDataBlock(GridRange, int[])`, `Raster.getPixels(int,int,int,int,int[])`, `UnpackedImageData`

### getDataBlock

    float[] getDataBlock(GridRange gridRange,
                         float[] destination)
                         throws InvalidRangeException,
                                ArrayIndexOutOfBoundsException

  Return a sequence of float values for a block. A value for each sample dimension will be returned. The semantic is the same as `getDataBlock(GridRange, double[])` except for the return type.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `destination` - An optionally preallocated array in which to store the values, or `null` if none.
  Returns:
    A sequence of float values for a given block in the coverage. If `destination` was non-null, then it is returned. Otherwise, a new array is allocated and returned.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `ArrayIndexOutOfBoundsException` - if the `destination` array is not null and too small to hold the output.
  See Also:
    `setDataBlock(GridRange, float[])`, `Raster.getPixels(int,int,int,int,float[])`, `UnpackedImageData`

### getDataBlock

    @UML(identifier="getValueBlockAsDouble",
         obligation=MANDATORY,
         specification=OGC_01004)
    double[] getDataBlock(GridRange gridRange,
                                                                                 double[] destination)
                          throws InvalidRangeException,
                                 ArrayIndexOutOfBoundsException

  Return a sequence of double values for a block. A value for each sample dimension will be returned. The return value is an N+1 dimensional safe-array, with dimensions (sample dimension, dimension n, dimension n-1, ... dimension 1). For 2 dimensional grid coverages, this safe array will be accessed as (sample dimension, column, row). The index values will be based from 0. The indices in the returned N dimensional safe array will need to be offset by `gridRange` minimum coordinates to get equivalent grid coordinates.

  The requested grid range must satisfy the following rules for each dimension of the grid coverage:

  minimum grid coordinate <= grid range mimimun <= grid range maximum <= maximum grid coordinate
  The number of values returned will equal:
  (max1 - min1 + 1) * (max2 - min2 + 1) ... * (maxn - minn + 1) * `numSampleDimensions`
  Where min is the minimum ordinate in the grid range, max is the maximum ordinate in the grid range and N is the number of dimensions in the grid coverage.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `destination` - An optionally preallocated array in which to store the values, or `null` if none.
  Returns:
    A sequence of double values for a given block in the coverage. If `destination` was non-null, then it is returned. Otherwise, a new array is allocated and returned.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `ArrayIndexOutOfBoundsException` - if the `destination` array is not null and too small to hold the output.
  See Also:
    `setDataBlock(GridRange, double[])`, `Raster.getPixels(int,int,int,int,double[])`, `UnpackedImageData`
  TODO:
    Which indices vary fastest?

### getPackedDataBlock

    @UML(identifier="getPackedDataBlock",
         obligation=MANDATORY,
         specification=OGC_01004)
    byte[] getPackedDataBlock(GridRange gridRange)
                              throws InvalidRangeException

  Return a block of grid coverage data for all sample dimensions. A value for each sample dimension will be returned. This operation provides efficient access of the grid values. The sequencing order of the values in the sequence will follow the rules given by `valueInBytePacking` and `bandPacking` defined in `GridPacking`. The requested grid range must satisfy the following rules for each dimension of the grid coverage:
  minimum grid coordinate <= grid range mimimun <= grid range maximum <= maximum grid coordinate
  The sequence of bytes returned will match the data type of the dimension. For example, a grid with one 16 bit unsigned (`UNSIGNED_16BITS`) sample dimension will return 2 bytes for every cell in the block.

  Byte padding rules for grid values of less than 8 bits
  For 2D grid coverages, padding is to the nearest byte for the following cases:

  For PixelInterleaved | For grids with multiple sample dimensions, padding occurs between pixels for each change in dimension type.
  For LineInterleaved | Padding occurs at the end of each row or column (depending on the valueSequence of the grid).
  For BandSequencial | Padding occurs at the end of every sample dimension.

  For grid values smaller than 8 bits, their order within each byte is given by the value defined in `valueInBytePacking`. For grid values bigger than 8 bits, the order of their bytes is given by the value defined in `byteInValuePacking`.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
  Returns:
    a block of grid coverage data for all sample dimensions.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
  TODO:
    This operation can't be implemented efficiently in Java with a `byte[]` return type, since there is no way to cast an array of arbitrary type to an array of type `byte[]`. Even the `java.nio.Buffer` doesnt allow that (it allows the opposite way however).

### setDataBlock

    @UML(identifier="setDataBlockAsBoolean",
         obligation=MANDATORY,
         specification=OGC_01004)
    void setDataBlock(GridRange gridRange,
                                                                             boolean[] values)
                      throws InvalidRangeException,
                             GridNotEditableException,
                             ArrayIndexOutOfBoundsException

  Set a block of boolean values for all sample dimensions. The semantic is the same as `setDataBlock(GridRange, double[])`.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `values` - Sequence of grid values for the given region.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `GridNotEditableException` - if the grid coverage is not editable.
    `ArrayIndexOutOfBoundsException` - if the `values` array is too small.
  See Also:
    `isDataEditable()`, `getDataBlock(GridRange, boolean[])`

### setDataBlock

    @UML(identifier="setDataBlockAsByte",
         obligation=MANDATORY,
         specification=OGC_01004)
    void setDataBlock(GridRange gridRange,
                                                                             byte[] values)
                      throws InvalidRangeException,
                             GridNotEditableException,
                             ArrayIndexOutOfBoundsException

  Set a block of 8 bits values for all sample dimensions. The semantic is the same as `setDataBlock(GridRange, double[])`.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `values` - Sequence of grid values for the given region.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `GridNotEditableException` - if the grid coverage is not editable.
    `ArrayIndexOutOfBoundsException` - if the `values` array is too small.
  See Also:
    `isDataEditable()`, `getDataBlock(GridRange, byte[])`

### setDataBlock

    @UML(identifier="setDataBlockAsByte",
         obligation=MANDATORY,
         specification=OGC_01004)
    void setDataBlock(GridRange gridRange,
                                                                             short[] values)
                      throws InvalidRangeException,
                             GridNotEditableException,
                             ArrayIndexOutOfBoundsException

  Set a block of 16 bits values for all sample dimensions. The semantic is the same as `setDataBlock(GridRange, double[])`.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `values` - Sequence of grid values for the given region.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `GridNotEditableException` - if the grid coverage is not editable.
    `ArrayIndexOutOfBoundsException` - if the `values` array is too small.
  See Also:
    `isDataEditable()`, `getDataBlock(GridRange, short[])`

### setDataBlock

    @UML(identifier="setDataBlockAsInteger",
         obligation=MANDATORY,
         specification=OGC_01004)
    void setDataBlock(GridRange gridRange,
                                                                             int[] values)
                      throws InvalidRangeException,
                             GridNotEditableException,
                             ArrayIndexOutOfBoundsException

  Set a block of 32 bits values for all sample dimensions. The semantic is the same as `setDataBlock(GridRange, double[])`.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `values` - Sequence of grid values for the given region.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `GridNotEditableException` - if the grid coverage is not editable.
    `ArrayIndexOutOfBoundsException` - if the `values` array is too small.
  See Also:
    `isDataEditable()`, `getDataBlock(GridRange, int[])`, `WritableRaster.setPixels(int,int,int,int,int[])`

### setDataBlock

    @UML(identifier="setDataBlockAsInteger",
         obligation=MANDATORY,
         specification=OGC_01004)
    void setDataBlock(GridRange gridRange,
                                                                             float[] values)
                      throws InvalidRangeException,
                             GridNotEditableException,
                             ArrayIndexOutOfBoundsException

  Set a block of float values for all sample dimensions. The semantic is the same as `setDataBlock(GridRange, double[])`.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `values` - Sequence of grid values for the given region.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `GridNotEditableException` - if the grid coverage is not editable.
    `ArrayIndexOutOfBoundsException` - if the `values` array is too small.
  See Also:
    `isDataEditable()`, `getDataBlock(GridRange, float[])`, `WritableRaster.setPixels(int,int,int,int,float[])`

### setDataBlock

    @UML(identifier="setDataBlockAsDouble",
         obligation=MANDATORY,
         specification=OGC_01004)
    void setDataBlock(GridRange gridRange,
                                                                             double[] values)
                      throws InvalidRangeException,
                             GridNotEditableException,
                             ArrayIndexOutOfBoundsException

  Set a block of double values for all sample dimensions. The requested grid range must satisfy the following rules for each dimension of the grid coverage:
  minimum grid coordinate <= grid range mimimun <= grid range maximum <= maximum grid coordinate
  The number of values must equal:
  (max1 - min1 + 1) * (max2 - min2 + 1) ... * (maxn - minn + 1) * `numSampleDimensions`
  Where min is the minimum ordinate in the grid range, max is the maximum ordinate in the grid range and N is the number of dimensions in the grid coverage.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `values` - Sequence of grid values for the given region.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `GridNotEditableException` - if the grid coverage is not editable.
    `ArrayIndexOutOfBoundsException` - if the `values` array is too small.
  See Also:
    `isDataEditable()`, `getDataBlock(GridRange, double[])`, `WritableRaster.setPixels(int,int,int,int,double[])`

### setPackedDataBlock

    @UML(identifier="setPackedDataBlock",
         obligation=MANDATORY,
         specification=OGC_01004)
    void setPackedDataBlock(GridRange gridRange,
                                                                                   byte[] values)
                            throws InvalidRangeException,
                                   GridNotEditableException,
                                   ArrayIndexOutOfBoundsException

  Deprecated. This operation can hardly be implemented efficiently in Java with a `byte[]` argument type, since we can't easily cast an array of `byte[]` to an array of arbitrary type.

  Set a block of grid coverage data for all sample dimensions. See `getPackedDataBlock(org.opengis.coverage.grid.GridRange)` for details on how to pack the values.

  Parameters:
    `gridRange` - Grid range for block of data to be accessed.
    `values` - Sequence of grid values for the given region.
  Throws:
    `InvalidRangeException` - if `gridRange` is out of this grid range bounds.
    `GridNotEditableException` - if the grid coverage is not editable.
    `ArrayIndexOutOfBoundsException` - if the `values` array is too small.

Copyright © 1994-2008 Open Geospatial Consortium. All Rights Reserved.