org.geotools.gce.imagepyramid

Class ImagePyramidReader

Object

AbstractGridCoverage2DReader

ImagePyramidReader

All Implemented Interfaces:

GridCoverage2DReader, GridCoverageReader

public final class ImagePyramidReader
extends AbstractGridCoverage2DReader
implements GridCoverageReader

This reader is responsible for providing access to a pyramid of mosaics of georeferenced coverages that are read directly through imageio readers, like tiff, pngs, etc...

Specifically this plugin relies on the image mosaic plugin to handle each single level of resolutions available, hence all the magic is done inside the mosaic plugin.

For information on how to build a mosaic, please refer to the ImageMosaicReader documentation.

If you are looking for information on how to create a pyramid, here you go.

The pyramid itself does no magic. All the magic is performed by the single mosaic readers that are polled depending on the requeste resolution levels. Therefore the first step is having a mosaic of images like geotiff, tiff, jpeg, or png which is going to be the base for the pyramid.

The second step is to build the next (lower resolution) levels for the pyramid.
If you look inside the spike dire of the geotools project you will find a (growing) set of tools that can be used for doing processing on coverages.
Specifically there is one tool called PyramidBuilder that can be used to build the pyramid level by level.

Last step is providing a prj file with the projection of the pyramid (btw all the levels has to be in the same projection) as well as a properties file with this structure:

           #
           #Mon Aug 21 22:23:27 CEST 2006
           #name of the coverage
           Name=ikonos
           #different resolution levels available
           Levels=1.2218682749859724E-5,9.220132503102996E-6 2.4428817977683634E-5,1.844026500620314E-5 4.8840552865873626E-5,3.686350299024973E-5 9.781791400307775E-5,7.372700598049946E-5 1.956358280061555E-4,1.4786360643866836E-4 3.901787184256844E-4,2.9572721287731037E-4
           #where all the levels reside
           LevelsDirs=0 2 4 8 16 32
           #number of levels available
           LevelsNum=6
           #envelope for this pyramid
           Envelope2D=13.398228477973406,43.591366397808976 13.537912459169803,43.67121274528585
 

Starting with 16.x ImagePyramid can now support ImageMosaics with inner overviews. See ImageLevelsMapper for additional details of the Levels entry of a pyramid of mosaics with inner overviews.

Since:

2.3

Author:

Simone Giannecchini, Stefan Alfons Krueger (alfonx), Wikisquare.de : Support for jar:file:foo.jar/bar.properties like URLs

Field Summary

Fields inherited from class AbstractGridCoverage2DReader

closeMe, coverageFactory, coverageName, crs, dtLayout, EPS, gzipped, highestRes, hints, inStream, inStreamSPI, numOverviews, originalEnvelope, originalGridRange, overViewResolutions, raster2Model, source

Fields inherited from interface GridCoverage2DReader

ELEVATION_DOMAIN, ELEVATION_DOMAIN_MAXIMUM, ELEVATION_DOMAIN_MINIMUM, ELEVATION_DOMAIN_RESOLUTION, FILE_SOURCE_PROPERTY, HAS_ELEVATION_DOMAIN, HAS_TIME_DOMAIN, MULTICRS_READER, REPROJECTING_READER, SOURCE_URL_PROPERTY, TIME_DOMAIN, TIME_DOMAIN_MAXIMUM, TIME_DOMAIN_MINIMUM, TIME_DOMAIN_RESOLUTION

Constructor Summary

Constructors

Constructor and Description
ImagePyramidReader(Object source) Constructor for an ImagePyramidReader.
ImagePyramidReader(Object source, Hints uHints) Constructor for an ImagePyramidReader.

Method Summary

