JavaTM Advanced Imaging API v1.1.3 Readme

Contents

Introduction

The current release, JAI 1.1.3, is a maintenance release intended primarily to fix a number of bugs. The bugs which were fixed were selected based on the number of votes the respective bug or issue report received, whether the bug or issue was filed by a customer, and the age of the report. Higher precedence was assigned to bugs which received more votes, were filed by customers, or were relatively recent. See "Changes From JAI 1.1.3-beta to JAI 1.1.3" for a listing of the changes in the present release.

The Maintenance Review release of the 1.1 version of the Java TM Advanced Imaging (JAI) specification contains some changes since the JAI 1.1 specification Final Release. The present reference implementation, called Java Advanced Imaging 1.1.3-alpha, implements the Maintenance Review version of the JAI 1.1 specification.

The Java Advanced Imaging API home page is located at http://java.sun.com/products/java-media/jai/. There you will find binaries, documentation, answers to frequently asked questions, and other information.

Java Advanced Imaging was migrated to java.net in February 2005. The java.net project structure and mailing lists are described here.

Installation and System Requirements

For general installation instructions please refer to the INSTALL page. For system requirements please refer to the system requirements section of the INSTALL page.

Documentation

Links to Java Advanced Imaging documentation are available at http://java.sun.com/products/java-media/jai/docs/

Bugs

Some bugs are known to exist. Currently bug reports are filed in two locations:

  1. the Bug Database on java.sun.com; and
  2. the Issue Tracker in the jai-core project on java.net.
The following links will generate a list of open JAI bugs: Note that the java.sun.com bug list includes some bugs which actually belong to JAI Image I/O Tools: these bugs have subcategory codec_imageio; all other subcategories are for bugs in JAI itself.

Changes From JAI 1.1.3-beta to JAI 1.1.3

In addition to resolving the issues and defects listed below, this version also introduces a Java-only download bundle which does not contain the native libraries. Please refer to the installation file for more information.

jai-core member contributions to JAI 1.1.3

Defects Resolved in JAI 1.1.3

java.net Issues Resolved
Issue IDSynopsis
7SubsampleBinaryToGray native-based operation inverts bilevel TIFF image loaded by Image I/O
18Native "AddConst" operation introduces vertical lines on linux-i586
20PlanarImage.getBounds has race condition and deadlocks
21ColorConvertOPImage assumes J2D ColorConvertOp to be reentrant, which [it] is not
39Windows CLASSPATH installer should put code in ./lib sub-folder
40convolve operation with a kernel 9x9, 11x11...
41Black images from SubsampleAverage (native linux)
44after rotate operator getAsBufferedImage increases image's brightness
47Localized JAI operation names are not case-insensitive
48FilteredSubsampleOpImage.computeRect() fails when scaling
49Generic windows registry key
50BandMerge fails for large tiled images in certain circumstances
51Convolve operator crashes in native implementation
54NullOpImage does not cache properly
56RenderedOp.dispose() should propagate to ImageDecoder outputs
59ArrayIndexOutOfBoundsException in ImageUtil.fillBackground
61JAI 1.1.3-beta has Implementation-Version 1.13-alpha in Manifest
62Windows installer for extensions should reinstall, not uninstall

java.sun.com Bugs Resolved
Bug IDSynopsis
4453915Localized JAI operation names are not case-insensitive
4505744SubsampleBinaryToGray gives incorrect results if xScale*yScale < 1.0/256.0
4667086The "invert" operation causes out of bounds exception on large images.
4906854"Affine" operation with bilinear interp. and ImageLayout hint crash medialib
4996204The TIFF codec sometimes throws an IllegalArgumentException
5034146BMPImageDecoder does not correctly read certain BI_BITFIELDS encoded images
6432127Damaged output when rescaling PNG image

Changes From JAI 1.1.3-alpha to JAI 1.1.3-beta

Defects Resolved in JAI 1.1.3-beta

