org.geotoolkit.coverage.io
Class GridCoverageReader

Object
  GridCoverageStore
      GridCoverageReader

All Implemented Interfaces:

Localized, LogProducer

Direct Known Subclasses:

ImageCoverageReader, LayerCoverageReader

public abstract class GridCoverageReader
extends GridCoverageStore

Base class of GridCoverage readers. Reading is a two steps process:

• The input must be set first using the setInput(Object) method.
• The actual reading is performed by a call to the read(int, GridCoverageReadParam) method.

Example:

GridCoverageReader reader = ...
reader.setInput(new File("MyCoverage.asc"));
GridCoverage coverage = reader.read(0, null);

Note: This class is conceptually equivalent to the ImageReader class provided in the standard Java library. Implementations of this class are often wrappers around a Java ImageReader, converting geodetic coordinates to pixel coordinates before to delegate the reading of pixel values.

Since:

3.09 (derived from 2.4)

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys), Johann Sorel (Geomatys)

See Also:

ImageReader

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

Fields inherited from class GridCoverageStore

abortRequested

Constructor Summary

protected

GridCoverageReader() Creates a new instance.

Method Summary

void	dispose() Allows any resources held by this reader to be released.
SpatialMetadata	getCoverageMetadata(int index) Returns the metadata associated with the given coverage, or null if none.
abstract List<? extends GenericName>	getCoverageNames() Returns the list of coverage names available from the current input source.
abstract GeneralGridGeometry	getGridGeometry(int index) Returns the grid geometry for the GridCoverage to be read at the given index.
Object	getInput() Returns the input which was set by the last call to setInput(Object), or null if none.
Metadata	getMetadata() Returns the ISO 19115 metadata object associated with the input source as a whole and each coverages.
Map<?,?>	getProperties(int index) Returns an optional map of properties associated with the coverage at the given index, or null if none.
abstract List<GridSampleDimension>	getSampleDimensions(int index) Returns the sample dimensions for each band of the GridCoverage to be read.
List<MeasurementRange<?>>	getSampleValueRanges(int index) Returns the ranges of valid sample values for each band in this format.
SpatialMetadata	getStreamMetadata() Returns the metadata associated with the input source as a whole, or null if none.
abstract GridCoverage	read(int index, GridCoverageReadParam param) Reads the grid coverage.
void	reset() Restores the GridCoverageReader to its initial state.
void	setInput(Object input) Sets the input source to the given object.

Methods inherited from class GridCoverageStore

abort, getLocale, getLogLevel, setLocale, setLogLevel

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GridCoverageReader

protected GridCoverageReader()

Creates a new instance.

Method Detail

setInput

public void setInput(Object input)
              throws CoverageStoreException

Sets the input source to the given object. The input is typically a File or a String object. But some other types (e.g. ImageInputStream) may be accepted as well depending on the implementation.

How streams are closed

• If the given input is an input stream, image input stream or a reader, then it is caller responsibility to close the given stream after usage.
• If an input stream has been generated automatically by this GridCoverageReader from the given input object, then this coverage reader will close the stream when the reset() or dispose() method is invoked, or when a new input is set.

Parameters:

input - The input (typically File or String) to be read.

Throws:

IllegalArgumentException - If the input is not a valid instance for this reader.

CoverageStoreException - If the operation failed.

See Also:

ImageReader.setInput(Object)

getInput

public Object getInput()
                throws CoverageStoreException

Returns the input which was set by the last call to setInput(Object), or null if none.

Returns:

The current input, or null if none.

Throws:

CoverageStoreException - If the operation failed.

See Also:

ImageReader.getInput()

getCoverageNames

public abstract List<? extends GenericName> getCoverageNames()
                                                      throws CoverageStoreException,
                                                             CancellationException

Returns the list of coverage names available from the current input source. The length of the returned list is the number of coverages found in the current input source. The elements in the returned list are the names of each coverage.

The returned list may be backed by this GridCoverageReader: it should be used only as long as this reader and its input source are valid. Iterating over the list may be costly and the operation performed on the list may throw a BackingStoreException.

Returns:

The names of the coverages.

Throws:

IllegalStateException - If the input source has not been set.

CoverageStoreException - If an error occurs while reading the information from the input source.

CancellationException - If GridCoverageStore.abort() has been invoked in an other thread during the execution of this method.

See Also:

ImageReader.getNumImages(boolean)

getGridGeometry

public abstract GeneralGridGeometry getGridGeometry(int index)
                                             throws CoverageStoreException,
                                                    CancellationException

Returns the grid geometry for the GridCoverage to be read at the given index.

Parameters:

index - The index of the coverage to be queried.

Returns:

The grid geometry for the GridCoverage at the specified index.

Throws:

IllegalStateException - If the input source has not been set.

IndexOutOfBoundsException - If the supplied index is out of bounds.

CoverageStoreException - If an error occurs while reading the information from the input source.

