org.geotools.coverage.grid.io
Class AbstractGridCoverage2DReader

Object
  AbstractGridCoverage2DReader

All Implemented Interfaces:

GridCoverageReader

Direct Known Subclasses:

ArcGridReader, ArcSDEGridCoverage2DReaderJAI, BaseGridCoverage2DReader, GeoTiffReader, GrassCoverageReader, GTopo30Reader, ImageMosaicJDBCReader, ImageMosaicReader, ImagePyramidReader, JP2KReader, WorldImageReader

public abstract class AbstractGridCoverage2DReader
extends Object
implements GridCoverageReader

This class is a first attempt for providing a way to get more informations out of a single 2D raster datasets (x,y). It is worth to remark that for the moment this is thought for 2D rasters not for 3D or 4D rasters (x,y,z,t).

The main drawback I see with the current GeoApi GridCoverageReader interface is that there is no way to get real information about a raster source unless you instantiate a GridCoverage. As an instance it is impossible to know the envelope, the number of overviews, the tile size. This information is needed in order to perform decimation on reading or to use built-in overviews
This really impacts the ability to exploit raster datasets in a desktop environment where caching is crucial.

Since:

2.3

Author:

Simone Giannecchini, GeoSolutions

Field Summary

protected boolean	closeMe Temp variable used in many readers.
protected GridCoverageFactory	coverageFactory GridCoverageFactory instance.
protected String	coverageName Coverage name
protected CoordinateReferenceSystem	crs crs for this coverage
static String	ELEVATION_DOMAIN Elevation domain (comma separated list of values)
static String	ELEVATION_DOMAIN_MAXIMUM Elevation domain maximum value
static String	ELEVATION_DOMAIN_MINIMUM Elevation domain minimum value
static String	ELEVATION_DOMAIN_RESOLUTION Elevation domain resolution
static double	EPS
static String	FILE_SOURCE_PROPERTY If a coverage has this property is means it been read straight out of a file without any sub-setting, it means the coverage represents the full contents of the file.
protected boolean	gzipped In case we are trying to read from a GZipped file this will be set to true.
static String	HAS_ELEVATION_DOMAIN Whether the elevation is expressed as a full domain or min/max/resolution (true if domain list available)
static String	HAS_TIME_DOMAIN If the time domain is available (or if a min/max/resolution approach has been chosen)
protected double[]	highestRes Highest resolution availaible for this reader.
protected Hints	hints Hints used by the AbstractGridCoverage2DReader subclasses.
protected ImageInputStream	inStream Input stream that can be used to initialize subclasses of AbstractGridCoverage2DReader.
protected ImageInputStreamSpi	inStreamSPI
protected int	numOverviews This contains the number of overviews.aaa
protected GeneralEnvelope	originalEnvelope Envelope read from file
protected GridEnvelope	originalGridRange The original GridRange for the GridCoverage2D of this reader.
protected double[][]	overViewResolutions Resolutions avialaible through an overviews based mechanism.
protected MathTransform	raster2Model 2DGridToWorld math transform.
protected Object	source Source to read from
static String	TIME_DOMAIN The time domain (comma separated list of values)
static String	TIME_DOMAIN_MAXIMUM The time domain max value
static String	TIME_DOMAIN_MINIMUM The time domain min value
static String	TIME_DOMAIN_RESOLUTION Time domain resolution (when using min/max/resolution)

Constructor Summary

protected	AbstractGridCoverage2DReader() Default protected constructor.
	AbstractGridCoverage2DReader(Object input) Creates a new instance of a AIGReader.
	AbstractGridCoverage2DReader(Object input, Hints hints) Creates a new instance of a AIGReader.

Method Summary

