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.
If the root of the data directory is
and image is stored as tiles in this directory
then the identifier will be the base64 encoding of
A request for a thumbnail URI may look like this
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.
There is a config.php file with commented variables to be set including the location of the data and cache directories.
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.
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 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