Modifier and Type	Method and Description
void	dispose() Disposes this reader.
CoordinateReferenceSystem	getCoordinateReferenceSystem(String coverageName) Retrieves the GeneralEnvelope for this AbstractGridCoverage2DReader.
DatasetLayout	getDatasetLayout(String coverageName) Returns the DatasetLayout for the specified coverage.
Set<ParameterDescriptor<List>>	getDynamicParameters(String coverageName) Return the set of dynamic parameterDescriptors (the ones related to domains) for this reader.
Format	getFormat() Returns the format handled by this GridCoverageReader.
int	getGridCoverageCount() Retrieve the number of coverages contained within the input source.
String[]	getGridCoverageNames() Retrieve the list of coverages contained within the input source.
ImageLayout	getImageLayout(String coverageName) Retrieve the ImageLayout for the specified coverage.
ImageMosaicReader	getImageMosaicReaderForLevel(Integer imageChoice) Retrieve the ImageMosaicReader for the requested Level and load if necessary
ImageMosaicReader	getImageMosaicReaderForLevel(String coverageName, Integer imageChoice) Retrieve the ImageMosaicReader for the requested Level and load if necessary
String[]	getMetadataNames() Returns the list of metadata keywords associated with the input source as a whole (not associated with any particular grid coverage).
String[]	getMetadataNames(String coverageName) Returns the list of metadata keywords associated with a specific gridCoverage referred by name.
String	getMetadataValue(String name) Retrieve data value for requested metadata
String	getMetadataValue(String coverageName, String name) Retrieve meta data value from requested coverage and for requested metadata
int	getNumOverviews(String coverageName) Number of predetermined overviews for the specified coverage.
GeneralEnvelope	getOriginalEnvelope(String coverageName) Retrieves the GeneralEnvelope for this AbstractGridCoverage2DReader.
GridEnvelope	getOriginalGridRange(String coverageName) Retrieves the GeneralGridEnvelope that represents the raster grid dimensions of the highest resolution level in this dataset.
MathTransform	getOriginalGridToWorld(String coverageName, PixelInCell pixInCell) Retrieves the original grid to world transformation for this AbstractGridCoverage2DReader.
double[][]	getResolutionLevels(String coverageName) Retrieve the resolution levels for the specified coverage.
GridCoverage2D	read(GeneralParameterValue[] params) Read the current grid coverage from the stream.
GridCoverage2D	read(String coverageName, GeneralParameterValue[] params) Retrieves the GridEnvelope associated to the specified coverageName for this GridCoverage2DReader.

Methods inherited from class AbstractGridCoverage2DReader

addAllSiblings, addSiblings, checkName, createImageCoverage, createImageCoverage, createImageCoverage, createImageCoverage, decimationOnReadingControl, finalize, getCoordinateReferenceSystem, getCrs, getCurrentSubname, getDatasetLayout, getDynamicParameters, getFiles, getGroundControlPoints, getGroundControlPoints, getHighestRes, getImageLayout, getInfo, getInfo, getMultiLevelROIProvider, getNumOverviews, getOriginalEnvelope, getOriginalGridRange, getOriginalGridToWorld, getOverviewGridEnvelope, getOverviewGridEnvelope, getReadingResolutions, getReadingResolutions, getRescaledRasterToModel, getResolution, getResolutionLevels, getSibling, getSource, getSourceAsFile, hasMoreGridCoverages, listSubNames, setlayout, setLayout, setReadParams, setReadParams, skip

Methods inherited from class Object

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

Methods inherited from interface GridCoverageReader

getCurrentSubname, getSource, hasMoreGridCoverages, listSubNames, skip

Constructor Detail

ImagePyramidReader

public ImagePyramidReader(Object source,
                          Hints uHints)
                   throws IOException

Constructor for an ImagePyramidReader.

Parameters:

source - The source object.

uHints - Hints to control the behaviour of this reader.

Throws:

IOException

UnsupportedEncodingException

ImagePyramidReader

public ImagePyramidReader(Object source)
                   throws IOException

Constructor for an ImagePyramidReader.

Parameters:

source - The source object.

Throws:

IOException

UnsupportedEncodingException

Method Detail

getFormat

public Format getFormat()

Description copied from interface: GridCoverageReader

Returns the format handled by this GridCoverageReader.

Specified by:

getFormat in interface GridCoverageReader

See Also:

GridCoverageReader.getFormat()