protected GridCoverage	createImageCoverage(PlanarImage image) Creates a GridCoverage for the provided PlanarImage using the originalEnvelope that was provided for this coverage.
protected GridCoverage2D	createImageCoverage(PlanarImage image, MathTransform raster2Model) Creates a GridCoverage for the provided PlanarImage using the raster2Model that was provided for this coverage.
protected void	decimationOnReadingControl(Integer imageChoice, ImageReadParam readP, double[] requestedRes) This method is responsible for evaluating possible subsampling factors once the best resolution level has been found, in case we have support for overviews, or starting from the original coverage in case there are no overviews available.
void	dispose() Disposes this reader.
protected void	finalize() Forcing disposal of this AbstractGridCoverage2DReader which may keep an ImageInputStream open.
CoordinateReferenceSystem	getCrs() Retrieves the CoordinateReferenceSystem for dataset pointed by this AbstractGridCoverage2DReader.
String	getCurrentSubname() Returns the name for the next grid coverage to be read from the input source.
Set<ParameterDescriptor<List>>	getDynamicParameters() Return the set of dynamic parameterDescriptors (the ones related to domains) for this reader.
int	getGridCoverageCount()
ServiceInfo	getInfo() Information about this source.
String[]	getMetadataNames() Returns the list of metadata keywords associated with the input source as a whole (not associated with any particular grid coverage).
String	getMetadataValue(String name) Retrieve the metadata value for a given metadata name.
GeneralEnvelope	getOriginalEnvelope() Retrieves the GeneralEnvelope for this AbstractGridCoverage2DReader.
GridEnvelope	getOriginalGridRange() Retrieves the GeneralGridEnvelope that represents the raster grid dimensions of the highest resolution level in this dataset.
MathTransform	getOriginalGridToWorld(PixelInCell pixInCell) Retrieves the original grid to world transformation for this AbstractGridCoverage2DReader.
double[]	getReadingResolutions(OverviewPolicy policy, double[] requestedResolution) Returns the actual resolution used to read the data given the specified target resolution and the specified overview policy
protected static double[]	getResolution(GeneralEnvelope envelope, Rectangle2D dim, CoordinateReferenceSystem crs) This method is responsible for computing the resolutions in for the provided grid geometry in the provided crs.
Object	getSource() Retrieves the source for this AbstractGridCoverage2DReader.
boolean	hasMoreGridCoverages() Returns true if there is at least one more grid coverage available on the stream.
String[]	listSubNames() Retrieve the list of grid coverages contained within the input source.
abstract GridCoverage2D	read(GeneralParameterValue[] parameters) Read the current grid coverage from the stream.
protected Integer	setReadParams(OverviewPolicy overviewPolicy, ImageReadParam readP, GeneralEnvelope requestedEnvelope, Rectangle requestedDim) This method is responsible for preparing the read param for doing an ImageReader.read(int, ImageReadParam).
void	skip() Skip the current grid coverage without reading it, and move the stream position to the next grid coverage.

Methods inherited from class Object

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

Methods inherited from interface GridCoverageReader

getFormat

Field Detail

TIME_DOMAIN

public static final String TIME_DOMAIN

The time domain (comma separated list of values)

See Also:

Constant Field Values

TIME_DOMAIN_RESOLUTION

public static final String TIME_DOMAIN_RESOLUTION

Time domain resolution (when using min/max/resolution)

See Also:

Constant Field Values

HAS_TIME_DOMAIN

public static final String HAS_TIME_DOMAIN

If the time domain is available (or if a min/max/resolution approach has been chosen)

See Also:

Constant Field Values

TIME_DOMAIN_MAXIMUM

public static final String TIME_DOMAIN_MAXIMUM

The time domain max value

See Also:

Constant Field Values

TIME_DOMAIN_MINIMUM

public static final String TIME_DOMAIN_MINIMUM

The time domain min value

See Also:

Constant Field Values

HAS_ELEVATION_DOMAIN

public static final String HAS_ELEVATION_DOMAIN

Whether the elevation is expressed as a full domain or min/max/resolution (true if domain list available)

See Also:

Constant Field Values

ELEVATION_DOMAIN

public static final String ELEVATION_DOMAIN

Elevation domain (comma separated list of values)

See Also:

Constant Field Values

