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.

The Presentation API offers a specific implementation challenge because the data contained in a manifest file may need to come from more than one system within an institution. The curation of image files is often delegated to a generic Digital Asset Management system (DAM) separate from the database used to curate specimens in the collection. The DAM may be capable of exposing images using the Image API but not have the information needed to populate the labels in the Presentation API, data which is stored in the collection database. Likewise the collection database may have all the information for the labels but not know the dimensions to size the canvases. The system that publishes the Presentation API to the internet must be able to pull this information from wherever it is stored in the institution and this will require collaboration between systems and the people who run them.

Recommendation: At an early stage in implementation make sure that the people responsible for the relevant systems are involved and that they have the technical skills required. Pulling the data together shouldn’t be technically challenging if the right people are involved.

Caution: Terminology can be confusing. The word manifest is used as a name for just about all Presentation API response documents. This is because usually there is one Manifest representing a single real world object in each file. But this is not always the case. A manifest file (response from the API) might contain Collections and multiple Manifests. Here Manifest (capital M) is used for the object and manifest (small m) is used in the loose sense of a IIIF Presentation API document.

Search API

Some IIIF objects (Manifests, Collections and Ranges) can contain large amounts of text. IIIF representations of books and newspapers are perhaps the examples that jumps to mind for this but even simple IIIF objects may contain multiple textual annotations. An image may have been OCR’d or transcribed and this text translated or interpreted by multiple scholars. There are therefore occasions where the user may want to search within a IIIF object. The Search API enables this.

Recommendation: Typical Natural History specimens have little text associated with them. Unless you have users who specifically require this functionality or are publishing manuscripts it is probably best to ignore the Search API during the initial roll out of IIIF.

Authentication API

Open access to content is desirable, but internal policies, legal regulations, business models, and other constraints can require users to authenticate and be authorized to interact with some resources. In IIIF this might also include access to certain zoom levels, adding watermarks to content or other measures. The IIIF Authentication API provides a guide to integrating existing authentication/authorisation systems within the IIIF viewer experience.

Recommendation: It is unlikely that the Authentication API will be needed during initial implementations of IIIF on Natural History collections because collections tend to default to open access. An exception is the obfuscation of location data on endangered species. This is already addressed by most collections only providing access on request to these records rather than requiring authentication for their whole collection. The Authentication API may be of importance in future rounds of implementation.

Change Discovery API

A Change Discovery API service describes changes to IIIF content resources and the location of those resources to harvest. Content providers can implement this API to enable the collaborative development of global or thematic search engines and portal applications that ultimately allow users to easily find and engage with content available via existing IIIF APIs. Change Discovery API is the most recent API to become stable (Version 1.0)

Recommendation: As discussed in the introduction the Natural History community has multiple metadata standards for aggregating specimen metadata. At this stage the Change Discovery API therefore seems redundant for our needs though may form a part of future network infrastructure.

Content State API

The Content State API provides a way of describing a Presentation API resource, or a part of a resource, in a compact format that can be used to initialize the view of that resource in any client that implements this specification. It provides the format of the “content state”, and mechanisms for passing it between applications regardless of their user interfaces and capabilities.

Recommendation: The Content State API is still in Beta so it is not recommended for adoption at this point, unless it meets specific current needs.

Three Dimensional Models

Discussion here is focussed on two dimensional media. This is partly due to the predominance of herbaria within the project but also the current dominance of two dimensional images across many subdomains of Natural History. It is easier to start with flat photographs of objects and so that is what has been done. As it stands the IIIF Presentation API allows multiple views of three dimensional objects to be presented and related to each other. It is possible to present, for example, the dorsal, ventral, lateral views of an insect or focus stack slices from a diatom in a single manifest to great effect. There is, however, also active development in the IIIF community to bring true 3D modelling into the standard and an official community group to steer this.

Recommendation: If you have an interest in 3D modelling on Natural History objects using IIIF it may be worth joining the IIIF 3D Community Group.

Time Based Media

Most Natural History museum objects are static and can be represented by one or a few still images. Version 3 of the IIIF Presentation API does however support integration of time based media such as audio and video recordings and canvases can have durations as well as heights and widths. This has tremendous potential for publishing richer data sets such as timelines and annotated audio and video recordings. Unfortunately this is beyond the scope of this introductory document but there is an active IIIF A/V Community Group who may be able to provide support.

Recommendation: If you have an interest in time based media consider joining the IIIF A/V Community Group.

Back to IIIF Home