read

public GridCoverage2D read(GeneralParameterValue[] params)
                    throws IOException

Description copied from class: AbstractGridCoverage2DReader

Read the current grid coverage from the stream.

Example:

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

Specified by:

read in interface GridCoverage2DReader

Specified by:

read in interface GridCoverageReader

Specified by:

read in class AbstractGridCoverage2DReader

Parameters:

params - Optional parameters matching Format.getReadParameters().

Returns:

a grid coverage from the input source.

Throws:

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.

getOriginalGridRange

public GridEnvelope getOriginalGridRange(String coverageName)

Description copied from class: AbstractGridCoverage2DReader

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

Specified by:

getOriginalGridRange in interface GridCoverage2DReader

Overrides:

getOriginalGridRange in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage to work with

Returns:

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

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem(String coverageName)

Description copied from class: AbstractGridCoverage2DReader

Retrieves the GeneralEnvelope for this AbstractGridCoverage2DReader.

Specified by:

getCoordinateReferenceSystem in interface GridCoverage2DReader

Overrides:

getCoordinateReferenceSystem in class AbstractGridCoverage2DReader

Returns:

the GeneralEnvelope for this AbstractGridCoverage2DReader.

getOriginalEnvelope

public GeneralEnvelope getOriginalEnvelope(String coverageName)

Description copied from class: AbstractGridCoverage2DReader

Retrieves the GeneralEnvelope for this AbstractGridCoverage2DReader.

Specified by:

getOriginalEnvelope in interface GridCoverage2DReader

Overrides:

getOriginalEnvelope in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage to work on.

Returns:

the GeneralEnvelope for this AbstractGridCoverage2DReader.

getOriginalGridToWorld

public MathTransform getOriginalGridToWorld(String coverageName,
                                            PixelInCell pixInCell)

Description copied from class: AbstractGridCoverage2DReader

Retrieves the original grid to world transformation for this AbstractGridCoverage2DReader.

Specified by:

getOriginalGridToWorld in interface GridCoverage2DReader

Overrides:

getOriginalGridToWorld in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage to work with

pixInCell - specifies the datum of the transformation we want.

Returns:

the original grid to world transformation for this AbstractGridCoverage2DReader.

getDynamicParameters

public Set<ParameterDescriptor<List>> getDynamicParameters(String coverageName)

Description copied from class: AbstractGridCoverage2DReader

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

Specified by:

getDynamicParameters in interface GridCoverage2DReader

Overrides:

getDynamicParameters in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage to work with

Returns:

the Set of dynamic read parameters supported by this GridCoverage2DReader.

getNumOverviews

public int getNumOverviews(String coverageName)

Description copied from interface: GridCoverage2DReader

Number of predetermined overviews for the specified coverage.

Specified by:

getNumOverviews in interface GridCoverage2DReader

Overrides:

getNumOverviews in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage for which we do want to get the number of overviews.

Returns:

The number of predetermined overviews for the specified coverage. 0 if none are available, -1 if infinite are available, otherwise a positive number.

getDatasetLayout

public DatasetLayout getDatasetLayout(String coverageName)

Description copied from interface: GridCoverage2DReader

Returns the DatasetLayout for the specified coverage.

Specified by:

getDatasetLayout in interface GridCoverage2DReader

Overrides:

getDatasetLayout in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage for which we do want to get the DatasetLayout

Returns:

a DatasetLayout object containing info about Overview number and Image masks.

getImageLayout

public ImageLayout getImageLayout(String coverageName)
                           throws IOException

Description copied from interface: GridCoverage2DReader

Retrieve the ImageLayout for the specified coverage.

Throw an IllegalArgumentException in case the name is wrong and/or no such a coverage exists.

Specified by:

getImageLayout in interface GridCoverage2DReader

Overrides:

getImageLayout in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage for which we want to know the GridEnvelope.

Returns:

an ImageLayout that is useful for actually knowing the ColorModel, the SampleModel as well as the tile grid for a certain coverage.

Throws:

IOException

getResolutionLevels

