Now serving all page images via djatoka

Last fall developers Ryan Chute and Herbert Van de Sompel from Los Alamos National Laboratory’s Research Library released djatoka, a new Open Source JPEG 2000 image server. This new project, first reported in D-Lib Magazine, provides a scalable and open solution for delivering high resolution JPEG 20000 images, such as the (nearly) 11 million pages scanned to date and made available through the Biodiversity Heritage Library.

This development was greeted with cheers by the BHL Technical Development Team, as it solves problems we’ve previously reported with the non-scalable, proprietary solutions used to serve JPEG 2000 images. Following a functional evaluation in December 2008, djatoka was integrated into the BHL staging site for performance testing and was promoted to production on Thursday, January 22, 2009.

To view djatoka in use on BHL materials, check out the following page from “Wild oxen, sheep & goats of all lands, living and extinct” by R. Lydekker published in 1898, selected in honor of the Chinese New Year, in this, the Year of the Ox:

View Full Size Image

JPEG 2000: An excellent format with poor support
Displaying JPEG 2000 images on the web can be a challenge because 1) the images are often too large to be downloaded quickly, 2) most web browsers don’t understand JPEG 2000 images without appropriate plug-ins, and 3) until the release of djatoka there were no active open source image servers; costly commercial solutions were the only option, aside from complete custom development.

JPEG 2000 images are different from traditional image formats like GIF, JPEG, and PNG in that they consist of several “layers”, one for each available resolution. Think of JPEG 2000 images as a pyramid – each layer of a JPEG 2000 file is a copy of the same image, each at progressively larger size as you step down the pyramid. The top layer may be relatively small but the bottom layer could be quite large. Consider a JPEG 2000 image whose bottom layer is 18,000 pixels square, such as this example. To view this image in its entirety using standard 1024 x 1280 monitors would require an array of 270 monitors stacked 15 high and running 18 wide! Cool, yes, but impractical.

So, to deliver JPEG 2000 images to web users, scalable software is needed to carve up the JPEG 2000 image into smaller chunks at a given resolution in a format natively understood by a users’ browser. And, since we are talking about this occurring during the load time of a web page, all of this has to happen very quickly.

BHL’s first approach to JPEG 2000 delivery
BHL has delivered JPEG 2000 images to users since its public launch in February 2007 using a mix of proprietary and open source technologies. BHL development activities are organized at Missouri Botanical Garden (MOBOT), whose Botanicus digital library system was an early prototype for BHL. Guided by previous work by MOBOT developers, and reusing the infrastructure already in place at MOBOT, BHL developers integrated LizardTech’s ExpressServer for server-side JPEG 2000 tiling and the open source GSIV javascript library for interface display.

Though functional, the addition of BHL’s 1,500 users per day pushed ExpressServer beyond its available capacity, causing a significant delay in delivering page images. Since it is a commercial solution, and one that is licensed by processor, to increase capacity would require the purchase of an additional ExpressServer license, costing upwards of $15,000USD. An open source option was needed, but none was available until the release of djatoka.

About djatoka
djatoka (pronounced jay-too-kay) uses the Kakadu library to process and present JPEG 2000 images. It is a Java-based web application that runs on Apache Tomcat. djatoka allows a web page to perform an asynchronous request to get image parameters, such as maximum size of the image or the number of resolution levels available. The web page can then execute some javascript to request the necessary image tiles from djatoka and arrange them within the browser to form a larger composite image, similar to the now ubiquitous Google Maps interface.

djatoka provides a streamlined API for developers to script against to generate and assemble the image tiles. Further, the existing IIPImage Javascript Viewer has been modified to work with djatoka, relieving potential adopters of the significant burden of writing complex code to calculate, request, and assemble necessary tiles. IIP also provides interface functionality that enables the user to pan around the image and zoom in or out.

For detailed information about djatoka, including source code for download, visit:

