# JavaTM Advanced Imaging Image I/O Tools 1.0 Notes

# Introduction

JAI Image I/O Tools provides reader, writer, and stream plug-ins for the JavaTM Image I/O Framework and Image I/O-based read and write operations for JavaTM Advanced Imaging. Reader-writer plug-ins are supplied for the BMP, JPEG, JPEG 2000, PNG, PNM, Raw, TIFF, and WBMP image formats. The supplied streams and associated service providers use the New I/O APIs. Please refer to the JAI Image I/O Tools API documentation for more information.

## Limitations

Some reader/writer plug-ins have known limitations which are described in this section.

### BMP

Can decode bmp images with version 3-5. Can encode only version 3 images.

### JPEG

- Cannot decode progressive JPEG images: the J2SE core JPEG reader plug-in should be used to read progressive JPEG images.
- Reading some JPEG-LS images may cause exceptions on Linux.
- Neither the reader not writer plug-in supports metadata: the J2SE core JPEG plug-ins should be used for this purpose.

### JPEG 2000

Supports bilevel images, multi-band images with a type of byte/ushort/short (including gray-scale, RGB, RGBA, and GA images), and color-indexed image with 256 colors.

### PNG

Neither the reader not writer plug-in supports metadata: the J2SE core PNG plug-ins should be used for this purpose.

### PNM

Supports bilevel, color-indexed (writer only), grayscale, and RGB images.

### Raw

Supports any data defined by `ComponentSampleModel`, `SinglePixelPackedSampleModel` and bilevel `MultiPixelPackedSampleModel`.

### TIFF

- The reader plug-in does not support old-style (TIFF 6.0) JPEG compression.
- The writer plug-in does not support LZW compression or old-style (TIFF 6.0) JPEG compression.

# Changes from 1.0-beta to 1.0-rc

This section describes changes which have been to JAI Image I/O Tools since the release of version 1.0-beta.

## Enhancements

### Generic

Added upper case format name strings to all reader and writer plug-in service provider interfaces (SPIs).

### Streams

Added `SegmentedImageInputStream` class and supporting class `StreamSegment` and interface `StreamSegmentMapper`.

### JPEG

- The documentation of lossless JPEG (ISO 10918-1) was clarified.
- Support for JPEG-LS (ISO 14495-1) was added.

### JPEG 2000

- Added ability to read pure code stream data.
- Added ability to write pure code stream data (Java implementation of plug-in only).
  For this purpose the methods `setWriteCodeStreamOnly()` and `getWriteCodeStreamOnly()` were added to `J2KImageWriteParam`.

### TIFF

- Added native acceleration for CCITT encoding and decoding of bilevel images.
- Added ability to write 32-bit integral and floating point data.
- Added pixel replacement capability to writer plug-in.
- Changed compression type names "CCITT Group 3" to "CCITT RLE" and "New JPEG" to "JPEG".

## Fixes

### BMP

Fixed bug which cause the red and blue channels to be interchanged in the image written by the writer plug-in.

### JPEG

Fixed problem with native library crashing on Linux for 12-bit lossy JPEG.

### JPEG 2000

Fixed bug which caused a `NullPointerException` in the reader plug-in when the `ImageReadParam` was `null`.

### PNG

- Fixed `ClassCastException` bug in the writer plug-in.
- Fixed erroneous compression level setting in the writer.
- Fixed problem with native library crashing on Linux during reading.

### Raw

- Fixed bug which prevented the reader plug-in from reading raw unsigned short (USHORT) images with non-zero band offset.
- Fixed bug which caused reader plug-in to create images with incorrect tile dimensions.

### TIFF

- Fixed bug which prevented image returned by `readAsRenderedImage()` from being subsampled.
- Fixed reader bug which incorrectly loaded bilevel imagery with LSB-to-MSB fill order.

# Changes from 1.0-rc to 1.0

This section describes changes which have been to JAI Image I/O Tools since the release of version 1.0-rc.

## Enhancements

### Generic

- Changed the BMP, JPEG 2000, and PNM plug-ins to use the node value in the metadata tree as well as the user object. Formerly only the user object had been used.
- Modified README (this file) to mention correct handling of mediaLib jar file in the JRE installation section.
- Enhanced writer plug-in verification that the image passed to `write()` can actually be written so as to avoid subsequent unexpected exceptions.

### BMP

- Added a constructor which accepts a `Locale` parameter.
- Fixed bug in writer plug-in which caused an `IndexOutOfBoundException` when writing `BufferedImage`s of type `TYPE_3BYTE_BGR`.
- Fixed bug in reader plug-in which caused an `ArithmeticException` when reading a BMP image with a zero-length palette.
- Fixed bug in reader plug-in which caused an `ArrayIndexOutOfBoundsException` when reading the image `g04rle.bmp` in the BMP test suite.
- Fixed problem in reader plug-in which caused a `NullPointerException` when retrieving standard image metadata "javax_imageio_1.0".
- Fixed bug in writer plug-in which caused an incorrect output to be produced when source subsampling was requested via an `ImageWriteParam`.
- Added support for writing images using the `BI_PNG` and `BI_JPEG` compression types.
- Fixed problems encountered writing images using the `BI_BITFIELDS` compression type. Supported image data for this compression type now includes 555 for 16-bit data and 888 for 32-bit data.