java.net Issues Resolved
Issue IDSynopsis
23Some classes throw an Error where an Exception would be appropriate
24Native SubsampleAverage creates black border
27Overflow in mediaLib scale operation
28SubsampleAverageOpImage.computeRect() fails when scaling GIF
30ColorConvert operation produces output with replicated regions
31Unable to decode PackBits compressed TIFF images
32BoxFilter operation does not have a mediaLib rendered image factory
33composite operation doesn't work with IndexColorModel
34ImageDecoder should work around fields with offset beyond EOF
36"fileload"" operation cannot be used in an application that is packaged as a JAR.
38MemoryCacheSeekableStream.read(byte[]) returns more bytes than available

java.sun.com Bugs Resolved
Bug IDSynopsis
4899296Erosion or dilation on bilevel image fails when kernel height is smaller then the width
4906856Problem with Histogram operator with polygon ROI on tiled images (TIFF files)
4936736Native version of transpose changes the minX of the image when flip horizontal
4944464Convolution using mediaLib returns a blank image
4957501ErrorDiffusion only supports up to 256 colors
4979025mapDestPoint() fails for "Rotate" of 90, 180, 270 degrees
4990552Native exception encountered in "Histogram" operation
5095110Blue hues lost during ColorConvert via IHS
5095479MemoryCacheSeekableStream appends extra bytes to end of data
5096947CMYK TIFF images should be assigned a CMYK ColorModel
5099236Erode and Dilate over Binary Images throws exception
6219398Out of memory issues with JAI
6294596Error in installation ".bin" file of jai 1.1.2
6314990com.sun.media.jai.codecimpl.util.ImagingException: Unable to decode Packbits com
6331419rotating by a small angle a tiled image with nearest neighbor interpolation
6331420SubsampleAverage adding 1 pixel border on right and lower edge.
6331421linux Autoinstall fails if uname -p returns multiple words

Enhancements Added in JAI 1.1.3-beta

java.net Enhancements Added
Issue IDSynopsis
29Make JAI available through webstart from java.net

java.sun.com Enhancements Added
Bug IDSynopsis
4754795WBMP decoder cannot read the attached image
4823200Make TIFF decoder robust to (comp) images with no strip/tile byte counts field
5037226MediaLibAccessor should use ImagingListener from default JAI instead of println
5105823JAI:please create a Java WebStart download page

Changes From JAI 1.1.2_01 to JAI 1.1.3-alpha

Bugs Fixed in JAI 1.1.3-alpha

Issue NumberSummary
4jai-core will not build using JDK 1.5
5Mosaic operation emits incorrect error message for non-conformant alpha bands
6Scale op with Nearest Interpolation results in image with black lines in some cases
10SubsampleAverage throws ArrayIndexOutOfBoundsException
12ColorQuantizer emits property named LUT that should be name JAI.LookupTable
13JPEG Encoder uses extra memory for some untiled source images
14Loading transparent GIF and storing as JPEG results in a corrupt image

Enhancements Added in JAI 1.1.3-alpha

Bug IDSynopsis
11Supply a 64-bit version on all appropriate platforms, e.g., AMD 64

Overview of JAI Functionality

Core Functionality

All areas of the JAI specification have been implemented for this release. The com.sun.media.jai.codec package continues to be an uncommitted part of JAI. For mode information on image reading and writing images on the Java 2 platform and in JAI please refer to the page Image I/O in Java Advanced Imaging.

All operators outlined in the Java Advanced Imaging API specification are implemented.

