Several common image formats are supported by the various decoders and encoders. A goal of Galia is to support common source formats without requiring any conversion before they can be served. Still, when there is the ability to choose, some formats are better suited for certain use cases (like deep zooming or thumbnailing) than others.
For variant formats, format choice is more influenced by the quality vs. size ratio and client support.
In the table below, "pyramidal" refers to the ability of a format to support reduced-resolution decoding for preview or thumbnail images, and "tiled" refers to the ability to efficiently supply cropped regions—to zooming image viewers, for example—without having to decode the whole image.
| Ideal for high-resolution source images | Ideal for variant images | |
|---|---|---|
| AVIF | When pyramidal & tiled | ✓ |
| BMP | × | × |
| GIF | × | Limited to 256 colors |
| HEIC | When pyramidal & tiled | ✓ |
| JPEG | × | ✓ |
| JPEG-XL | × | ✓ |
| JPEG2000 | ✓ | Poor browser support |
| Vector only | N/A | |
| PNG | × | There are better options |
| TIFF (notes) | When pyramidal & tiled | Can't be streamed by an encoder |
| WebP | × | ✓ |
TIFF source images must be encoded in a particular way in order to be delivered efficiently.
The 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. TIFF images must be tile-based in order to permit efficient region extraction.
When using the built-in TIFFDecoder, information about TIFF source images is logged at debug level. These messages reveal whether a TIFF is strip-based or tile-based. A request for a tiled TIFF will generate a log message like:
DEBUG i.g.c.t.TIFFDecoder - Acquiring region 0,0/500x500 from 8848x6928 image (128x128 tile size)
While tiles permit efficient reading of reduced regions, pyramidal TIFF permits efficient reading 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 10,000×10,000 pixel main image would include variants of 5,000×5,000 pixels, 2,500×2,500 pixels, 1,250×1,250 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, 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.
The core application bundles TIFFDecoder, which wraps the Image I/O TIFF plugin included in the JRE. This implementation has several drawbacks, including a lack of support for BigTIFF images. Users who need better support for TIFF source images should use the LibTIFF Plugin instead.
Some image formats, like PDF and TIFF, can accommodate multiple embedded subimages. These can be accessed by supplying a page number in the URI identifier (see meta-identifiers).
A client may want to know how many such pages an image file contains (in order to render pagination controls, for example). The IIIF Image API has no concept of pages, but Galia extends the Image API information response to include a pageCount key.
Every source image is considered to have a unique identifier, which appears in endpoint URIs and is used to reference the image throughout the application.
Identifiers may be the same as, or may map to, filenames, pathnames, object keys, database column values, or some other identifying token. The Quick Start describes a simple setup in which URI identifiers map to pathname fragments on a filesystem, but this can make for identifiers that are unaesthetic, unstable, and/or insecure. See Sources for information on setting up your underlying storage to meet your particular use case.
An identifier references a unique source image file, but for some images, more specificity may be needed. For example, an "image" like a PDF document may contain multiple pages, each of which must be requested individually. A page number can be appended to the PDF's identifier to create a meta-identifier that can be supplied to an IIIF Image API endpoint in order to convey this extra information to the endpoint that its API does not natively support.
Meta-identifiers rely on a transformer object that performs serialization and deserialization (i.e. converting to and from the form appearing in the URL). There are two such transformers available, selectable using the meta_identifier.transformer configuration key:
This is the out-of-the-box default transformer, supporting the following formats:
identifieridentifier;page_numberidentifier;scale_constraintidentifier;page_number;scale_constraintThe default component delimiter is a semicolon, but this can be changed using the meta_identifier.transformer.StandardMetaIdentifierTransformer.delimiter configuration key.
This transformer invokes a pair of delegate methods to enable full control over serialization and deserialization (and, therefore, the precise format of the meta-identifiers). See the documentation of the serialize_meta_identifier() and deserialize_meta_identifier() methods in the sample delegate script for more information.
Both slashes and URI-illegal characters in identifiers must be URI-encoded. For example, an image with an identifier of a6/b3/c4(d).jp2 would need to appear in a URI as a6%2Fb3%2Fc4%28d%29.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.
All output is RGB or RGBA in the sRGB color space with a maximum of 8 bits per component. Images with a smaller sample size may be upsampled depending on the decoder and/or encoder implementation and the chosen variant format, but images with a larger sample size will always be downscaled. An alpha channel will be included if the source image contains one and the variant format supports one.
All decoders support embedded color profiles and will either automatically copy them into variant images or automatically apply them to the output pixels.
See Metadata.