org.geotoolkit.image.io.mosaic
Class MosaicImageReader

Object
  ImageReader
      MosaicImageReader

All Implemented Interfaces:

Closeable, Disposable, LogProducer

public class MosaicImageReader
extends ImageReader
implements LogProducer, Closeable, Disposable

An image reader built from a mosaic of other image readers. The mosaic is specified as a collection of Tile objects, organized in a TileManager. Images are read using the read(int,ImageReadParam) method. The ImageReadParam argument is optional by strongly recommended, since the whole purpose of MosaicImageReader is to read efficiently only subsets of big tiled images.

Since:

2.5

Version:

3.18

Author:

Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Nested Class Summary

static class

MosaicImageReader.Spi Service provider for MosaicImageReader.

Field Summary

Fields inherited from class ImageReader

availableLocales, ignoreMetadata, input, locale, minIndex, originatingProvider, progressListeners, seekForwardOnly, updateListeners, warningListeners, warningLocales

Constructor Summary

MosaicImageReader()
Constructs an image reader with the default provider.

MosaicImageReader(ImageReaderSpi spi)
Constructs an image reader with the specified provider.

Method Summary

void	abort() Requests that any current read operation be aborted.
void	close() Closes any image input streams that may be held by tiles.
void	dispose() Allows any resources held by this reader to be released.
float	getAspectRatio(int imageIndex) Returns the aspect ratio.
Locale[]	getAvailableLocales() Returns an array of locales that may be used to localize warning listeners.
ImageTypePolicy	getDefaultImageTypePolicy() Returns the policy for computing image types.
MosaicImageReadParam	getDefaultReadParam() Returns default parameters appropriate for this format.
int	getHeight(int imageIndex) Returns the height in pixels of the given image within the input source.
IIOMetadata	getImageMetadata(int imageIndex) Returns the metadata associated with the given image, or null if none.
Iterator<ImageTypeSpecifier>	getImageTypes(int imageIndex) Returns possible image types to which the given image may be decoded.
TileManager[]	getInput() Returns the input, which is a an array of tile managers.
Level	getLogLevel() Returns the logging level for tile information during read operations.
int	getNumImages(boolean allowSearch) Returns the number of images, not including thumbnails.
ImageTypeSpecifier	getRawImageType(int imageIndex) Returns an image type which most closely represents the "raw" internal format of the image.
IIOMetadata	getStreamMetadata() Returns the metadata associated with the input source as a whole, or null.
int	getTileHeight(int imageIndex) Returns the height of a tile in the given image.
Set<ImageReaderSpi>	getTileReaderSpis() Returns the Service Provider Interfaces (SPI) of every image readers to be used for reading tiles.
int	getTileWidth(int imageIndex) Returns the width of a tile in the given image.
int	getWidth(int imageIndex) Returns the width in pixels of the given image within the input source.
boolean	isImageTiled(int imageIndex) Returns true if there is more than one tile for the given image index.
boolean	isRandomAccessEasy(int imageIndex) Returns true if the storage format of the given image places no inherent impediment on random access to pixels.
BufferedImage	read(int imageIndex, ImageReadParam param) Reads the image indexed by imageIndex using a supplied parameters.
BufferedImage	readTile(int imageIndex, int tileX, int tileY) Reads the tile indicated by the tileX and tileY arguments.
void	setInput(Object input, boolean seekForwardOnly, boolean ignoreMetadata) Sets the input source, which is expected to be an array of tile managers.
void	setLocale(Locale locale) Sets the current locale of this image reader and every tile readers.
void	setLogLevel(Level level) Sets the logging level for tile information during read operations.

Methods inherited from class ImageReader

abortRequested, addIIOReadProgressListener, addIIOReadUpdateListener, addIIOReadWarningListener, canReadRaster, checkReadParamBandSettings, clearAbortRequest, computeRegions, getDestination, getFormatName, getImageMetadata, getLocale, getMinIndex, getNumThumbnails, getOriginatingProvider, getSourceRegion, getStreamMetadata, getThumbnailHeight, getThumbnailWidth, getTileGridXOffset, getTileGridYOffset, hasThumbnails, isIgnoringMetadata, isSeekForwardOnly, processImageComplete, processImageProgress, processImageStarted, processImageUpdate, processPassComplete, processPassStarted, processReadAborted, processSequenceComplete, processSequenceStarted, processThumbnailComplete, processThumbnailPassComplete, processThumbnailPassStarted, processThumbnailProgress, processThumbnailStarted, processThumbnailUpdate, processWarningOccurred, processWarningOccurred, read, readAll, readAll, readAsRenderedImage, readerSupportsThumbnails, readRaster, readThumbnail, readTileRaster, removeAllIIOReadProgressListeners, removeAllIIOReadUpdateListeners, removeAllIIOReadWarningListeners, removeIIOReadProgressListener, removeIIOReadUpdateListener, removeIIOReadWarningListener, reset, setInput, setInput

Methods inherited from class Object

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

Constructor Detail

MosaicImageReader

public MosaicImageReader()

Constructs an image reader with the default provider.

MosaicImageReader