### JPEG

- Modified the JPEG reader plug-in service provider interface to return `false` from its `canDecodeInput()` method for progressive JPEG images. If the JPEG reader is not obtained on the basis of the supplied input source it will throw an exception if supplied with a progressive JPEG image.
- Fixed customer-reported problems with the lossless JPEG implementation for 8-bit images.
- Fixed bugs encountered reading lossless JPEG images with bit depths 12 or greater.
- Fixed bugs encountered reading JPEG-LS images with bit depths 12 or greater.
- Further clarified bit depths supported in package overview javadoc.
- Enhanced reader and writer plug-ins to retrieve and set the bit depth and in particular to set the `ColorModel` component sizes on reading to the correct value(s).

### JPEG 2000

- Separated the native and Java implementations of both the reader and writer plug-ins into separate plug-ins for both reading and writing, i.e., there are now four plug-ins with a native reader and writer and a Java reader and writer.
- Fixed reader plug-in problem which caused `StackException`s when reading constant-valued images.
- Fixed reader plug-in so as not to throw a `NullPointerException` when `ChannelDefinitionBox` is not defined in the code stream.
- To the native implementation added code stream-only writing capability.
- Fixed problem in the native implementation which caused different progression type settings to produce identical files.

### PNM

- Fixed problem in reader plug-in which caused an `IllegalStateException` when retrieving standard image metadata "javax_imageio_1.0".

### Raw

- Enhanced reader plug-in to better handle data sources which do not have an intrinsic or "natural" color space representation. The constructor which accepts a `SampleModel` in lieu of an `ImageTypeSpecifier` was added for this purpose.

### TIFF

- Fixed some problems with the pluggable compression architecture which were reported with respect to a pluggable LZW compressor.

  These changes were made to `TIFFCompressor`:

  - Added fields `compressionTagValue`, `compressionType`, and `isCompressionLossless`.
  - Added accessor methods for the new fields.
  - Added a constructor which allows setting the values of the new fields.

  `TIFFImageWriteParam` was modified such that its `setTIFFCompressor()` method affects which compression types are available. Please refer to the documentation of that method for details on using a pluggable compressor.

  The foregoing changes allow a compressor to be plugged in either to support unknown compression types or to override the compressor supplied for known compression types.

- Added `GeoTIFFTagSet` for GeoTIFF tags and included this in the sets used to initialize `TIFFImageReadParam`.
- Added erroneously omitted support in reader plug-in for `DEFLATE` compression type.
- Fixed reader plug-in problems encountered in reading signed short integer (16-bit) images.
- Fixed reader plug-in bugs encountered reading 32-bit integer and floating point images.
- Fixed native CCITT decoder problems with CCITT T.4 2D-mode and EOL-padding options.
- Fixed error which prevented emission of standard image metadata "javax_imageio_1.0".
- Modified reader plug-in to throw an `IIOException` instead of other exceptions such as `RuntimeException` and `NullPointerException` which were observed for some TIFF test images.
- Fixed bugs which prevented LSB-to-MSB fill order (`FillOrder` tag value `2`) from being written correctly.
- Significantly improved performance of both reading and writing.
- Added support for reading old-style JPEG compressed data for the baseline sequential process.
- Corrected JPEG compressed output to set tile sizes to 8*MCU as specified in TIFF Technical Note #2.
- Corrected missing and erroneous tags and associated values in `BaselineTIFFTagSet` and `FaxTIFFTagSet`.
- Added `getTagNumbers()` and `getTagNames()` to `TIFFTagSet`.
- Added ability to set `DEFLATE` and JPEG compression levels using `setCompressionQuality()`. The `DEFLATE` level is `8*getCompressionQuality()+1`. The JPEG quality is `100*getCompressionQuality()`.
- Fixed bug which caused an `ArrayIndexOutOfBoundsException` to be thrown by the Java implementation of the T.6 decompressor for certain images.
- Added code to handle horizontal differencing predictors in LZW decompression.
- Improved javadoc and package documentation for TIFF.

### WBMP

- Fixed bug which caused cropped images (generated by the JavaTM Advanced Imaging "Crop" operation) to be written incorrectly.

# Installation

JavaTM Advanced Imaging Image I/O Tools is provided as a bundle containing jar files and native libraries. No installation script is provided so the user must manually place the jar files and native libraries in the appropriate locations and set executable and library search paths as needed.

## System Requirements

### Platform Requirements

