org.geotoolkit.coverage.io
Class ImageCoverageWriter

Object
  GridCoverageStore
      GridCoverageWriter
          ImageCoverageWriter

All Implemented Interfaces:

Localized, LogProducer

public class ImageCoverageWriter
extends GridCoverageWriter

A GridCoverageWriter implementation which use an ImageWriter for writing sample values. This implementation reads the sample values from a RenderedImage, and consequently is targeted toward two-dimensional slices of data.

ImageCoverageWriter basically works as a layer which converts geodetic coordinates (for example the region to read) to pixel coordinates before to pass them to the wrapped ImageWriter, and conversely: from pixel coordinates to geodetic coordinates. The later conversion is called "grid to CRS" and is determined from the GridGeometry2D provided by the GridCoverage.

Closing the output stream
An Image Output Stream may be created automatically from various output types like File or URL. That output stream is not closed after a write operation, because many consecutive write operations may be performed for the same output. To ensure that the automatically generated output stream is closed, user shall invoke the setOutput(Object) method with a null input, or invoke the reset() or dispose() methods.

Note that output streams explicitly given by the users are never closed. It is caller responsibility to close them.

Since:

3.14

Version:

3.20

Author:

Martin Desruisseaux (Geomatys), Johann Sorel (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

protected ImageWriter

imageWriter The ImageWriter to use for encoding RenderedImages.

Fields inherited from class GridCoverageStore

abortRequested

Constructor Summary

ImageCoverageWriter()
Creates a new instance.

Method Summary

void	abort() Cancels the write operation.
protected boolean	canReuseImageWriter(ImageWriterSpi provider, String formatName, Object output, RenderedImage image) Returns true if the image writer created by the given provider can be reused.
protected void	completeImageMetadata(IIOMetadata metadata, GridCoverage coverage) Creates additional metadata to be merged with the one created by ImageCoverageReader.
protected ImageWriteParam	createImageWriteParam(RenderedImage image) Returns the default Java I/O parameters to use for writing an image.
protected ImageWriter	createImageWriter(String formatName, Object output, RenderedImage image) Creates an ImageWriter that claim to be able to encode the given output.
void	dispose() Allows any resources held by this writer to be released.
void	reset() Restores the GridCoverageWriter to its initial state.
void	setLocale(Locale locale) Sets the current locale of this coverage reader or writer to the given value.
void	setLogLevel(Level level) Sets the logging level to use for write operations.
void	setOutput(Object output) Sets the output destination to the given object.
void	write(GridCoverage coverage, GridCoverageWriteParam param) Writes a single grid coverage using ImageWriter.write(IIOMetadata, IIOImage, ImageWriteParam).
void	write(Iterable<? extends GridCoverage> coverages, GridCoverageWriteParam param) Writes a single or many grid coverages using ImageWriter.write or writeToSequence(IIOImage, ImageWriteParam).

Methods inherited from class GridCoverageWriter

getOutput

Methods inherited from class GridCoverageStore

getLocale, getLogLevel

Methods inherited from class Object

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

Field Detail

imageWriter

protected ImageWriter imageWriter

The ImageWriter to use for encoding RenderedImages. This writer is initially null and lazily created when first needed. Once created, it is reused for subsequent outputs if possible.

Constructor Detail

ImageCoverageWriter

public ImageCoverageWriter()

Creates a new instance.

Method Detail

setLogLevel

public void setLogLevel(Level level)

Sets the logging level to use for write operations. If the image writer implements the LogProducer interface, then it is also set to the given level.

Specified by:

setLogLevel in interface LogProducer

Overrides:

setLogLevel in class GridCoverageStore

Parameters:

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

Since:

3.15

setLocale

public void setLocale(Locale locale)

Sets the current locale of this coverage reader or writer to the given value. A value of null removes any previous setting, and indicates that the reader or writer should localize as it sees fit.

The given locale will also be given to the wrapped image writer, providing that the image writer supports the locale language. If it doesn't, then the image writer locale is set to null.

Overrides:

setLocale in class GridCoverageStore

Parameters:

locale - The new locale to use, or null for a default one.

See Also:

ImageReader.setLocale(Locale), ImageWriter.setLocale(Locale)

setOutput

public void setOutput(Object output)
               throws CoverageStoreException

Sets the output destination to the given object. The output is typically a File, URL or String object, but other types (especially ImageOutputStream) may be accepted as well depending on the image writer implementation.

The given output can also be an ImageWriter instance with its output initialized, in which case it is used directly as the image writer wrapped by this ImageCoverageWriter.

Overrides:

setOutput in class GridCoverageWriter

Parameters:

output - The output (typically File or String) to be written.

Throws:

IllegalArgumentException - if output is not a valid instance for this writer.

CoverageStoreException - if the operation failed.

See Also:

ImageWriter.setOutput(Object)

canReuseImageWriter

protected boolean canReuseImageWriter(ImageWriterSpi provider,
                                      String formatName,
                                      Object output,
                                      RenderedImage image)
                               throws IOException

Returns true if the image writer created by the given provider can be reused. This method is invoked automatically for determining if the current image writer can be reused for writing the given output.

The default implementation performs the following checks:

1. If formatName is non-null, then this method checks if the given name is one of the format names declared by the provider. If not, then this method immediately returns false.
2. Next, this method returns true if the writer can encode the given image, or false otherwise.

Overriding
Subclasses can override this method if they want to determine in another way whatever the image writer can be reused. Subclasses can optionally set the image writer output or leave it null, at their choice. If they set the output, then that output will be used. Otherwise the caller will set the output automatically.

Parameters:

provider - The provider of the image writer.

formatName - The format to use for fetching an ImageWriter, or null if unspecified.

output - The output to set to the image writer.

image - The image to be written, or null if unknown.

Returns:

true if the image writer can be reused.

Throws:

IOException - If an error occurred while determining if the current image writer can write the given image to the given output.

createImageWriter

protected ImageWriter createImageWriter(String formatName,
                                        Object output,
                                        RenderedImage image)
                                 throws IOException

Creates an ImageWriter that claim to be able to encode the given output. This method is invoked automatically for assigning a new value to the imageWriter field.

The default implementation performs the following choice:

• If a non-null format name is specified, delegate to XImageIO.getWriterByFormatName(String, Object, RenderedImage).
• Otherwise delegate to XImageIO.getWriterBySuffix(Object, RenderedImage).

Overriding
Subclasses can override this method if they want to create a new image writer in another way. Subclasses can optionally set the image writer output or leave it null, at their choice. If they set the output, then that output will be used. Otherwise the caller will set the output automatically.

Parameters:

formatName - The format to use for fetching an ImageWriter, or null if unspecified.

output - The output destination.

image - The image to be written, or null if unknown.

Returns:

An initialized image writer for writing to the given output.

Throws:

IOException - If no suitable image writer has been found, or if an error occurred while creating it.

createImageWriteParam

protected ImageWriteParam createImageWriteParam(RenderedImage image)
                                         throws IOException

Returns the default Java I/O parameters to use for writing an image. This method is invoked by the write(GridCoverage, GridCoverageWriteParam) method in order to get the Java parameter object to use for controlling the writing process.

The default implementation returns ImageWriter.getDefaultWriteParam() with tiling, progressive mode and compression set to ImageWriteParam.MODE_DEFAULT. Subclasses can override this method in order to perform additional parameter settings. Note however that any source region, source subsampling and source bands settings may be overwritten by the write method, which perform its own computation.

Parameters:

image - The image which will be written.

Returns:

A default Java I/O parameters object to use for controlling the writing process.

Throws:

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

See Also:

write(GridCoverage, GridCoverageWriteParam)

completeImageMetadata

protected void completeImageMetadata(IIOMetadata metadata,
                                     GridCoverage coverage)
                              throws IOException

Creates additional metadata to be merged with the one created by ImageCoverageReader. This method is invoked automatically just before to write the image, with a metadata argument containing basic information in the RectifiedGridDomain and Dimensions nodes (see Image metadata for a tree description). The default implementation does nothing. However subclasses can override this method in order to create additional metadata that this writer can not infer.

Parameters:

metadata - The default metadata, to be modified in-place.

coverage - null for stream metadata, or the coverage being written for image metadata.

Throws:

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

Since:

3.17

write

public void write(GridCoverage coverage,
                  GridCoverageWriteParam param)
           throws CoverageStoreException,
                  CancellationException

Writes a single grid coverage using ImageWriter.write(IIOMetadata, IIOImage, ImageWriteParam). The default implementation wraps the given coverage in a singleton set and delegates to write(Iterable, GridCoverageWriteParam).

Specified by:

write in class GridCoverageWriter

Parameters:

coverage - The coverage to write.

param - Optional parameters used to control the writing process, or null.

Throws:

CoverageStoreException - If an error occurs while writing the information to the output destination.

CancellationException - If GridCoverageStore.abort() has been invoked in an other thread during the execution of this method.

write

public void write(Iterable<? extends GridCoverage> coverages,
                  GridCoverageWriteParam param)
           throws CoverageStoreException,
                  CancellationException

Writes a single or many grid coverages using ImageWriter.write or writeToSequence(IIOImage, ImageWriteParam). For each coverage in the given iterable, this method performs the following steps:

• Get the coverage RenderedImage and GridGeometry2D.
• Create an initially empty block of image parameters by invoking the createImageWriteParam(RenderedImage) method.
• Convert the given geodetic parameters to image parameters using the above grid geometry. The main properties to be set are:
  • source region
  • source subsampling
  • source bands
• Write the rendered image by invoking the image writer write or writeSequence method, depending on whatever the given iterable contains one or more coverages.

Overrides:

write in class GridCoverageWriter

Parameters:

coverages - The coverages to write.

param - Optional parameters used to control the writing process, or null.

Throws:

CoverageStoreException - If the iterable contains an unsupported number of coverages, or if an error occurs while writing the information to the output destination.

CancellationException - If GridCoverageStore.abort() has been invoked in an other thread during the execution of this method.

See Also:

ImageWriter.write(IIOMetadata, IIOImage, ImageWriteParam), ImageWriter.writeToSequence(IIOImage, ImageWriteParam)

abort

public void abort()

Cancels the write operation. The default implementation forward the call to the image writer, if any. The content of the coverage following the abort will be undefined.

Overrides:

abort in class GridCoverageStore

See Also:

GridCoverageStore.abortRequested, ImageReader.abort(), ImageWriter.abort()

reset

public void reset()
           throws CoverageStoreException

Restores the GridCoverageWriter to its initial state.

Overrides:

reset in class GridCoverageWriter

Throws:

CoverageStoreException - If an error occurs while restoring to the initial state.

See Also:

ImageWriter.reset()

dispose

public void dispose()
             throws CoverageStoreException

Allows any resources held by this writer to be released. The result of calling any other method subsequent to a call to this method is undefined.

The default implementation closes the image writer output if the later is a stream, then disposes that writer.

Overrides:

dispose in class GridCoverageWriter

Throws:

CoverageStoreException - If an error occurs while disposing resources.

See Also:

ImageWriter.dispose()