public MosaicImageReader(ImageReaderSpi spi)

Constructs an image reader with the specified provider.

Parameters:

spi - The image reader provider, or null for the default one.

Method Detail

getLogLevel

public Level getLogLevel()

Returns the logging level for tile information during read operations. The default value is one of the PerformanceLevel constants, determined according the duration of the read operation.

Specified by:

getLogLevel in interface LogProducer

Returns:

The current logging level.

setLogLevel

public void setLogLevel(Level level)

Sets the logging level for tile information during read operations. A null value restores the default level documented in the getLogLevel() method.

Specified by:

setLogLevel in interface LogProducer

Parameters:

level - The new logging level, or null for the default.

getInput

public TileManager[] getInput()

Returns the input, which is a an array of tile managers. The array length is the number of images. The element at index i is the tile manager to use when reading at image index i.

Overrides:

getInput in class ImageReader

setInput

public void setInput(Object input,
                     boolean seekForwardOnly,
                     boolean ignoreMetadata)
              throws IllegalArgumentException

Sets the input source, which is expected to be an array of tile managers. If the given input is a singleton, an array or a collection of Tile objects, then it will be wrapped in an array of TileManagers.

Overrides:

setInput in class ImageReader

Parameters:

input - The input.

seekForwardOnly - if true, images and metadata may only be read in ascending order from this input source.

ignoreMetadata - if true, metadata may be ignored during reads.

Throws:

IllegalArgumentException - if input is not an instance of one of the expected classes, or if the input can not be used because of an I/O error (in which case the exception has a IOException as its cause).

getTileReaderSpis

public Set<ImageReaderSpi> getTileReaderSpis()

Returns the Service Provider Interfaces (SPI) of every image readers to be used for reading tiles. This method returns an empty set if no input has been set.

Returns:

The service providers for tile readers.

See Also:

TileManager.getImageReaderSpis()

getAvailableLocales

public Locale[] getAvailableLocales()

Returns an array of locales that may be used to localize warning listeners. The default implementations returns the union of the locales supported by this reader and every tile readers.

Overrides:

getAvailableLocales in class ImageReader

Returns:

An array of supported locales, or null.

setLocale

public void setLocale(Locale locale)
               throws IllegalArgumentException

Sets the current locale of this image reader and every tile readers.

Overrides:

setLocale in class ImageReader

Parameters:

locale - The desired locale, or null.

Throws:

IllegalArgumentException - if locale is non-null but is not one of the available locales.

getNumImages

public int getNumImages(boolean allowSearch)
                 throws IOException

Returns the number of images, not including thumbnails.

Specified by:

getNumImages in class ImageReader

Throws:

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

isImageTiled

public boolean isImageTiled(int imageIndex)
                     throws IOException

Returns true if there is more than one tile for the given image index.

Overrides:

isImageTiled in class ImageReader

Parameters:

imageIndex - The index of the image to be queried.

Returns:

true If there is at least two tiles.

Throws:

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

getWidth

public int getWidth(int imageIndex)
             throws IOException

Returns the width in pixels of the given image within the input source.

Specified by:

getWidth in class ImageReader

Parameters:

imageIndex - The index of the image to be queried.

Returns:

The width of the image.

Throws:

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

getHeight

public int getHeight(int imageIndex)
              throws IOException

Returns the height in pixels of the given image within the input source.

Specified by:

getHeight in class ImageReader

Parameters:

imageIndex - The index of the image to be queried.

Returns:

The height of the image.

Throws:

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

getTileWidth

public int getTileWidth(int imageIndex)
                 throws IOException

Returns the width of a tile in the given image.

Overrides:

getTileWidth in class ImageReader

Parameters:

imageIndex - The index of the image to be queried.

Returns:

The width of a tile.

Throws:

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

getTileHeight

public int getTileHeight(int imageIndex)
                  throws IOException

Returns the height of a tile in the given image.

Overrides:

getTileHeight in class ImageReader

Parameters:

imageIndex - The index of the image to be queried.

Returns:

The height of a tile.

Throws:

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

isRandomAccessEasy

public boolean isRandomAccessEasy(int imageIndex)
                           throws IOException

Returns true if the storage format of the given image places no inherent impediment on random access to pixels. The default implementation returns true if the input of every tiles is a File and isRandomAccessEasy returned true for all tile readers.

Overrides:

isRandomAccessEasy in class ImageReader

Throws:

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

getAspectRatio

public float getAspectRatio(int imageIndex)
                     throws IOException

Returns the aspect ratio. If all tiles have the same aspect ratio, then that ratio is returned. Otherwise the default value is returned.

Overrides:

getAspectRatio in class ImageReader

Parameters:

imageIndex - The index of the image to be queried.

Throws:

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

getDefaultImageTypePolicy

public ImageTypePolicy getDefaultImageTypePolicy()

Returns the policy for computing image types. This is also the policy used by read method when none has been explicitly set in read parameters.

The default implementation makes the following choice based on the number of reader providers:

• SUPPORTED_BY_ALL if two or more
• SUPPORTED_BY_FIRST if exactly one
• ALWAYS_ARGB if none.

