IIIF Framework

Part of IIIF Pages

It can be daunting for a newcomer to reach an understanding of what IIIF is as it consists of a series of technical and social components working together towards three goals (from the IIIF website):

• To give scholars an unprecedented level of uniform and rich access to image-based resources hosted anywhere.
• To define a set of common application programming interfaces that support interoperability between image repositories.
• To develop, cultivate and document shared technologies, such as image servers and web clients, that provide a world-class user experience in viewing, comparing, manipulating and annotating images.

The four components that make up IIIF in the broad sense are:

1. Technical standards in the form or Application Programming Interfaces (APIs).
2. Software applications including image viewers, server components and scripts that run in the background to publish image data.
3. The IIIF Consortium (IIIF-C), a membership organisation that provides steering and sustainability for the IIIF community. It comprises more than 40 Founding Members who have committed to support the growth and adoption of IIIF. It has a small paid staff and is most visible in organising workshops, conferences and training events.
4. The IIIF community which includes the adopters, users and developers of IIIF standards and software. By extension, dear reader, that includes you.

Here we will mainly discuss IIIF in the narrow sense of the APIs and software but these are just the concrete manifestation of the collaboration between individuals and institutions who maintain them. There are currently six distinct APIs. Below is a brief outline of what they do and how they interact with each other. The specifications themselves are quite accessible and provide full descriptions of each API.

Recommendation: The most recent versions of the APIs are Version 3.0 for Image and Presentation and Version 1.0 for Authentication, Search and Change Discover. Adoption of these most current versions of APIs is recommended. Earlier versions are not discussed here.

IIIF APIs - Summary

Images are exposed to the world through a set of APIs. The Presentation API describes what the images are and how they relate to both each other and the object they are of - so a human knows what they are looking at. The Image API provides the pixels to display on the screen. The Search API makes it possible to find text within objects like books. There is an Authentication API in case you need to control who can see what and a Change Discovery API to keep track of modifications to big collections. The new kid on the block is the Content State API that enables you to direct someone to a particular place within a complex multimedia object.

But, as the Wizard Gandalf might say, “The one API to rule them all, the one API to find them, the one API to bring them all, and in the darkness bind them” is the Presentation API.

Image API

The Image API defines how a client application can retrieve the pixels of an image to display. It is similar to other image server APIs. Two types of call are specified. One returns a simple JSON based description of the image, such as its pixel dimensions, the other defines the syntax of a URI. This syntax can specify the region, size, rotation, quality characteristics and format of the image to be returned.

One of the main uses of the Image API is to provide a tile service whereby the original image is divided into sub-images at various resolution levels. This allows the client application to zoom the image without downloading the whole file from the server.

An important feature of the Image API is the notion of Compliance Level. Although a suite of image manipulation features are specified, installations can implement a subset of these features and still be compliant. Level 0 compliance can be achieved with only static files and no dedicated software at all.

OpenSeadragon is a popular image viewer that can read image tile services provided by IIIF.

If IIIF only consisted of the Image API then it would not have made such a significant contribution to sharing images online. Image servers have had similar REST APIs for many years. Where IIIF goes further is in the Presentation API.

Recommendation: Because the Image API is so similar to APIs already provided by image servers it may be a good first step on the path to deploying IIIF on your collection. An existing image server may support publishing as IIIF Image API already (see the IIIF website for examples ) or a wrapper script could be written to translate between the two (as is done for Djakota and FSI Servers)

Caution: Don’t stop here! It may be tempting to flick the switch on an image server to enable the Image API and feel the job is done but without the Presentation API in place the Image API offers few advantages over regular image servers. The minimum needed to integrate with others is to have both the Image API and the Presentation API running.

Presentation API

The IIIF Presentation API specifies how multiple images (and other media and data) relate to a real or virtual object and to each other. If we consider the case of a field notebook containing hand written observations associated with specimens in a museum. It may have many pages. The handwriting may not be legible to the unfamiliar and so providing a transcription is important. It may be desirable to provide translations to other languages and scholarly interpretation to make it useful for other researchers. The ordering of the pages and layering of annotations onto these pages isn’t possible from a simple image server but requires some way to specify the relationships between these different pieces of data. This is what the Presentation API enables. From the specification:

“A compound object may comprise a series of pages, surfaces, or extents of time; for example the single view of a painting, the two sides of a photograph, four cardinal views of a statue, the many pages of an edition of a newspaper or book, or the duration of an act of an opera. This specification addresses how to provide an order for these views or extents, the references to the resources needed to present them, and the descriptive information needed to allow the user to understand what is being seen or heard.”

The syntax of the Presentation API is JSON-LD which combines the now ubiquitous JSON data exchange format with Linked Data principles. The result is a format that can be parsed by commonly available software libraries on all platforms and is also easy to interlink with other data. In addition to this the current version (3.0) has incorporated the W3C Web Annotation Data Model (with some caveats around the label property) allowing for extension and integration with generic annotation servers.

The data model (Figure 2) can appear daunting at first but is easily summarised.

1. Manifests represent real world objects such as specimens or books.
2. Collections define sets of Manifests and other Collections.
3. Canvases are views of the object such as pages, sides, angles, different times.
4. Ranges order Canvases such as page order.
5. Annotations represent everything else. An image from an Image API service will be attached to a canvas as an annotation of that canvas. Text notes will be layered on in the same way. Annotations are further organised into pages and collections.

See the full specification for a more detailed explanation of the structure.

Presentation API Data Model (from version 3.0 specification)

Back to IIIF Home