The major areas of JAI functionality are described below:

  1. Tiling

    Images are made up of tiles. Different images may have different tile sizes. Each tile can be processed and stored in memory separately. Tiles may be stored in a centrally-maintained cache for performance. The use of tiling also facilitates the use of multiple threads for computation. Previously allocated tiles may also be re-used to save memory.

  2. Deferred execution

    Image operations performed on an image do not take place immediately when they are defined. Calculation of pixels happens only when a portion of the resultant image is requested, and only tiles that are needed are processed. However, operations always appear semantically to be completed immediately.

  3. Threaded Computation

    Requests for tiles are given to several running threads, allowing potential speedups on multi-processor systems or when requesting data over the network.

  4. Object-Oriented Extensibility

    Users can add their own image operators or override existing operators by registering the new operators with the operation registry. Please see the "The Java Advanced Imaging API White Paper," the API documentation, the JAI tutorial, the sample code, and the jai-interest archives for more information (in the archives search for subjects beginning with "sample code").

    Additionally, users may extend a number of non-image classes in order to add functionality to JAI:

  5. Graphics2D-Style Drawing

    Graphics2D-style drawing may be performed on a TiledImage in a manner analogous to that available for java.awt.image.BufferedImage.

    The RenderableGraphics class provides a way to store a sequence of drawing commands and to "replay" them at an arbitrary output resolution.

  6. Regions of interest (ROIs)

    Non-rectangular portions of an image may be specified using a ROI or ROIShape object. These ROIs may be used as parameters to the Extrema, Mean, Histogram or Mosaic operations and the TiledImage.set() and TiledImage.setData() methods. Operations produce an appropriate ROI property on their output when one exists on their input.

  7. Image file handling

    This release of Java Advanced Imaging supports BMP, FlashPIX, GIF, JPEG, PNG, PNM, and TIFF images as defined in the TIFF 6.0 specification, and WBMP type 0 B/W uncompressed bitmaps. TIFF G3 (1D and 2D), G4, PackBits, LZW, JPEG, and DEFLATE (Zip) compression types are understood.

    The classes dealing with image file handling (the com.sun.media.jai.codec package and private implementation packages that provide support for it) are provided in a separate jai file, jai_codec.jar. This jar file may be used separately from the jai_core.jar file containing the various javax.media.jai packages and their supporting classes.

    As described in the Core Functionality section of this document, the image codec classes should be considered as temporary helper functions. They will be replaced by a new API for image I/O that has been defined under the Java Community Process.

  8. Image Layouts

    Images with arbitrary pixel layouts may be processed in a uniform manner using the PixelAccessor and RasterAccessor classes.

    Source images with ComponentColorModels and IndexColorModels are supported. DirectColorModel images are not supported.

    PixelAccessor and RasterAccessor provide the most efficient support for the ComponentSampleModel/ComponentColorModel combination.

  9. Image Collections

    The output of a standard image operator on an instance of java.util.Collection is a collection of the same type. Nested collections are supported. Operators may also emit collections of their choice, or take collections as sources and emit a single image.

  10. Remote Imaging

    JAI allows operations to be performed remotely to be created in a manner similar to local operations. RemoteJAI.create() and RemoteJAI.createRenderable() can be used to create operations that are performed on remote hosts. Operation chains are created on the client and can contain a mix of local and remote operations by using JAI.create() and RemoteJAI.create(), respectively to create the operations.

    The "fileload" and "filestore" operations can allow files that reside only on remote filesystems to be loaded and stored remotely. This can be accomplished by setting the checkFileLocally argument to the operation to be false, in which case the presence of the file to be loaded or stored is not checked on the local file system when the operation is first created.

    See sections below for instructions on how to use the JAI 1.0.2 and 1.1 or later versions of remote imaging.

  11. Iterators

    Optimized Rect and Random iterators exist as well as a non-optimized version of the Rook iterator.

  12. Snapshotting of External Sources

    SnapshotImage provides an arbitrary number of synchronous views of a possibly changing WritableRenderedImage.

  13. Meta-data Handling

    Meta-data handling is provided via a name-value database of properties associated with each JAI image. Mechanisms are provided by which such properties may be generated and processed in the course of image manipulation. The ability to defer computation of such data is also provided in a manner conceptually equivalent to that available for image data. Please refer to the DeferredData and DeferredProperty classes for more information.

  14. Serialization Support

    SerializerFactory provides a framework is provided to assist in serializing instances of classes which do not implement java.io.Serializable. Such objects must be serialized by extracting a serializable version of their state from which the original object may be extracted after deserialization.

Operators

Java Advanced Imaging extends the imaging functionality provided in the Java 2D API by providing a more flexible and scalable architecture targeted for complex, high performance imaging requirements. In this context a large number of imaging operators are provided.

How to Run the JAI 1.1 (and later) version of Remote Imaging

1. Create a Security Policy File

If $JAI is the base directory where Java Advanced Imaging is installed, create a text file named $JAI/policy containing the following: 

  grant {
    // Allow everything for now
    permission java.security.AllPermission;
  };
Note that this policy file is for testing purposes only, and it is not recommended that full permission be given to all programs.

For more information on policy files and permissions please see:

http://java.sun.com/products/j2se/1.5.0/docs/guide/security/PolicyFiles.html