Note that SUPPORTED_BY_FIRST is not a really safe choice even if there is only one provider, because the image type can also depends on tile input. However the safest choice in all cases (SUPPORTED_BY_ALL) is costly and often not necessary. The current implementation is a compromise between safety and performance.

If Java assertions are enabled, this reader will verify that SUPPORTED_BY_ONE and SUPPORTED_BY_FIRST produce the same result than SUPPORTED_BY_ALL.

Subclasses can override this method if they want a different policy.

Returns:

The default image type policy.

getRawImageType

public ImageTypeSpecifier getRawImageType(int imageIndex)
                                   throws IOException

Returns an image type which most closely represents the "raw" internal format of the image. The default implementation depends on the default image type policy:

• For SUPPORTED_BY_ONE, this method delegates directly to the reader of an arbitrary tile (typically the first one).
• For SUPPORTED_BY_ALL, this method invokes getRawImageType for every tile readers, omits the types that are not declared in getImageTypes(imageIndex) for every tile readers, and returns the most common remaining value. If none is found, then some default specifier is returned.

Overrides:

getRawImageType in class ImageReader

Parameters:

imageIndex - The image index, from 0 inclusive to getNumImages(boolean) exclusive.

Returns:

A raw image type specifier.

Throws:

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

getImageTypes

public Iterator<ImageTypeSpecifier> getImageTypes(int imageIndex)
                                           throws IOException

Returns possible image types to which the given image may be decoded. The default implementation depends on the default image type policy:

• For SUPPORTED_BY_ONE, this method delegates directly to the reader of an arbitrary tile (typically the first one).
• For SUPPORTED_BY_ALL, this method invokes getImageTypes(imageIndex) on every tile readers and returns the intersection of all sets (i.e. only the types that are supported by every readers).

Specified by:

getImageTypes in class ImageReader

Parameters:

imageIndex - The image index, from 0 inclusive to getNumImages(boolean) exclusive.

Returns:

The image type specifiers that are common to all tiles.

Throws:

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

getDefaultReadParam

public MosaicImageReadParam getDefaultReadParam()

Returns default parameters appropriate for this format.

Overrides:

getDefaultReadParam in class ImageReader

getStreamMetadata

public IIOMetadata getStreamMetadata()
                              throws IOException

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

Note: A previous implementation was iterating over every tiles and attempted to merge the metadata using the IIOMetadata.mergeTree(String, Node) method. However this was extremely slow on large mosaics, and the result was usually not the expected one since the merge operation is hard to implement correctly.

Specified by:

getStreamMetadata in class ImageReader

Throws:

IOException - if an error occurs during reading.

getImageMetadata

public IIOMetadata getImageMetadata(int imageIndex)
                             throws IOException

Returns the metadata associated with the given image, or null if none. The default implementation returns an instance of SpatialMetadata with a "RectifiedGridDomain" node inferred from the information returned by TileManager.getGridGeometry().

Specified by:

getImageMetadata in class ImageReader

Parameters:

imageIndex - the index of the image whose metadata is to be retrieved.

Returns:

The metadata, or null.

Throws:

IllegalStateException - if the input source has not been set.

IndexOutOfBoundsException - if the supplied index is out of bounds.

IOException - if an error occurs during reading.

read

public BufferedImage read(int imageIndex,
                          ImageReadParam param)
                   throws IOException

Reads the image indexed by imageIndex using a supplied parameters. While optional, it is strongly recommended to supply parameters as an instance of MosaicImageReadParam on which param.setSubsamplingChangeAllowed(true) has been invoked.

If the above recommendation has been followed, then the supplied param object will be modified by call to this method since the subsampling effectively used will be written back in the given parameters.

Specified by:

read in class ImageReader

Parameters:

imageIndex - The index of the image to be retrieved.

param - The parameters used to control the reading process, or null. An instance of MosaicImageReadParam is expected but not required.

Returns:

The desired portion of the image.

Throws:

IOException - if an error occurs during reading.

See Also:

MosaicImageReadParam

readTile

public BufferedImage readTile(int imageIndex,
                              int tileX,
                              int tileY)
                       throws IOException

Reads the tile indicated by the tileX and tileY arguments.

Overrides:

readTile in class ImageReader

Parameters:

imageIndex - The index of the image to be retrieved.

tileX - The column index (starting with 0) of the tile to be retrieved.

tileY - The row index (starting with 0) of the tile to be retrieved.

Returns:

The desired tile.

Throws:

IOException - if an error occurs during reading.

abort

public void abort()

Requests that any current read operation be aborted.

Overrides:

abort in class ImageReader

close

public void close()
           throws IOException

Closes any image input streams that may be held by tiles. The streams will be opened again when they will be first needed.

Specified by:

close in interface Closeable

Throws:

IOException - if error occurred while closing a stream.

dispose

public void dispose()

Allows any resources held by this reader to be released. The default implementation closes any image input streams that may be held by tiles, then disposes every tile image readers.

Specified by:

dispose in interface Disposable

Overrides:

dispose in class ImageReader