CancellationException - If GridCoverageStore.abort() has been invoked in an other thread during the execution of this method.

See Also:

ImageReader.getWidth(int), ImageReader.getHeight(int)

getSampleDimensions

public abstract List<GridSampleDimension> getSampleDimensions(int index)
                                                       throws CoverageStoreException,
                                                              CancellationException

Returns the sample dimensions for each band of the GridCoverage to be read. If sample dimensions are not known, then this method returns null.

Parameters:

index - The index of the coverage to be queried.

Returns:

The list of sample dimensions for the GridCoverage at the specified index, or null if none. This list length is equals to the number of bands in the GridCoverage.

Throws:

IllegalStateException - If the input source has not been set.

IndexOutOfBoundsException - If the supplied index is out of bounds.

CoverageStoreException - If an error occurs while reading the information from the input source.

CancellationException - If GridCoverageStore.abort() has been invoked in an other thread during the execution of this method.

getSampleValueRanges

public List<MeasurementRange<?>> getSampleValueRanges(int index)
                                               throws CoverageStoreException,
                                                      CancellationException

Returns the ranges of valid sample values for each band in this format. The ranges are always expressed in geophysics units.

The default implementation computes the ranges from the information returned by getSampleDimensions(int), if any.

Parameters:

index - The index of the coverage to be queried.

Returns:

The ranges of values for each band, or null if none.

Throws:

CoverageStoreException - If an error occurs while reading the information from the input source.

CancellationException - If GridCoverageStore.abort() has been invoked in an other thread during the execution of this method.

Since:

3.10

getMetadata

public Metadata getMetadata()
                     throws CoverageStoreException

Returns the ISO 19115 metadata object associated with the input source as a whole and each coverages. The default implementation constructs the metadata from the stream metadata and the coverage metadata, eventually completed by the getGridGeometry(int).

Since the relationship between Image I/O metadata and ISO 19115 is not always a "one-to-one" relationship, this method works on a best effort basis.

Returns:

The ISO 19115 metadata (never null).

Throws:

CoverageStoreException - If an error occurs while reading the information from the input source.

Since:

3.18

See Also:

Metadata formats

getStreamMetadata

public SpatialMetadata getStreamMetadata()
                                  throws CoverageStoreException

Returns the metadata associated with the input source as a whole, or null if none. The default implementation returns null in every cases.

Returns:

The metadata associated with the input source as a whole, or null.

Throws:

CoverageStoreException - If an error occurs while reading the information from the input source.

Since:

3.14

See Also:

ImageReader.getStreamMetadata()

getCoverageMetadata

public SpatialMetadata getCoverageMetadata(int index)
                                    throws CoverageStoreException

Returns the metadata associated with the given coverage, or null if none. The default implementation returns null in every cases.

Parameters:

index - The index of the coverage to be queried.

Returns:

The metadata associated with the given coverage, or null.

Throws:

CoverageStoreException - If an error occurs while reading the information from the input source.

Since:

3.14

See Also:

ImageReader.getImageMetadata(int)

getProperties

public Map<?,?> getProperties(int index)
                       throws CoverageStoreException,
                              CancellationException

Returns an optional map of properties associated with the coverage at the given index, or null if none. The properties are implementation-specific; they are available to subclasses for any use. The GridCoverageReader class will simply gives those properties to the PropertySource object to be created by the read method, without any processing.

The default implementation returns null in every cases.

Parameters:

index - The index of the coverage to be queried.

Returns:

The properties, or null if none.

Throws:

CoverageStoreException - If an error occurs while reading the information from the input source.

CancellationException - If GridCoverageStore.abort() has been invoked in an other thread during the execution of this method.

read

public abstract GridCoverage read(int index,
                                  GridCoverageReadParam param)
                           throws CoverageStoreException,
                                  CancellationException

Reads the grid coverage.

Parameters:

index - The index of the coverage to be queried.

param - Optional parameters used to control the reading process, or null.

Returns:

The GridCoverage at the specified index.

Throws:

IllegalStateException - if the input source has not been set.

IndexOutOfBoundsException - if the supplied index is out of bounds.

CoverageStoreException - If an error occurs while reading the information from the input source.

CancellationException - If GridCoverageStore.abort() has been invoked in an other thread during the execution of this method.

See Also:

ImageReader.read(int)

reset

public void reset()
           throws CoverageStoreException

Restores the GridCoverageReader to its initial state.

Overrides:

reset in class GridCoverageStore

Throws:

CoverageStoreException - If an error occurs while restoring to the initial state.

See Also:

ImageReader.reset()

dispose

public void dispose()
             throws CoverageStoreException

Allows any resources held by this reader to be released. The result of calling any other method subsequent to a call to this method is undefined.

Overrides:

dispose in class GridCoverageStore

Throws:

CoverageStoreException - If an error occurs while disposing resources.

See Also:

ImageReader.dispose()