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