Package org.geotoolkit.image.io

Base classes for extensions to ImageReader and ImageWriter for spatial data.

See:
Description

Interface Summary

AggregatedImageStore	Interface for ImageReader and ImageWriter implementations that may store a large dataset as an aggregation of smaller datasets.
MultidimensionalImageStore	Interface for ImageReader and ImageWriter implementations handling data which can have more than two dimensions.
NamedImageStore	Interface for ImageReader and ImageWriter implementations where each image have a name.
WarningProducer	Interface for objects that may produce warnings for recoverable failures.

Class Summary

DimensionIdentification	Identifies a domain dimension by its index, its name or its axis direction.
DimensionSet	The set of DimensionIdentification instances managed by a given MultidimensionalImageStore instance.
DimensionSlice	Tuple of a dimension identifier and index in that dimension for a slice to read or write in a data file.
FileImageReader	Base class for image readers that require File input source.
FileImageWriter	Base class for image writers that require File output destination.
IIOListeners	A container of image I/O listeners.
IIOReadProgressAdapter	An abstract adapter class for receiving image progress events.
ImageReaderAdapter	Base class for readers which delegate most of their work to an other ImageReader.
ImageReaderAdapter.Spi	Service provider interface (SPI) for ImageReaderAdapters.
ImageWriterAdapter	Base class for writers which delegate most of their work to an other ImageWriter.
ImageWriterAdapter.Spi	Service provider interface (SPI) for ImageWriterAdapters.
Palette	A set of RGB colors created by a palette factory from a Palette.name.
PaletteFactory	A factory for index color models created from RGB values listed in files.
SampleConverter	Converts samples from the values stored in the image file to the values stored in the raster.
SpatialImageReader	Base class for readers of spatial (usually geographic) data.
SpatialImageReader.Spi	Service provider interfaces (SPI) for SpatialImageReaders.
SpatialImageReadParam	Default parameters for SpatialImageReader.
SpatialImageWriteParam	Default parameters for SpatialImageWriter.
SpatialImageWriter	Base class for writers of spatial (usually geographic) data.
SpatialImageWriter.Spi	Service provider interfaces (SPI) for SpatialImageWriters.
StreamImageReader	Base class for image readers that expect an InputStream or channel input source.
StreamImageReader.Spi	Service provider interface (SPI) for StreamImageReaders.
StreamImageWriter	Base class for image writers that expect an OutputStream or channel output.
StreamImageWriter.Spi	Service provider interface (SPI) for StreamImageWriters.
TextImageReader	Base class for image readers that expect a BufferedReader input source.
TextImageReader.Spi	Service provider interface (SPI) for TextImageReaders.
TextImageWriter	Base class for image writers that expect a BufferedWriter output.
TextImageWriter.Spi	Service provider interface (SPI) for TextImageWriter.
XImageIO	Extensions to the set of static methods provided in the standard ImageIO class.

Enum Summary

DimensionSlice.API	The standard Java API used for selecting the slice to read or write in a particular dimension.
InformationType	The type of information produced or modified by an image reader or writer.
Protocol	The protocol used for connecting to an image source through the network.
SampleConversionType	Kind of conversions which are allowed on sample values during the read process.

Exception Summary

IllegalImageDimensionException	Thrown by MultidimensionalImageStore implementations when a slice of data in an hypercube is accessed in an illegal way.
ImageMetadataException	Thrown if an error occurred while reading or writing the image metadata.
ImageNameNotFoundException	Thrown by NamedImageStore implementations when no image is found for a given name.
InvalidImageStoreException	Thrown if the input given to a reader or the output given to a writer is invalid.
UnsupportedImageFormatException	Thrown by XImageIO when the requested image format is not available in the Image I/O registry.

Package org.geotoolkit.image.io Description

Base classes for extensions to ImageReader and ImageWriter for spatial data. This package provides the following classes which can be used as a base for plugin implementations:

