Page History
Table of Contents |
---|
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).
Info | ||
---|---|---|
| ||
Running IIIF in production requires an IIIF-compatible image server. You are free to use any compatible image server you choose. However, instructions for configuring the Cantaloupe Image Server are included below. A preconfigured Cantaloupe image server is included in the Docker build to simplify evaluation and testing. |
Required DSpace Settings
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".
Code Block | ||
---|---|---|
| ||
iiif.enabled = true |
In addition, you need to provide the URL for your IIIF image server. e.g.:
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
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.
Property | Description |
---|---|
iiif.enabled | Enables the DSpace IIIF service. |
iiif.image.server | Base URL path for the IIIF image server. e.g. http://localhost:8182/iiif/2/ |
iiif.document.viewing.hint | Default viewing hint. Can be overridden with the metadata setting described below. |
iiif.logo.image | Optional URL for a small image. This will be included in all IIIF manifests. |
iiif.cors.allowed-origins | Comma separated list of allowed CORS origins. The list must include the default value: ${dspace.ui.url}. |
iiif.metadata.item | Sets the Dublin Core metadata that will be added to the IIIF resource manifest. This property can be repeated. |
iiif.metadata.bitstream | Sets the Bitstream metadata that will be added to the IIIF canvas metadata for individual images. This property can be repeated. |
iiif.license.uri | Sets the metadata used for information about the resource usage rights. |
iiif.attribution | The text to use as attribution in the iiif manifests. Defaults to: ${dspace.name} |
iiif.document.viewing.hint | Either "individuals", "paged" or "continuous". Can be overridden with the metadata setting described below. |
Metadata Settings
Note | ||
---|---|---|
| ||
Note that the |
IIIF behavior at the Item level is flexible and can be modified using metadata. Canvas sizes, image labels, ranges and and other settings are managed using the following fields.
Schema | Element | Qualifier | Scope | Description |
---|---|---|---|---|
dspace | iiif | enabled | Item or Collection | Stores a boolean text value (true or false) to indicate if the iiif feature is enabled or not |
iiif | label | Bitstream | Metadata field used to set the IIIF label associated with the canvas resource otherwise the system | |
iiif | description | Item | Metadata field used to set the IIIF description associated with the resource. | |
iiif | canvas | naming | Item | Metadata field used to set the base label used to name all the canvas in the Item. The canvas |
iiif | viewing | hint | Item | Metadata field used to set the viewing hint overriding the configuration value if any. Possible |
iiif | image | width | Item or Bitstream | Metadata field used to store the width of an image in pixels. Determines the canvas size. |
iiif | image | height | Item or Bitstream | Metadata field used to store the height of an image in pixels. Determines the canvas size. |
iiif | toc | Bitstream | Metadata field used to set the position of the iiif resource in the "table of contents" structure. | |
iiif | search | enabled | Item | Metadata field used to enable the IIIF Search service at the item level. This feature is |
Adding the Mirador Viewer
The Mirador 3.0 viewer is included in the DSpace Angular source. Before enabling it, be sure to review the instructions for installing the Angular frontend.
To add the Mirador viewer to your installation, run the following command:
Code Block |
---|
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 can vary with your setup. One possible command-line scenario is the following:
Code Block |
---|
yarn run build:mirador yarn run build:prod yarn run serve:ssr |
Note | ||
---|---|---|
| ||
In the Dspace 7.1 release, the Mirador viewer cannot be used when running in development mode. For now, you need to use a production build (e.g. yarn start). |
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. Be sure to 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.
Installing the 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 image server works with DSpace. First, the base path to the image server is defined in config/modules/iiif.cfg.
Code Block |
---|
iiif.image.server = https://imageserver.mycampus.edu/image-server/cantaloupe/iiif/2/ |
Given this configuration, when the Mirador client requests a manifest
from the DSpace IIIF backend it will include an image resource annotation like the following:
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Code Block | ||
---|---|---|
| ||
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 an experimental 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
:
Code Block | ||
---|---|---|
| ||
iiif.search.url = ${solr.server}/word_highlighting iiif.search.plugin = org.dspace.app.rest.iiif.service.WordHighlightSolrSearch |
Once your METS/ALTO data has been added to the solr index, you can enable the search API for an Item by adding the iiif.search.enabled metadata
field. Set the value to true
.