readme-jai.txt

jai-1_1_2.rar

JavaTM Advanced Imaging API v1.1.2 Readme

Contents

   * Introduction
        o Installation and System Requirements
        o Documentation
        o Bugs
   * Overview of JAI Functionality
        o Core Functionality
        o Operators
             + Native Acceleration
        o How to Run the JAI 1.1 version of Remote Imaging
        o How to Run the JAI 1.0.2 version of Remote Imaging
   * What's New
        o Core Classes
        o Operations
        o Network Imaging
        o Widget Package
        o Fixed Bugs
   * Changes From JAI 1.1.2-beta to JAI 1.1.2-RC
        o Bugs Fixed in JAI 1.1.2-RC
        o Enhancements Added in JAI 1.1.2-RC
   * Changes From JAI 1.1.2-RC to JAI 1.1.2
        o Bugs Fixed in JAI 1.1.2
        o Enhancements Added in JAI 1.1.2

   * Feedback

Introduction

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, implements the Maintenance Review version of
the JAI 1.1 specification and also contains bug fixes and performance
enhancements with respect to the most recent implementation of the JAI 1.1
specification Final Release which was called JAI 1.1.1_01. It represents
development pursuant to maintenance of the Java Advanced Imaging 1.1 JSR.

The changes since JAI 1.1.1_01 are described in the "What's New" section of
this document.

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

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 - see the BUGS page for details.

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:

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

        o Image Warping

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

        o Pixel Interpolation

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

        o Color Spaces

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

  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.

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

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

        o GIF file handling:

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

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

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

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

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

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

  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