djatoka in BHL
djatoka offers a rich user interface through integration of the IIPImage JavascriptViewer.BHL already had an existing interface for delivering images that tested well with users, so our goal was to use djatoka as a drop-in replacement for ExpressServer without affecting end user functionality. With those objectives in mind, we made the following changes to IIPImage and left the server alone; it’s running pretty much in its default state save for some caching options we customized.

djatoka brought with it some improvements to our user interface:

  • Preview thumbnail. This allows a user to see which portion of the overall image is being viewed. This also lets the user easily view different parts of the image by simply dragging the control to the desired part of the image.
  • Simplified zoom controls. With our djatoka implementation we got rid of the radio buttons formerly used to zoom in and out and replaced them with plus and minus buttons.

Some changes we made to the djatoka viewer are as follows:

  • We needed to retain the Save and Print image features from the previous image viewer. Therefore, we rolled these into the djatoka viewer.
  • BHL defaults to serving a single low resolution JPEG images, when available, and only escalates to more costly JPEG 2000 processing when instructed by the user. We made the djatoka viewer friendlier toward raw JPEGs. djatoka itself handles raw JPEGs with aplomb.
  • We removed a text box that provides a way to embed a Region Of Interest (ROI), or “slice,” of the image as tiled by djatoka. While this is a very useful feature, we felt the current implementation consumed too much screen space of the visible page image. We plan to reintroduce this in a less obtrusive manner.

In the end, we were successful in creating a drop-in replacement for the existing viewer. We didn’t drastically change our user interface but still managed to make significant improvements. We chose an evolution this time around; the revolution has been carefully scheduled for another date.

Towards a scalable infrastructure
BHL developer Phil Cryer has written an excellent and detailed blog post about the technical infrastructure devised to provide scalability and fault tolerance to our djatoka implementation. It is available at

Future work
While we are happy with our initial implementation of djatoka, we have already planned some future enhancements and have begun discussions concerning priorities with the djatoka development community, including lead developers Chute and Van de Sompel. These enhancements are as follows:

  • An embed image link. This will directly replace functionality we removed from our implementation of the djatoka viewer. Drawing from similar features elsewhere, we are leaning toward a clickable link icon which pops up a box which contains a URI for the image as the user is currently viewing it.
  • The current djatoka viewer is based on an old version of MooTools. Newer versions of MooTools are not compatible with the djatoka viewer. We’d like to fix this so that it’s easier to drop into a website that uses a current or future version of MooTools. This will allow us to use a newer and more flexible version of this useful code library, and will allow others to reuse our work more easily.

Currently, our changes to the djatoka viewer are pretty specific to the BHL. In the spirit of Open Source, we will make these enhancements available to the community. We have the goal of making the viewer generic enough so that it can be used without major customizations, and we will be considering several use cases for our work.

As described above, djatoka has easily integrated into the production BHL infrastructure and user interface with minimal effort. It has nullified problems that existed with the previous, proprietary solution used to deliver JPEG 2000 images, and thus far has performed without significant error or delay since being promoted into production at Because this is an open source solution, BHL can easily scale up without significant expense should we require additional capacity. Our experience implementing djatoka has been overwhelmingly positive, and we would encourage any project currently serving JPEG 2000 images to evaluate its features and functionality within your infrastructure.

If you’d like to learn more about djatoka visit the main web site or get the code from SourceForge. Join the listservs to become an active member of the djatoka development community, as the lists are the best source of current information and have an active user base. Finally, please leave comments or feedback about our specific implementation of djatoka in BHL using the Comment form below.

Chris Freeland, BHL Technical Director
chris.freeland (at)

Chris Moyers, BHL Developer
chris.moyers (at)

Avatar for Chris Freeland
Written by

Chris Freeland served as the BHL Technical Director from 2006-2012. He is currently the Director of the Open Libraries program at Internet Archive. In this capacity he works with libraries & publishers to digitize their collections, working towards the Archive’s mission of providing “universal access to all knowledge.”