org.geotoolkit.coverage.sql
Interface Layer

public interface Layer

A layer of grid coverages sharing common properties. Layers are created by the CoverageDatabase.getLayer(String) method. The list of layers available in a database can be displayed in a Swing widget using the LayerList panel.

Layer instances are immutable and thread-safe.

Since:

3.10 (derived from Seagis)

Version:

3.16

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

coverage/geotk-coverage-sql (download)

View source code for this class

Method Summary

void	addCoverageReferences(Collection<?> files, CoverageDatabaseController controller) Adds new coverage references in the database.
SortedSet<Number>	getAvailableElevations() Returns the set of altitudes where a coverage is available.
SortedSet<Date>	getAvailableTimes() Returns the set of dates when a coverage is available.
RenderedImage	getColorRamp(int band, MeasurementRange<?> range, Map<String,?> properties) Creates a color ramp for the coverages in this layer.
int	getCoverageCount() Returns the number of coverages in this layer.
CoverageDatabase	getCoverageDatabase() Returns the database which created this layer, or null if unknown.
GridCoverageReference	getCoverageReference(CoverageEnvelope envelope) Returns a reference to a coverage that intersect the given envelope.
Set<GridCoverageReference>	getCoverageReferences(CoverageEnvelope envelope) Returns a reference to every coverages available in this layer which intersect the given envelope.
CoverageEnvelope	getEnvelope(Date time, Number elevation) Returns the envelope of this layer, optionally centered at the given date and elevation.
Layer	getFallback() Returns a layer to use as a fallback if no data is available in this layer for a given position.
GeographicBoundingBox	getGeographicBoundingBox() Returns the geographic bounding box, or null if unknown.
SortedSet<GeneralGridGeometry>	getGridGeometries() Returns the grid geometries used by the coverages in this layer, sorted by decreasing frequency of use.
SortedSet<File>	getImageDirectories() Returns the directories where the image files are stored, sorted by decreasing frequency of use.
SortedSet<String>	getImageFormats() Returns the image format used by the coverages in this layer, sorted by decreasing frequency of use.
String	getName() Returns the name of this layer.
List<MeasurementRange<?>>	getSampleValueRanges() Returns the ranges of valid geophysics values for each band.
DateRange	getTimeRange() Returns a time range encompassing all coverages in this layer, or null if none.
double[]	getTypicalResolution() Returns the typical pixel resolution in this layer.

Method Detail

getCoverageDatabase

CoverageDatabase getCoverageDatabase()

Returns the database which created this layer, or null if unknown. The returned value is never null except when this Layer is the result of a deserialization.

Returns:

The database which created this layer, or null if unknown.

Since:

3.12

getName

String getName()

Returns the name of this layer.

Returns:

The layer name.

getCoverageCount

int getCoverageCount()
                     throws CoverageStoreException

Returns the number of coverages in this layer.

Returns:

The number of coverages in this layer.

Throws:

CoverageStoreException - if an error occurred while counting the coverages.

getTimeRange

DateRange getTimeRange()
                       throws CoverageStoreException

Returns a time range encompassing all coverages in this layer, or null if none.

Returns:

The time range encompassing all coverages, or null.

Throws:

CoverageStoreException - if an error occurred while fetching the time range.

getAvailableTimes

SortedSet<Date> getAvailableTimes()
                                  throws CoverageStoreException

Returns the set of dates when a coverage is available.

Returns:

The set of dates, or null if unknown.

Throws:

CoverageStoreException - if an error occurred while fetching the set.

getAvailableElevations

SortedSet<Number> getAvailableElevations()
                                         throws CoverageStoreException

Returns the set of altitudes where a coverage is available. If different coverages have different set of altitudes, then this method returns the union of all altitudes set.

Returns:

The set of altitudes, or null if unknown.

Throws:

CoverageStoreException - if an error occurred while fetching the set.

getSampleValueRanges

List<MeasurementRange<?>> getSampleValueRanges()
                                               throws CoverageStoreException

