Java Advanced Imaging API v1.0.2Readme

Introduction

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 freqeuently asked questions, and other information.

Two small API additions were made to the unofficial classes in the com.sun.media.jai.codec package.

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

System Requirements

Core Functionality

Sun has submitted a JSR (Java Specification Request) for image I/O and will be developing a specification and a reference implementation under the Java Community Process. The results of this process will replace the temporary I/O helper classes shipped as part of this release in the com.sun.media.jai.codec package. The JSR may be found at http://java.sun.com/aboutJava/communityprocess/jsr/jsr_015_iio.html.

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

Some known bugs exist - see the BUGS file for details.

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.

2. Deferred execution
   
   Image operations performed on an image do not take place immediately when they are applied. 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 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 tuorial, and the sample code for more information.

   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.

5. Graphics2D-Style Drawing
   
   The TiledImageGraphics class provides the drawing functionality of the Graphics2D class for images that are instances of the TiledImage class. 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 or Histogram operations and the TiledImage.set and TiledImage.setData methods. Operations produce an appropriate ROI property on their output when one exists on their input.

   Due to a bug in the FCS version of Java 1.2 (Java 2), initialization of a ROIShape from an Area is not performed correctly. This prevents methods such as add(), subtract(), intersect(), and exclusiveOr() from functioning correctly.

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. TIFF G3, G4, PackBits and LZW 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) have been separated into a new jar file, jai_codec.jar. This jar file may be used separately from the jai_core.jar file containing the javax.media.jai, javax.media.jai.iterator, javax.media.jai.operator, and javax.media.jai.widget packages as well as their supporting packages.

   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 is to be 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. Compression is not supported.

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

     GIF files are read using the JDK's internal reader. There is no GIF writer. Due to a bug in the AWT GIF decoder, GIFs with a transparent background will be decoded as if their background were black.

     GIF files may not be read remotely, i.e., via RemoteImage, on hosts without window system access as the reader uses the AWT toolkit which requires window system access.

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

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

     • Compressed formats may not be written.
     • RGB images which have extra components can be read in and manipulated but no display support has been provided for these yet. In addition it is expected that each band has a depth of 8 bits.

8. Image Layouts
   
   Images with arbitrary pixel layouts may be processed in a uniform manner using the RasterAccessor class.

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

   Source images with SampleModel types other than ComponentSampleModel have not been extensively tested. ComponentSampleModel/ComponentColorModel sources are processed most efficiently by RasterAccessor.

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
    
    Image operator chains may be evaluated on remote hosts, with the final pixels being transferred to the local host over the network. A local image may be served to remote hosts tile-by-tile.

    Note that the "fileload" operation may not be used to load images remotely if the image file is not visible to the client file system even if the file is visible to the server file system. Use the "URL" operation instead for this purpose. The "filestore" operation may however be used to store an image on a server to a file not visible from the client file system. The "filestore" and other "immediate" operations are rendered upon deserialization of the associated RenderedOp and should not be created using JAI.create() if they are to be processed remotely.

    See section below for instructions on how to use remote imaging in JAI.

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.

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

Performance Issues

How to Run Remote Imaging in JAI

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

Documentation

The Java Advanced Imaging API White Paper, the HTML document of the API, and a programmer's guide – "Programming in Java Advanced Imaging" – as well as a quick-reference guide can be found at http://java.sun.com/products/java-media/jai/docs/

What's New

• The Version 1.0.2 reference implementation is a bug-fix release for the 1.0.1 reference implementation. Version 1.0.1 is no longer available.

  GENERAL CHANGES

• An API incompatibility that was inadvertently introduced in Version 1.0.1 has been fixed. In Version 1.0.1, a new public variable was introduced in the KernalJAI class; this caused the 1.0.1 implementation to differ from the specification and broke the serialization compatibility between 1.0 and 1.0.1 objects. In 1.0.2, the public variable has been made private.

• A bug which caused 1.0.1 to not work in applet environments has been fixed. Version 1.0.1 tried to read an environment variable in order to access its registry file. This access is a security violation in the applet environment. Not all JVMs caught this security violation, resulting in inconsistent behavior. In 1.0.2, a modified registry discovery mechanism has been introduced, correcting this problem.

