org.opengis.coverage

Interface Coverage

All Known Subinterfaces:

GridAnalysis, GridCoverage

@UML(identifier="CV_Coverage",
     specification=OGC_01004)
public interface Coverage

Provides access to a coverage. The essential property of coverage is to be able to generate a value for any point within its domain. How coverage is represented internally is not a concern. For example consider the following different internal representations of coverage:

• A coverage may be represented by a set of polygons which exhaustively tile a plane (that is each point on the plane falls in precisely one polygon). The value returned by the coverage for a point is the value of an attribute of the polygon that contains the point.
• A coverage may be represented by a grid of values. The value returned by the coverage for a point is that of the grid value whose location is nearest the point.
• Coverage may be represented by a mathematical function. The value returned by the coverage for a point is just the return value of the function when supplied the coordinates of the point as arguments.
• Coverage may be represented by combination of these. For example, coverage may be represented by a combination of mathematical functions valid over a set of polynomials.

A coverage has a corresponding SampleDimension for each sample dimension in the coverage.

Implementation note:
We expect that many implementations of GridCoverage will want to leverage the rich set of Java Advanced Imaging (JAI) features. For those implementations, it is recommended (but not required) to implement the javax.media.jai.PropertySource interface as well. In this case, implementation of javax.media.jai.PropertySource methods must be consistent with getMetadataNames() and getMetadataValue(java.lang.String) methods.

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

See Also:

RenderableImage, javax.media.jai.ImageFunction

Method Summary

Modifier and Type	Method and Description
java.lang.Object	evaluate(DirectPosition point) Return the value vector for a given point in the coverage.
boolean[]	evaluate(DirectPosition point, boolean[] destination) Return a sequence of boolean values for a given point in the coverage.
byte[]	evaluate(DirectPosition point, byte[] destination) Return a sequence of unsigned byte values for a given point in the coverage.
double[]	evaluate(DirectPosition point, double[] destination) Return a sequence of double values for a given point in the coverage.
float[]	evaluate(DirectPosition point, float[] destination) Return a sequence of float values for a given point in the coverage.
int[]	evaluate(DirectPosition point, int[] destination) Return a sequence of integer values for a given point in the coverage.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Specifies the coordinate reference system used when accessing a coverage or grid coverage with the evaluate(...) methods.
InternationalString[]	getDimensionNames() The names of each dimension in the coverage.
Envelope	getEnvelope() The bounding box for the coverage domain in coordinate reference system coordinates.
java.lang.String[]	getMetadataNames() List of metadata keywords for a coverage.
java.lang.String	getMetadataValue(java.lang.String name) Retrieve the metadata value for a given metadata name.
int	getNumSampleDimensions() The number of sample dimensions in the coverage.
java.awt.image.renderable.RenderableImage	getRenderableImage(int xAxis, int yAxis) Returns 2D view of this coverage as a renderable image.
SampleDimension	getSampleDimension(int index) Retrieve sample dimension information for the coverage.
java.util.List<? extends Coverage>	getSources() Returns the sources data for a coverage.

Method Detail

getCoordinateReferenceSystem

@UML(identifier="coordinateSystem",
     obligation=MANDATORY,
     specification=OGC_01004)
CoordinateReferenceSystem getCoordinateReferenceSystem()

Specifies the coordinate reference system used when accessing a coverage or grid coverage with the evaluate(...) methods. It is also the coordinate reference system of the coordinates used with the math transform (see gridToCoordinateSystem). This coordinate reference system is usually different than coordinate system of the grid. Grid coverage can be accessed (re-projected) with new coordinate reference system with the GridCoverageProcessor component. In this case, a new instance of a grid coverage is created.

Note: If a coverage does not have an associated coordinate reference system, the returned value will be null. The gridToCoordinateSystem) attribute should also be null if the coordinate reference system is null.

Returns:

The coordinate reference system used when accessing a coverage or grid coverage with the evaluate(...) methods, or null.

getEnvelope

@UML(identifier="envelope",
     obligation=MANDATORY,
     specification=OGC_01004)
Envelope getEnvelope()

The bounding box for the coverage domain in coordinate reference system coordinates. For grid coverages, the grid cells are centered on each grid coordinate. The envelope for a 2-D grid coverage includes the following corner positions.

 (Minimum row - 0.5, Minimum column - 0.5) for the minimum coordinates
 (Maximum row - 0.5, Maximum column - 0.5) for the maximum coordinates
 

