org.geotoolkit.image.io.mosaic
Class MosaicImageWriter

Object
  ImageWriter
      MosaicImageWriter

All Implemented Interfaces:

ImageTranscoder, Disposable, LogProducer

public class MosaicImageWriter
extends ImageWriter
implements LogProducer, Disposable

An image writer which takes a large image (potentially tiled) in input and write tiles as output. The mosaic to write is specified as a collection of Tile objects given to the setOutput(Object) method. The pixel values to write can be specified either as a RenderedImage (this is the standard API), or as a single File or a collection of source tiles given to the writeFromInput(Object, ImageWriteParam) method. The later alternative is non-standard but often required since the image to mosaic is typically bigger than the capacity of a single RenderedImage.

Caching of source tiles
This class may be slow when reading source images encoded in a compressed format like PNG, because multiple passes over the same image may be necessary for writing different tiles and compression makes the seeks harder. This problem can be mitigated by copying the source images to temporary files in an uncompressed RAW format. The inconvenient is that a large amount of disk space will be temporarily required until the write operation is completed.

Caching are enabled by default. If the environment is constrained by disk space or if the source tiles are known to be already uncompressed, then caching can be disabled by overriding the isCachingEnabled(ImageReader,int) method.

Filtering source images
It is possible to apply an operation on source images before to create the target tiles. The operation can be specified by the MosaicImageWriteParam.setSourceTileFilter(BufferedImageOp) method, for example in order to add transparency to fully opaque images. Note that if an operation is applied, then the source tiles will be cached in temporary RAW files as described in the above section even if isCachingEnabled(ImageReader,int) returns false.

Since:

2.5

Version:

3.18

Author:

Martin Desruisseaux (Geomatys), Cédric Briançon (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Nested Class Summary

static class

MosaicImageWriter.Spi Service provider for MosaicImageWriter.

Field Summary

Fields inherited from class ImageWriter

availableLocales, locale, originatingProvider, output, progressListeners, warningListeners, warningLocales

Constructor Summary

MosaicImageWriter()
Constructs an image writer with the default provider.

MosaicImageWriter(ImageWriterSpi spi)
Constructs an image writer with the specified provider.

Method Summary

IIOMetadata	convertImageMetadata(IIOMetadata inData, ImageTypeSpecifier imageType, ImageWriteParam param) Returns image metadata initialized to the specified state, or null.
IIOMetadata	convertStreamMetadata(IIOMetadata inData, ImageWriteParam param) Returns stream metadata initialized to the specified state, or null.
void	dispose() Disposes resources held by this writer.
protected boolean	filter(ImageReader reader) Invoked after MosaicImageWriter has created a reader and set the input.
protected boolean	filter(ImageWriter writer) Invoked after MosaicImageWriter has created a writer and set the output.
IIOMetadata	getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param) Returns the default image metadata, or null if none.
IIOMetadata	getDefaultStreamMetadata(ImageWriteParam param) Returns the default stream metadata, or null if none.
MosaicImageWriteParam	getDefaultWriteParam() Returns default parameters appropriate for this format.
Level	getLogLevel() Returns the logging level for tile information during read and write operations.
long	getMaximumMemoryAllocation() Returns the maximal amount of memory that writeFromInput is allowed to use.
TileManager[]	getOutput() Returns the output, which is a an array of tile managers.
protected boolean	isCachingEnabled(ImageReader input, int inputIndex) Returns true if this writer is allowed to copy source images to temporary uncompressed RAW files.
protected void	onTileWrite(Tile tile, ImageWriteParam parameters) Invoked automatically when a tile is about to be written.
void	reset() Resets this writer to its initial state.
void	setLogLevel(Level level) Sets the logging level for tile information during read and write operations.
void	setOutput(Object output) Sets the output, which is expected to be an array of tile managers.
void	write(IIOMetadata metadata, IIOImage image, ImageWriteParam param) Writes the specified image as a set of tiles.
boolean	writeFromInput(Object input, ImageWriteParam param) Reads the image from the given input and writes it as a set of tiles.
boolean	writeFromInput(Object input, int inputIndex, ImageWriteParam param) Reads the image from the given input and writes it as a set of tiles.

Methods inherited from class ImageWriter