public double[][] getResolutionLevels(String coverageName)
                               throws IOException

Description copied from interface: GridCoverage2DReader

Retrieve the resolution levels for the specified coverage.

Throw an IllegalArgumentException in case the name is wrong and/or no such a coverage exists.

Specified by:

getResolutionLevels in interface GridCoverage2DReader

Overrides:

getResolutionLevels in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage for which we want to know the resolution levels.

Returns:

the resolution levels for the specified coverage.

Throws:

IOException

read

public GridCoverage2D read(String coverageName,
                           GeneralParameterValue[] params)
                    throws IOException

Description copied from interface: GridCoverage2DReader

Retrieves the GridEnvelope associated to the specified coverageName for this GridCoverage2DReader.

Specified by:

read in interface GridCoverage2DReader

Specified by:

read in interface GridCoverageReader

Overrides:

read in class AbstractGridCoverage2DReader

Parameters:

coverageName - the name of the coverage to work with

params - an array of GeneralParameterValue that uses a subset of the available read params for this GridCoverage2DReader as specified by the Format

Returns:

a GridCoverage2D for the underlying default coverage for this GridCoverage2DReader or null in case no GridCoverage2D can be read for the provided parameters.

Throws:

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.

dispose

public void dispose()

Description copied from class: AbstractGridCoverage2DReader

Disposes this reader.

This method just tries to close the underlying ImageInputStream.

Specified by:

dispose in interface GridCoverageReader

Overrides:

dispose in class AbstractGridCoverage2DReader

See Also:

GridCoverageReader.dispose()

getGridCoverageNames

public String[] getGridCoverageNames()

Description copied from interface: GridCoverageReader

Retrieve the list of 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:

getGridCoverageNames in interface GridCoverageReader

Overrides:

getGridCoverageNames in class AbstractGridCoverage2DReader

Returns:

The list of grid coverages contained within the input source.

getGridCoverageCount

public int getGridCoverageCount()

Description copied from interface: GridCoverageReader

Retrieve the number of coverages contained within the input source.

Specified by:

getGridCoverageCount in interface GridCoverageReader

Overrides:

getGridCoverageCount in class AbstractGridCoverage2DReader

Returns:

the number of coverages for this reader.

See Also:

GridCoverageReader.getGridCoverageCount()

getMetadataValue

public String getMetadataValue(String coverageName,
                               String name)

Retrieve meta data value from requested coverage and for requested metadata

Specified by:

getMetadataValue in interface GridCoverageReader

Overrides:

getMetadataValue in class AbstractGridCoverage2DReader

Parameters:

coverageName -

name -

Returns:

getMetadataValue

public String getMetadataValue(String name)

Retrieve data value for requested metadata

Specified by:

getMetadataValue in interface GridCoverageReader

Overrides:

getMetadataValue in class AbstractGridCoverage2DReader

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)

getMetadataNames

public String[] getMetadataNames(String coverageName)

Description copied from interface: GridCoverageReader

Returns the list of metadata keywords associated with a specific gridCoverage referred by name. If no metadata is available, the array will be empty.

Specified by:

getMetadataNames in interface GridCoverageReader

Overrides:

getMetadataNames in class AbstractGridCoverage2DReader

Returns:

The list of metadata keywords for the input source.

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

Overrides:

getMetadataNames in class AbstractGridCoverage2DReader

Returns:

The list of metadata keywords for the input source.

See Also:

GridCoverageReader.getMetadataNames()

getImageMosaicReaderForLevel

public ImageMosaicReader getImageMosaicReaderForLevel(Integer imageChoice)
                                               throws IOException

Retrieve the ImageMosaicReader for the requested Level and load if necessary

Returns:

ImageMosaicReader for level

Throws:

IOException

getImageMosaicReaderForLevel

public ImageMosaicReader getImageMosaicReaderForLevel(String coverageName,
                                                      Integer imageChoice)
                                               throws IOException

Retrieve the ImageMosaicReader for the requested Level and load if necessary

Returns:

ImageMosaicReader for level

Throws:

IOException