Java Image Server Technical Information

by Stephen Perry

Introduction

This document gives an overview of the technical aspects behind the Java Image Server. It includes information on how to start the server, how the various image formats are handled, and how to communicate with the server.

Starting the Server

The image server is started using the supplied script serve.sh. A number of paramaters can be passed into this script by setting the environment variables listed below to override the default values given to them by the script if they are unset.
JDK_HOME
Location of the Java installation. Defaults to /usr/java. When running under CYGWIN this path should be written using the MSDOS convection - for example C:\JDK1.1.8.
PORT_NUMBER
Port number that the server will listen on. Defaults to 9999.
FILE_CACHE_SIZE
Maximum size of the file handle cache. This relates to the name as passed into the server, and does not include any extra files which maybe opened to service the request (such as may occur with image sequences). Defaults to 500.
TILE_CACHE_SIZE
Maximum size of the tile cache. This should probably be set to be as high as possible within the memory available for maximum performance when serving multiple clients. Defaults to 500.
DEBUG
Flag controlling whether or not debugging information is turned on or off. Defaults to on - set to off to remove debugging output. This assumes that debugging has been left in the built server, which may not always be the case.
ROOT_DIRECTORY
The root directory out of which all image requests will be served. For example, if the root directory is set to /foo and the image bar.tif is requested, the actual image opened will be /foo/bar.tif. Defaults to C: when running under CYGWIN, and / otherwise.

Setting the variables above should be the only way in which the behavious of the server needs to be customised. The script assumes that a Java installation is present and working, with it's location specified in the environment variable JDK_HOME. Any further problems related to starting Java can usually be fixed by adding the Java interpreter to the PATH, and setting the CLASSPATH to include the location of the system class files. These are usually present in either $JDK_HOME/lib/classes.zip, or $JDK_HOME/lib/rt.jar.

Image Handlers

The base image server simply parses the IIP request and hands it to any of a number of image handlers, which are dynamically loaded when first required. The handler is responsible for opening the particular type of image, and returning image information and image tiles. The server sequentually calls the handler to fullfill each part of the request, caches any file handles and tiles, and returns the results to the client.

Each handler is represented by a Java class file, which is loaded into the JVM at runtime the first time a request is made for that particular image type. Each image type is identified by the extension given to the image name, and that is used to construct a name for the class to be loaded. For example, JPEG images are identified by a .jpg extension, which causes the server to load the IIPSrvJPGImageHandler class. Similarly TIFF images (.tif) and handled by the IIPSrvTIFImageHandler class.

Each of the currently availably image handlers are described in greater detail below.

JPEG Images

The JPEG image handler (IIPSrvJPGImageHandler) is a simple test handler that enables JPEG images to be viewed using the IIP viewer and server. It is not particularly fast and the JPEG compression/decompression is done entirely in Java, and is quite memory expensive as a decompressed version of each image must be kept in memory. Performance is adequate once enough tiles have been cached though. Given these limitations this module is not really meant for extensive use.

Tiled TIFF Pyramids

The TIFF image handler (IIPSrvTIFImageHandler) is invoked for images with a .tif extension, and consists of a piece of platform independant Java with a platform specific native library. The native code takes the form of a dynamically linked library which is loaded in to the JVM when it is first required. The library consists of code to extract and decompress/compress tiles from tiled TIFF images with JPEG compression, and as is simple wrapper around libtiff and libjpeg. Native libraries currently exist for Intel Linux, Solaris Sparc, Irix Mips, Windows 95/98, and Windows NT.

Tiled TIFF Pyramid Sequences

The Tiled TIFF Pyramid Sequence handler (IIPSrvTTPImageHandler) handles sequences of TIFF images as used by the ACOHIR system. Access to the TIFF images is handled in exactly the same way as described above, except that there is a translation layer which maps the requested filename and frame number to a new filename using the ACOHIR naming convention. The module keeps an array with an entry for every image in the sequence, opening and caching each as necessary.

Java Tiled Image Pyramids

Support for this format as used by the LRMF is problematic for a number of reasons, not least of which is the apparent confusion over the naming of the images themselves. The module is currently under development.

Communicating With The Server

Once the server has been started, there are two ways main ways of communicating with it - directly, and using the Java viewer. To communicate directly, send IIP commands using GET to the server. This can be useful for checking that the server is working correctly. For example, to find out the maximum size of the image foo.tif the following URL could be used:
    http://localhost:9999/iipsrv?fif=foo.tif&obj=max-size

To return the toplevel tile from an image the following could be used:

    http://localhost:9999/iipsrv?fif=foo.tif&jtl=0,0
Using the Java viewer is the usual way to access images using the server. The server also functions as a full Web server, and is capable of transfering HTML content and class files directly to the browser for local execution. Although easy to customise, the easiest way to get an image into the browser is to use the standard frontpage iipview.html. This takes an image name as a parameter and uses some Javascript to create the Web page with an applet to view the appropriate image. The browser then downloads the class files for the viewer, and starts the applet which then begins to talk IIP to the server. URL's to access images in this way often look like:
    http://localhost:9999/iipview.html?imageName=foo.tif

A similar technique is used to access image sequences, except that an imageSequence argument is used in place of imageName. For example, to access the lladrocal sequence, the following might be used:

    http://localhost:9999/iipview.html?sequenceName=lladrocal.ttp