• Changes from 1.0 to 1.0.1 implementation

  • Version 1.0.1 reference implementation is built on the FCS version of the Java 2 platform (JDK 1.2), as was the previous release. The changes described here are to fix bugs and enhance performance. No API changes were made in this release.

    GENERAL CHANGES

  • The runtime files are now installed directly into the Java Runtime Environment (JRE). Applications that use Java Advanced Imaging no longer need to set the CLASSPATH and (on the Solaris Operating Environment) LD_LIBRARY_PATH variables. The registry file has been renamed to registryFile.jai and is installed into the lib/ext directory of the JRE, along with the jar files. A copy is present in the jai_core.jar file as well, which is used if a separate file is not present or is unreadable.

  • Exception Handling: Fixed bug where a NullPointerException was being thrown during attempts to access exception message strings.

  • Remote imaging: Added support for the case where a RemoteImage may be used as the data source of another imaging chain without actually transferring data to the client machine.

  • Memory usage: Due to changes made in the implementation of the JAI tile cache, it is now especially important to specify the memory allocation pool (the garbage collected heap) which is available to the java virtual machine. This can be done with the -Xmx flag to the java command. A minimum setting of 48 megabytes is recommended. For applications making use of large images, performance can also be enhanced by programmatically specifying the tile cache memory capacity rather than accepting the default (16 MB).

    CLASS-LEVEL CHANGES

  • ComponentSampleModelJAI:
    • Corrected erroneous ignoring of bankIndices.

  • OperationRegistry:
    • Cleaned up some MT-unsafe code, fixed serializability of the registry.

  • ParameterBlockJAI:
    • Fixed a bug with null parameter values.

  • PlanarImage: Provide an error message in
    • getData if the size of the resulting buffer would be bigger than Integer.MAX_VALUE.

  • RectIter:
    • SampleModel translation factors are now taken into account. The ComponentSampleModel case has been sped up.

  • RenderedOp (and CollectionOp): Fix
    • createInstance so it will "unfreeze" nodes as indicated.

  • TileCache:
    • Revised, more efficient implementation. Tile capacity is ignored and only memory capacity is used. The initial capacity of the cache has been lowered to 16 Mbytes.
    • Use hard references instead of soft due to VM implementation issues.

  • TiledImage:
    • Set ColorModel using PlanarImage.createColorModel() in secondary constructors. Fix a bug where floating point samples were being truncated to integers in setData.

  • TileScheduler:
    • Default implementation now uses 2 worker threads.

  • UntiledOpImage:
    • Fix bug where image origin and tile grid offsets were being ignored, causing images to have more than one tile.

    CHANGES TO WIDGETS

  • ScrollingImagePanel
    • Gutted and rewritten.
    • No longer forces non-visible tiles to load.
    • Fixed scrolling problems on Windows.
    • Fixed resize and auto-centering problems.
    • Removed unimplemented mouse-drag scrolling feature from the documentation.

    CHANGES TO CODEC HELPER CLASSES

  • Added two new methods in the com.sun.media.jai.codec package:
    • TIFFDecodeParam.decodeSigned16BitsTo8Bits
    • TIFFDirectory.isBigEndian

    OPERATOR CHANGES

  • AddCollection:
    • Fixed unsigned short case.

  • Affine:
    • Fix incorrect clamping of float and double output values.
    • Java implementation of nearest-neighbor interpolation has been accelerated for binary (1 bit) images.

  • BandCombine:
    • Add mediaLib acceleration; limited to 3-band source and destination.

  • BandSelect:
    • Add mediaLib acceleration; limited to monotonically increasing band indices.

  • BoxFilter:
    • Corrected argument validation.

  • Border:
    • Set tile grid offsets more efficiently.

  • Constant:
    • Fix a bug in how the data type of the image is determined.

  • Convolve:
    • Suppress invocation of mediaLib for kernels with size 1 in either dimension.
    • Corrected bugs in Java implementation of convolution for 1D and separable 2D kernels.
    • Improved kernel separability testing and normalization of horizontal and vertical arrays.

  • Crop:
    • Fix incorrect tile grid layout.

  • DCT:
    • Force image origin to coincide with that of its source.

  • DFT:
    • Force image origin to coincide with that of its source.
    • Added enhanced mediaLib acceleration for single-component (real or complex) image data. Enhanced version uses direct 2D FFT rather than 1D FFTs applied in row-column order.
    • Corrected scaling of unitary DFT for in interface to mediaLib FFT.

  • ErrorDiffusion:
    • Fixed exception bug when source image had non-zero origin.

  • FileLoad/FileStore:
    • Close streams created internally by these operators when the images that they return are finalized by the garbage collector. This should alleviate a problem of too many open files observed by customers.

  • Format:
    • Allow SampleModel to be changed using ImageLayout in RenderingHints.

  • IIP:
    • Modified to use server-side processing when available.

  • IIPResolution:
    • Enhanced performance by retrieving a block of tiles at a time over the HTTP connection rather than a single tile at a time.
    • Corrected bug which prevented use of this operator with any client which did not return the response to the OBJ=IIP,1.0 command last in the sequence, e.g., TrueSpectra's "IrisAccelerate" product.

  • MedianFilter:
    • Added mediaLib acceleration for 3x3, 5x5, and 7x7 masks.

  • PeriodicShift:
    • Fix incorrect truncation of float and double values.

  • Rotate:
    • Fix incorrect clamping of float and double output values.
    • Fixed a bug where the rotation center was not properly taken into account for rotations angles that are a multiple of 90 degrees.
    • Java implementation of nearest-neighbor interpolation has been accelerated for binary (1 bit) images.

  • Scale:
    • Fix incorrect clamping of float and double output values.
    • Java implementation of nearest-neighbor interpolation has been accelerated for binary (1 bit) images.

  • Statistics operators (Extrema, Histogram, Mean):
    • Fixed bug where xPeriod and yPeriod were not taken into account properly.
    • Fix ROI intersection problems.

  • SubtractConst:
    • Do not modify original "constant" parameters.

  • Transpose :
    • The specification has been clarified to state that the output image will always have the same min X and Y as the source image.
    • Java implementation handles tiling more efficiently.
    • Java implementation has been specially accelerated for binary (1 bit) images.

  • Warp:
    • Added mediaLib acceleration of polynomial and grid warping.

    CODEC CHANGES

  • SeekableStream
    • readLongLE() no longer loses upper 32 bits of 64-bit words.

  • ImageCodec
    • Fixed bug in createGrayIndexColorModel() wherein the blackIsZero parameter was being interpreted opposite to its intent.

  • BMP
    • Fixed decoding of 1-bit (binary) images.

  • JPEG
    • Fixed encoding of JFIF files from PlanarImages with non-zero origins.

  • TIFF
    • For ASCII fields do not read more than the number of bytes indicated by the "count" value in the tag as some TIFF writers do not respect NULL termination of strings stored in these fields as required by the TIFF specification.
    • Be more lenient about byte counts in FAX decoding.
    • Fixed encoding of grayscale images.
    • Fixed bug where the "filestore" operation did not set its second parameter to a default value.
    • Added decoding of signed and unsigned short integer images.
    • Added support for writing 16-bit files excepting palette-color images.
    • Improved decoding speed for fax images.

    DEMO CHANGES

  • Added auto mode (animation).

  • Added dyadic (two-source) demos.

  What's Old (changes prior to version 1.0 FCS)

  The information below is included for historical reasons only. Versions of the Java Advanced Image API prior to the 1.0 version are unsupported and should not be used.

