How to use JIMI

Contents

1. A note about this release
2. Installing JIMI
3. Running the JimiBrowserApp demo
4. Loading Images
5. Saving Images
6. Accessing Format Specific Options
7. Loading Images from Multiple Image Formats
8. Saving Images to Multiple Image Formats
9. FAQ
10. The Jimi API
11. Support

A note about this release

Installing JIMI

In order to keep your costs down every copy of JIMI must be licensed with a unique key class containing information specific to your application.  At the time that you purchase JIMI this class will be provided to you.  You must include your JimiKey.class class in your application's classpath as well as the JimiClasses archives.  To make it easier to deploy your application it is permissible to repackage the JimiKey.class into the JimiClasses archive.

For example if you are a Jimi Core customer you would change your classpath to include either JimiCore.jar or JimiCore.zip but NOT BOTH.  A Jimi Pro customer would add JimiPro.jar (or JimiPro.zip) to their classpath.  Both customers would need to add JimiKey.class to their classpath.

The documentation and archives are packaged as .ZIP archives and as an installer.  Simply unzip the archive or run the installer to extract the JimiCoreClasses.jar (or .zip) archive and the documentation.  Follow the same procedure for the Professional version.

The Jimi Demo version ships with BOTH the JimiProClasses and the JimiCoreClasses. You should only use the archive which is appropriate for your JimiKey and license. For evaluation and demonstration keys use the JimiProClasses archive.

Running the JimiBrowserApp demo

The JimiBrowserApp demo is a simple demonstration of an application that loads and saves images using JIMI.  The JimiBrowserApp demo does not provide a means of selecting format specific options, nor robust error handling, however it should prove as a guide and an introduction to JIMI.

To run the JimiBrowserApp demo simply install Jimi with the JimiCoreClasses archive in your classpath.  Add the JimiDemos.zip archive to your classpath, and "jre com.activated.jimidemo.JimiBrowserApp".  You should be able to load and save images using the appropriate file dialog.
 
A sample batch file for running JimiBrowserApp in Windows, Win32JimiBrowserApp.bat, is included as an example.

Loading Images

     java.awt.Image img =           com.activated.jimi.Jimi.getImage("c:\\Examples\\Jimi\\two_blind_men.png");

import java.awt.Image;
import com.activated.jimi.Jimi;
import java.net.URL;

public class Example2 {
 

public static void main(String[] args) {
 
Image img;
URL exampleURL = new URL("http://www.activated.com/activated.gif");
img  = Jimi.getImage(exampleURL);
  }
 }

All format types for JIMI use MIME type compatible strings, however convenience methods that check the file name extension and automatically use the appropriate MIME type string.  Please check the API documentation for these convenience methods.

Here is an example of using an explicit format type to load an image :
 

 Image img = Jimi.getImage("c:\\Examples\\Jimi\\really_a_jpg.gif",
    "image/jpeg");

Saving Images

Example :

import com.activated.jimi.Jimi;
import java.awt.Image;
import java.io.File;
import java.io.FileOutputStream;
import java.io.BufferedOutputStream;

public class Example3 {

public static void main(String[] args) {
Image img;
FileOutputStream fRawOut;
BufferedOutputStream fileOut;

/*

Load an image from a file
*/
img = Jimi.getImage("c:\\Examples\\Jimi\\base_image.png");

/*

Create the output stream, and destination file for the
converted image
*/
fRawOut = new FileOutputStream(new File("c:\\Examples\\Jimi\\new_image.JPG"));
fileOut = new BufferedOutputStream(fRawOut);

/*

Save the image in the new file format
*/
try {
Jimi.putImage("image/jpeg", testImage, fileOut);
} catch(Exception e) {
System.out.println("Image write failed.  Error: " + e);
}
}
}

putImage will also take an ImageProducer instead of an image.  This can be more efficient since an AWT peer does not need to be created if no Image is made.
 

Accessing Format Specific Options

JimiReader's and JimiWriter's can be created by using the factory methods of the Jimi class. For example :

  com.activated.jimi.JimiWriter pngWriter = Jimi.createJimiWriter("PNG");

Once you have a reference to the appropriate JimiReader or JimiWriter you can use the setProperty method to specify the value of the format specific option.  Although the appropriate values for the properties is normally found in the documentation you can determine at runtime which values are supported, and which options may be set by using the getPropertyNames and getPossibleValuesForProperty methods.