If a grid coverage does not have any associated coordinate reference system, the minimum and maximum coordinate points for the envelope will be empty sequences.

Returns:

The bounding box for the coverage domain in coordinate system coordinates.

getDimensionNames

@UML(identifier="dimensionNames",
     obligation=MANDATORY,
     specification=OGC_01004)
InternationalString[] getDimensionNames()

The names of each dimension in the coverage. Typically these names are x, y, z and t. The number of items in the sequence is the number of dimensions in the coverage. Grid coverages are typically 2D (x, y) while other coverages may be 3D (x, y, z) or 4D (x, y, z, t). The number of dimensions of the coverage is the number of entries in the list of dimension names.

getNumSampleDimensions

@UML(identifier="numSampleDimensions",
     obligation=MANDATORY,
     specification=OGC_01004)
int getNumSampleDimensions()

The number of sample dimensions in the coverage. For grid coverages, a sample dimension is a band.

Returns:

The number of sample dimensions in the coverage.

getSampleDimension

@UML(identifier="getSampleDimension",
     obligation=MANDATORY,
     specification=OGC_01004)
SampleDimension getSampleDimension(int index)
                                                                                                                           throws java.lang.IndexOutOfBoundsException

Retrieve sample dimension information for the coverage. For a grid coverage a sample dimension is a band. The sample dimension information include such things as description, data type of the value (bit, byte, integer...), the no data values, minimum and maximum values and a color table if one is associated with the dimension. A coverage must have at least one sample dimension.

Parameters:

index - Index for sample dimension to retrieve. Indices are numbered 0 to (n-1).

Returns:

Sample dimension information for the coverage.

Throws:

java.lang.IndexOutOfBoundsException - if index is out of bounds.

getSources

@UML(identifier="getSource, numSource",
     obligation=MANDATORY,
     specification=OGC_01004)
java.util.List<? extends Coverage> getSources()

Returns the sources data for a coverage. This is intended to allow applications to establish what Coverages will be affected when others are updated, as well as to trace back to the "raw data". This implementation specification does not include interfaces for creating collections of coverages therefore the list size will usually be one indicating an adapted grid coverage, or zero indicating a raw grid coverage.

Returns:

The list of sources data for a coverage.

getMetadataNames

@UML(identifier="metadataNames",
     obligation=MANDATORY,
     specification=OGC_01004)
java.lang.String[] getMetadataNames()

List of metadata keywords for a coverage. If no metadata is available, the sequence will be empty.

Returns:

the list of metadata keywords for a coverage.

See Also:

getMetadataValue(java.lang.String), javax.media.jai.PropertySource#getPropertyNames

getMetadataValue

@UML(identifier="getMetadataValue",
     obligation=MANDATORY,
     specification=OGC_01004)
java.lang.String getMetadataValue(java.lang.String name)
                                                                                                                        throws MetadataNameNotFoundException

Retrieve the metadata value for a given metadata name.

Parameters:

name - Metadata keyword for which to retrieve data.

Returns:

the metadata value for a given metadata name.

Throws:

MetadataNameNotFoundException - if there is no value for the specified metadata name.

See Also:

getMetadataNames(), javax.media.jai.PropertySource#getProperty

evaluate

@UML(identifier="evaluate",
     obligation=MANDATORY,
     specification=OGC_01004)
java.lang.Object evaluate(DirectPosition point)
                                                                                                        throws CannotEvaluateException

Return the value vector for a given point in the coverage. A value for each sample dimension is included in the vector. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor. The coordinate system of the point is the same as the grid coverage coordinate reference system (specified by the getCoordinateReferenceSystem() method).

Parameters:

point - Point at which to find the grid values.

Returns:

The value vector for a given point in the coverage.

Throws:

PointOutsideCoverageException - if the point is outside the coverage envelope.

CannotEvaluateException - If the point can't be evaluate for some othe reason.

See Also:

Raster.getDataElements(int, int, Object)

evaluate

@UML(identifier="evaluateAsBoolean",
     obligation=MANDATORY,
     specification=OGC_01004)
boolean[] evaluate(DirectPosition point,
                                                                                                                 boolean[] destination)
                                                                                                          throws CannotEvaluateException,
                                                                                                                 java.lang.ArrayIndexOutOfBoundsException

