Java(TM) Advanced Imaging API README 1.1.2_01

Contents

• Introduction
• • Installation and System Requirements
  • Documentation
  • Bugs
• Changes From JAI 1.1.2 to JAI 1.1.2_01
• • Bugs Fixed in JAI 1.1.2_01
  • Enhancements Added in JAI 1.1.2_01
  • Unresolved Issues in JAI 1.1.2_01
• Overview of JAI Functionality
• • Core Functionality
  • Operators
  • • Native Acceleration
  • How to Run the JAI 1.1 (and later) version of Remote Imaging
  • How to Run the JAI 1.0.2 version of Remote Imaging

• Feedback

Introduction

The current release, JAI 1.1.2_01, is a patch release intended primarily to fix a problem in the Windows installers which was observed with pre-FCS versions of the J2SE 1.5 platform. See " Changes From JAI 1.1.2 to JAI 1.1.2_01" for a listing of the changes in the present patch 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.2_01, 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.

Installation and System Requirements

Documentation

Bugs

Some bugs are known to exist - see the BUGS page for details.

Changes From JAI 1.1.2 to JAI 1.1.2_01

Bugs Fixed in JAI 1.1.2_01

Enhancements Added in JAI 1.1.2_01

Unresolved Issues in JAI 1.1.2_01

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:

2. 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.

3. 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.

4. 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.

5. 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:

   • Border Extension
     
     Operators may obtain an extended view of their sources using an extensible mechanism for generating pixel values outside of the source image bounds. New subclasses of BorderExtender may be used to obtain customized functionality.

   • Image Warping
     
     Subclasses of Warp may be written to perform customized image warping.

   • Pixel Interpolation
     
     Subclasses of Interpolation may be written to perform customized pixel interpolation.

   • Color Spaces
     
     Subclasses of ColorSpaceJAI may be written to implement mathematically defined color space transformations without the need for ICC profiles.

6. 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.

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

8. 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.

   • BMP File Handling:
     

     The BMP reader can read Version 2.x, 3.x and some 4.x BMP images. BMP images with 1, 4, 8, 24 bits can be read with this reader. Support for 16 and 32 bit images has also been implemented, although such images are not very common.

     Reading of compressed BMPs is supported. BI_RGB, BI_RLE8, BI_RLE4 and BI_BITFIELDS compressions are handled.

     The BMP reader emits properties such as type of compression, bits per pixel etc. Use the getPropertyNames() method to get the names of all the properties emitted.

     BMP Limitations:

     • Only the default RGB color space is supported.
     • Alpha channels are not supported.

     BMP Writer:

     • The BMP writer is capable of writing images in the Version 3 format. Images which make use of a IndexColorModel with 2, 16, or 256 palette entries will be written in palette form.
     • RLE4 and RLE8 compression is supported when compatible with the image data.

   • FlashPIX file handling:
     
     A limited FlashPIX reader is provided that is capable of extracting a single resolution from a FlashPIX image file. Only simple FlashPix files are decoded properly.

     The image view object is ignored, and image property information is not exported.

     There is no FlashPIX writer.

   • GIF file handling:
     

     There is no GIF writer due to the patent on the LZW compression algorithm.

   • JPEG file handling:
     

     • JPEG files are read and written using the classes found in the com.sun.image.codec.jpeg package of the JDK. A set of simple JAI wrapper classes around these classes is provided.
     • The JPEG decoder cannot read abbreviated streams, either tables-only or image-only.

   • PNG file handling:
     
     All files in the PNGSuite test suite have been read and written successfully. See the documentation in com.sun.media.jai.codec.PNGDecodeParam and PNGEncodeParam for more information.

   • PNM file handling:
     
     PNM files may be read and written in both ASCII and raw formats. The encoder automatically selects between PBM (bitmap), PGM (grayscale) and PPM (RGB) files according to the number of bands and bit depth of the source image.

     Due to the limitations of the format, only images with 1 or 3 bands may be written.

   • TIFF file handling:
     

     TIFF support has the following limitations:

     • The TIFF encoder does not support LZW compression due to the patent on the algorithm.
     • Planar format (PlanarConfiguration field has value 2) is not supported for decoding or encoding.

   • WBMP file handling:
     
     The WBMP codec reads and writes images in the Wireless Bitmap format described in chapter 6 and Appendix A of the Wireless Application Protocol (WAP) Wireless Application Environment Specification, Version 1.3, 29 March 2000. The WBMP type supported is WBMP Type 0: B/W, Uncompressed Bitmap. There are no limitations on the image dimensions.

9. 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.

10. 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.

11. 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.

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

13. Snapshotting of External Sources
    
    SnapshotImage provides an arbitrary number of synchronous views of a possibly changing WritableRenderedImage.

14. 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.

15. 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.

