IIIF Configuration

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 can configure IIIF behavior at the Collection, Item, Bundle and Bitstream levels using metadata. To support additional sharing, viewing, comparing, and annotating, DSpace can be configured to share IIIF metadata with external IIIF clients (see CORS Configuration). IIIF REST endpoints implement the same security protocol as the primary REST API so that DSpace authorization policies are enforced for IIIF access as well.

Format Support

Currently, DSpace only supports IIIF viewing of Image formats (any format whose MIME type starts with "image/*").  For example, PDF viewing is not currently supported.

Enable IIIF Support on Backend

Install a IIIF 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, the IIIF manifest returned by the DSpace backend 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 (see below) uses this annotation to communicate with the image server using the IIIF Image API.

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, e.g.:

 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

Required IIIF Configuration

To enable IIIF, edit config/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 newly installed 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.  Restart your DSpace backend (i.e. Tomcat) for these changes to all take effect.

Additional Configuration Options

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

CORS Configuration

The wildcard "*" configuration is the default CORS setting for IIIF. With this setting, all remote viewers and applications can retrieve manifests, assuring maximum interoperability. You can restrict CORS origins using the iiif.cors.allowed-origins property defined in iiif.cfg. Remove the wildcard and add a comma-separated list of origins instead.

IIIF Search API

DSpace 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 the 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 search within a DSpace Item by adding the iiif.search.enabled metadata field. 

Enable/Install the Mirador Viewer on Frontend

The Mirador 3.0 viewer is included in the dspace-angular (UI) source code.  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:

# This builds and runs the DSpace UI with the Mirador Viewer in a single step
yarn run start:mirador:prod

This will build and copy Mirador to your dist/ directory and start the frontend server.

The actual steps for deploying the Angular UI with Mirador into Production will likely vary with your setup. However, one possible command-line scenario is the following:

# Build Mirador viewer
yarn run build:mirador
# Build DSpace UI for production
yarn run build:prod
# Run the DSpace UI with Mirador viewer
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. 

Configure IIIF viewer via Metadata Fields

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.