JadeDisplay Public Release version 2.0
--------------------------------------
JadeDisplay is a high-performance image display component for serious
imaging applications using JAI (Java Advanced Imaging). It works
asynchronously, loading/computing and displaying image tiles in background
threads. This frees up the GUI thread so the user does not have to wait for
the entire image to load, and scrolling is fast regardless of image size
(as long as the image is tiled).
The display is capable of handling huge images. It has been tested with
images larger than 2GB with good performance. It also supports painting
of user-supplied graphics overlays.
It is written using JAI 1.1.1 or later and accepts any standard RenderedImage
object, meaning that almost any Java image can be displayed. It is completely
image-file-format neutral, and is pure Java so it is platform independent.
Release 2.0 is the Open Source release (using a BSD-style license). There
are only minor differences from the prior 1.0 (non-source) release, most
notably the BackgroundPainter, as well as some bug fixes.
Features
--------
* Fast and responsive
* Graphics overlay supported
* Support for large images (>2GB)
* Displays any Java2D RenderedImage
* Asynchronous display updates
* Background loading/processing of images
* Standards-based (JAI/Java2D)
* Component architecture (JavaBeans)
* Diagonal scrolling
* Background painter
* 3 repaint policies: immediate, deferred, cache
* Manages double-buffering for efficiency
* Full javadocs
Usage Notes
-----------
Here is a simple example of a complete program using JadeDisplay:
--
import javax.media.jai.*;
import javax.swing.*;
import java.awt.image.*;
import jpl.mipl.jade.*;
/** Simplest possible program that loads an image using a JAI codec, and
* displays it using JadeDisplay. The file to load is the (only) command
* line argument.
*/
public class SimpleDisplayTest
{
public static void main(String argv[])
{
// Load the image. Replace "fileload" with "imageread" to use
// ImageI/O and the IIO Tools package.
RenderedImage img = JAI.create("fileload", argv[0]);
// Set up JadeDisplay scrollbars and mouse-scrolling
JScrollPane sp = JadeDisplay.createDisplay(img, 500, 500, true);
// Put it in a window for display
JFrame window = new JFrame("JadeDisplay");
window.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); // optional
window.getContentPane().add(sp);
window.pack();
window.setVisible(true);
}
}
--
A more extensive example, exercising most of the JadeDisplay features, is
part of the download package.
Read the JadeDisplay javadocs. It should give you all the information you
need. The JadeDisplayTest.java test program also exercises most of the
display's features. It is a good source for example code.
The "flashing" of black, unpainted areas is intentional. That is the result
of tiles being computed in the background for later display. If you find
this objectionable, use setRepaintPolicy(REPAINT_IMMEDIATE). However, you
lose background processing by doing this (it is how most image displays
work, including DisplayJAI and ScrollingImagePanel).
If your image is not tiled, you will not get good performance. The best
tiling happens in the codec or Image I/O plugin. If your codec/plugin does
not output a tiled image, then the entire image must be loaded in order to
do anything, which is a huge performance hit (and memory hog!) for large
images. This component may still be useful, however, if downstream
operations take significant time (just make sure THEY output a tiled image).
Obtaining JadeDisplay
---------------------
JadeDisplay is available (free) in Open Source form using a BSD-style license.
The official distribution is handled by Open Channel (an organization that
maintains software downloads for NASA).
Installation and Platforms
--------------------------
JadeDisplay requires Java, of course, as well as Java Advanced Imaging (JAI):
It is easiest to install JAI inside your JDK (see the JAI installation
instructions), but any kind of JAI installation should work.
Formal testing was conducted only on Solaris 9, and Red Hat Enterprise 4
Linux, using JDK 1.5.0 and JAI 1.1.3. However, any JDK version 1.3 or later,
or JAI version 1.1.1 or later, should work. It should also work on other
platforms with no problems, but caveat emptor. We have successfully run
it on Windows and Mac OS X, but no formal testing has occurred on those
platforms.
To use JadeDisplay, simply extract jade_display.jar, and add it to your
CLASSPATH using the standard mechanisms.
The sample programs simply require extracting and compiling. Assuming you've
installed JAI inside your JDK, the following will compile and run them for
Solaris, Linux, or Mac OS X (from a terminal):
% javac -classpath jade_display.jar SimpleDisplayTest.java
% java -classpath .:jade_display.jar SimpleDisplayTest
% javac -classpath jade_display.jar JadeDisplayTest.java
% java -classpath .:jade_display.jar JadeDisplayTest
For Windows, use a ; instead of : between the classpath elements.
The sample programs use the JAI codecs, which means they support BMP,
GIF, FlashPix, JPEG, PNG, PNM, TIFF, and WBMP formats. Add your own
codecs to the CLASSPATH for more file formats. Of course, this is an
artifact of the test programs completely unrelated to JadeDisplay itself;
any RenderedImage can be displayed. Specifically, modern programs should
use the Image I/O plugin mechanism (JAI "imageread" operator) instead of
the codecs.
Support
-------
JadeDisplay is provided as-is. It was developed to support JPL missions,
and is in use at several places within JPL. It is being provided for download
basically as a public service (your tax dollars at work). However, we are
not paid to support the public users in any way, add features, answer
questions, or even fix bugs.
That said, we DO support this product for our own uses. So please contact
us to report any bugs you find, or to request features. While we can't
promise to fix/add any, we can take that into account when prioritizing our
own work. If the feature is useful to us, we might add it. If it's a bug,
we'll probably fix it since it might affect us in the future too. If it's
a question, I'll try to answer it but can't promise anything. The JAI
interest list:
may be a good place for questions, if I am not able to respond.
Of course, since it is open source, you can also fix problems or add features
yourself. While not a requirement, I would appreciate hearing about any
changes you make to the code. Also, it would be nice to hear about the uses
to which JadeDisplay is put. It's always nice to see your work in action
somewhere.
This component was developed by Bob Deen at the JPL Multimission Image
Processing Lab (MIPL), under NASA sponsorship and funding. Public Release
2.0 is derived from VICAR delivery 36.0 (VICAR is the image processing system
developed by MIPL).
Contact
-------
Bob Deen
Jet Propulsion Laboratory
4800 Oak Grove Dr. MS 168-514
Pasadena, CA 91109
USA
818-354-7492
Bob.Deen@jpl.nasa.gov