• Native Acceleration

  Pure Java implementations are provided for all image operators and imaging performance is addressed for some of these by providing C-based native code. Native C-code based acceleration for a certain subset of operators under specific conditions (listed in the table below) is available for the Sun/Solaris, Win32 and Linux (x86 only) platforms. On Sun UltraSPARC-based platforms, additional performance is gained with hardware acceleration via the VIS instructions for most natively supported operators. On Win32 platforms which support MMX instructions, hardware acceleration is gained for a subset of the natively supported operators.

  If a native implementation is present it is, by default, the preferred implementation. But if the nature of the sources and parameters of the operation are incompatible with the native operation then processing will revert to Java code. In general the following minimum requirements must be adhered to for the mediaLib native implementation of an operation to be executed:

  • All sources must be RenderedImages.
  • All sources and destination must have
    • a SampleModel which is a ComponentSampleModel and
    • a ColorModel which is a ComponentColorModel or no ColorModel (i.e., it is null).
  • All sources and the destination must have at most 4 bands of pixel data.
  • If Interpolation type is one of the arguments to the operator, then native acceleration is available only for Nearest, Bilinear, Bicubic and Bicubic2 cases. Additionally for byte images InterpolationTable is also supported for native acceleration.

  Further restrictions may be imposed by individual operations but the above are the most common requirements.

