Processors

• Operating System Compatibility
• Resolver Compatiblity
• Supported Features
• Supported Source Formats
• Implementations
  • Java2dProcessor
  • JaiProcessor
  • GraphicsMagickProcessor
  • ImageMagickProcessor
  • KakaduProcessor
  • OpenJpegProcessor
  • FfmpegProcessor
  • PdfBoxProcessor

Processors are responsible for reading source images from resolvers and transforming them according to request parameters. Processors are modular and pluggable. Particular processors can be assigned to handle particular source formats, and a fallback processor can be assigned to all others.

Different processors have different quality, compatibility, dependency, and performance characteristics. The ability to choose among different processors is intended to make it easy to add support for new image formats; improve support for existing image formats via the substitution of better codecs; and decouple the image server implementation from any one codec.

In terms of format support, a distinction is made between the concepts of source format and output format. Available output formats may differ on a per-platform or per-instance basis depending on the source format.

Supported source formats depend on the processor, and possibly installed libraries/delegates, etc., as well. Lists of these are displayed on the landing page, as well as in one of the tables below. A list of output formats supported for a given source format is contained within the response to an information request (such as /iiif/2/{identifier}/info.json).

Operating System Compatibility

Resolver Compatibility

✓*: Not natively compatible, but will work if the source cache is enabled

Supported Features

✓*: Copied into derivative images.

✓**: Derivative image pixel data is modified according to the ICC profile.

Supported Source Formats

Implementations

Java2dProcessor

Java2dProcessor uses the Java ImageIO framework and Java 2D API to read and process images in a native-Java way. This is a good processor to get started with as it has no external dependencies.

Java2dProcessor has been written to exploit the ImageIO image readers as efficiently as possible. Special attention has been paid to its handling of tiled images, such as tile-encoded TIFFs, for which it reads only the necessary tiles for a given request. It is also capable of reading the sub-images contained within multi-resolution (pyramidal) TIFF images.

Because Java2dProcessor does all its work in Java, it places a burden on the JVM heap. Although it tries to be efficient at reading images, it does have to create derivative images at every processing step (scaling, rotating, etc.), which have to be temporarily buffered in RAM. (See the section on memory considerations.)

JaiProcessor

Java Advanced Imaging (JAI) is a sophisticated image processing library developed by Sun Microsystems from the late 1990s to the mid-2000s. It offers several advantages over Java 2D: a pull-based rendering pipeline that can reduce memory usage, and efficient region-of-interest decoding with some formats.

As JaiProcessor and Java2dProcessor use the same ImageIO readers and writers, they can read and write the same formats.

Years ago, Sun published platform-native accelerator JARs called mediaLib for Windows, Linux, and Solaris, which improved JAI's performance. It is unknown whether these still work on modern platforms.

GraphicsMagickProcessor

GraphicsMagickProcessor uses im4java to invoke the GraphicsMagick executable (gm). As such, GraphicsMagick must be installed.

GraphicsMagick produces high-quality output—competitive with ImageMagick—and supports all of the IIIF transforms and most IIIF output formats (assuming the necessary libraries are installed; see Supported Formats).

GraphicsMagickProcessor is typically faster than ImageMagickProcessor. However, like ImageMagickProcessor, it is neither tile- nor multi-resolution-aware and thus fares poorly with large images.

ImageMagickProcessor

ImageMagickProcessor, like GraphicsMagickProcessor, uses im4java to wrap ImageMagick commands. As such, ImageMagick must be installed. Currently, the convert and identify executables from version 6.x are used. Version 7 replaces these with a single magick command, which is not yet supported. Therefore, if using ImageMagick 7, be sure that the convert and identify commands ("legacy utilities" as the Windows installer calls them) are installed.

ImageMagick supports all of the IIIF transforms and all IIIF output formats, assuming the necessary delegates are installed. It also supports a wide array of source formats.

ImageMagick's output quality is excellent; its thumbnails, in particular, are hard to beat. This comes at the expense of performance, which suffers increasingly as image size increases.

KakaduProcessor

KakaduProcessor uses the kdu_expand and kdu_jp2info binaries from the Kakadu SDK to efficiently decode JPEG2000 source images. This processor is capable of performing well even with large JP2s. Kakadu is extensively optimized and will make use of all available CPU cores.

Although it does support some other operations, kdu_expand is mainly a decompression tool, and Cantaloupe uses only its cropping and level-reduction features. All other operations (differential scaling, rotation, etc.) are performed using Java 2D.

To use this processor, Kakadu must be installed. (See the note below.) The Kakadu binaries will automatically be detected if they are on the path; otherwise, set the KakaduProcessor.path_to_binaries configuration key to the absolute path of the containing directory. The LD_LIBRARY_PATH environment variable will also need to be set to locate the Kakadu shared library.

OpenJpegProcessor

OpenJpegProcessor uses the opj_decompress and opj_dump tools from the open-source OpenJPEG project to decode JPEG2000 source images.

Although it does support some other operations, opj_decompress is mainly a decompression tool, and Cantaloupe uses only its cropping and level-reduction features. The rest of the IIIF operations (differential scaling, rotation, etc.) are performed using Java 2D.

To use this processor, OpenJPEG must be installed. The OpenJPEG binaries will automatically be detected if they are on the path; otherwise, set the OpenJpegProcessor.path_to_binaries configuration key to the absolute path of the containing directory. The LD_LIBRARY_PATH environment variable will also need to be set to locate the OpenJPEG shared library.

FfmpegProcessor

FfmpegProcessor uses the FFmpeg tool to extract still frames from video files. It can be used for thumbnail generation á la YouTube, as well as deep zooming of high-resolution still frames.

FfmpegProcessor has been tested with FFmpeg version 2.8. Other versions may or may not work.

Optional Parameters

FFmpegProcessor supports a time URL query parameter (which is nonstandard and Cantaloupe-specific) which can be used to return a frame at a particular second in the source video. The value of this parameter should be in hh:mm:ss format, like:

http://example.org/iiif/2/video.mp4/full/full/0/default.jpg?time=00:02:15

If the time parameter is missing, the first frame will be returned.

PdfBoxProcessor

PdfBoxProcessor uses the Apache PDFBox library to read and rasterize PDF files. This is a pure-Java library that is bundled in and has no dependencies.

As PDF is a vector format, PdfBoxProcessor will convert to a raster (pixel) image and use a Java 2D pipeline to transform it according to the request parameters.

The size of the default raster image, corresponding to a scale of one, is configurable with the PdfBoxProcessor.dpi configuration option. When a request asks for a scale of ≤ 50% or ≥ 200%, a fraction or multiple of this will be used, respectively, in order to improve efficiency at small scales, and detail at large scales.

Optional Parameters

PdfBoxProcessor supports a page URL query parameter (which is nonstandard and Cantaloupe-specific) which can be used to return a particular page of a PDF. For example:

http://example.org/iiif/2/document.pdf/full/full/0/default.jpg?page=2

If the page parameter is missing, the first page will be returned. If the given page number is invalid or greater than the number of pages in the PDF, the first page will be returned.