The platform requirements for JAI Image I/O Tools are as follows:

JAI Image I/O Tools Bundles
Platform | Requirement
--- | ---
All | JavaTM 2 platform, v1.4.0 or later
Solaris | Solaris operating environment 2.6 or later
Linux | Red Hat 6.2 or subsequent compatible version
Windows | Windows 95, 98, ME, NT 4.0, 2000 or XP

### JavaTM Advanced Imaging

JavaTM Advanced Imaging is not required for the image streams and reader-writer plug-ins to be used. It is of course required if the "ImageRead" and "ImageWrite" operations are to be used. In this case the minimum version is JAI 1.1.1_01.

### Native Libraries

If use of native code is disallowed then the JPEG and PNG reader-writer plug-ins will not be available nor will the native implementation of the JPEG 2000 reader-writer plug-in; the JavaTM implementation of the JPEG 2000 plug-in will however be available. The respective plug-ins will detect that native libraries cannot be used and respond accordingly.

## Download Bundles

The bundles supplied for the various platforms are as follows:

JAI Image I/O Tools Bundles
Platform | Bundle Name
--- | ---
Solaris-SPARC | jai_imageio-1_0-lib-solaris-sparc.tar.gz
Solaris-x86 | jai_imageio-1_0-lib-solaris-i586.tar.gz
Linux | jai_imageio-1_0-lib-linux-i586.tar.gz
Windows | jai_imageio-1_0-lib-windows-i586.zip

A separate bundle containing the JavaTM Advanced Imaging Image I/O Tools API Documentation is also available.

## Common Bundle Contents

The following files are contained in the bundles for all platforms:

JAI Image I/O Tools Common Files
File | Contents
--- | ---
COPYRIGHT-jai_imageio.txt | Copyright notice
LICENSE-jai_imageio.txt | License agreement
README-jai_imageio.html | Release information and installation instructions (this file)
jai_imageio.jar | JAI Image I/O Tools classes
clibwrapper_jiio.jar | codecLib wrapper classes
mlibwrapper_jai.jar | mediaLib wrapper classes

The remaining contents of each bundle aside from the foregoing jar files and this installation notes file consists of native code.

## Native Bundle Contents

### Solaris-SPARC

The bundle contains the following native libraries in the directory structure shown:

        libclib_jiio.so
        cpu/sparcv9+vis/sparcv9/libclib_jiio.so
        cpu/sparcv9+vis/libclib_jiio.so
        cpu/sparcv9+vis2/libclib_jiio.so
        cpu/sparcv9+vis2/sparcv9/libclib_jiio.so
        sparcv9/libclib_jiio.so

### Solaris-x86 and Linux

The bundle contains the single native library `libclib_jiio.so`.

### Windows

The bundle contains the single native library `clib_jiio.dll`.

## Installation

The installation procedure depends on whether the location is within a JRE or at an arbitrary location.

### Installation at an Arbitrary Location

#### All Platforms

All jar files must be added to the CLASSPATH environment variable. If JavaTM Advanced Imaging 1.1.1_01 or higher is installed then `mlibwrapper_jai.jar` must not be added to the CLASSPATH as it is a sealed jar file and will be obtained from the JAI CLASSPATH installation.

#### Unix Platforms

The directory containing the native library or library hierarchy should be added to the LD_LIBRARY_PATH environment variable. For the Solaris-SPARC platform it is imperative that the correct native library directory structure be maintained.

#### Windows

The directory containing the native library should be added to the PATH environment variable.

### Installation in a JRE

The package may be installed in a JRE or in a JRE within a JDK.

#### All Platforms

If JavaTM Advanced Imaging 1.1.1_01 or higher is installed then `mlibwrapper_jai.jar` must not be placed in the JRE as described below because it is a sealed jar file and will be obtained from the JAI JDK/JRE installation.

#### Unix Platforms

All jar files must be placed in `jre/lib/ext`. The native library or library hierarchy must be placed in `jre/lib/sparc` on Solaris-SPARC or `jre/lib/i386` on Solaris-x86 or Linux. Again, for the Solaris-SPARC platform it is imperative that the correct native library directory structure be maintained.

#### Windows

The jar file must be placed in `jre\lib\ext` and the native library in `jre\bin`.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Portions may be derived from Berkeley BSD systems, licensed from U. of CA. Sun, Sun Microsystems, the Sun logo, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Federal Acquisitions: Commercial Software - Government Users Subject to Standard License Terms and Conditions.

Copyright 2002 Sun Microsystems, Inc. Tous droits réservés. Distribué par des licences qui en restreignent l'utilisation. Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun. Des parties de ce produit pourront être dérivées des systèmes Berkeley BSD licenciés par l'Université de Californie. Sun, Sun Microsystems, le logo Sun, Java, et Solaris sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays.

Last modified: Tue Jul 8 14:47:33 PDT 2003