org.geotoolkit.coverage.sql
Interface GridCoverageReference

All Superinterfaces:

CoverageStack.Element

public interface GridCoverageReference
extends CoverageStack.Element

Reference to a GridCoverage2D. This object holds some metadata about the coverage (time range, geographic bounding box, etc.) without the need to open the image file, since the metadata are extracted from the database. The actual loading of pixel values occurs when CoverageStack.Element.getCoverage(IIOListeners) is invoked for the first time.

Usage example:

CoverageDatabase db       = new CoverageDatabase(...);
Layer            layer    = db.getLayer("My Layer").result();
CoverageEnvelope envelope = layer.getEnvelope(null, null);
envelope.setHorizontalRange(...);
envelope.setVerticalRange(...);
envelope.setTimeRange(...);
GridCoverageReference ref = layer.getCoverageReference(envelope);
GridCoverage2D coverage = ref.getCoverage(null);

GridCoverageReference instances are immutable and thread-safe.

Since:

3.10 (derived from Seagis)

Version:

3.16

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

Layer.getCoverageReference(CoverageEnvelope), Layer.getCoverageReferences(CoverageEnvelope)

Module:

coverage/geotk-coverage-sql (download)

View source code for this class

Method Summary

void	abort() Aborts the image reading.
CoordinateReferenceSystem	getCoordinateReferenceSystem(boolean includeTime) Returns the native Coordinate Reference System of the coverage.
GridCoverageReader	getCoverageReader(GridCoverageReader recycle) Gets a grid coverage reader which can be used for reading the coverage represented by this GridCoverageReference.
Envelope	getEnvelope() Returns the spatio-temporal envelope of the coverage.
<T> T	getFile(Class<T> type) Returns the path to the image file as an object of the given type.
GeographicBoundingBox	getGeographicBoundingBox() Returns the geographic bounding box of the coverage envelope.
GridGeometry2D	getGridGeometry() Returns the coverage grid geometry.
String	getImageFormat() Returns the image format.
String	getName() Returns a name for the coverage, for use in graphical user interfaces.
GridSampleDimension[]	getSampleDimensions() Returns the coverage sample dimensions, or null if unknown.
DateRange	getTimeRange() Returns the temporal part of the coverage envelope.
Rectangle2D	getXYRange() Returns the range of values in the two first dimensions, which are horizontal.
NumberRange<?>	getZRange() Returns the range of values in the third dimension, which may be vertical or temporal.
GridCoverage2D	read(CoverageEnvelope envelope, IIOListeners listeners) Reads the data and returns the coverage.

Methods inherited from interface CoverageStack.Element

getCoverage

Method Detail

getName

String getName()

Returns a name for the coverage, for use in graphical user interfaces.

Specified by:

getName in interface CoverageStack.Element

Returns:

The coverage name, suitable for use in a graphical user interface.

getFile

<T> T getFile(Class<T> type)
          throws IOException

Returns the path to the image file as an object of the given type. The current implementation supports only the File, URL and URI types.

In the particular case of input of the File type, the returned path is expected to be absolute. If the file is not absolute, then the file is probably not accessible on the local machine (i.e. the path is relative to a distant server and can not be represented as a File object). In such case, consider using the URI type instead.

Type Parameters:

T - The compile-time type of the type argument.

Parameters:

type - The desired input type: File, URL or URI.

Returns:

The input as an object of the given type.

Throws:

IOException - If the input can not be represented as an object of the given type.

getImageFormat

String getImageFormat()

Returns the image format. The returned string should be one of the names recognized by the Java image I/O framework. For example, the returned string shall be understood by ImageIO.getImageReadersByFormatName(String).

Returns:

The Java Image I/O format name.

getCoordinateReferenceSystem

CoordinateReferenceSystem getCoordinateReferenceSystem(boolean includeTime)

Returns the native Coordinate Reference System of the coverage. The returned CRS may be up to 4-dimensional.

Parameters:

includeTime - true if the returned CRS should include the time component (if available), or false for a spatial-only CRS.

Returns:

The native CRS of the coverage.

getGeographicBoundingBox

GeographicBoundingBox getGeographicBoundingBox()

Returns the geographic bounding box of the coverage envelope. Invoking this method is equivalent to extracting the horizontal component of the envelope and transform the coordinates if needed.

This method return null if the geographic bounding box can not be computed.

Returns:

The geographic component of the envelope, or null if unknown.

getEnvelope

Envelope getEnvelope()