ELEVATION_DOMAIN_MAXIMUM

public static final String ELEVATION_DOMAIN_MAXIMUM

Elevation domain maximum value

See Also:

Constant Field Values

ELEVATION_DOMAIN_MINIMUM

public static final String ELEVATION_DOMAIN_MINIMUM

Elevation domain minimum value

See Also:

Constant Field Values

ELEVATION_DOMAIN_RESOLUTION

public static final String ELEVATION_DOMAIN_RESOLUTION

Elevation domain resolution

See Also:

Constant Field Values

FILE_SOURCE_PROPERTY

public static final String FILE_SOURCE_PROPERTY

If a coverage has this property is means it been read straight out of a file without any sub-setting, it means the coverage represents the full contents of the file. This can be used for different types of optimizations, such as avoiding reading and re-encoding the original file when the original file would do.

See Also:

Constant Field Values

EPS

public static final double EPS

See Also:

Constant Field Values

numOverviews

protected int numOverviews

This contains the number of overviews.aaa

raster2Model

protected MathTransform raster2Model

2DGridToWorld math transform.

crs

protected CoordinateReferenceSystem crs

crs for this coverage

originalEnvelope

protected GeneralEnvelope originalEnvelope

Envelope read from file

coverageName

protected String coverageName

Coverage name

source

protected Object source

Source to read from

hints

protected Hints hints

Hints used by the AbstractGridCoverage2DReader subclasses.

highestRes

protected double[] highestRes

Highest resolution availaible for this reader.

closeMe

protected boolean closeMe

Temp variable used in many readers.

gzipped

protected boolean gzipped

In case we are trying to read from a GZipped file this will be set to true.

originalGridRange

protected GridEnvelope originalGridRange

The original GridRange for the GridCoverage2D of this reader.

inStream

protected ImageInputStream inStream

Input stream that can be used to initialize subclasses of AbstractGridCoverage2DReader.

overViewResolutions

protected double[][] overViewResolutions

Resolutions avialaible through an overviews based mechanism.

coverageFactory

protected GridCoverageFactory coverageFactory

GridCoverageFactory instance.

inStreamSPI

protected ImageInputStreamSpi inStreamSPI

Constructor Detail

AbstractGridCoverage2DReader

protected AbstractGridCoverage2DReader()

Default protected constructor. Useful for wrappers.

AbstractGridCoverage2DReader

public AbstractGridCoverage2DReader(Object input)
                             throws DataSourceException

Creates a new instance of a AIGReader. I assume nothing about file extension.

Parameters:

input - Source object for which we want to build an AIGReader.

Throws:

DataSourceException

AbstractGridCoverage2DReader

public AbstractGridCoverage2DReader(Object input,
                                    Hints hints)
                             throws DataSourceException

Creates a new instance of a AIGReader. I assume nothing about file extension.

Parameters:

input - Source object for which we want to build an AIGReader.

hints - Hints to be used by this reader throughout his life.

Throws:

DataSourceException

Method Detail

read

public abstract GridCoverage2D read(GeneralParameterValue[] parameters)
                             throws IllegalArgumentException,
                                    IOException

Read the current grid coverage from the stream.

Example:

The method hasMoreGridCoverages() should be invoked first in order to verify that a coverage is available.

Specified by:

read in interface GridCoverageReader

Parameters:

parameters - Optional parameters matching Format.getReadParameters().

Returns:

a grid coverage from the input source.

Throws:

InvalidParameterNameException - if a parameter in parameters doesn't have a recognized name.

InvalidParameterValueException - if a parameter in parameters doesn't have a valid value.

ParameterNotFoundException - if a parameter was required for the operation but was not provided in the parameters list.

CannotCreateGridCoverageException - if the coverage can't be created for a logical reason (for example an unsupported format, or an inconsistency found in the data).

IOException - if a read operation failed for some other input/output reason, including FileNotFoundException if no file with the given name can be found, or IIOException if an error was thrown by the underlying image library.