Returns the ranges of valid geophysics values for each band. The length of the returned list is the maximal number of bands in all coverages. If some coverages found in this layer have different range of values, then this method returns the union of their ranges.

Returns:

The range of valid sample values for each bands.

Throws:

CoverageStoreException - If an error occurred while fetching the information.

getColorRamp

RenderedImage getColorRamp(int band,
                           MeasurementRange<?> range,
                           Map<String,?> properties)
                           throws CoverageStoreException,
                                  IllegalArgumentException

Creates a color ramp for the coverages in this layer. This method searches for a category which intersect the given range. Then, an image is created with the colors from that category and optionally a graduation for the given range.

Note that the default implementation of this method requires the optional geotk-display module to be on reachable the classpath.

Note: There is usually only one quantitative category for a layer. However if more than one quantitative category is found, the one which seems the "best fit" for the given range is selected. The definition of "best fit" is implementation-dependent.

The range given to this method is typically the following value:

MeasurementRange<?> range = getSampleValueRanges().get(band);

However a different value can be specified, typically in the following situations:

• When no graduation is desired, the range can be null.
• When the same range needs to be expressed in different units. In such case, the value given to this method can be computed by range.convertTo(displayUnit).
• When the caller want to apply the color palette on a subrange of the layer range. In such case, the range given to this method can be the subrange of interest. Note that it is caller responsibility to apply a corresponding ColorMap operation on the coverage read.

This method accepts an optional map of properties, which provide more control on the image to be generated. Current implementation recognizes the following entries (all other entries are silently ignored):

Key	Value type	Description
"size"	Dimension	The image size, in pixels.
"font"	Font	The font to use for rendering graduation labels.
"foreground"	Color	The color to use for rendering graduation labels.
"graphics"	Graphics2D	If provided, paints the image using the given graphics handle instead than creating a new image. In such case, this method returns null.

Parameters:

band - The band for which to create a color ramp, from 0 inclusive to getSampleValueRanges().size() exclusive.

range - The range for the graduation, or null if no graduation should be written. See the above javadoc for a suggested value.

properties - An optional map of properties controlling the rendering. See the above javadoc for a description of expected entries.

Returns:

The color ramp as an image, or null if none.

Throws:

IllegalArgumentException - If the units of the given range are incompatible with the units of measurement found in this layer.

CoverageStoreException - If an error occurred while creating the color ramp.

Since:

3.16

See Also:

ColorRamp

getImageFormats

SortedSet<String> getImageFormats()
                                  throws CoverageStoreException

Returns the image format used by the coverages in this layer, sorted by decreasing frequency of use. The strings in the returned set shall be names known to the Java Image I/O framework.

Returns:

The image formats, with the most frequently used format first.

Throws:

CoverageStoreException - if an error occurred while querying the database.

getImageDirectories

SortedSet<File> getImageDirectories()
                                    throws CoverageStoreException

Returns the directories where the image files are stored, sorted by decreasing frequency of use.

Returns:

The image directories, with the most frequently used directory first.

Throws:

CoverageStoreException - if an error occurred while querying the database.

Since:

3.12

getTypicalResolution

double[] getTypicalResolution()
                              throws CoverageStoreException

Returns the typical pixel resolution in this layer. Values are in the unit of the main CRS used by the database (typically degrees of longitude and latitude for the horizontal part, and days for the temporal part). Some elements of the returned array may be NaN if they are unknown.

Returns:

The typical pixel resolution.

Throws:

CoverageStoreException - if an error occurred while fetching the resolution.

getGridGeometries

SortedSet<GeneralGridGeometry> getGridGeometries()
                                                 throws CoverageStoreException

Returns the grid geometries used by the coverages in this layer, sorted by decreasing frequency of use. The grid geometries may be 2D, 3D or 4D, including the vertical and temporal ranges if any. The Coordinate Reference System is the one declared in the database for the coverages.

Returns:

