IIIF Configuration (Draft)

Overview

DSpace supports the International Image Interoperability Framework (IIIF). The DSpace REST API implements the IIIF Presentation API version 2.1.1, IIIF Image API version 2.1.1, and the IIIF Search API version 1.0 (experimental). The DSpace Angular frontend uses the Mirador 3.0 viewer. Administrators have the ability to configure IIIF behavior at the Collection, Item, Bundle and Bitstream levels using metadata. To support sharing, viewing, comparing, manipulating and annotating of images, DSpace can be configured to share IIIF metadata with external IIIF clients (see CORS Configuration).

Required DSpace Configuration

DSpace IIIF support is not enabled by default. To enable IIIF, make the these changes to your DSpace configuration.

To enable IIIF, first edit modules/iiif.cfg or your local.cfg file and set iiif.enabled to be "true".

iiif.enabled = true

In addition, you need to provide the URL for your IIIF image server. e.g.:

iiif.image.server = http://localhost:8182/iiif/2/

Finally, update dspace.cfg or your local.cfg file by adding "iiif" to the default event dispatcher, as shown below:

event.dispatcher.default.consumers = versioning, discovery, eperson, iiif

With these changes in place, DSpace will be ready to respond to IIIF requests.

Additional Configuration Options

The full set if IIIF configuration options can be found in config/modules.iiif.cfg. 

Metadata Settings

IIIF configuration at the Item level is quite flexible and is managed using metadata. Canvas sizes, image labels, ranges and and other settings are controlled by using the following fields.

Adding the Mirador Viewer

The Mirador 3.0 viewer is included in the DSpace Angular source.  Before enabling Mirador, be sure to review the instructions for installing the Angular frontend if you haven't already.

To add the  Mirador viewer to your DSpace frontend installation, run the following command:

yarn run build:mirador

This will build and copy Mirador to your dist/ directory.

The actual steps for running the frontend with Mirador in production will likely vary with your setup. However, one possible command-line scenario is the following:

yarn run build:mirador
yarn run build:prod
yarn run serve:ssr

Configuring Mirador

The Mirador viewer is highly configurable. The Mirador configuration file for DSpace includes a number of settings that you can override manually, including CSS values for styling. Note that some of the Mirador behavior (like the inclusion of thumbnail navigation on the right) is set by the Angular component at runtime. You can choose to override these runtime settings if you like. 

Adding an Image Server

The Cantaloupe Image Server is currently recommended for use with DSpace, but you are free to use the image server of your choice. A list of IIIF-compliant image servers is maintained by the IIIF community.

Here is a brief overview of how the IIIF image server works with DSpace.

First, the base path to the image server is defined in config/modules/iiif.cfg.  

iiif.image.server = https://imageserver.mycampus.edu/image-server/cantaloupe/iiif/2/

Given this configuration, when the Mirador client requests an IIIF manifest from the DSpace backend that manifest will include an image resource annotation like the following:

resource: {
	@id: "https://imageserver.mycampus.edu/image-server/cantaloupe/iiif/2/4b415036-57a8-42f4-a971-c5e982f55f92/full/full/0/default.jpg",
	@type: "dctypes:Image",
	service: {
		@context: "http://iiif.io/api/image/2/context.json",
		@id: "https://imageserver.mycampus.edu/image-server/cantaloupe/iiif/2/4b415036-57a8-42f4-a971-c5e982f55f92",
		profile: "http://iiif.io/api/image/2/level1.json",
		protocol: "http://iiif.io/api/image"
	},
	format: "image/jp2"
}

The Mirador viewer uses this annotation to retrieve the image. This example assumes that the image server (in this case, Cantaloupe) responds at the image server base URL provided in config/modules/iiif.cfg.

Finally, notice that the image server needs to retrieve the requested bitstream from DSpace. There are a number of ways to do this and the details vary with the image server chosen. The easiest approach is for the image server to request the bitstream via HTTP and the DSpace API, using a URL like http:/dspace.mycampus.edu:8080/server/api/core/bitstreams/4b415036-57a8-42f4-a971-c5e982f55f92/content

Installing and Configuring Cantaloupe

The Cantaloupe getting started page provides installation instructions. The basic installation process is simple.

The simplest way to configure Cantaloupe to retrieve images from DSpace is to use HTTPSource with the following configuration.

HttpSource.BasicLookupStrategy.url_prefix = <dspace-url>/server/api/core/bitstreams/
HttpSource.BasicLookupStrategy.url_suffix = /content

CORS Configuration

By default, the DSpace IIIF backend is configured to accept requests from the Angular client origin. To support the type of sharing that IIIF facilitates you can configure addtional CORS origins using the iiif.cors.allowed-origins property defined in iiif.cfg. Currently, DSpace does not support the "*" wildcard but you are free to add multiple, comma-separated origins to the list.

Search API

DSpace 7.1 includes a plugin to support the IIIF Search API. This plugin is designed to work specifically with the Solr OCR Highlighting Plugin and METS/ALTO data. You are welcome to experiment with this plugin. To do so,uncomment the following settings in config/modules/iiif.cfg:

iiif.search.url = ${solr.server}/word_highlighting
iiif.search.plugin = org.dspace.app.rest.iiif.service.WordHighlightSolrSearch

Once you have successfully indexed ALTO files using the Solr plugin, you can enable the search API for a DSpace Item by adding the iiif.search.enabled metadata field.