IllegalArgumentException

setReadParams

protected Integer setReadParams(OverviewPolicy overviewPolicy,
                                ImageReadParam readP,
                                GeneralEnvelope requestedEnvelope,
                                Rectangle requestedDim)
                         throws IOException,
                                TransformException

This method is responsible for preparing the read param for doing an ImageReader.read(int, ImageReadParam).

This method is responsible for preparing the read param for doing an ImageReader.read(int, ImageReadParam). It sets the passed ImageReadParam in terms of decimation on reading using the provided requestedEnvelope and requestedDim to evaluate the needed resolution. It also returns and Integer representing the index of the raster to be read when dealing with multipage raster.

Parameters:

overviewPolicy - it can be one of Hints#VALUE_OVERVIEW_POLICY_IGNORE, Hints#VALUE_OVERVIEW_POLICY_NEAREST, Hints#VALUE_OVERVIEW_POLICY_QUALITY or Hints#VALUE_OVERVIEW_POLICY_SPEED. It specifies the policy to compute the overviews level upon request.

readP - an instance of ImageReadParam for setting the subsampling factors.

requestedEnvelope - the GeneralEnvelope we are requesting.

requestedDim - the requested dimensions.

Returns:

the index of the raster to read in the underlying data source.

Throws:

IOException

TransformException

getReadingResolutions

public double[] getReadingResolutions(OverviewPolicy policy,
                                      double[] requestedResolution)

Returns the actual resolution used to read the data given the specified target resolution and the specified overview policy

Parameters:

policy -

resolutions -

Returns:

decimationOnReadingControl

protected final void decimationOnReadingControl(Integer imageChoice,
                                                ImageReadParam readP,
                                                double[] requestedRes)

This method is responsible for evaluating possible subsampling factors once the best resolution level has been found, in case we have support for overviews, or starting from the original coverage in case there are no overviews available. Anyhow this method should not be called directly but subclasses should make use of the setReadParams method instead in order to transparently look for overviews.

Parameters:

imageChoice -

readP -

requestedRes -

createImageCoverage

protected final GridCoverage createImageCoverage(PlanarImage image)
                                          throws IOException

Creates a GridCoverage for the provided PlanarImage using the originalEnvelope that was provided for this coverage.

Parameters:

image - contains the data for the coverage to create.

Returns:

a GridCoverage

Throws:

IOException

createImageCoverage

protected final GridCoverage2D createImageCoverage(PlanarImage image,
                                                   MathTransform raster2Model)
                                            throws IOException

Creates a GridCoverage for the provided PlanarImage using the raster2Model that was provided for this coverage.

This method is vital when working with coverages that have a raster to model transformation that is not a simple scale and translate.

Parameters:

image - contains the data for the coverage to create.

raster2Model - is the MathTransform that maps from the raster space to the model space.

Returns:

a GridCoverage

Throws:

IOException

getResolution

protected static final double[] getResolution(GeneralEnvelope envelope,
                                              Rectangle2D dim,
                                              CoordinateReferenceSystem crs)
                                       throws DataSourceException

This method is responsible for computing the resolutions in for the provided grid geometry in the provided crs.

It is worth to note that the returned resolution array is of length of 2 and it always is lon, lat for the moment.
It might be worth to remove the axes reordering code when we are confident enough with the code to handle the north-up crs.

TODO use orthodromic distance?

Parameters:

envelope - the GeneralEnvelope

dim -

crs -

Throws:

DataSourceException

getCrs

public final CoordinateReferenceSystem getCrs()

Retrieves the CoordinateReferenceSystem for dataset pointed by this AbstractGridCoverage2DReader.

Returns:

the CoordinateReferenceSystem for dataset pointed by this AbstractGridCoverage2DReader.

getOriginalGridRange

public final GridEnvelope getOriginalGridRange()

Retrieves the GeneralGridEnvelope that represents the raster grid dimensions of the highest resolution level in this dataset.

Returns:

the GeneralGridEnvelope that represents the raster grid dimensions of the highest resolution level in this dataset.

getOriginalEnvelope

public final GeneralEnvelope getOriginalEnvelope()

Retrieves the GeneralEnvelope for this AbstractGridCoverage2DReader.

Returns:

the GeneralEnvelope for this AbstractGridCoverage2DReader.

getOriginalGridToWorld

public final MathTransform getOriginalGridToWorld(PixelInCell pixInCell)

Retrieves the original grid to world transformation for this AbstractGridCoverage2DReader.

Parameters:

pixInCell - specifies the datum of the transformation we want.

Returns:

the original grid to world transformation for this AbstractGridCoverage2DReader.

getSource

public final Object getSource()

Retrieves the source for this AbstractGridCoverage2DReader.

Specified by:

getSource in interface GridCoverageReader

Returns:

the source for this AbstractGridCoverage2DReader.

dispose

public void dispose()

Disposes this reader.

This method just tries to close the underlying ImageInputStream.

Specified by:

dispose in interface GridCoverageReader

skip

public void skip()

Description copied from interface: GridCoverageReader

Skip the current grid coverage without reading it, and move the stream position to the next grid coverage.

Specified by:

skip in interface GridCoverageReader

See Also:

GridCoverageReader.skip()

hasMoreGridCoverages

public boolean hasMoreGridCoverages()

Description copied from interface: GridCoverageReader

Returns true if there is at least one more grid coverage available on the stream.

Specified by:

hasMoreGridCoverages in interface GridCoverageReader

See Also:

GridCoverageReader.hasMoreGridCoverages()

listSubNames

public String[] listSubNames()

Description copied from interface: GridCoverageReader

Retrieve the list of grid coverages contained within the input source. Each grid can have a different coordinate system, number of dimensions and grid geometry. For example, a HDF-EOS file (GRID.HDF) contains 6 grid coverages each having a different projection. An empty array will be returned if no sub names exist.

Specified by:

listSubNames in interface GridCoverageReader

Returns:

The list of grid coverages contained within the input source.

See Also:

GridCoverageReader.listSubNames()

getCurrentSubname

public String getCurrentSubname()

Description copied from interface: GridCoverageReader

Returns the name for the next grid coverage to be read from the input source.

Specified by:

getCurrentSubname in interface GridCoverageReader

See Also:

GridCoverageReader.getCurrentSubname()

getMetadataNames

public String[] getMetadataNames()

Description copied from interface: GridCoverageReader

Returns the list of metadata keywords associated with the input source as a whole (not associated with any particular grid coverage). If no metadata is available, the array will be empty.

Specified by:

getMetadataNames in interface GridCoverageReader

Returns:

The list of metadata keywords for the input source.

See Also:

GridCoverageReader.getMetadataNames()

getMetadataValue

public String getMetadataValue(String name)

Description copied from interface: GridCoverageReader

Retrieve the metadata value for a given metadata name.

Specified by:

getMetadataValue in interface GridCoverageReader

Parameters:

name - Metadata keyword for which to retrieve metadata.

Returns:

The metadata value for the given metadata name. Should be one of the name returned by GridCoverageReader.getMetadataNames().

See Also:

GridCoverageReader.getMetadataValue(java.lang.String)

getGridCoverageCount

public int getGridCoverageCount()

See Also:

org.opengis.coverage.grid.GridCoverageReader#getGridCoverageCount()

getInfo

public ServiceInfo getInfo()

Information about this source.

Subclasses should provide additional format specific information.

Returns:

ServiceInfo describing getSource().

finalize

protected void finalize()
                 throws Throwable

Forcing disposal of this AbstractGridCoverage2DReader which may keep an ImageInputStream open.

Overrides:

finalize in class Object

Throws:

Throwable

getDynamicParameters

public Set<ParameterDescriptor<List>> getDynamicParameters()

Return the set of dynamic parameterDescriptors (the ones related to domains) for this reader. Default implementation returns an empty set of parameters

Returns: