org.geotools.coverage.io
Class AbstractGridCoverageReader

java.lang.Object
  extended by org.geotools.coverage.io.AbstractGridCoverageReader
All Implemented Interfaces:
GridCoverageReader
Direct Known Subclasses:
ExoreferencedGridCoverageReader

public abstract class AbstractGridCoverageReader
extends java.lang.Object
implements GridCoverageReader

Base class for reading GridCoverage objects. Reading is a two steps process: The input file must be set first, then the actual reading is performed with the getGridCoverage(int). Example:

 AbstractGridCoverageReader reader = ...
 reader.setInput(new File("MyCoverage.dat"), true);
 GridCoverage coverage = reader.getGridCoverage(0);
 
Subclasses needs to implements at least the following methods: The default implementation should be able to create acceptable grid coverage using informations provided by the two above-mentioned methods. However, other methods may be overriden too in order to get finner control on the result.

Since:
2.2
Version:
$Id: AbstractGridCoverageReader.java 34079 2009-10-05 20:41:26Z jive $
Author:
Martin Desruisseaux (IRD)

Field Summary
protected  GridToEnvelopeMapper gridToEnvelope
          The object to use for creating math transform from the grid range and the envelope.
protected  javax.imageio.ImageReader reader
          The ImageReader to use for decoding RenderedImages.
 
Constructor Summary
AbstractGridCoverageReader(Hints hints)
          Constructs a AbstractGridCoverageReader.
AbstractGridCoverageReader(Hints hints, java.lang.String formatName)
          Constructs a AbstractGridCoverageReader for the specified format name.
 
Method Summary
abstract  org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateReferenceSystem(int index)
          Returns the coordinate reference system for the GridCoverage to be read.
abstract  org.opengis.geometry.Envelope getEnvelope(int index)
          Returns the envelope for the GridCoverage to be read.
 org.opengis.coverage.grid.GridCoverage getGridCoverage(int index)
          Reads the grid coverage.
 org.opengis.coverage.grid.GridEnvelope getGridRange(int index)
          Returns the grid range for the GridCoverage to be read.
protected  java.util.Iterator getImageReaders(java.lang.Object input)
          Returns an Iterator containing all currently registered ImageReaders that claim to be able to decode the image.
 java.util.Locale getLocale()
          Returns the currently set Locale, or null if none has been set.
 org.opengis.referencing.operation.MathTransform getMathTransform(int index)
          Returns the transform from grid range to CRS coordinates.
 java.lang.String getName(int index)
          Gets the GridCoverage name at the specified index.
 int getNumImages(boolean allowSearch)
          Returns the number of images available from the current input source.
 GridSampleDimension[] getSampleDimensions(int index)
          Returns the sample dimensions for each band of the GridCoverage to be read.
 void reset()
          Restores the AbstractGridCoverageReader to its initial state.
 void setInput(java.lang.Object input, boolean seekForwardOnly)
          Sets the input source to the given object.
 void setLocale(java.util.Locale locale)
          Sets the current locale of this coverage reader to the given value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

reader

protected javax.imageio.ImageReader reader
The ImageReader to use for decoding RenderedImages. This reader is initially null and lazily created the first time setInput(java.lang.Object, boolean) is invoked. Once created, it is reused as much as possible. Invoking reset() dispose the reader and set it back to null.


gridToEnvelope

protected final GridToEnvelopeMapper gridToEnvelope
The object to use for creating math transform from the grid range and the envelope. Subclasses can change its configuration after AbstractGridCoverageReader construction in order to change its behavior regarding axis reversal or axis swapping for example.

Since:
2.4
See Also:
getMathTransform(int)
Constructor Detail

AbstractGridCoverageReader

public AbstractGridCoverageReader(Hints hints)
Constructs a AbstractGridCoverageReader. The image reader will be determined from the file extension, if any.

Parameters:
hints - The factory hints to use.
Since:
2.4

AbstractGridCoverageReader

public AbstractGridCoverageReader(Hints hints,
                                  java.lang.String formatName)
Constructs a AbstractGridCoverageReader for the specified format name. This format name should be known to ImageIO.getImageReadersByFormatName(String).

Parameters:
hints - The factory hints to use.
formatName - The format name of the image reader to use, or null for relying on file extension instead.
Since:
2.4
Method Detail

reset

public void reset()
           throws java.io.IOException
Restores the AbstractGridCoverageReader to its initial state.

Specified by:
reset in interface GridCoverageReader
Throws:
java.io.IOException - if an error occurs while disposing resources.

getLocale

public java.util.Locale getLocale()
Returns the currently set Locale, or null if none has been set.


setLocale

public void setLocale(java.util.Locale locale)
Sets the current locale of this coverage reader to the given value. A value of null removes any previous setting, and indicates that the reader should localize as it sees fit.


getImageReaders

protected java.util.Iterator getImageReaders(java.lang.Object input)
Returns an Iterator containing all currently registered ImageReaders that claim to be able to decode the image. The default implementation returns ImageIO.getImageReadersByFormatName(formatName).

Parameters:
input - The input source.

setInput

public void setInput(java.lang.Object input,
                     boolean seekForwardOnly)
              throws java.io.IOException
Sets the input source to the given object. The input is usually a File or an URL object. But some other types (e.g. ImageInputStream) may be accepted too.

If this method is invoked for the first time or after a call to reset(), then it will queries getImageReaders(java.lang.Object) for a list of ImageReaders and select the first one that accept the input.

Specified by:
setInput in interface GridCoverageReader
Parameters:
input - The File or URL to be read.
seekForwardOnly - if true, grid coverages and metadata may only be read in ascending order from the input source.
Throws:
java.io.IOException - if an I/O operation failed.
java.lang.IllegalArgumentException - if input is not an instance of one of the classes declared by the ImageReader service provider.

getNumImages

public int getNumImages(boolean allowSearch)
                 throws java.io.IOException
Returns the number of images available from the current input source. Note that some image formats do not specify how many images are present in the stream. Thus determining the number of images will require the entire stream to be scanned and may require memory for buffering. The allowSearch parameter may be set to false to indicate that an exhaustive search is not desired.

Specified by:
getNumImages in interface GridCoverageReader
Parameters:
allowSearch - If true, the true number of images will be returned even if a search is required. If false, the reader may return -1 without performing the search.
Returns:
The number of images, or -1 if allowSearch is false and a search would be required.
Throws:
java.lang.IllegalStateException - If the input source has not been set, or if the input has been specified with seekForwardOnly set to true.
java.io.IOException - If an error occurs reading the information from the input source.

getName

public java.lang.String getName(int index)
                         throws java.io.IOException
Gets the GridCoverage name at the specified index. The default implementation returns the input filename, or the "Untitled" string if input is not a File or an URL object.

Specified by:
getName in interface GridCoverageReader
Parameters:
index - The index of the image to be queried.
Returns:
The name for the GridCoverage at the specified index.
Throws:
java.lang.IllegalStateException - if the input source has not been set.
java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.
java.io.IOException - if an error occurs reading the information from the input source.

getCoordinateReferenceSystem

public abstract org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateReferenceSystem(int index)
                                                                                            throws java.io.IOException
Returns the coordinate reference system for the GridCoverage to be read.

Specified by:
getCoordinateReferenceSystem in interface GridCoverageReader
Parameters:
index - The index of the image to be queried.
Returns:
The coordinate reference system for the GridCoverage at the specified index.
Throws:
java.lang.IllegalStateException - if the input source has not been set.
java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.
java.io.IOException - if an error occurs reading the width information from the input source.

getEnvelope

public abstract org.opengis.geometry.Envelope getEnvelope(int index)
                                                   throws java.io.IOException
Returns the envelope for the GridCoverage to be read. The envelope must have the same number of dimensions than the coordinate reference system.

Specified by:
getEnvelope in interface GridCoverageReader
Parameters:
index - The index of the image to be queried.
Returns:
The envelope for the GridCoverage at the specified index.
Throws:
java.lang.IllegalStateException - if the input source has not been set.
java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.
java.io.IOException - if an error occurs reading the width information from the input source.

getGridRange

public org.opengis.coverage.grid.GridEnvelope getGridRange(int index)
                                                    throws java.io.IOException
Returns the grid range for the GridCoverage to be read. The grid range must have the same number of dimensions than the envelope. The default implementation construct a GridRange object using information provided by ImageReader.getWidth(int) and ImageReader.getHeight(int).

Specified by:
getGridRange in interface GridCoverageReader
Parameters:
index - The index of the image to be queried.
Returns:
The grid range for the GridCoverage at the specified index.
Throws:
java.lang.IllegalStateException - if the input source has not been set.
java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.
java.io.IOException - if an error occurs reading the width information from the input source.

getMathTransform

public org.opengis.referencing.operation.MathTransform getMathTransform(int index)
                                                                 throws java.io.IOException
Returns the transform from grid range to CRS coordinates. The default implementation uses the gridToEnvelope mapper.

Specified by:
getMathTransform in interface GridCoverageReader
Throws:
java.io.IOException
Since:
2.4

getSampleDimensions

public GridSampleDimension[] getSampleDimensions(int index)
                                          throws java.io.IOException
Returns the sample dimensions for each band of the GridCoverage to be read. If sample dimensions are not known, then this method returns null. The default implementation always returns null.

Specified by:
getSampleDimensions in interface GridCoverageReader
Parameters:
index - The index of the image to be queried.
Returns:
The category lists for the GridCoverage at the specified index. This array's length must be equals to the number of bands in GridCoverage.
Throws:
java.lang.IllegalStateException - if the input source has not been set.
java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.
java.io.IOException - if an error occurs reading the width information from the input source.

getGridCoverage

public org.opengis.coverage.grid.GridCoverage getGridCoverage(int index)
                                                       throws java.io.IOException
Reads the grid coverage. The default implementation gets the default ImageReadParam and checks if it is an instance of RawBinaryImageReadParam. If it is, this method then invokes RawBinaryImageReadParam.setStreamImageSize(java.awt.Dimension) with informations provided by getGridRange(int). Finally, a grid coverage is constructed using informations provided by getName(int), getCoordinateReferenceSystem(int) and getEnvelope(int).

Specified by:
getGridCoverage in interface GridCoverageReader
Parameters:
index - The index of the image to be queried.
Returns:
The GridCoverage at the specified index.
Throws:
java.lang.IllegalStateException - if the input source has not been set.
java.lang.IndexOutOfBoundsException - if the supplied index is out of bounds.
java.io.IOException - if an error occurs reading the width information from the input source.


Copyright © 1996-2010 Geotools. All Rights Reserved.