Java(TM) Advanced Imaging API README 1.1.2_01

   

 

Contents

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 here. There you will find binaries, documentation, answers to frequently asked questions, and other information.

Installation and System Requirements

INSTALLsystem requirements section

Documentation

link

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

Bug ID Synopsis
4990502 JAI FAQ is not current (for browsers)
5044839 JAI installation program does not seem to install on Java 1.5 beta on Win32

Enhancements Added in JAI 1.1.2_01

Bug ID Synopsis
4896805 JAI FAQ should have an item about file locking in FileLoad/FileStore ops
5090980 JAI INSTALL should contain clear instructions on using auto-install in browsers

Unresolved Issues in JAI 1.1.2_01

JAI bugs pageBug Database

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.  

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

    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.

     

    1.  

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

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

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

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

    10. Sourceless Operators

       

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

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

    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:

here

here

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: here

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:

here

here

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.

Left Curve
Java SDKs and Tools
Right Curve
Left Curve
Java Resources
Right Curve
JavaOne Banner
Java 8 banner (182)