Return a sequence of boolean values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor. The coordinate reference system of the point is the same as the grid coverage coordinate reference system.

Parameters:

point - Point at which to find the coverage values.

destination - An optionally preallocated array in which to store the values, or null if none.

Returns:

A sequence of boolean values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.

Throws:

PointOutsideCoverageException - if the point is outside the coverage envelope.

CannotEvaluateException - if the point can't be evaluate for some othe reason.

java.lang.ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.

evaluate

@UML(identifier="evaluateAsByte",
     obligation=MANDATORY,
     specification=OGC_01004)
byte[] evaluate(DirectPosition point,
                                                                                                           byte[] destination)
                                                                                                    throws CannotEvaluateException,
                                                                                                           java.lang.ArrayIndexOutOfBoundsException

Return a sequence of unsigned byte values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor. The coordinate reference system of the point is the same as the grid coverage coordinate reference system.

Parameters:

point - Point at which to find the coverage values.

destination - An optionally preallocated array in which to store the values, or null if none.

Returns:

A sequence of unsigned byte values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.

Throws:

PointOutsideCoverageException - if the point is outside the coverage envelope.

CannotEvaluateException - if the point can't be evaluate for some othe reason.

java.lang.ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.

evaluate

@UML(identifier="evaluateAsInteger",
     obligation=MANDATORY,
     specification=OGC_01004)
int[] evaluate(DirectPosition point,
                                                                                                             int[] destination)
                                                                                                      throws CannotEvaluateException,
                                                                                                             java.lang.ArrayIndexOutOfBoundsException

Return a sequence of integer values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor. The coordinate reference system of the point is the same as the grid coverage coordinate reference system.

Parameters:

point - Point at which to find the grid values.

destination - An optionally preallocated array in which to store the values, or null if none.

Returns:

A sequence of integer values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.

Throws:

PointOutsideCoverageException - if the point is outside the coverage envelope.

CannotEvaluateException - if the point can't be evaluate for some othe reason.

java.lang.ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.

See Also:

Raster.getPixel(int, int, int[])

evaluate

float[] evaluate(DirectPosition point,
                 float[] destination)
          throws CannotEvaluateException,
                 java.lang.ArrayIndexOutOfBoundsException

Return a sequence of float values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor. The coordinate reference system of the point is the same as the grid coverage coordinate reference system.

Parameters:

point - Point at which to find the grid values.

destination - An optionally preallocated array in which to store the values, or null if none.

Returns:

A sequence of float values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.

Throws:

PointOutsideCoverageException - if the point is outside the coverage envelope.

CannotEvaluateException - if the point can't be evaluate for some othe reason.

java.lang.ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.

See Also:

Raster.getPixel(int, int, float[])

evaluate

@UML(identifier="evaluateAsDouble",
     obligation=MANDATORY,
     specification=OGC_01004)
double[] evaluate(DirectPosition point,
                                                                                                               double[] destination)
                                                                                                        throws CannotEvaluateException,
                                                                                                               java.lang.ArrayIndexOutOfBoundsException

Return a sequence of double values for a given point in the coverage. A value for each sample dimension is included in the sequence. The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor. The coordinate reference system of the point is the same as the grid coverage coordinate reference system.

Parameters:

point - Point at which to find the grid values.

destination - An optionally preallocated array in which to store the values, or null if none.

Returns:

A sequence of double values for a given point in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.

Throws:

PointOutsideCoverageException - if the point is outside the coverage envelope.

CannotEvaluateException - If the point can't be evaluate for some othe reason.

java.lang.ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.

See Also:

Raster.getPixel(int, int, double[])

getRenderableImage

java.awt.image.renderable.RenderableImage getRenderableImage(int xAxis,
                                                             int yAxis)
                                                      throws java.lang.UnsupportedOperationException,
                                                             java.lang.IndexOutOfBoundsException

Returns 2D view of this coverage as a renderable image. This optional operation allows interoperability with Java2D. If this coverage is a GridCoverage backed by a RenderedImage, the underlying image can be obtained with: getRenderableImage(0,1).createDefaultRendering()

Parameters:

xAxis - Dimension to use for the x axis.

yAxis - Dimension to use for the y axis.

Returns:

A 2D view of this coverage as a renderable image.

Throws:

java.lang.UnsupportedOperationException - if this optional operation is not supported.

java.lang.IndexOutOfBoundsException - if xAxis or yAxis is out of bounds.