• Changes from Beta to 1.0

  • Version 1.0 is built on the FCS version of the Java 2 platform (JDK 1.2), as was the previous release.

    CLASS-LEVEL CHANGES

  • The javax.media.jai.codec package has been renamed to com.sun.media.jai.codec. See the Core Functionality section for more information.

  • The following classes are no longer serializable: RenderableGraphics, OperationDescriptor

  • The following classes/interfaces have become serializable: MultiResolutionRenderableImage, PropertyGenerator

  • The following class has become externalizable: OperationRegistry

  • The following classes/interfaces have been removed: CRIFJAI, Coordinate, CoordinateMapper, PointMapper, PropertyGeneratorImpl

    Coordinate support will be considered for reintroduction in a future release of JAI.

    OPERATOR CHANGES

  • "IIP" and "IIPResolution" operators were added.

  • A "Renderable" operation has been added that takes a RenderedImage and provides a renderable "view" of it.

  • The following operations now work in the renderable layer: Constant, DCT, DFT, IDCT, IDFT, Magnitude, Magnitudesquared, Max, Min, Phase, Transpose

  • When instantiating an operation using the JAI.create or JAI.createNS methods, trailing parameters of an operation ParameterBlock may now be omitted. The parameters will be filled in with default values as specified by the OperationDescriptor being used. If default values do not exist for one or more of the parameters, an exception will be thrown.

  • The order of the parameters to the "BoxFilter" operation has changed.

  • The width and height parameters to the "Constant" operation are now of type float in order to allow the operation to work in the Renderable layer.

  • The "Transpose" operator has had its parameters adjusted so that FLIP_VERTICAL flips about a horizontal axis and FLIP_HORIZONTAL flips about a vertical axis.

  • Additional native accelerations for composite, invert, min, max, and threshold have beedn added.

  • All geometric operations now support a table-driven general interpolation.

    CHANGES TO CORE CLASSES

  • Some methods of PlanarImage have been made protected: setImageParamters, addSource, addSink, removeSource, removeSink. The setSource(PlanarImage, int) and getBounds2D methods have been removed from the API.

  • A method OpImage.computesUniqueTiles has been added in order to prevent incorrect optimization when using certain image sources.

  • OperationDescriptor no longer uses the value null to indicate the absence of a default value for a parameter. Instead, a constant value of NO_PARAMETER_DEFAULT is used. This allows the use of null as a default value.

  • The methods of OperationDescriptor dealing with hints have been removed: getHintClasses, getHintKeys, getHintDefaults. Methods to support renderable mode operation have been added: getRenderableSourceClasses, getRenderableDestClass, validateRenderableArguments.

  • The method OperationDescriptor.getDefaultValue has had its name changed to getParamDefaultValue.

  • Some methods have been removed from the OperationRegistry class: registerOperationByName, registerRIFByClassName, registerCRIFByClassName, registerCIFByClassName. These methods existed for convenience only and accordingly no functionality has been lost.

  • The JAI class has had methods createRenderableCollection and createRenderableCollectionNS added.

  • Several instance variables of the RenderedOp class have been made private; accessor methods have been provided for them.

  • It is no longer possible to register multiple instances of ContextualRenderedImageFactory (CRIF) for a single operation. The notions of product and preference for CRIFs have been removed.

  • Properties are now supported in the Renderable layer. In order to add this support, several methods were added: PropertyGenerator.getProperty(String, RendererableOp), PropertySource.getPropertySource(RenderableOp), and RenderableOp.getOperationName.

    CHANGES TO COLLECTION CLASSES

  • The specification of the ImageMIPMap class has been changed to remove the previous limitation on resolution selection.

    CHANGES TO INTERPOLATION CLASSES

  • The instance variables of the Interpolation classes have been modified to simplify the implementation of subclasses.

    CHANGES TO WARP CLASSES

  • The Warp classes now consider the "energy" of a pixel to lie in the center of that pixel for consistency with Java2D and the rest of JAI. This requires a change to the calculation of the warp grids. The documentation for Warp.warpRect describes the semantics in detail.

  • Accessor methods have been added to the WarpPolynomial and WarpGrid classes.

  • A mapSourceRect method has been added to the Warp class and its subclasses.

  • The implementation for the "scale" operator has been internally modified to reduce the amount of cobbling done. The current implementation forward maps each source tile to write the corresponding destination image area. Cobbling is only done along source tile edges when neccesitated by higher order interpolations. Since the computeRect method is called per source tile, it is recommended that tile sizes be larger in order to reduce the overhead of calling computeRect repeatedly.

    CHANGES TO CODEC CLASSES

  • The TIFF decoder now handles LZW decoding (but not encoding)

  • The PNM encoder now handles images with IndexColorModels.

