This version of the manual refers to an earlier version of the software.

Processors

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

Linux OS X Windows
FfmpegProcessor
GraphicsMagickProcessor
ImageMagickProcessor
JaiProcessor
Java2dProcessor
KakaduProcessor
OpenJpegProcessor
PdfBoxProcessor

Resolver Compatibility

Amazon S3 Azure Storage Filesystem HTTP JDBC
FfmpegProcessor ✓* ✓* ✓* ✓*
GraphicsMagickProcessor
ImageMagickProcessor
JaiProcessor
Java2dProcessor
KakaduProcessor ✓* ✓* ✓* ✓*
OpenJpegProcessor ✓* ✓* ✓* ✓*
PdfBoxProcessor

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


Supported Features

GraphicsMagick ImageMagick Java 2D JAI Kakadu OpenJPEG FFmpeg PDFBox
Mirroring
Region By Percent
Region By Pixels
Arbitrary Rotation
Rotation By 90°s
Size Above Full
Size By Forced Width/Height
Size By Height
Size By Width
Size By Percent
Size By Width/Height
Grayscale Output
Bitonal Output
Watermarking
Redaction
Tiled Reading N/A N/A
Multiresolution Reading N/A N/A

Supported Source Formats

BMP GIF JPEG JPEG2000 PDF PNG TIFF WebP
GraphicsMagickProcessor Uses JasPer (requires plugin). No level-reduction or region decoding. Requires plugin; no source DPI control All aspects, but no multi-resolution or ROI decoding Requires plugin
ImageMagickProcessor Uses OpenJPEG (requires delegate). No level-reduction or region decoding. Requires delegate; no source DPI control All aspects, but no multi-resolution or ROI decoding Requires delegate
JaiProcessor RGB, 8-bit, baseline, line-interlaced, plane-interlaced RGB, RGBA, 8-bit RGB, RGBA; 8-bit; uncompressed, PackBits, LZW, ZIP, JPEG; striped, tiled, and multi-resolution reading; BigTIFF
Java2dProcessor RGB, 8-bit, baseline, line-interlaced, plane-interlaced RGB, RGBA, 8-bit RGB, RGBA; 8-bit, 16-bit; uncompressed, PackBits, LZW (8-bit only), ZIP (8-bit only), JPEG (8-bit only); striped, tiled, and multi-resolution reading; BigTIFF
KakaduProcessor
OpenJpegProcessor
PdfBoxProcessor

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 and works out-of-the-JAR.

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, and applying scale-appropriate subsampling for faster reading.

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 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.

It is recommended to find or compile a "Q8" version of GraphicsMagick, as its memory use will be halved.

ImageMagickProcessor

ImageMagickProcessor, like GraphicsMagickProcessor, uses im4java to wrap ImageMagick commands. As such, ImageMagick must be installed.

ImageMagick produces high-quality output and 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 is not known for being particularly fast or efficient. Because it runs in an external process, it is not constrained by the JVM's memory limits, so using it with very large images can cause memory consumption to spiral out of control and effectively hang the server.
It is recommended to find or compile a "Q8" version of ImageMagick, as its memory use will be halved.

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 hardware-optimized and will make full 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 either the Java 2D or JAI APIs (configurable).

Note: Kakadu is not free and the SDK is not included with Cantaloupe. As of this writing, the necessary binaries can be downloaded from the Kakadu website and used for demonstration purposes.

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 either the Java 2D or JAI APIs (configurable).


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.