image

Many common image I/O operations may be performed using the static methods of the ImageIO class.

This package contains the basic classes and interfaces for describing the contents of image files, including metadata and thumbnails (IIOImage); for controlling the image reading process (ImageReader, ImageReadParam, and ImageTypeSpecifier) and image writing process (ImageWriter and ImageWriteParam); for performing transcoding between formats (ImageTranscoder), and for reporting errors (IIOException).

All implementations of javax.imageio provide the following standard image format plug-ins:

Standard Plug-in Notes

Standard plug-in for GIF image format

ImageIO provides ImageReader and ImageWriter plug-ins for the Graphics Interchange Format (GIF) image format. These are the "standard" GIF plug-ins, meaning those that are included in the JRE, as distinct from those included in standard extensions, or 3rd party plug-ins. The following notes and metadata specification apply to the standard plug-ins.

Writing GIF images

• the number of bands is 1;
• the number of bits per sample is not greater than 8;
• the size of a color component is not greater than 8;

By default the GIF writer plug-in creates version "89a" images. This can be changed to "87a" by explicitly setting the version in the stream metadata (see GIF Stream Metadata Format Specification).

The GIF writer plug-in supports the creation of animated GIF images through the standard sequence writing methods defined in the ImageWriter class.

A global color table is written to the output stream if one of the following conditions is met:

• stream metadata containing a GlobalColorTable element is supplied;
• a sequence is being written and image metadata containing a LocalColorTable element is supplied for the first image in the sequence;
• image metadata is not supplied or does not contain a LocalColorTable element.

In the first case the global color table in the stream metadata is used, in the second the local color table in the image metadata is used, and in the third a global color table is created from the ColorModel or SampleModel of the (first) image.

A local color table is written to the output stream only if image metadata containing a LocalColorTable element is supplied to the writer, or no image metadata is supplied to the writer and the local color table which would be generated from the image itself is not equal to the global color table.

A Graphic Control Extension block is written to the output stream only if image metadata containing a GraphicControlExtension element is supplied to the writer, or no image metadata is supplied and the local color table generated from the image requires a transparent index. Application, Plain Text, and Comment Extension blocks are written only if they are supplied to the writer via image metadata.

The writing of interlaced images can be controlled by the progressive mode of the provided ImageWriteParam instance. If progressive mode is MODE_DISABLED then a non-interlaced image will be written. If progressive mode is MODE_DEFAULT then an interlaced image will be written. If progressive mode is MODE_COPY_FROM_METADATA, then the metadata setting is used (if it is provided, otherwise an interlaced image will be written).

The GIF image writer plug-in supports setting output stream metadata from metadata supplied to the writer in either the native GIF stream metadata format javax_imageio_gif_stream_1.0 or the standard metadata format javax_imageio_1.0, and setting output image metadata from metadata supplied to the writer in either the native GIF image metadata format javax_imageio_gif_image_1.0 or the standard metadata format javax_imageio_1.0. The mapping of standard metadata format to the GIF native stream and image metadata formats is given in the tables here .

The IIOReadProgressListener interface allows for notification of the percentage of an image that has been read successfully.

The IIOReadUpdateListener interface allows for notification of the portions of an image that have been read. This is useful, for example, for implementing dynamic display of an image as it is loaded.

The IIOReadWarningListener interface allows for notification of non-fatal errors during reading.

The IIOWriteWarningListener and IIOWriteProgressListener interfaces perform analogous functions for writers. @since 1.4

When reading an image, its per-stream and per-image metadata is made available as an IIOMetadata object. The internals of this object are specific to the plug-in that created it. Its contents may be accessed in the form of an XML Document, which is implemented as a tree of IIOMetadataNode objects.

When writing an image, its metadata may be set by defining or modifying an IIOMetadata object. Such an object may be obtained from an ImageWriter or ImageTranscoder (from the javax.imageio package). Once such an object has been obtained, its contents may be set of modified via a Document consisting of IIOMetadataNodes. The document format may optionally be described using an IIOMetadataFormat object.

The format of the metadata contained in the XML Document is identified by a string which appears as the root node of the tree of IIOMetadataNode objects. This string contains a version number, e.g. "javax_imageio_jpeg_image_1.0". Readers and writers may support multiple versions of the same basic format and the Image I/O API has methods that allow specifying which version to use by passing the string to the method/constructor used to obtain an IIOMetadata object. In some cases, a more recent version may not be strictly compatible with a program written expecting an older version (for an example, see the Native Metadata Format section of the JPEG Metadata Usage Notes below).

Plug-ins may choose to support a standard (plug-in neutral) format. This format does not provide lossless encoding of metadata, but allows a portion of the metadata to be accessed in a generic manner.

Each of the standard plug-ins supports a so-called "native" metadata format, which encodes its metadata losslessly:

• GIF metadata
• JPEG metadata
• PNG metadata
• BMP metadata
• WBMP metadata

This package contains some support classes for the built-in JPEG reader and writer plug-ins. Classes are provided for representing quantization and Huffman tables, and extensions of ImageReadParam and ImageWriteParam are provided to supply tables during the reading and writing process. For more information about the operation of the built-in JPEG plug-ins, see the JPEG metadata format specification and usage notes.


@since 1.4

The javax.imageio.spi package contains service provider interfaces for reading, writing, and transcoding images, and obtaining input and output streams, as well as a run-time registry that discovers installed service provider instances and allows new instances to be registered dynamically. @since 1.4

The ImageInputStream interface unifies streaming and file-based operations. An abstract base class, ImageInputStreamImpl is provided to simplify writing a new ImageInputStream class. Concrete implementation classes (FileImageInputStream, FileCacheImageInputStream, and MemoryCacheImageInputStream) are provided that allow input to come from a File or InputStream with or without the use of a temporary cache file.

The ImageOutputStream interface performs an analogous function for output. An abstract base class, ImageOutputStreamImpl is provided, along with concrete implementation classes (FileImageOutputStream, FileCacheImageOutputStream, and MemoryCacheImageOutputStream) are provided that allow output to go to a File or OutputStream with or without the use of a temporary cache file.

The IIOByteBuffer class provides an alternative way to perform reads of sequences of bytes that reduces the amount of internal data copying. @since 1.4