http://java.sun.com/products/j2se/1.5.0/docs/guide/security/permissions.html

2. Start the RMI Registry

Log in to the remote machine where the image server will be running and start the RMI registry. For example, in the Solaris operating environment using a Bourne-compatible shell (e.g., /bin/sh): 

  $ unset CLASSPATH
  $ rmiregistry &
Note that the CLASSPATH environment variable is deliberately not set.

3. Start the JAI Remote Image Server

While still logged in to the remote server machine, set the CLASSPATH and LD_LIBRARY_PATH environment variables as required for JAI (see the INSTALL file) and start the remote imaging server: 

  $ CLASSPATH=$JAI/lib/jai_core.jar:$JAI/lib/jai_codec.jar:\
              $JAI/lib/mlibwrapper_jai.jar
  $ export CLASSPATH
  $ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAI/lib
  $ export LD_LIBRARY_PATH
  $ java \
  -Djava.rmi.server.codebase=\
  "file:$JAI/lib/jai_core.jar file:$JAI/lib/jai_codec.jar" \
  -Djava.rmi.server.useCodebaseOnly=false \
  -Djava.security.policy=file:$JAI/policy \
  com.sun.media.jai.rmi.JAIRMIImageServer

For example, when the above steps are executed on a machine with IP address 123.456.78.90 the following is printed: 

  Server: using host 123.456.78.90 port 1099
  Registering image server as "rmi://123.456.78.90:1099/JAIRMIRemoteServer1.1".
  Server: Bound RemoteImageServer into the registry.
4. Run the Local Application

Run the local application making sure that the serverName parameter of any javax.media.jai.remote.RemoteJAI constructors corresponds to the machine on which the remote image server is running. For example, if the machine with IP address 123.456.78.90 above is named myserver the serverName parameter of any RemoteJAI constructors should be "myserver".

How to Run the JAI 1.0.2 version of Remote Imaging

For more information on RMI (remote method invocation) please refer to: http://java.sun.com/products/jdk/rmi/index.html

1. Create a Security Policy File

If $JAI is the base directory where Java Advanced Imaging is installed, create a text file named $JAI/policy containing the following: 

grant {
  // Allow everything for now
  permission java.security.AllPermission;
};
Note that this policy file is for testing purposes only.

For more information on policy files and permissions please see:

http://java.sun.com/products/jdk/1.2/docs/guide/security/PolicyFiles.html

http://java.sun.com/products/jdk/1.2/docs/guide/security/permissions.html

2. Start the RMI Registry

Log in to the remote machine where the image server will be running and start the RMI registry. For example, in the Solaris operating environment using a Bourne-compatible shell (e.g., /bin/sh): 

$ unset CLASSPATH
$ rmiregistry &
Note that the CLASSPATH environment variable is deliberately not set.

3. Start the JAI Remote Image Server

While still logged in to the remote server machine, set the CLASSPATH and LD_LIBRARY_PATH environment variables as required for JAI (see the INSTALL file) and start the remote imaging server: 

$ CLASSPATH=$JAI/lib/jai_core.jar:$JAI/lib/jai_codec.jar:\
            $JAI/lib/mlibwrapper_jai.jar
$ export CLASSPATH
$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAI/lib
$ export LD_LIBRARY_PATH
$ java \
-Djava.rmi.server.codebase=\
"file:$JAI/lib/jai_core.jar file:$JAI/lib/jai_codec.jar" \
-Djava.rmi.server.useCodebaseOnly=false \
-Djava.security.policy=file:$JAI/policy \
com.sun.media.jai.rmi.RMIImageImpl

For example, when the above steps are executed on a machine with IP address 123.456.78.90 the following is printed: 

Server: using host 123.456.78.90 port 1099
Registering image server as
  "rmi://123.456.78.90:1099/RemoteImageServer".
Server: Bound RemoteImageServer into
   the registry.
4. Run the Local Application

Run the local application making sure that the serverName parameter of any RemoteImage constructors corresponds to the machine on which the remote image server is running. For example, if the machine with IP address 123.456.78.90 above is named myserver the serverName parameter of any RemoteImage() constructors should be "myserver".

Copyright 2005 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 2005 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.