abort, abortRequested, addIIOWriteProgressListener, addIIOWriteWarningListener, canInsertEmpty, canInsertImage, canRemoveImage, canReplaceImageMetadata, canReplacePixels, canReplaceStreamMetadata, canWriteEmpty, canWriteRasters, canWriteSequence, clearAbortRequest, endInsertEmpty, endReplacePixels, endWriteEmpty, endWriteSequence, getAvailableLocales, getLocale, getNumThumbnailsSupported, getOriginatingProvider, getPreferredThumbnailSizes, prepareInsertEmpty, prepareReplacePixels, prepareWriteEmpty, prepareWriteSequence, processImageComplete, processImageProgress, processImageStarted, processThumbnailComplete, processThumbnailProgress, processThumbnailStarted, processWarningOccurred, processWarningOccurred, processWriteAborted, removeAllIIOWriteProgressListeners, removeAllIIOWriteWarningListeners, removeIIOWriteProgressListener, removeIIOWriteWarningListener, removeImage, replaceImageMetadata, replacePixels, replacePixels, replaceStreamMetadata, setLocale, write, write, writeInsert, writeToSequence

Methods inherited from class Object

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

Constructor Detail

MosaicImageWriter

public MosaicImageWriter()

Constructs an image writer with the default provider.

MosaicImageWriter

public MosaicImageWriter(ImageWriterSpi spi)

Constructs an image writer with the specified provider.

Parameters:

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

Method Detail

getLogLevel

public Level getLogLevel()

Returns the logging level for tile information during read and write operations. The default value is one of the PerformanceLevel constants, determined according the duration of the 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 and write 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.

getOutput

public TileManager[] getOutput()

Returns the output, which is a an array of tile managers. The array length is the maximum number of images that can be inserted. The element at index i is the tile manager to use when writing at image index i.

Overrides:

getOutput in class ImageWriter

setOutput

public void setOutput(Object output)
               throws IllegalArgumentException

Sets the output, 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:

setOutput in class ImageWriter

Parameters:

output - The output.

Throws:

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

getDefaultWriteParam

public MosaicImageWriteParam getDefaultWriteParam()

Returns default parameters appropriate for this format.

Overrides:

getDefaultWriteParam in class ImageWriter

write

public void write(IIOMetadata metadata,
                  IIOImage image,
                  ImageWriteParam param)
           throws IOException

Writes the specified image as a set of tiles. The default implementation copies the image in a temporary file, then invokes writeFromInput(java.lang.Object, javax.imageio.ImageWriteParam). This very inefficient approach may be changed in a future version.

Specified by:

write in class ImageWriter

Parameters:

metadata - The stream metadata.

image - The image to write.

param - The parameter for the image to write.

Throws:

IOException - if an error occurred while writing the image.

writeFromInput

public boolean writeFromInput(Object input,
                              ImageWriteParam param)
                       throws IOException

Reads the image from the given input and writes it as a set of tiles. This is equivalent to writeFromInput(input, 0, param) except that this method ensures that the input contains only one image. If more than one image is found, then an exception is throw. This is often desirable when the input is a collection of Tiles, since having more than one "image" (where "image" in this context means an input mosaic as a whole) means that we failed to create a single mosaic from a set of source tiles.

Parameters:

input - The image input, typically as a File.

param - The write parameters, or null for the default.

Returns:

true on success, or false if the process has been aborted.

Throws:

IOException - If an error occurred while reading or writing.

Since:

3.00

writeFromInput

public boolean writeFromInput(Object input,
                              int inputIndex,
                              ImageWriteParam param)
                       throws IOException

Reads the image from the given input and writes it as a set of tiles. The input is typically a File object, but other kind of inputs may be accepted depending on available image readers. The output files and tiling layout can be specified as a collection of Tile objects given to setOutput(Object) method.

Parameters:

input - The image input, typically as a File.

inputIndex - The image index to read from the given input file.

param - The write parameters, or null for the default.

Returns:

true on success, or false if the process has been aborted.

Throws:

IOException - If an error occurred while reading or writing.

TODO:

Current implementation do not yet supports source region and subsampling settings. An exception will be thrown if any of those parameters are set.

getMaximumMemoryAllocation

public long getMaximumMemoryAllocation()

Returns the maximal amount of memory that writeFromInput is allowed to use. The default implementation computes a value from the amount of memory available in the current JVM. Subclasses can override this method for returning a different value.

The returned value will be considered on a best effort basis. There is no guarantee that no more memory than the returned value will be used.

Returns:

An estimation of the maximum amount of memory allowed for allocation, in bytes.

isCachingEnabled

protected boolean isCachingEnabled(ImageReader input,
                                   int inputIndex)
                            throws IOException

Returns true if this writer is allowed to copy source images to temporary uncompressed RAW files. Doing so can speed up considerably the creation of large mosaics, at the expense of temporary disk space.

