Usage

Invenio module to serve images complying with IIIF standard.

Invenio-IIIF integrates Invenio-Records-Files with Flask-IIIF to provide an endpoint for serving images complying with the International Image Interoperability Framework (IIIF) API standards.

Invenio-IIIF registers the REST API endpoint provided by Flask-IIIF in the Invenio instance through entry points. On each image request, it delegates authorization check and file retrieval to Invenio-Files-REST and it serves the image after adaptation by Flask-IIIF.

Basics

Preview

Invenio-IIIF can be used in a combination with Invenio-Previewer to preview images. It provides an extension to preview the most common image formats and it is exposed via the entry point named iiif_image.

The template used to render the image can be configured with the configuration IIIF_PREVIEW_TEMPLATE.

To use it with an existing Invenio instance you should update your PREVIEWER_PREFERENCE configuration by adding iiif_image to the list of available previewers with the desired precedence order. For example:

PREVIEWER_PREFERENCE = [
    'iiif_image',
    'json_prismjs',
    'xml_prismjs',
    'pdfjs',
    'zip',
]

Caching

Image caching is provided by Flask-IIIF. You can change cache expiration by setting the IIIF_CACHE_TIME.

# 60 seconds * 60 (1 hour) * 24 (1 day)
IIIF_CACHE_TIME = 60 * 60 * 24

By default Flask-IIIF caches images in memory. You can cache images on Redis by using the available ImageRedisCache handler (providing Redis URL) or point to your own custom handler by setting it in IIIF_CACHE_HANDLER.

# Cache handler
IIIF_CACHE_HANDLER = 'flask_iiif.cache.redis:ImageRedisCache'

# Redis URL
IIIF_CACHE_REDIS_URL = 'redis://localhost:6379/0'

PDF cover

When the retrieved file is a PDF and with ImageMagick/Wand installed in your environment (see Installation documentation), then a cover image with the first page of the PDF file can be generated and served it as preview.

Authorization

Permissions to retrieve the requested images are delegated to Invenio-Files-REST. At each request, authorization is checked to ensure that the user has sufficient privileges.

Thumbnails

The module can pre-cache thumbnails of requested images. It provides a celery task that will fetch a given image and resize it to create a thumbnail. It is then cached so it can be served efficiently.

from invenio_iiif.tasks import create_thumbnail
create_thumbnail(image_key, '250')

Initialization

First create a Flask application:

>>> from flask import Flask
>>> app = Flask('myapp')
>>> app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite://'

Then, you can define the IIIF API prefix by setting the Invenio configuration IIIF_UI_URL.

>>> app.config.update(IIIF_UI_URL='/iiif-demo')

The example below will demonstrate how Invenio-IIIF works with a simple image. First, initialize the needed Invenio extensions:

>>> from invenio_db import InvenioDB, db
>>> from invenio_files_rest import InvenioFilesREST
>>> ext_db = InvenioDB(app)
>>> ext_files_rest = InvenioFilesREST(app)
>>> app.app_context().push()
>>> db.create_all()

Add sample images

To be able to add the files to Invenio, let’s create a default location first:

>>> import tempfile
>>> tmpdir = tempfile.mkdtemp()
>>> from invenio_files_rest.models import Location
>>> loc = Location(name='local', uri=tmpdir, default=True)
>>> db.session.add(loc)
>>> db.session.commit()

And a bucket with the previously created location:

>>> from invenio_files_rest.models import Bucket
>>> b1 = Bucket.create(loc)

Now, add a few sample images:

>>> import os
>>> from invenio_files_rest.models import ObjectVersion
>>> demo_files_path = 'examples/demo_files'
>>> demo_files = (
...     'img.jpg',
...     'img.png')
>>> for f in demo_files:
...     with open(os.path.join(demo_files_path, f), 'rb') as fp:
...         img = ObjectVersion.create(b1, f, stream=fp)
>>> db.session.commit()

Serving an image

While Flask-IIIF requires the UUID of the image to retrieve as part of the URL, Invenio needs the bucket id, version id and the key of the file so that it can be retrieved via Invenio-Files-REST. Invenio-IIIF provides an utility to prepare such URLs, e.g. /v2/<uuid>/<path>, and convert the uuid parameter to a concatenation of <bucket_id>:<version_id>:<key>.

Given a previously created image object:

>>> img_obj = ObjectVersion.get_versions(bucket=b1,
...                                      key=demo_files[1]).first()

you can create the corresponding IIIF URL:

>>> from invenio_iiif.utils import ui_iiif_image_url
>>> image_url = ui_iiif_image_url(
...       obj=img_obj, version='v2', region='full', size='full', rotation=0,
...       quality='default', image_format='png')

The result will be /iiif-demov2/<bucket_id>:<version_id>:img.png/full/full/0/default.png