The grid geometries, with the most frequently used geometry first.

Throws:

CoverageStoreException - if an error occurred while querying the database.

getGeographicBoundingBox

GeographicBoundingBox getGeographicBoundingBox()
                                               throws CoverageStoreException

Returns the geographic bounding box, or null if unknown. If the CRS used by the database is not geographic (for example if it is a projected CRS), then this method will transform the layer envelope from the layer CRS to a geographic CRS.

Returns:

The layer geographic bounding box, or null if none.

Throws:

CoverageStoreException - if an error occurred while querying the database or while projecting the layer envelope.

Since:

3.11

getEnvelope

CoverageEnvelope getEnvelope(Date time,
                             Number elevation)
                             throws CoverageStoreException

Returns the envelope of this layer, optionally centered at the given date and elevation. Callers are free to modify the returned instance before to pass it to the getCoverageReference methods.

Parameters:

time - The central date, or null.

elevation - The central elevation, or null.

Returns:

A default envelope instance.

Throws:

CoverageStoreException - if an error occurred while querying the database.

getCoverageReferences

Set<GridCoverageReference> getCoverageReferences(CoverageEnvelope envelope)
                                                 throws CoverageStoreException

Returns a reference to every coverages available in this layer which intersect the given envelope. This method does not load immediately the coverages; it returns only references to the coverages.

If the given envelope is null, then this method returns the references to every coverages available in this layer regardless of their envelope.

Parameters:

envelope - The envelope for filtering the coverages, or null for no filtering.

Returns:

The set of coverages in the layer which intersect the given envelope.

Throws:

CoverageStoreException - if an error occurred while querying the database.

getCoverageReference

GridCoverageReference getCoverageReference(CoverageEnvelope envelope)
                                           throws CoverageStoreException

Returns a reference to a coverage that intersect the given envelope. If more than one coverage intersect the given envelope, then this method will select the one which seem the most representative. The criterion for this selection is implementation-dependant and may change in future versions.

Parameters:

envelope - The envelope for filtering the coverages, or null for no filtering. A null value is useful for layers that are expected to contain only one coverage, but should be avoided otherwise.

Returns:

A reference to a coverage, or null if no coverage was found.

Throws:

CoverageStoreException - if an error occurred while querying the database.

addCoverageReferences

void addCoverageReferences(Collection<?> files,
                           CoverageDatabaseController controller)
                           throws DatabaseVetoException,
                                  CoverageStoreException

Adds new coverage references in the database. The new references are given by a collection of inputs. Each input can be any of the following instances:

• File, URL, URI or String instances.

• Tile instances, which will be added to the "GridCoverages" table (not to the "Tiles" table).

• ImageReader instances with their input set and image metadata conform to the Geotk spatial metadata format. The reader input shall be one of the above-cited instances. If this is not possible (for example because a ImageInputStream is required), consider wrapping the ImageReaderSpi and the input in a Tile instance.

This method will typically read only the required metadata rather than the full image.

Multi-images files
If a file contains more than one image, then the images to insert can be selected by the CoverageDatabaseController.filterImages(List, boolean) method. If no controller has been supplied, then the default behavior is to insert only the first image on the assumption that other images are typically error estimations or overviews.

Parameters:

files - The image inputs.

controller - An optional controller to be notified when new references are added. The controller can modify the values declared in NewGridCoverageReference before they are written in the database.

Throws:

DatabaseVetoException - If a listener vetoed against the operation.

CoverageStoreException - If an error occurred while accessing the database.

Since:

3.12

getFallback

Layer getFallback()
                  throws CoverageStoreException

Returns a layer to use as a fallback if no data is available in this layer for a given position. For example if no data is available in a weekly averaged Sea Surface Temperature (SST) coverage because a location is masked by clouds, we may want to look in the monthly averaged SST coverage as a fallback.

Returns:

The fallback layer, or null if none.

Throws:

CoverageStoreException - If an error occurred while fetching the information.