• Imaging Operators

  The following image operators are implemented in this release. Only a brief description of each operator is provided here. For detailed information on these operators, refer to the package javax.media.jai.operator in the full documentation available at http://java.sun.com/products/java-media/jai/docs/index.html.

  All operations are performed on a per-band basis, unless specified otherwise. C acceleration applies to all platforms whereas VIS is specific to Sun UltraSPARC and MMX to Windows.

  2. Point and Arithmetic Operators

     Operator Name	Description	Native Acceleration
     		C	VIS	MMX	Notes
     absolute	Computes the absolute value of the pixels of an image.	X	X	X
     add	Adds the pixel values of two source images.	X	X	X
     addcollection	Adds a collection of images to one another.
     addconst	Adds a set of constant values to the pixel values of a source image.	X	X	X
     addconsttocollection	Adds a set of constant values to the pixel values of a Collection of source images.	X	X	X
     and	And's the pixel values of two source images.	X	X	X
     andconst	And's the pixel values of a source image with a set of constants.	X	X	X
     bandcombine	Computes a linear combination of the bands of an image.	X	X	X	3x4 matrix only.
     bandmerge	Creates an image consisting of all bands of all sources concatenated in the order encountered.
     bandselect	Selects a subset of the bands of an image, possibly reordering them.	X	X	X	Only if the band selection is monotonically increasing.
     binarize	Thresholds a single-band image to two levels to generate a bilevel output.	X	X
     clamp	Set all pixel values below the low value to that low value, set all the pixel values above the high value to that high value.	X	X	X
     colorconvert	Converts an image to a given ColorSpace.
     colorquantizer	Generates an optimal LUT by executing a color quantization algorithm
     composite	Combines two images based on their alpha values at each pixel.	X	X	X
     constant	Creates an image with constant pixel values.
     divide	Divides the pixel values of the first source image by the pixel values of the second source image.	X
     dividebyconst	Divides the pixel values of a source image by a set of constants.	X
     divideintoconst	Divides a set of constants by the pixel values of a source image.	X
     exp	Computes the exponential of the pixel values of an image.	X
     format	Performs reformatting on an image, including data type casting, replacing the SampleModel and ColorModel, and restructuring the tile grid.
     invert	Inverts the pixel values of an image.	X	X	X
     log	Computes the natural logarithm of the pixel values of an image.	X
     lookup	Performs general table lookup on an image.	X	X	X	Only if table has less than or equal to 4 bands.
     matchcdf	Performs a piecewise linear remapping of pixel values to match a given cumulative distribution function.
     max	Chooses the maximum pixel values between two images.	X	X	X
     min	Chooses the minimum pixel values between two images.	X	X	X
     multiply	Multiplies the pixel values of two source images.	X	X
     multiplyconst	Multiplies the pixel values of a source image by a set of constants.	X	X
     not	Inverts the pixel values of a source image.	X	X	X
     or	Or's the pixel values of two source images.	X	X	X
     orconst	Or's the pixel values of a source image with a set of constants.	X	X	X
     overlay	Overlays one image on top of another image.
     piecewise	Performs piecewise linear remapping of the pixel values of an image.
     rescale	Performs a linear remapping of the pixel values of an image.	X	X
     subtract	Subtracts the pixel values of one image from those of another.	X	X	X
     subtractconst	Subtracts a set of constant values from the pixel values of an image.	X	X	X
     subtractfromconst	Subtracts a set of constant values from the pixel values of an image.	X	X	X
     threshold	Maps the pixel values that fall between a low and high value to a set of constants.	X	X	X
     xor	Xor's the pixel values of two source images.	X	X	X
     xorconst	Xor's a source image with a set of constants.	X	X	X

  4. Area and Geometric Operators

     Operator Name	Description	Native Acceleration
     		C	VIS	MMX	Notes
     affine	Performs first order geometric image warping.	X	X	X	InterpolationTable is not MMX accelerated for even byte images.
     border	Adds a border around an image.
     boxfilter	Convolves an image using a two-dimensional box filter.
     convolve	Performs an MxN image convolution.	X	X	X	General and separable cases.
     crop	Extracts a subarea of an image.
     dilate	Performs morphological dilation on an image.	X	X	X	Only single band, 3x3 kernels centered at 1,1
     erode	Performs morphological erosion on an image.	X	X	X	Only single band, 3x3 kernels centered at 1,1
     filteredsubsample	Performs a combined integral subsample and symmetric product-separable filter.	X	X	X
     gradientmagnitude	Performs edge detection using orthogonal gradient masks.	X	X	X
     maxfilter	Computes the maximum value of a pixel neighborhood.	X	X	X	Only single band; only for a SQUARE mask of size 3, 5, or 7
     medianfilter	Computes the median value of a pixel neighborhood.	X	X	X
     minfilter	Computes the minimum value of a pixel neighborhood.	X	X	X	Only single band; only for a SQUARE mask of size 3, 5, or 7
     mosaic	Creates a mosaic of two or more rendered images.	X	X	X
     rotate	Rotates an image about an arbitrary point.	X	X	X	InterpolationTable is not MMX accelerated for even byte images.
     scale	Scales and translates an image.	X	X	X	InterpolationTable is not MMX accelerated for even byte images.
     shear	Shears an image.	X	X	X	InterpolationTable is not MMX accelerated for even byte images.
     subsampleaverage	Subsamples an image by averaging over a moving window.	X	X
     subsamplebinarytogray	Subsamples a bilevel image to a grayscale image.	X	X
     translate	Translates an image by an integral or fractional amount.	X	X	X	InterpolationTable is not MMX accelerated for even byte images.
     transpose	Reflects an image in a specified direction or rotates an image in multiples of 90 degrees.	X	X	X
     unsharpmask	Sharpens an image by suppressing the low frequencies.	X	X	X	General and separable kernels.
     warp	Performs geometric warping on an image.	X	X	X	polynomial and grid only.

  6. Frequency-domain, Transform, and Complex Operators

     Operator Name	Description	Native Acceleration
     		C	VIS	MMX	Notes
     conjugate	Computes the complex conjugate of an image.
     dct	Computes the Discrete Cosine Transform of an image.	X
     dft	Computes the Discrete Fourier Transform of an image, possibly resulting in a complex image.	X
     dividecomplex	Computes the quotient of two complex images.
     idct	Computes the inverse Discrete Cosine Transform of an image.	X
     idft	Computes the inverse Discrete Fourier Transform of an image.	X
     magnitude	Computes the magnitude of a complex image.
     magnitudesquared	Computes the squared magnitude of a complex image.
     multiplycomplex	Computes the product of two complex images.
     periodicshift	Shifts an image periodically.
     phase	Computes the phase angle of a complex image.
     polartocomplex	Creates a complex image from two images representing magnitude and phase.

  8. Statistical Operators

     Operator Name	Description	Native Acceleration
     		C	VIS	MMX	Notes
     extrema	Computes the maximum and minimum pixel values of an image.	X	X	X		Only if the ROI is null or encloses the entire image.
     histogram	Computes the histogram of an image.	X	X	X
     mean	Computes the mean pixel value of a region of an image.	X	X	X		Only if the ROI is null or encloses the entire image and the sampling period is 1.

  10. Sourceless Operators

      Operator Name	Description
      imagefunction	Creates an image by evaluating a function.
      pattern	Creates an image consisting of a repeated pattern.

  12. File and Stream Operators

      Operator Name	Description
      awtimage	Converts a java.awt.Image into a PlanarImage.
      bmp	Loads an image in BMP format.
      encode	Writes an image to an OutputStream.
      fileload	Loads an image from a file.
      filestore	Writes an image to a file in a given format.
      fpx	Loads an image in FlashPIX format.
      gif	Loads an image in GIF format.
      iip	Reads an image from a remote IIP server, performing IIP view transforms (affine, colortwist, filter, crop).
      iipresolution	Reads a single resolution of an image from a remote IIP server.
      jpeg	Loads an image in JPEG format.
      png	Loads an image in PNG 1.0 or 1.1 format.
      pnm	Loads an image in PBM, PGM, or PPM format.
      stream	Loads an image from a stream.
      tiff	Loads an image in TIFF 6.0 format.
      url	Loads an image from a URL.

  14. Other Operators

      Operator Name	Description
      errordiffusion	Performs error diffusion color quantization using a specified color map and error filter.
      null	Performs no processing. Useful as a placeholder in an operation chain or as a node which emits meta-data.
      ordereddither	Performs color quantization using a specified color map and a fixed dither mask.
      renderable	Constructs a RenderableImage from a RenderedImage source.

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;
  };

For more information on policy files and permissions please see:

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

http://java.sun.com/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 &

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.

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;
};

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 &

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.

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 2004 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 2004 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.