org.opengis.coverage.grid
Interface GridCoverage

All Superinterfaces:

Coverage

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.

Version:

Grid Coverage specification 1.0

Author:

OpenGIS® consortium

See Also:

RenderedImage, PixelAccessor

UML identifier (abstract type): CV_GridCoverage

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.
GridCoverage	getSource(int sourceDataIndex) Returns the source data for a grid coverage.
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) Set a block of grid coverage data for all sample dimensions.

Methods inherited from interface Coverage

evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, getCoordinateReferenceSystem, getDimensionNames, getEnvelope, getMetadataNames, getMetadataValue, getNumSampleDimensions, getNumSources, getRenderableImage, getSampleDimension

Method Detail

isDataEditable

boolean isDataEditable()

Returns true if grid data can be edited.

Returns:

true if grid data can be edited.

UML identifier (mandatory attribute): dataEditable

getGridPacking

GridPacking getGridPacking()

Information for the packing of grid coverage values.

Returns:

The information for the packing of grid coverage values.

UML identifier (mandatory attribute): gridPacking

getGridGeometry

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.

UML identifier (mandatory attribute): gridGeometry

getOptimalDataBlockSizes

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.

UML identifier (optional attribute): optimalDataBlockSizes

getNumOverviews

int getNumOverviews()

Number of predetermined overviews for the grid.

Returns:

The number of predetermined overviews for the grid.

UML identifier (mandatory attribute): numOverviews

getOverviewGridGeometry

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.

UML identifier (operation): getOverviewGridGeometry

getOverview

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.

UML identifier (operation): getOverview

getSource

GridCoverage getSource(int sourceDataIndex)
                       throws IndexOutOfBoundsException

Returns the source data for a grid coverage. If the GridCoverage was produced from an underlying dataset (by read(...) for instance) the getNumSources() method should returns zero, and this method should not be called. If the GridCoverage was produced using {link org.opengis.coverage.processing.GridCoverageProcessor} then it should return the source grid coverage of the one used as input to GridCoverageProcessor. In general the getSource(i) method is intended to return the original GridCoverage on which it depends. This is intended to allow applications to establish what GridCoverages will be affected when others are updated, as well as to trace back to the "raw data".

Specified by:

getSource in interface Coverage

Parameters:

sourceDataIndex - Source grid coverage index. Indexes start at 0.

Returns:

The source data for a grid coverage.

Throws:

IndexOutOfBoundsException - if sourceDataIndex is out of bounds.

See Also:

Coverage.getNumSources(), getSource(int)

UML identifier (operation): Coverage.getSource

getDataBlock

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[])

UML identifier (operation): getDataBlockAsBoolean

getDataBlock

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

UML identifier (operation): getDataBlockAsByte

getDataBlock

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

UML identifier (operation): getDataBlockAsInteger

getDataBlock

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

UML identifier (operation): getDataBlockAsInteger

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

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: (max₁ � min₁ + 1) * (max₂ � min₂ + 1) ... * (max_n � min_n + 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

UML identifier (operation): getValueBlockAsDouble

Name change from the UML:

Renamed getValueBlockAsDouble as getDataBlockAsDouble for consistency with all others getDataBlock... methods and setDataBlockAsDouble.

getPackedDataBlock

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.

UML identifier (operation): #getPackedDataBlock

setDataBlock

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[])

UML identifier (operation): setDataBlockAsBoolean

setDataBlock

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[])

UML identifier (operation): setDataBlockAsByte

setDataBlock

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[])

UML identifier (operation): setDataBlockAsByte

setDataBlock

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[])

UML identifier (operation): setDataBlockAsInteger

setDataBlock

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[])

UML identifier (operation): setDataBlockAsInteger

setDataBlock

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: (max₁ � min₁ + 1) * (max₂ � min₂ + 1) ... * (max_n � min_n + 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[])

UML identifier (operation): setDataBlockAsDouble

setPackedDataBlock

void setPackedDataBlock(GridRange gridRange,
                        byte[] values)
                        throws InvalidRangeException,
                               GridNotEditableException,
                               ArrayIndexOutOfBoundsException

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.

UML identifier (operation): setPackedDataBlock