This manual refers to a future version of the software that is still in development. It may be incomplete or inaccurate and the software may change before a final release.


Source Formats

Several common source image formats are supported by at least one processor, but some are inherently better suited for high resolutions than others. In the table below, "pyramidal coding" refers to the ability of a format to support reduced-resolution decoding for preview or thumbnail images, and "region coding" refers to the ability to efficiently supply cropped regions—to zooming image viewers, for example.

Supports pyramidal coding Supports region coding Recommended for high-resolution source images Recommended processor
BMP × × × Java2dProcessor
GIF × × ×
JPEG × × ×
JPEG2000 (notes) KakaduNativeProcessor or OpenJpegProcessor
PDF × × × PdfBoxProcessor
PNG × × × Java2dProcessor
TIFF (notes) Striped × × ×
Tiled × ×
Pyramidal Striped × ×
Pyramidal Tiled


JPEG2000 uses advanced compression techniques to enable efficient reduced-scale and region-of-interest decoding. With a performant decoder, it is well-suited for use with very large source images.

KakaduNativeProcessor is the most efficient processor for this format.

OpenJpegProcessor uses the OpenJPEG codec, which is one of the fastest open-source JPEG2000 codecs.


TIFF is a common format, but there are some criteria that source images must meet in order to be delivered efficiently.

Strip-Based vs. Tile-Based

The Adobe TIFF 6.0 specification permits arrangements of image data in either strips or tiles. Strips may consist of one or more whole rows of pixels, but tiles are typically square. By default, most TIFF encoders produce strip-based TIFFs, which are increasingly slow to read as their size increases. High-resolution TIFFs must be tile-based in order to permit efficient region extraction.

When using an Image I/O-based processor, information about TIFF source images is logged at debug level. These messages will tell you whether a TIFF is strip-based or tile-based. For example, a request for a tiled TIFF will generate a log message like:

DEBUG e.i.l.c.p.c.TIFFImageReader - Acquiring region 0,0/500x500 from 8848x6928 image (128x128 tile size)

Pyramidal TIFF

Pyramidal TIFFs can be read much more efficiently at reduced scales. In addition to the main image, a pyramidal TIFF file will contain a sequence of progressively half-scaled sub-images: for example, a 10000×10000 pixel main image would include variants of 5000×5000 pixels, 2500×2500 pixels, 1250×1250 pixels, and so on, in the same file.

Each of the images in a multi-resolution TIFF file can be striped or tiled, just as in a mono-resolution file. (They can even be encoded in other, non-TIFF formats.) Tiled and pyramidal encodings are complementary: the former improves efficiency with reduced regions at large scales, and the latter improves efficiency at reduced scales. For efficient deep zooming, TIFF images need to be pyramidal, and each level of the pyramid must be tiled.


Every source image is considered to have a unique identifier, which appears in endpoint URIs and is used throughout the application to refer to the image.

Identifiers may be the same as, or may map to, filenames, pathnames, object keys, or some other identifying token in the underlying storage. The Getting Started section describes a simple setup in which URI identifiers map to pathname fragments on a filesystem, but this can make for identifiers that are ugly, unstable, and/or insecure. See Sources for information on setting up your underlying storage to meet your particular use case.

URI Considerations

URI-illegal characters in identifiers must be encoded. For example, an image with an identifier of a6/b3/c4.jp2 would need to appear in a URI as a6%2Fb3%2Fc4.jp2. When the application is behind a reverse proxy that cannot pass through encoded slashes (%2F) without decoding them, the slash_substitute configuration key can be used to specify a different character or character sequence to treat as a slash.

Color Depth

Most processors can read images that have more than 8 bits per sample. However, as most web clients can't display more than that, all output is limited to 8 bits per sample (24-bit RGB or 32-bit RGBA).

Color Profiles

A color profile maps the color space in which an image was produced to its internal color data, which enables viewers to reproduce image colors accurately, as they were seen by the producer. By embedding a color profile in an image, the producer need not know anything about the displays on which an image will be viewed, and need not destructively modify the color values within the image data itself.

Most processors support embedded color profiles and will either automatically copy them into derivative images or automatically adjust the output pixels; see the table of processor-supported features.

There is typically no need to embed a profile into profile-less images, as viewers will tend to assume that these map to an sRGB space, and apply the conversion themselves. There is therefore no provision for embedding profiles into profile-less images.


See Metadata.