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 of JadeDisplay
- 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
Here is a simple example of a complete program using JadeDisplay:
/** 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);
// 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
A more extensive example, exercising most of the JadeDisplay features, is part of the download package.
Read the JadeDisplay javadocs. They 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).
From this page, you can request a copy of JadeDisplay by clicking on the "Get JadeDisplay" link. You must create a user login and password for yourself on the Open Channel site before you can request the software. You can do this from any page on the site by clicking on the "New User" link on the black bar at the top of the page.
Note that due to NASA, JPL, and Caltech regulations, you must download the license, print it, sign it, and fax it back in to Open Channel. They will then send you download instructions.
Read the license. It's basically for non-commercial use.
Commercial use is possible; send an email to info at openchannelsoftware dot com for license terms. Don't ask me, I'm not a lawyer and have no clue about this stuff.
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.
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:
https://jai.dev.java.net/index.html#Feedback_and_Discussion 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).
Jet Propulsion Laboratory
4800 Oak Grove Dr. MS 168-514
Pasadena, CA 91109
mail to: Bob.Deen at jpl dot nasa dot gov
The following links, also listed on the left side of all JadeDisplay pages, will give you more information about JadeDisplay:
|| Get JadeDisplay||
|| Coming Soon...
|| COTS Architectural Foundation
|| How the Display Works ||
|| Users of JadeDisplay ||
|| Return to main JadeDisplay page ||