• Changes from Early Access 3 to Beta

  • Beta is built on the FCS version of the Java 2 platform (JDK 1.2), as was the previous release.

  • The previous release made use of a single jar file, jai.jar. The current release uses two files: jai_core.jar and jai_codec.jar. The jai_codec.jar file, which includes the javax.media.jai.codec package, may be used independently. However, use of jai_core.jar requires the presence of jai_codec.jar.

    This split is preliminary; there may be additional changes to the jar file structure in the final release.

    CLASS-LEVEL CHANGES

  • Added new classes/interfaces:

    In package javax.media.jai:

    BorderExtender, BorderExtenderConstant, BorderExtenderCopy, BorderExtenderReflect, BorderExtenderWrap, BorderExtenderZero, CanvasJAI, CollectionImageFactory, ComponentSampleModelJAI, FloatDoubleColorModel, ImageFunction, RasterFormatTag

    In package javax.media.jai.codec:

    PNGEncodeParam, PNGSuggestedPaletteEntry, TIFFEncodeParam

    In package javax.media.jai.operator:

    AddConstToCollectionDescriptor, ColorConvertDescriptor, ConjugateDescriptor, CropDescriptor, EncodeDescriptor, FileStoreDescriptor, GradientMagnitudeDescriptor, ImageFunctionDescriptor, MatchCDFDescriptor, PeriodicShiftDescriptor, PiecewiseDescriptor, PolarToComplexDescriptor, URLDescriptor

  • Changed classes to interfaces:

    TileCache, TileScheduler

  • Removed old classes/interfaces:

    In package javax.media.jai:

    DisplayOpImage, FloatComponentSampleModel, MultiSourceOpImage, PixelChain, PointLUTOpImage, RenderingHintsJAI

    In package javax.media.jai.operator:

    DilateDescriptor, ErodeDescriptor, FPXFileDescriptor, SobelDescriptor

  • Java implementations for the following operators have been added: AddConstToCollection, BoxFilter, ColorConvert, Conjugate, CropDescriptor, Encode, FileStore, GradientMagnitude, ImageFunction, MatchCDF, PeriodicShift, Piecewise, PolarToComplex, URL

  • Native implementations for the following operators have been added:

    DCT, DFT, Exp, Extrema, Gradient, IDCT, IDFT, Log, Shear

  • The following operations now work in the renderable layer:

    Absolute, Add, AddConst, Affine, And, AndConst, BandCombine, BandSelect, Clamp, ColorConvert, Composite, Conjugate, Constant, Crop, Divide, DivideByConst, DivideIntoConst, DivideComplex, Exp, Format, Invert, Log, Lookup, MatchCDF, Multiply, MultiplyConst, MultiplyComplex, Not, Or, OrConst, Overlay, PeriodicShift, Piecewise, PolarToComplex, Rescale, Rotate, Scale, Subtract, SubtractConst, SubtractFromConst, Threshold, Translate, Xor, XorConst

    CHANGES TO CORE CLASSES

  • Many previously unimplemented property handling methods have been implemented. However, properties handling is still not fully implemented for Renderable chains. In particular, RenderableOp.getProperty(String) is not implemented.

  • The algorithm for setting the layout of an OpImage during construction has been improved to allow more control while at the same time producing better default behavior. See the documentation for the OpImage constructor for details.

    In particular, setting the output SampleModel to have a data type with more range and/or precision than the source data type will cause the pixel processing to be done in the more precise data type.

  • By default, source images of an OpImage that have an IndexColorModel are dynamically expanded by the RasterAccessor class. The BMP, PNG, PNM, and TIFF image decoders may produce output with IndexColorModels. Other codecs may do so in the future.

  • Some instances of PointOpImage support in-place operations in order to conserve memory and reduce object construction overhead. The PointOpImage.permitInPlaceOperation() method determines whether to allow such operations on a given image.

    For debugging purposes, it is possible to disable all in-place operations by setting the Java system property javax.media.jai.PointOpImage.InPlace to false. This property may be removed in a future release.

  • TileCache and TileScheduler are now interfaces. It is possible to use a rendering hint to specify the TileCache instance to be used to hold the tiles from a given OpImage.

    The TileCache interface now allows the capacity to be set in terms of a maximum number of tiles held and a maximum amount of memory associated with those tiles.

    TileScheduler now performs multi-threading by default.

  • New methods PlanarImage.getTiles and prefetchTiles have been added to provide performance hints to the tile scheduler.

  • The JAI class may now be instantiated. Each instance may reference a different OperationRegistry and TileCache and a different set of default rendering hints.

  • RasterAccessor.findCompatibleTag now takes a SampleModel instead of a Raster in order to allow the tag values to be reused. RasterFormatTag is now a class rather than being represented by an enumerated value.

    OpImage now has a method getFormatTags that computes and caches a suitable RasterFormatTag based on the source and destination image formats.

  • The notion of BorderExtenders has been added. A BorderExtender provides a way to retrieve a portion of PlanarImage that may extend beyond the normal boundaries of that image. The area outside the image is computed dynamically by the BorderExtender. Two new methods on PlanarImage, getExtendedData and copyExtendedData make use of a BorderExtender argument.

    OpImage now has a method hasExtender(int sourceIndex) which indicates whether a BorderExtender was supplied for the specified source image during construction.

  • New classes ComponentSampleModelJAI and FloatDoubleColorModel fix bugs and address limitations of the Java2D ComponentSampleModel and ComponentColorModel classes. The RasterFactory class may be used to instantiate the new classes using familiar interfaces.

  • The PlanarImage.createColorModel(RenderedImage) method has been removed. The createColorModel(SampleModel) method has been extended to handle a greater variety of input SampleModels.

  • OperationDescriptor now implements java.io.Serializable.

  • OperationDescriptorImpl now includes a constant NO_PARAMETER_DEFAULT that may be used by subclasses to indicate the lack of a default value for a given parameter. This change allows the use of null as a parameter default. The logic in OperationDescriptorImpl.validateParameters has been changed to make use of this mechanism.

    A mechanism is being considered for the final release that would allow a variable number of arguments to be used for all operations.

  • Rendering hints from RenderingHintsJAI now live in the JAI class. The following rendering hint keys were added:

    KEY_BORDER_EXTENDER, KEY_ENCODE_PARAM, KEY_OPERATION_REGISTRY, KEY_OPERATION_BOUND, KEY_TILE_CACHE

    The following rendering hint key was removed:

    KEY_PNG_EMIT_SQUARE_PIXELS

  • The ImageLayout.unsetImageDimensions method has been renamed to unsetImageBounds.

  • The isPositivePowerOf2 and nextPositivePowerOf2 methods have been removed from UntiledOpImage.

  • RenderedOp was modified such that "immediate" operations, i.e., those which have an associated OperationDescriptor the isImmediate method of which returns true, will be rendered upon deserialization. When creating an imaging graph for remote evaluation such operations should be created by explicitly constructing a RenderedOp rather than invoking JAI.create which will itself force evaluation of the operation.

    CHANGES TO ITERATOR CLASSES

  • RectIter.jumpLines and jumpPixels now throw IndexOutOfBoundsException when leaving the bounding rectangle of the iterator.

    CHANGES TO WARP CLASSES

  • Polynomial warp constructors now take separate arrays for X and Y.

    CHANGES TO INTERPOLATION CLASSES

  • Interpolation classes now support the double data type.

    The method Interpolation.create has been renamed to Interpolation.getInstance. It now returns a previously created instance of the standard Interpolation subclasses.

  • InterpolationTable now requires the dataH and dataV constructor parameters to have the correct length.

    CHANGES TO COLLECTION CLASSES

  • The ImageMIPMap and ImagePyramid classes have been reworked. ImageMIPMap now includes a getAsRenderable method to produce a RenderableImage based on the pyramid data.

    The current implementation of ImageMIPMap has a limitation of not allowing higher resolutions to be retrieved after retrieving lower levels.

    CHANGES TO OPERATIONS

  • OperationDescriptor contains new methods isRenderedSupported, and isRenderableSupported. These methods are used by the JAI.createNS and createRenderableNS methods to determine the suitability of the operation.

  • The OperationDescriptor.isImmediate method, if it returns true, will force the JAI.create method to immediately request a rendering of the operation rather than simply returning a RenderedOp representing the operation.

  • The Pattern operator takes a RenderedImage as a source instead of a Raster parameter.

  • An ImageFunction interface for use by the ImageFunction operation was added.

  • The semantics of the geometric operators (Affine, Rotate, Scale, Shear, and Translate), were changed to produce an output image of a fixed size regardless of the type of interpolation being performed. If no BorderExtender is specified, the edges of the output image will be left blank. If a BorderExtender is specified, it will be used to provide additional source pixels as needed in order to fill in the entirety of the output.

  • The kernel of a convolution operation is now rotated by 180 degrees before performing convolution. This rotation was previously described in the specification but not actually performed. The method KernelJAI.getRotatedKernel provides the rotated kernel.

  • Complex operators now permit any even number of bands for complex data. If an appropriate ImageLayout hint is supplied, single-component complex imagery may be applied to multi-component imagery to generate a multi-component result.

  • Arithmetic operators now allow mixing sources of N bands and 1 band. The single band is processed repeatedly for each of the N bands other source image. This behavior is obtained by supplying an appropriate ImageLayout hint; the default behavior has not been modified.

  • An additional parameter containing an ImageDecodeParam object has been added to the FileLoad, FPX, PNG, Stream, TIFF, and URL operations. It is possible to omit this parameter or to set it to null.

  • The Encode and FileStore operations take an ImageEncodeParam object as a parameter. This parameter may be omitted or set to null.

  • PropertyGenerators which set a Boolean-valued property named "COMPLEX" have been added to the following operations: "dft", "idft", "magnitude", "phase", "magnitudesquared", "mutiplycomplex", "dividecomplex", "conjugate", "polartocomplex" and "imagefunction".

  • A second parameter has been added to the OperationDescriptors of the "dft" and "idft" operations to indicate whether the input and output image data are real or complex.

    CHANGES TO IMAGE CODEC CLASSES

  • The PNG decoder now performs gamma correction by default. The PNGDecodeParam class has been updated to allow more control over the decoding process.

  • The BMP decoder now emits 1, 4, and 8 bit images in packed format. The BMP encoder now writes 1, 4, and 8 bit palette images as well as 24 bit truecolor images.

  • The BMPEncodeParam class has been simplified.

  • A PNG encoder has been added, along with a PNGEncodeParam class. Another new class, PNGSuggestedPaletteEntry, has been created for use by PNGEncodeParam.

  • TIFFDecodeParam now allows the user to specify byte or short output for palette color images. The TIFF decoder now handles G3, G4, and PackBits compressed bilevel images.

  • A TIFF encoder has been added to perform baseline (non-compressed) TIFF encoding. The TIFFField class now has a public constructor.

  • Add getNumPages(), decodeAsRaster(int page) and decodeAsRenderedImage(int page) methods to ImageDecoder.

  • Replace ImageEncoder.encode(Raster) with ImageEncoder.encode(Raster, ColorModel).

  • Add methods to ImageCodec: getCodecs(), getDecoderNames(), getEncoderNames(), getEncodeParamClass(), getDecodeParamClass(), and canEncodeImage()

  • The JPEGEncodeParam interface has been completely rewritten. This solves problems with color conversion in the previous release as well as providing an easier-to-use interface.

    CHANGES TO SAMPLE CODE

  • The SampleDescriptor class has undergone the following changes:

    • The superclass constructor has an additional null parameter indicating that the default TileCache should be used.

    • The lines:

      int formatTag = RasterAccessor.findCompatibleTag(sources, dest); RasterAccessor srcAccessor = new RasterAccessor(source, srcRect, formatTag); RasterAccessor dstAccessor = new RasterAccessor(dest, destRect, formatTag);

      
      have been replaced by:

      RasterFormatTag[] formatTags = getFormatTags(); RasterAccessor srcAccessor = new RasterAccessor(sources[0], srcRect, formatTags[0], getSource(0).getColorModel()); RasterAccessor dstAccessor = new RasterAccessor(dest, destRect, formatTags[1], getColorModel());

      
      

  • JAIExampleApp.java and JAISamplePanel.java have undergone the following change. The line:

    OperationRegistry or = JAI.getOperationRegistry();
    

    has been changed to:

    OperationRegistry or =
      JAI.getDefaultInstance().getOperationRegistry();
    

  • JAIImageReader.java has undergone the following change. The line:

    String[] names = ImageCodec.getCodecNames(stream);
    

    has been changed to:

    String[] names = ImageCodec.getDecoderNames(stream);
    

  • JAIPatternPanel.java has undergone the following change. The "pattern" operation now takes a RenderedImage source instead of a Raster parameter.

  • JAIRotatePanel.java and JAIScalePanel have undergone the following change. The Interpolation.create method has had its name changed to Interpolation.getInstance.

  • JAIWarpDemo.java has been changed to use the new coefficient order from the Warp class.

  • IconJAI handles the setting of a background color slightly differently, and does not fill the background if the image has an opaque ColorModel.

  • The JAI demo now allows the tile cache to be flushed and to have its capacity set using a graphical interface.

  • The panels associated with the JAI demo make use of make use of a global rendering hint containing the BorderExtender to be used.

  • The "Convolve" panel of the JAI demo has additional kernel choices.

  • A "Gradient" panel has been added to the JAI demo.

    CHANGES TO CODEC SAMPLE CODE

  • FormatDemo.java has had the line:

    String[] names = ImageCodec.getCodecNames(stream);
    

    changed to:

    String[] names = ImageCodec.getDecoderNames(stream);
    

  • SamplePNMCodec has had the following methods added:

    getEncodeParamClass
    getDecodeParamClass
    canEncodeImage
    

  • SamplePNMImageDecoder has had its decodeAsRenderedImage method modified to take a 'page' argument, in accordance with its superclass.

  • The getPropertyNames(String prefix) method of SimpleRenderedImage has an implementation.

• Changes from Early Access 2 to Early Access 3
  • EA3 is built on the FCS version of the Java 2 platform (JDK 1.2). The previous release was built on JDK 1.2 Release Candidate 1.

  • Added New Classes:

    CollectionImage, CollectionOp, CoordinateImage, IntegerSequence, RasterFactory, SequentialImage, UntiledOpImage, ByteArraySeekableStream, FPXDecodeParam, FileCacheSeekableStream, FileSeekableStream, ForwardSeekableStream, MemoryCacheSeekableStream, PNGDecodeParam, SeekableStream, SegmentedSeekableStream, StreamSegment, StreamSegmentMapper, TIFFDecodeParam, AddCollectionDescriptor, DCTDescriptor, DFTDescriptor, FileLoadDescriptor, IDCTDescriptor, IDFTDescriptor, OrderedDitherDescriptor

  • Removed Old Classes:

    FormatRecognizer, ImageCollection, InputStreamOpImage, OutputStreamOpImage, RemoteImageImpl, RemoteRenderedImage, ContrastDescriptor, FFTDescriptor, FileDescriptor, GIFFileDescriptor, IFFTDescriptor, PowConstDescriptor, TIFFFileDescriptor

  • Java implementations for the following operators have been added:
    • dct
    • dft
    • fileload
    • flashpix
    • magnitude
    • magnitudesquared
    • ordereddither
    • phase
    • rescale

  • Several operators have enhanced performance via:

    A C-based native library on Windows NT and 95
    A C-based native library on Solaris
    Hardware acceleration on UltraSPARC-based systems
    

    These operators are:

    • absolute
    • affine
    • convolve (separable cases)
    • divide
    • mean
    • multiply
    • rescale
    • rotate
    • scale
    • translate
    • transpose

    Most native operators now support byte, short, int, float, and double data types.

    All operators continue to have pure-Java implementations.

  • Support for operating on collections of images has been added. The APIs for using collections within JAI have changed. See the documentation for java.util.Collection for more about the concept of collections.

    The output of a standard image operator on a 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 by returning an appropriate result from the OperationDescriptor.getDestClass() method.

  • Remote imaging has been implemented. The APIs have changed as well. The public API is located in the javax.media.jai.RemoteImage class. A number of classes have been made Serializable for use with RemoteImage. See section above for details on how to use remote imaging.

  • The javax.media.jai.codec package now contains a new set of classes including SeekableStream and its subclasses. These classes are as follows:
    • SeekableStream: an abstract class combining the functionality of InputStream and RandomAccessFile, along with the ability to read primitive data types in little-endian format.
    • ByteArraySeekableStream: implements SeekableStream functionality on data stored in an array of bytes.
    • FileSeekableStream: implements SeekableStream functionality on data stored in a File.
    • ForwardSeekableStream: provides SeekableStream functionality on data from an InputStream with minimal overhead, but does not allow seeking backwards. ForwardSeekableStream may be used with input formats that support streaming, avoiding the need to cache the input data.
    • FileCacheSeekableStream: provides SeekableStream functionality on data from an InputStream, using a cache file to allow seeking backwards.
    • MemoryCacheSeekableStream: provides SeekableStream functionality on data from an InputStream, using an in-memory cache to allow seeking backwards. MemoryCacheSeekableStream should be used when security or lack of access to local disk precludes the use of FileCacheSeekableStream.
    • SegmentedSeekableStream: provides a contiguous view of non-contiguous source data.
    • StreamSegment and StreamSegmentMapper: utility classes used with SegmentedSeekableStream.

    By adding the ability to seek to the usual streaming semantics of InputStream, the codec architecture is greatly simplified.

    Numerous other changes have occurred in the java.media.jai.codec package, including extensions to the ImageCodec class. The FormatRecognizer class has been removed and its functionality subsumed by ImageCodec.

  • Most operators now support all pixel datatypes, including float and double.

  • The OperationRegistry is more robust. Failure to load an operator is dealt with gracefully. It is therefore possible to run in pure-Java code only by not loading the native libraries.

    Parameters are checked for validity earlier and more thoroughly, simplifying debugging.

  • A framework for Internationalization/Localization of error messages and other strings has been put in place.

  • The semantics of geometric operators have changed. Source pixels are now considered to have their energy located in the pixel center. This is compatible with Java2D's model.

  • The semantics of the "phase" operator has been changed to use angles between -PI and PI instead of 0 to 2*PI. Complex-valued images may now have an even number of bands rather than only two bands.

  • Not all FlashPIX files may be read. Only reading of a single resolution of the hierarchy (as opposed to applying a viewing transform) is supported currently.

  • The methods PlanarImage.getMaxX() and getMaxY() have been changed to return the index of the first row or column outside of the image. This usage is more consistent with other Java API classes including java.awt.Rectangle.

  • The OperationDescriptor.validateParameters() method has been changed to validateArguments().

  • Operators which previously had numeric arguments of type Number now use the double datatype.

  • Added a RasterFactory class to work around bugs in Java2D's Raster creation methods. This class may be removed when Java2D is updated.

  • Cobbling performance has been improved. This speeds up area and geometric operations such as convolve and scale.

  • Non-optimized Rect and Rook iterators are now implemented.

  • Add a new variant of the ROI.transform() methods that takes an Interpolation argument.

  • Added a new method TIFFDirectory.getNumDirectories() to determine the number of images in a multipage TIFF file.

  • Fixed bugs reported on the jai-interest mailing list:
    • BMP reader deals with RLE4 and RLE8 encodings incorrectly
    • BMP writer does not deal with non-zero minX and minY
    • PNM writer writes an extra character in raw mode headers
    • The edges of some scaled images have a black line
    • Excessive memory use by PNM reader and writer
    • PlanarImage.getSplits() ignores image borders
    • Format recognizers can't be registered properly
    • Error when reading past the last image in a multipage TIFF file

• Changes from Early Access 1 to Early Access 2
  • EA2 is built on JDK 1.2 Release Candidate 1. The previous release was built on JDK 1.2 Beta 4.

  • Several operators have enhanced performance via:

    A C-based native library on Windows NT and 95
    A C-based native library on Solaris
    Hardware acceleration on UltraSPARC-based systems
    

    These operators are:

    • lookup
    • convolve
    • arithmetic operators
    • logical operators

  • Java implementations for the following operators have been added:
    • multiply/multiplyconst
    • divide/divideconst/divideintoconst
    • exponent
    • log
    • clamp
    • threshold
    • absolute value
    • or/orconst
    • xor/xorconst
    • transpose
    • error diffusion dither
    • warp

  • A new class, javax.media.jai.InputStreamOpImage, was added.

  • BMP, PNG, and PNM (PBM/PGM/PPM) formats may now be read.

  • Image encoding capability, using a new codec architecture, was added. The public interfaces are in javax.media.jai.codec and the private implementations are in com.sun.media.jai.codec. For example, to encode a JPEG file, you might use the following code:

    RenderedImage im; String filename; FileOutputStream dst = new FileOutputStream(filename); ImageEncoder enc = ImageCodec.createImageEncoder("JPEG", dst, null); enc.encode(im); dst.close();

    
    

    JPEG, BMP, and PNM formats may currently be written.

  • An abstract class javax.media.jai.FormatRecognizer now exists. It may be subclassed and instances of its subclasses may be registered with the OperationRegistry in order to automatically detect new file types when using the Stream and File operators.

  • The javax.media.jai.operator.TIFFDescriptor class now specifies reading from an InputStream instead of a File.

  • A new class, javax.media.jai.operator.TIFFFileDescriptor, was added.

  • An implementation for javax.media.jai.InterpolationBicubic2 is provided.

  • The javax.media.jai.operator.TransposeDescriptor class was modified for better conformance with Java2D.

  • The implementation of the Rotate operation now calls Copy/Transpose for certain angles and center of rotation.

  • An implementation of the error diffusion color quantization algorithm was added. In support of this operation a method findNearestEntry() was added to LookupTableJAI to find the nearest entry to a given pixel value. A subclass javax.media.jai.ColorCube of javax.media.jai.LookupTableJAI was also added to support faster processing in the error diffusion algorithm: finding the nearest color is considerably faster when the lookup table used is a color cube. The error diffusion implementation includes a single optimization for the case of a 3-band byte source image when a ColorCube is used for the color map and the error filter is the Floyd-Steinberg filter.

    Double precision source images are not currently supported by the error diffusion operation. The findNearestEntry() methods of LookupTableJAI and ColorCube do not yet support tables which are of other than byte data type.

  • An implementation for getAsBufferedImage() method in PlanarImage is now provided.

  • The convenience method signatures for Affine and Scale in the javax.media.jai.JAI class were changed.

  • The method signature of writeToStream() in OutputStreamOpImage was changed to allow it to throw IOExceptions.

  • Two static convenience methods were added to javax.media.jai.PlanarImage that create a suitable color model for a particular SampleModel:

    static ColorModel
      createColorModel(RenderedImage)
    static ColorModel
      createColorModel(SampleModel)
    

    Two static convenience methods were added to compute the X and Y coordinates of the upper-left corner of a given tile:

    static int tileXtoX(int tx, int tileGridXOffset, int tileWidth) static int tileYtoY(int ty, int tileGridYOffset, int tileHeight)

    
    

  • The Warp class and its subclasses were improved. The hierarchy is now:

    class javax.media.jai.Warp class javax.media.jai.WarpGrid class javax.media.jai.WarpPerspective class javax.media.jai.WarpPolynomial class javax.media.jai.WarpAffine class javax.media.jai.WarpCubic class javax.media.jai.WarpGeneralPolynomial class javax.media.jai.WarpQuadratic

    
    

    All Warp subclasses now have two versions of the WarpPoint, WarpRect, and WarpSparseRect classes. One version returns or fills in an int array of fixed-point warp positions, and the other uses a float array.

    The Warp class implements both versions of WarpPoint and WarpRect in terms of WarpSparseRect. The integer version of WarpSparseRect is implemented in terms of the float version.

    The WarpPolynomial subclasses were reorganized to leave WarpPolynomial abstract, with a WarpGeneralPolynomial class providing the implementation. WarpAffine is now a subclass of WarpPolynomial, and a WarpCubic class has been added. WarpAffine now has additional constructors using the same parameters as the other WarpPolynomial subclasses.

    All WarpPolynomial classes now order the polynomial coefficients as follows:

    1, x, y, x^2, x*y, y^2, ...

    WarpPolynomial offers a static factory method createWarp() that takes a set of corresponding points in the source and destination coordinate systems and creates a "best-fit" instance of WarpPolynomial. The fitting algorithm is implementation-dependent.

    All WarpPolynomial classes allow the specification of scale factors to be applied to the source and destination coordinates. Thus the result of a WarpPolynomial may be described as:

    dest_x = post_scale_x*x_poly(source_x*pre_scale_x, source_y*pre_scale_y dest_y = post_scale_y*y_poly(source_x*pre_scale_x, source_y*pre_scale_y)

    
    

  • The get/set method names and signatures in the iterator classes now match their counterparts in Raster and SampleModel.

  • A validateParameters() method was added to the OperationDescriptor and OperationDescriptorImpl classes. This method is responsible for determining if a given set of sources and parameters are allowed by the specification of an operation, independent of a particular implementation.

  • A static method was added to OpImage to create pixel-interleaved and banded SampleModels.

  • A mergeRunLengthList() method was added to the ROI class. A version of getAsRectangleList() was also added with a boolean argument mergeRectangles that causes the initial set of run length Rectangles to be merged into a minimal set.

  • A method rectangleListToBitmask() was added to the ROIShape class.

  • Most operators support operation on images with byte, unsigned short, and int data types. Support for signed short, float, and double data types will be added in a future release.