ImageReader	ImageWriter	Purpose
SpatialImageReader	SpatialImageWriter	Base class for readers/writers of spatial (usually geographic) data.
StreamImageReader	StreamImageWriter	Base class for readers/writers working with InputStream/OutputStream or channels. Other kind of input/output are converted to stream when first needed.
TextImageReader	TextImageWriter	Base class for readers/writers working with Reader/Writer. This implies the use of a character encoding, which may be local-dependent.
FileImageReader	FileImageWriter	Base class for readers/writers that require File input or output. Other kind of input/output are copied in a temporary file. This is used for wrapping native libraries which doesn't work with Java streams.
ImageReaderAdapter	ImageWriterAdapter	Base class for readers/writers which delegate most of their work to an other reader/writer. This is used for appending additional metadata to the ones processed by the standard readers/writers.
ImageReadParam	ImageWriteParam	Purpose
SpatialImageReadParam	SpatialImageWriteParam	Specializations of the standard IIOParam class for multi-dimensional dataset and for specifying color palette.
IIOMetadata		Purpose
SpatialMetadata		Geographic metadata structured in an arborescence similar to ISO 19115-2.

Concrete implementations are provided in the plugin and mosaic sub-packages.

Multi-dimensional dataset
The Java Image I/O library is designed for two-dimensional images. The Geotk library extends the Java library with the MultidimensionalImageStore interface, which provide method for accessing data above the two first dimensions. See the MultidimensionalImageStore javadoc for more details.

Conversion of sample values
Spatial image formats often contain geophysical values (e.g. temperatures in Celsius degrees, elevation in metres, etc.) better represented as floating point numbers than integers. Those files may be simple ASCII files containing values written as decimal numbers, or RAW files containing values written in the IEEE 754 binary format. Those files may contains missing values represented by a "pad" or "fill" value. The SpatialImageReader class provides SampleConverter for:

• Replacing fill values by NaN if the destination image is backed by floating point values.
• Scaling the values in the range of the destination image type if the image is backed by some integer type. Such conversions are applied only if they are necessary for storing the data in the destination image.

The default sample type is DataBuffer.TYPE_FLOAT. This default value is a compromise between compactness and reducing the risk of information lost. However rendering floating-point images is usually very slow. After reading, users can exploit Java Advanced Imaging operations in order to reformat data as needed. The example below reformats the TYPE_FLOAT data into TYPE_BYTE and replaces the grayscale colors by an indexed color model.

import java.awt.RenderingHints;
import java.awt.image.DataBuffer;
import java.awt.image.IndexColorModel;
import java.awt.image.renderable.ParameterBlock;
import javax.media.jai.operator.FormatDescriptor;
import javax.media.jai.operator.RescaleDescriptor;

public class Example {
    public static RenderedImage reformat(RenderedImage image) {
        // Prepare the indexed color model. Arrays
        // R, G and B should contains 256 RGB values.
        final byte[] R = ...
        final byte[] G = ...
        final byte[] B = ...
        final IndexColorModel colors = new IndexColorModel(8, 256, R, G, B);
        final ImageLayout     layout = new ImageLayout().setColorModel(colorModel);
        final RenderingHints   hints = new RenderingHints(JAI.KEY_IMAGE_LAYOUT, layout);

        // Rescale the image.   First, all pixels values are transformed using
        // the equation pi=CO+C1*p. Then, type float is clamp to type byte and
        // the new index color model is set.   Displaying such an image should
        // be much faster.
        final double C0 = ...
        final double C1 = ...
        image = RescaleDescriptor.create(image, new double[] {C1}, new double[] {C0}, null);
        image = FormatDescriptor .create(image, DataBuffer.TYPE_BYTE, null);
        return image;
    }
}

Static utility methods
The XImageIO class provides static methods completing the ones provided in the standard ImageIO class. Those methods consider the input or output type before to select an image reader or writer, because not every plugins can accept the standard types (image input or output stream) defined by the Java Image I/O specification.

The CoverageIO class provides higher-level static methods related to GridCoverage I/O operations.

System initialization
While not mandatory, it is recommended to invoke the following methods at least once before to use the Geotk library. Those methods are not invoked automatically in order to let users control their application configuration.

1. Invoke some AWT method first; see setDefaultCodecPreferences() below for explanation.
2. Registry.setDefaultCodecPreferences()
3. WorldFileImageReader.Spi.registerDefaults(ServiceRegistry)
4. WorldFileImageWriter.Spi.registerDefaults(ServiceRegistry)

Alternative: Setup.initialize(Properties) performs (among other tasks) all the above tasks except 1.

Those methods can be invoked more than once if the set of standard readers available (PNG, TIFF, etc.) is changed. For example invoking WorldFileImageReader.Spi.registerDefaults(...) again will replace the old World File readers by new one wrapping the new standard readers.

Since:

1.2

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys), Antoine Hnawia (IRD)

See Also:

org.geotoolkit.image.io.plugin

Module:

coverage/geotk-coverageio (download)