Knowledge Base

IIIF

Designed for galleries, libraries, archives and museums, the International Image Interoperability Framework, or IIIF, enables global collaboration between institutions.

IIIF is an API tool that can be useful for academics, curators and researchers needing to access detailed information from any location. Because of its advanced zooming capabilities, IIIF is particularly useful for viewing art and artifacts such as paintings, maps and manuscripts. Samples can be found here.

ResourceSpace first began supporting IIIF in order to link with the TMS plugin - to enable publishing of resources related to a specified TMS object as a IIIF manifest. In this context, there’s usually a collections management system involved, although TMS is not a requirement to enable the IIIF interface.

Please note that IIIF support requires additional web server configuration. Further instructions for this are available below under ‘Configuration’.

Supported IIIF APIs

The ResourceSpace IIIF interface currently supports:

• Presentation: the IIIF Presentation API 3.0* (as detailed at https://iiif.io/api/presentation/3.0/) for publishing the manifest. ResourceSpace creates dynamic manifests based on metadata, whereas most systems create static files using e.g. scheduled tasks

• Image: the presentation of images to meet the minimum requirement (level 0) of the IIIF Image API 3.0* (https://iiif.io/api/image/3.0/)

• Video and audio file support requires the use of IIIF presentation API version 3.0 - see $iiif_media_extensions below

 * Version 2.1 of the standards only are supported prior to ResourceSpace version 10.3

IIIF Manifests

Manifests contain basic information and sub-elements relating to a resource. A URL links to a page overview of the object, which can be parsed into different formats.

Based on the IIIF Presentation API (JSON structure), these include:

See below for a sample or click here to view the full manifest:

• IIIF manifests are created based on search results returned for the specified identifier in the designated metadata field ($iiif_identifier_field)

• The metadata for each manifest is obtained from the first resource returned. If using TMS, the metadata stored in ResourceSpace is based on the object metadata retrieved from TMS and therefore will be the same for all resources with the same TMS object ID

• Each canvas in the sequence described by a IIIF manifest will correspond to a ResourceSpace resource

• The sequence of views published by the manifest will be based upon data stored in another ResourceSpace metadata field, thus allowing for reordering

Access/Publishing

It’s useful to create a dedicated IIIF user account with custom permissions to determine which resources are published and the metadata that’ll be displayed. Resources can then be made available or hidden from the IIIF interface via metadata fields and search filters.

Configuration

IMPORTANT: A URL rewrite rule must be configured on the web server to rewrite any paths under [resourcespace_url]/iiif to the IIIF handler file api/iiif/handler/php. Please see the bottom of this article for some information on standard web server rewrite configuration (Apache/IIS). Please refer to your web server configuration instructions for full instructions as to how to implement this.

Example URLs that must be handled by this file:

• https://[resourcespace_url]/iiif/363792/manifest
• https://[resourcespace_url]/iiif/image/363792/full/max/0/default.jpg
• https://[resourcespace_url]/iiif/363792/canvas/0

The following configuration settings are used. These should be set in the ResourceSpace configuration file (include/config.php)

Additional configuration options

The following options are also available. These provide tiling support as well as the ability to request custom sizes. Whilst this does not meet the full requirements to meet compliance level 1 of the Image API, it does provide support for the widely used Mirador and Universal IIIF viewers.

Web server rewrite rules

Apache

The following steps can be used to set up a rewrite rule in Apache. Please refer to the configuration instructions for your own server to ensure these are correct for your version

1. Enable apache rewrite functionality

   a2enmod rewrite
   

2. Add the following to your virtual host configuration

   RewriteEngine On
   RewriteCond %{HTTP_HOST} ^ [NC]
   ReWriteBase "/"
   RewriteRule    "^iiif(.*)$"  "/api/iiif/handler.php" [PT] 
   

   e.g.

   RewriteEngine On
   RewriteCond %{HTTP_HOST} ^mycompany.resourcespace.com [NC]
   ReWriteBase "/"
   RewriteRule    "^iiif(.*)$"  "/api/iiif/handler.php" [PT] 
   

IIS

The following steps can be used to set up a rewrite rule in IIS (Windows server). Please refer to the configuration instructions for your own server to ensure these are correct for your version

1. Open IIS Manager
2. Select the ResourceSpace website
3. Click on the 'URL Rewrite' icon in the right hand panel
4. Click on 'View rewrite maps' in the top right actions menu
5. Click on 'Add Rewrite Map' in the actions menu
6. Add a name for the map e.g. 'IIIF'
7. Click on 'Add Mapping Entry'
8. Set '/iiif' as the original value and '/api/iiif/handler.php' as the new value and click OK
9. Return to the Rewrite rules page and click on 'Add Rule(s)' in the top right actions menu
10. Select 'Inbound rules' ->'Rule with rewrite map'
11. Select 'Rewrite' as the rule action and the map you just created from the dropdown list. Click OK
12. Once finished and saved, the rule summary should look as in the images below

ARK identifiers

Archival Resource Keys (ARKs) serve as persistent identifiers, or stable, trusted references for information objects. You can use ARKs as IIIF identifers by URL encoding them.

For this to work, an approach is to create a new metadata field, let's call it "ARK ID", and set an on-change macro to:

iiif_identifier_ark_onchange_macro($macro_resource_id, $val, 102);
(note: 102 is the ID of the IIIF identifier metadata field, update as needed)

In your config.php add the following macro definition:

function iiif_identifier_ark_onchange_macro(int $resource, ?string $field_value, int $update_field_id)
    {
    $ark_id = trim((string) $field_value);
    if (mb_strcut($ark_id, 0, 3, 'UTF-8') === 'ark')
        {
        update_field($resource, $update_field_id, urlencode(urlencode($ark_id)));
        }
    return;
    }

Now, whenever you edit a resource, adding an ARK will automatically encode it and set it as the IIIF identifier. When requesting a manifest, make sure to use the value of the IIIF identifier, for example /iiif/ark%253A12345%252Fmytest/manifest.

Useful links

• https://iiif.io/

• https://universalviewer.io/

• https://mirador-dev.netlify.app/__tests__/integration/mirador/

• https://resources.digirati.com/iiif/an-introduction-to-iiif/