The default implementation returns true if the following conditions are meet:

• The input tiles format is not an uncompressed format like RAW, BMP or TIFF (the later is assumed uncompressed, while this is not always true). There is no advantage to copy an uncompressed format to an other uncompressed format.
• The usable space in the temporary directory is greater then the space required for writing the input tiles in RAW format.
• The usable space in the output directory is greater than the space required for writing the output tiles in their output format (a very approximative compression factor is guessed).
• Other conditions (not documented because they may change in future implementations). In case of doubt, it is safer to conservatively return false.

Subclasses should override this method if they can provide a better answer, or if they known that their source tiles are already uncompressed.

Note: This method is invoked only in the context of writeFromInput(Object, …) methods, which get the image to write from an ImageReader. This method is not invoked in the context of the write(RenderedImage) method because an image available in memory (ignoring JAI tiling) is assumed to not need disk cache. For this reason there is no isCachingEnabled(RenderedImage) method.

Parameters:

input - The input image or mosaic, an an ImageReader with its input set.

inputIndex - The image index to read from the given input file.

Returns:

true if this writer can cache the source tiles.

Throws:

IOException - If this method required an I/O operation and that operation failed.

Since:

3.00

filter

protected boolean filter(ImageReader reader)
                  throws IOException

Invoked after MosaicImageWriter has created a reader and set the input. Users can override this method for performing additional configuration and may returns false if the given reader is not suitable. The default implementation returns true in all case.

Parameters:

reader - The image reader created and configured by MosaicImageWriter.

Returns:

true If the given reader is ready for use, or false if an other reader should be fetched.

Throws:

IOException - if an error occurred while inspecting or configuring the reader.

filter

protected boolean filter(ImageWriter writer)
                  throws IOException

Invoked after MosaicImageWriter has created a writer and set the output. Users can override this method for performing additional configuration and may returns false if the given writer is not suitable. The default implementation returns true in all case.

Parameters:

writer - The image writer created and configured by MosaicImageWriter.

Returns:

true If the given writer is ready for use, or false if an other writer should be fetched.

Throws:

IOException - if an error occurred while inspecting or configuring the writer.

onTileWrite

protected void onTileWrite(Tile tile,
                           ImageWriteParam parameters)
                    throws IOException

Invoked automatically when a tile is about to be written. The default implementation does nothing. Subclasses can override this method in order to set custom write parameters.

The source region and source subsampling parameters can not be set through this method. Their setting will be overwritten by the caller because their values depend on the strategy chosen by MosaicImageWriter for reading images, which itself depends on the amount of available memory.

Parameters:

tile - The tile to be written.

parameters - The parameters to be given to the image writer. This method is allowed to change the parameter values.

Throws:

IOException - if an I/O operation was required and failed.

getDefaultStreamMetadata

public IIOMetadata getDefaultStreamMetadata(ImageWriteParam param)

Returns the default stream metadata, or null if none. The default implementation returns null in all cases.

Specified by:

getDefaultStreamMetadata in class ImageWriter

getDefaultImageMetadata

public IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType,
                                           ImageWriteParam param)

Returns the default image metadata, or null if none. The default implementation returns null in all cases.

Specified by:

getDefaultImageMetadata in class ImageWriter

convertStreamMetadata

public IIOMetadata convertStreamMetadata(IIOMetadata inData,
                                         ImageWriteParam param)

Returns stream metadata initialized to the specified state, or null. The default implementation returns null in all cases since this plugin doesn't provide metadata encoding capabilities.

Specified by:

convertStreamMetadata in interface ImageTranscoder

Specified by:

convertStreamMetadata in class ImageWriter

convertImageMetadata

public IIOMetadata convertImageMetadata(IIOMetadata inData,
                                        ImageTypeSpecifier imageType,
                                        ImageWriteParam param)

Returns image metadata initialized to the specified state, or null. The default implementation returns null in all cases since this plugin doesn't provide metadata encoding capabilities.

Specified by:

convertImageMetadata in interface ImageTranscoder

Specified by:

convertImageMetadata in class ImageWriter

reset

public void reset()

Resets this writer to its initial state. If there is any temporary files, they will be deleted.

Overrides:

reset in class ImageWriter

dispose

public void dispose()

Disposes resources held by this writer. This method should be invoked when this writer is no longer in use, in order to release some threads created by the writer.

Specified by:

dispose in interface Disposable

Overrides:

dispose in class ImageWriter