IIIF: Unshackle your images

Andy Cummins, Cogapp, UK

Abstract

Keywords: IIIF, images, standards, APIs

1. Introduction

This paper captures a how-to session on the International Image Interoperability Framework (IIIF). I will describe the current state of image delivery on the Web and the problems inherent therein. I will then discuss IIIF and how it can help you deliver your images on the Web in a flexible manner using modern software.

The problem

The current state of image delivery on the Web is one of those things that we have all learned to live with. In terms of both creation and consumption, it’s broken; we can do better.

Creation

When developing a website, one job we’ll need to do sooner or later is create image derivatives.

For example, if we decided to build a new online collection for our museum, we would decide on our image sizes and implement a process to create these derivatives. We might choose to have a large image, a medium-sized image, and a thumbnail. If we added new objects to our collection, we’d update our image set. If we decided we needed a new image size, we’d reprocess the entire set to create this new derivative and copy them up to our Web server.

This is a lot of work. It’s error prone, it’s slow, and it’s restrictive in terms of creativity; it makes change, aka innovation, difficult.

Consumption

We consume images online everyday. We’re trained to work around the obstacles that have become invisible to us. If we want to use a specific image, it has to be the size we need; if the one we want doesn’t match the dimensions required for our purpose, we compromise. We either choose a less-appropriate image or go with the original choice and compromise on quality. Think of all those images you’ve seen that are stretched, squashed, upscaled, or just plain tiny.

It doesn’t need to be like this.

2. A solution

The solution that I’m putting forward in this paper is to use IIIF. The International Image Interoperability Framework allows us to request images and associated metadata in a standardised way. We can request images at the dimensions we require and also request associated metadata.

IIIF was proposed in 2011 and came from the world of libraries and universities. The first institutions involved were the British Library, Stanford University, the Bodleian Libraries, the Bibliothèque nationale de France, Nasjonalbiblioteket (National Library of Norway), Los Alamos National Laboratory Research Library, and Cornell University.

The framework is a great example of international collaboration to create something of true value for the wider community and in this case the wider world. A combination of rigour and pragmatism has led to a focused, easily understood framework that can be applied to any discipline where images are of importance.

The APIs

IIIF currently has two parts: the Image API and Presentation API. These combine to solve the problems outlined earlier in this paper.

Image API

The Image API deals with the actual delivery of binary images in a flexible, convenient manner. Through this API, we can request images at our desired dimensions, crop, rotation, quality, or format.

This means that through URL parameters we can specify exactly the derivative of the image we require. No longer do we have to choose between a limited set of derivatives; we don’t have to download and then crop or rotate in Photoshop. We can ask for the image as we require it, and it will be delivered as specified.

The IIIF Image API URI for requesting an image must conform to the following URI template:

{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}

Some specific examples with the pertinent parameters in bold would be:

• Full image, resized to a maximum side-length of 200 pixels (http://images.qdl.qa/iiif/images/81055/vdc_100000001524.0x000395/Mss+Eur+F126_10_0001.jp2/full/!200,200/0/default.jpg):

• The same image, rotated by 90 degrees (http://images.qdl.qa/iiif/images/81055/vdc_100000001524.0x000395/Mss+Eur+F126_10_0001.jp2/full/!200,300/90/default.jpg):

• The same image, zoomed in, and cropped to a specific region (http://images.qdl.qa/iiif/images/81055/vdc_100000001524.0x000395/Mss+Eur+F126_10_0001.jp2/700,300,800,600/!200,200/0/default.jpg):

Full details on the URI syntax can be found on the IIIF website: http://iiif.io/api/image/2.0/#image-request-parameters. More examples can also be found at http://www.qdl.qa/en/image-options

How do we achieve this utopian image heaven?

To live the dream outlined above, we need two things:

1. Source images as large as we have them in an appropriate format
2. An image server to convert the source images on the fly

Source image format

Two image format options are currently supported by servers: Pyramidal TIFF (PTIFF) or JPEG2000 (JP2).

Both compressed formats contain copies of the image at different resolutions. This characteristic makes them ideal for creating our image derivatives on the fly. It enables the conversion to be performant enough for delivery over the Web.

Fair disclosure here: one drawback of choosing the JP2 format is that, although the format itself is an open standard, the best software in terms of decoding, and possibly encoding as well, is proprietary. This software is called Kakadu and is available from http://kakadusoftware.com. There is no standard pricing model for this software; you will have to get a quote if you decide to use it.

If you are set on JP2 as your source image format, there is the OpenJPEG codec to help with encoding and decoding. Currently, the performance of this codec isn’t up to the on-the-fly nature of decoding required for image delivery over the Web.

If you want a free performant option, we would suggest the use of Pyramidal TIFFs. When used in conjunction with a high-performance image server, this format will give you the performance required to implement IIIF.

Processing images into these formats

To process images into these formats, we have successfully used the open source ImageMagick library. Other image toolkits can achieve the same result, but this worked well for us and is free from any licensing requirements.

Image server

Once you have decided on a source image format, you will need to choose the software that will convert your source images to those that your user has requested. For example, if your user has requested a crop at a given size, you need an image server to take the source image and create the requested derivative on the fly.

Several options are available to you; a full list can be found on the IIIF website: http://iiif.io/apps-demos/.

The most mature of these options is IIPImage Server. Employing this server gives you the comfort of knowing that there is a wide user base with all the benefits that the community provides in terms of documentation and avenues for help.

IIPImage Server is open source and extremely performant, and supports both PTIFFs and JP2s as source images.

Installing IIPImage Server

Installation of IIPImage Server is relatively pain free. There are binaries for installation on Windows and Mac. If you use Linux, depending on the flavour and version, packages are available through the apt and yum package managers. Alternatively, there are packages for download on the IIPImage Server site: http://iipimage.sourceforge.net/download/.

Hosted option

If you would prefer your image server to be hosted on a third-party service, there is the reasonably priced offer from http://www.iiifhosting.com/. Their monthly pricing is based on the storage required for your images. It ranges from $69 for around 15,000 images up to $399 for 1,500,000 images.

There are a few other options in the pipeline; for example, major aggregators like the DPLA and Europeana are also planning on providing IIIF hosting platforms.

Presentation API

The Presentation API deals with the metadata associated with the images that are being delivered. It provides the information needed to understand what the image is and what it represents. It also gives information about how a particular image relates to other images in a set (e.g., pages of a book) or multiple images of a work of art (e.g., x-ray or raking light images).

Originally, the Presentation API was going to be called the Metadata API. This was changed to ensure that focus was maintained on the reason for the API existing: to enable the effective delivery and understanding of the images being delivered by the software that was presenting them. With this in mind, the Presentation API name was finalised.

What the Presentation API helps us achieve is fundamental to unlocking some of the major benefits of IIIF. With the API providing metadata about the images in a consistent manner, we can use software to leverage the potential within our images and metadata.

Below is a link to an example manifest file that adheres to the IIIF specification (http://iiif.io/api/presentation/2.0/) (http://www.qdl.qa/en/iiif/81055/vdc_100000007136.0x000001/manifest).

How do we deliver these manifests?

The infrastructure needed to deliver the metadata manifest files is much simpler than that required to fulfil the Image API. Chances are your organisation already has the necessary infrastructure.

Each institution is different, and as such there isn’t a one-case-fits-all solution for the Presentation API. To deliver the manifest files, a custom implementation will be needed, although this need not be overly complex.

For example, if your institution already has the metadata online in some form (e.g., driving an online collection), then most of the work is already done. All you need to do is take the data that is presented in your collection and have it output as JSON according to the IIIF specification.

Why bother with manifests?

The manifests contain all the metadata on a resource and the associated images. They also help to link images together for a resource in terms of sequence, for example.

Having this information available in a predictable, standardised form allows us to build software to interpret that information and present the images and information.

One area of software being developed that stands out is image viewers. A collection of viewers has been developed to take advantage of IIIF, and they each have their strengths and applications.

The most powerful of these viewers is called Mirador (http://iiif.github.io/mirador/). Mirador is an open-source project jointly run by Stanford University and Harvard University in collaboration with many other contributors.

Mirador is an extremely powerful image viewer that allows users, in particular digital scholars, to really get to work on your images (e.g., http://labs.cogapp.com/iiif/#13f8bfa4-b0af-4b7a-b822-e99253a3defa).

Available features include:

• Deep-zoomable images
• Side-by-side comparison of images
• Annotation creation and viewing
• Metadata display
• Bookmarking

An alternative to Mirador comes in the form of Universal Viewer (https://github.com/UniversalViewer/universalviewer). This viewer is also extremely powerful, and the choice between this and Mirador is down to the intended user and their preference (e.g., http://labs.cogapp.com/iiif/universal-viewer.html#?si=0&ci=0).

A third viewer that is widely used is the Internet Archive Book Reader. You may be familiar with this viewer. This has the simplest interface of the three I am going to mention here, and again its use depends on the target audience (e.g., http://labs.cogapp.com/iiif/iiif-book-reader.html).

By applying IIIF in your institution, you enable the use of community-built software like the viewers described above and other IIIF compliant software. The key to take away from this is that all of these viewers are interpreting IIIF data, so they are interchangeable. This empowers your users to choose the software they prefer most for the task at hand.

How do I actually get these viewers in front of my users?

There are a couple of options. The first is the most simple. Just provide a link to your manifest file somewhere online. A user can then drag and drop the link onto the viewer they prefer. This option assumes your users are somewhat informed and can load up a viewer in their browser to drag your link onto it.

A second option is to embed the viewers in your site. This is the more complicated of the two options but is not a complicated process in itself. This would involve adding the code for the viewers into your site’s template files and implementing the code to render the viewers on your site.

3. How does implementing IIIF directly benefit my organisation?

Future-proofing your image pipeline

Implementing IIIF results in a flexible and dynamic image-delivery platform. This helps to future-proof the delivery of your assets. By removing the restrictions on size and the crop of the images you are delivering, you keep all options open for future use of those images.

A concrete example of where IIIF would help is the redesign of pages on your website. For example, a mobile implementation or simply a redesign for aesthetic reasons would not be restricted in terms of image sizes. This allows for faster, more cost-effective development.

The same applies to any development based on, for example, your collection. With IIIF in place, you already have a flexible image pipeline in place for new projects.

Streamlining your communications

The use of imagery in any communication channels you might have (such as your blog, your Facebook page, mail outs, and so forth) will be given a turbo boost in terms of production time. Anyone on your team with minimal training will be able to construct a URL that will create the perfect crop, zoom, or size they need for their Medium article or Instagram post. There would be no more Photoshop hassle for your content creators. They wouldn’t have to upload images directly to your blog. They will be served directly from you IIIF image server, reducing duplication and maintaining quality.

Advanced features for free

With IIIF, you receive some advanced features straight out of the box. These include:

• High-performance deep-zoom through OpenSeadragon or other libraries
• A choice of viewers, including those mentioned earlier
• Interoperability: you can open up your images to being used by others in ways that would not be possible otherwise

4. Enabling innovation

As mentioned, IIIF gives you a sound basis for extremely performant, flexible delivery of images on the Web. This flexibility opens the door to innovation. Below are some examples of how IIIF has been leveraged to create unique online experiences.

The Digital Mushaf

This pulls together Mushaf pages that are dispersed across various libraries into a single online resource (http://digitalmushaf.bodleian.ox.ac.uk).

Cantus Ultimus

This optical musical recognition project allows you to search a musical manuscript for sequences of musical notes to return an image crop of those notes (http://cantus.simssa.ca/manuscript/133/?folio=018v).

Transcriptinator

This Cogapp-developed proof of concept for crowd-sourced transcription validation was developed to run on an arcade machine in the British Library (http://labs.cogapp.com/transcriptinator/).