Returns the spatio-temporal envelope of the coverage. The CRS of the returned envelope is the spatio-temporal CRS of this entry, which may vary on a coverage-by-coverage basis. If an envelope is some unified CRS is desired, consider using getXYRange(), getZRange() and getTimeRange() instead.

This method is equivalent to the following call:

return getGridGeometry().getEnvelope();

Specified by:

getEnvelope in interface CoverageStack.Element

Returns:

The coverage spatio-temporal envelope.

getXYRange

Rectangle2D getXYRange()

Returns the range of values in the two first dimensions, which are horizontal. This method returns the range in units of the database horizontal CRS, which may not be the same than the horizontal CRS of the coverage.

If the range of values in units of the coverage CRS is desired, then use the getEnvelope() method instead.

Returns:

The range of values in the two first dimensions, in units of the database CRS.

getZRange

NumberRange<?> getZRange()

Returns the range of values in the third dimension, which may be vertical or temporal. The main purpose of this method is to allow sorting of entries, not to get the elevation. If the coverage is not restricted to a particular range along the third dimension, then this method returns a range with infinite bounds.

Unit of measurement
This method returns the range in units of the database vertical or temporal CRS, which may not be the same than the vertical or temporal CRS of the coverage. This is done that way in order to allow sorting coverages by elevation or by time no matter how the coverage represents those quantities. If elevation or time in units of the coverage CRS is desired, then use the getEnvelope() method instead.

Specified by:

getZRange in interface CoverageStack.Element

Returns:

The range of values in the third dimension, in units of the database CRS.

getTimeRange

DateRange getTimeRange()

Returns the temporal part of the coverage envelope. If the coverage is not restricted to a particular time range, then this method returns a range with infinite bounds.

Invoking this method is equivalent to extracting the temporal component of the envelope and transforming the coordinates if needed.

Returns:

The temporal component of the envelope.

getGridGeometry

GridGeometry2D getGridGeometry()

Returns the coverage grid geometry.

Specified by:

getGridGeometry in interface CoverageStack.Element

Returns:

The coverage grid geometry.

getSampleDimensions

GridSampleDimension[] getSampleDimensions()

Returns the coverage sample dimensions, or null if unknown. This method returns always the geophysics version of sample dimensions (geophysics(true)), which is consistent with the coverage returned by getCoverage(...).

Specified by:

getSampleDimensions in interface CoverageStack.Element

Returns:

The sample dimensions, or null if unknown.

getCoverageReader

GridCoverageReader getCoverageReader(GridCoverageReader recycle)
                                     throws CoverageStoreException

Gets a grid coverage reader which can be used for reading the coverage represented by this GridCoverageReference. This method is provided for inter-operability with API requirying GridCoverageReader instances. When possible, callers are encouraged to use the read(CoverageEnvelope, IIOListeners) method instead.

This method accepts an optional GridCoverageReader instance in argument. The provided instance will be recycled if possible, for avoiding the cost of creating a new reader on each method invocation. If the argument is null or the given instance can not be reused, then this method returns a new instance.

Callers should set the input to null, reset or dispose the reader as soon as the reading process is completed, in order to close the underlying image input stream.

Parameters:

recycle - An optional existing instance to recycle if possible, or null.

Returns:

A reader which can be used for reading the grid coverage.

Throws:

CoverageStoreException - if an error occurred while creating the reader.

Since:

3.14

read

GridCoverage2D read(CoverageEnvelope envelope,
                    IIOListeners listeners)
                    throws CoverageStoreException,
                           CancellationException

Reads the data and returns the coverage. This method accepts an optional envelope parameter, which restrict the spatio-temporal extent of data to be read. If the envelope is null, then the default extent is loaded.

The default Geotk implementation cache the returned coverage if and only if the envelope is null. In the later case, if the coverage has already been read previously and has not yet been reclaimed by the garbage collector, then the existing coverage may be returned immediately.

This method returns always the geophysics view of data.

Parameters:

envelope - The spatio-temporal envelope and the preferred resolution of the image to be read, or null for the default.

listeners - Objects to inform about progress, or null if none.

Returns:

The coverage.

Throws:

CoverageStoreException - if an error occurred while reading the image.

CancellationException - if abort() has been invoked during the reading process.

abort

void abort()

Aborts the image reading. This method can be invoked from any thread. If read(...) was in progress at the time this method is invoked, then it will stop and throw CancellationException.

Note that if more than one read was in progress concurrently, all of them will be aborted by the call to this method.