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.