Skip to content
Simple IIIF Image API server from a directory of files using PHP
PHP
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
images/examples
.gitignore
.htaccess
README.md
cache_manager.php
config.php
functions.php
image_info.php
image_server.php
index.php
manifest.php

README.md

iiif_file

A simple IIIF Image API server using PHP.

Only the IIIF Image API version 3 is implemented. It is assumed that informative IIIF Manifest files that reference these image endpoints are generated by other applications such as collection catalogue web front ends.

(n.b. For testing purposes a skeletal IIIF Manifest will be generated for each image but no attempt is made to include meaningful data in it.)

All image data is stored in a directory structure with a single logical root. Each image is stored either as a tile pyramid or as a single file.

IIIF Image API v3 is still in Beta and may change. This code is "rough and ready" and may change as well. Suggested improvements welcome.

Image Identifier to Path Mapping

The IIIF Image API has the notion of an image identifier as part of the URI Syntax. Here a Base64 encoded path to the image data from the data directory root is used as the image identifier. This is because:

  • It abstracts any path related characters that may break the URI syntax.
  • It is trivial to encode and decode Base64 in any application.
  • The IIIF Manifest generating applications are likely to have access to, or be able to calculate, the storage path of the image and use it as the image identifier.

Examples

If the root of the data directory is

images/

and image is stored as tiles in this directory

images/examples/zoom_example

then the identifier will be the base64 encoding of

examples/zoom_example

which is

ZXhhbXBsZXMvem9vbV9leGFtcGxl

A request for a thumbnail URI may look like this

http://example.com/iiif/ZXhhbXBsZXMvem9vbV9leGFtcGxl/full/500,/0/default.jpg

Zoomify Image Tiles

If the decoded image identifier path is to a directory then it is assumed the image is stored as a Zoomify tile pyramid with a metadata file called ImageProperties.xml within that directory.

Zoomify is commercial web image zooming software with a well known tile pyramid format. A directory of tiles can be generated using a number of tools. Notably Photoshop has it as an export option. There is also a PHP based library to generate tiles.

Envisaged Usage: Publishing high resolution images to IIIF Image API by exporting them from Photoshop direct to the image data directory.

Simple Image Files

If the decoded image identifier is a path to a file then it is assumed this is a JPEG of the image. It will be served through the IIIF endpoint with subregions and scaling being generated on the fly. There is some caching of derived images to help improve efficiency but this is clearly for smaller images that can be easily loaded into memory only.

Envisaged usage: Publishing lower resolution images via the IIIF Image API such as multipage manuscripts or photographs used to annotate larger canvases or images that will rarely be viewed.

Setup

config.php

There is a config.php file with commented variables to be set including the location of the data and cache directories.

Cache Dir

An Apache writeable cache directory must be created. This is used both for when serving single file images and zoomified images. Although the zoomify version needs a lot less caching it still creates and stores full images at different resolutions when requested - this is very common for thumbnails.

The cache_manager.php script that will maintain this directory at a certain size by deleting files that have not been accessed for a while. To do this it needs to be called regularly by a cron job. Adding something like this to your crontab will accomplish this.

22 6 * * * wget -O - https://example.com/something/cache_clean.php > /dev/null 2>&1

index.php and example images

For convenience an index.php is included with links to the example images. These could be deleted in production.

Apache2

Two Apache modules need to be enable:

sudo a2enmod rewrite
sudo a2enmod headers

Rewrite rules need to be set in the site configuration or in an .htaccess file. A .htaccess file given in the git repository. If you are using .htaccess make sure it is enabled in the site configuration with something like:

AllowOverride All
Require all granted

You will probably need to change the RewriteBase in the .htaccess file to suit your install location.

PHP

PHP 7 is assumed. It may work with earlier distributions.

The script uses ImageMagick to do the image manipuation. Do something like this on Ubuntu and similar to install it:

sudo apt-get install php-imagick
You can’t perform that action at this time.