Home

Awesome

iiif-processor

Build Status Maintainability Test Coverage

This module provides a full-featured image processor supporting the IIIF Image API versions 2.1 and 3.0. It covers only the image processing pipeline itself, leaving input and output to the caller.

Install with NPM

npm install iiif-processor --save

Usage

const IIIF = require('iiif-processor');

const processor = new IIIF.Processor(url, streamResolver, opts);

Examples

Full Self-Contained Application

See the TinyIIIF example.

Stream Resolver

The calling function must supply the processor with a Stream Resolver callback function, which takes information about the request (id and baseUrl) and returns an open Readable Stream from which the source image can be read.

Pairtree File Source

function streamResolver({ id, baseUrl }) {
  let imagePath = '/path/to/image/root/' + id.match(/.{1,2}/g).join('/') + '/image.tif';
  return fs.createReadStream(imagePath);
}

The Stream Resolver can also take an async callback as its second parameter, in which case it should return the value of applying the callback to the stream. This allows the function to do its own cleanup.

Amazon S3 Bucket Source

const { GetObjectCommand, S3Client } = require('@aws-sdk/client-s3');

async function streamResolver({ id, baseUrl }, callback) {
  const s3 = new S3Client();
  const command = new GetObjectCommand({
    Bucket: 'my-tiff-bucket',
    Key: `${id}.tif`
  });
  const response = await s3.send(command);
  const body = response.Body;

  if (!stream) {
    throw new Error(`Could not fetch object from S3: ${id}`);
  }

  try {
    return callback ? await callback(stream) : stream;
  } finally {
    stream.destroy();
  }
}

Dimension Function

The calling function can also supply the processor with an optional Dimension callback that takes information about the request (id and baseUrl) and returns the dimensions of the source image. This allows for caching dimensions and avoiding an expensive image request.

The function should return either:

Providing the dimensions of all available pages allows the processor to choose the most efficient starting image for the size requested.

async function dimensionFunction({ id, baseUrl }) {
  let dimensions = lookDimensionsUpInDatabase(id);
  return { width: dimensions.width, height: dimensions.height };
}

Path Prefix

The pathPrefix constructor option provides a tremendous amount of flexibility in how IIIF URLs are structured. The prefix includes one placeholder {{version}}, indicating the major version of the IIIF Image API to use when interpreting the rest of the path.

Processing

Promise

const IIIF = require('iiif-processor');

let url = 'http://iiif.example.com/iiif/2/abcdefgh/full/400,/0/default.jpg'
let processor = new IIIF.Processor(url, streamResolver, { dimensionFunction });
processor.execute()
  .then(result => handleResult(result))
  .catch(err => handleError(err));

Async/Await

const IIIF = require('iiif-processor');

let url = 'http://iiif.example.com/iiif/2/abcdefgh/full/400,/0/default.jpg'
let processor = new IIIF.Processor(url, streamResolver, { dimensionFunction });
try {
  let result = await processor.execute();
  return result;
} catch (err) {
  handleError(err);
}

id / baseUrl

The stream resolver and dimensions function functions both accept an object with id and baseUrl specified.

For instance, for the request:

https://example.org/iiif/assets/42562145-0998-4b67-bab0-6028328f8319.png/10,20,30,40/pct:50/45/default.png

The id parameter is 42562145-0998-4b67-bab0-6028328f8319.png and the baseUrl is https://example.org/iiif/assets.

Contributing

Contributions are welcome in the form of bug reports, suggestions, pull requests, and/or documentation.

If you're working on a PR for this project, create a feature branch off of main.

This project uses the debug library for selective debugging output. To view all IIIF-related debug messages, set the environment variable DEBUG=iiif-processor:*. To view just the main or transformer contexts, set DEBUG=iiif-processor:main or DEBUG=iiif-processor:transform.

This repository follows the Samvera Community Code of Conduct and language recommendations. Please do not create a branch called master for this repository or as part of your pull request; the branch will either need to be removed or renamed before it can be considered for inclusion in the code base and history of this repository.

License

node-iiif is available under the Apache 2.0 license.