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 | |
| × | × | × | 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.
ImageMagickProcessor's JPEG2000 delegate, if installed, will also use the OpenJPEG library, but very inefficiently as the whole image is decompressed.
GraphicsMagickProcessor can read and write JPEG2000 using the JasPer library, if the necessary plugin is installed, with the same caveats as ImageMagickProcessor.
TIFF is a common format, but there are some criteria that source images must meet in order to be delivered efficiently.
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 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-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.
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).
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.
Many image file formats are capable of storing supplementary technical and/or descriptive metadata alongside the actual image data. Formats may be able to store standard metadata formats like EXIF, IPTC IIM, and XMP, and they may also define their own metadata formats. More than one such format may be present even within the same file.
When an image request is received—unless it calls for the full-sized unmodified source image—the image server will have to dynamically create and return a derivative image. As this is a whole new image, distinct from the source image, populating it with metadata would require an additional step.
When processor.metadata.preserve is set to true in the configuration file, an effort will be made to copy metadata from source images into derivative images. This doesn't work with all processors; see the Supported Features table for a breakdown. It also does not generally work across formats.