A few of the format specific options can be found in the Formats.html document that shipped with JIMI.  The Pro version of JIMI comes with a Formats.html document that replaces the Core version's document.

A subclass of JimiException, InvalidOptionException will be thrown if you specify a value for a property which is not valid for the format.

Here is code snippet that turns interlacing on when saving a GIF image.
 

 
    JimiWriter JW = Jimi.createJimiWriter("GIF");
    // Or preferably :
    //    JimiWriter JW = Jimi.createTypedJimiWriter("image/gif");
    JW.setProperty("interlace", Boolean.TRUE);
    JW.setSource(image);
    JW.putImage(out);
     

Loading Images from Multiple Image Formats

The means of accessing images from multiple image formats is to use the JimiReader.getImage(int num) method.  This method will return the requested image from the input stream.  The images are indexed starting at 0.  For InputStreams that support mark() and reset() it is possible to access images in any order, however in the cases where mark is unsupported a NoImageAvailException will be thrown if you attempt to get an image with a lower ordinal index than the greatest indexed image loaded so far.  Unfortunately it also means that you can not get the same image twice.  If you attempt to index an image which does not exist, a NoImageAvailException will be thrown.
(note: If a BufferedInputStream is used as the InputStream for decoding then the entire image in its raw undecoded will be buffered. Therefore this should be kept in mind and the JimiReader object with which this is used should be discarded as soon as possible to free that memory.)

The second means is used when you wish to get all of the images from the format one at a time in order.  The JimiReader.getImageEnumeration() method will return an enumeration for simple sequential retrieval of the images via the java.util.Enumeration interface.
 

Saving Images to Multiple Image Formats

Jimi.putImage is the primary mechanism for encoding single images, however there is no corresponding Jimi.putImage(Image[] images) method at this time.  [We felt that it would be convenient, but multiple images will normally require the use of format specific options anyway.  We may provide a corresponding Jimi.putImage(EncoderOptions, Object[]).]  Instead, you should create an instance of a JimiWriter using Jimi.createJimiWriter() and use the setSource(Object[]) method to provide the images to be encoded.  Each of the source objects must be either an Image or an ImageProducer, but they do not all need to be the same type.

In the following example we load a series of 10 GIF images, which are then saved as a single animated GIF image.

import com.activated.jimi.Jimi;
import java.awt.Image;
import java.io.File;
import java.io.FileOutputStream;
import java.io.BufferedOutputStream;

public class Example4 {

private static final int NUM_IMS=10;

public static void main(String[] args) {

Image img;
FileOutputStream fRawOut;
BufferedOutputStream fileOut;

/*

Load the images from files

*/

Image[] imgs = new Image[NUM_IMS];

for(int i=0;  i < NUM_IMS;  i++) {

    imgs[i] = Jimi.getImage("/ImageDirectory/aGIF_image" + i + ".gif");

}

/*

Create the output stream, and destination file for the
converted image
*/
fRawOut = new FileOutputStream(new File("/ImageDirectory/Animated.GIF"));
fileOut = new BufferedOutputStream(fRawOut);

/*

Save the image in the new file format
*/
try {
 
JimiWriter JW = Jimi.createTypedJimiWriter("image/gif");
JW.setProperty("gif image delay", new java.lang.Integer(100));
JW.setSource(imgs);
JW.putImage(fRawOut);
 
} catch(Exception e) {
System.out.println("Image write failed.  Error: " + e);
}
}

 FAQ

• What is the future of JIMI?

• What other formats does JIMI support?

In addition, the following formats may be loaded only :

    TIFF
    XBM
    RLE
    DIB
    XPM
    ICO
    CUR

More formats are being developed, along with better support for existing formats.  These formats will be released as extensions or incorporated into future versions of JIMI Pro.  You should expect to see CALS, and PCX very soon.

JIMI Core includes only support for GIF, JPEG, and PNG encoding and decoding.
 

• What format specific options are supported by these available formats?

• Can I use JIMI in an environment, such as servlets, or embedded java, that may or may not have an AWT?

• How efficient is JIMI?

• How do I add new format to JIMI?

We will also provide extensions of our own for JIMI.  If you are interested in supplying format for general distribution you can contact us at info@activated.com.  We are always looking to expand the functionality of JIMI.
 

• How do I access individual pixels using JIMI?

• How efficient is JIMI?

• How does JIMI cope with very large images?

• Are there other products as good, or better than JIMI?

Support

Conclusion