fiv/docs/wide-thumbnail-spec.adoc

Wide Thumbnail Managing Standard

Introduction

This document is a follow-up to the Thumbnail Managing Standard, in particular version 0.9.0. It extends the specification to cover wide-format file thumbnails, providing a well-defined mechanism for sharing them amongst different programs. It also addresses new needs that have arisen with high-density, wide-gamut monitors.

Please contact the author of this document if you intend to use it.

Rationale

Photos tend to be in a 4:3 format. Yet, nearly all file browsers at the time of this document’s conception (end of year 2021) show previews in a rectangular grid. This wastes a lot of display real estate with padding, and looks subjectively awkward. The Web at large has long been moving off of this concept, instead preferring freely flowing items of fixed height—​notably on such sites as DeviantArt and Google/Duck image search. The general Unix desktop keeps lagging behind.

Scaling sub-nominal thumbnail sizes up, or larger sizes down is not a practical solution: the former gives blurry images, while the latter may waste a significant amount of disk space. Both require reprocessing. Seeing as these issues have only become worse with the higher resolutions added to the 0.9.0 revision of the preceding standard, a new one is necessary.

Storage

The base directory for thumbnails is the same as in the original specification. The list of subdirectories is similar, but a wide- prefix is added, turning large into wide-large, and so on. The fail directory does not constitute an exception to this rule, and is also duplicated, if necessary.

The dimensions differ like so: the original height for the respective sizes is kept, but a factor of 2 is applied to the width:

• $XDG_CACHE_HOME/thumbnails/wide-normal contains previews proportionally scaled down to 256x128 pixels,

• $XDG_CACHE_HOME/thumbnails/wide-large contains 512x256 pixel previews,

• $XDG_CACHE_HOME/thumbnails/wide-x-large contains 1024x512 pixel previews,

• $XDG_CACHE_HOME/thumbnails/wide-xx-large contains 2048x1024 pixel previews.

It is unspecified whether non-square pixels are scaled down accordingly, but it is recommended to do so.

File format

To account for very large thumbnail sizes, this specification has chosen the WebP codec, in its extended file format. Thumbnail files still derive their name from the MD5 hash of input URIs, as in the original standard, because this widespread algorithm shows surprisingly good results for this use case. The filename, however, deviates in that it receives the appropriate .webp file extension.

Both lossy and lossless encodings may be used. Animations are assumed to be representative samples, and their timing needn’t be respected. No metadata chunks are allowed other than THUM, which is described below. Any Exif orientation changes need to be "baked-in" to the image.

Metadata

Because WebP doesn’t directly provide any means of storing simple key-value pairs, thumbnail attributes are stored in a custom chunk named "THUM". It consists of a stream of NUL-terminated pairs, using the UTF-8 encoding. The last NUL byte may not be omitted. The behavior of repeated keys is undefined.

All keys from the original specification are adopted, including the extension mechanism, plus these additions:

Table 1. Additional fields

Key	Description
Thumb::ColorSpace	The thumbnail’s color space, if it is known.

The color space field may only be included if the producing program has applied color management to the input image, e.g., using any embedded ICC profiles, so that the color space is now known and normalized. No rendering intent is hereby suggested. It is permitted to assume sRGB for input images with unspecified color spaces. The full list of allowed values is:

Table 2. Color spaces

Value	Description
sRGB	IEC 61966-2-1
Display P3	sRGB with DCI-P3 primaries, as used by Apple.

Interactions

Programs may fall back to picking up and rescaling a square-sized thumbnail if they fail to find a wide one, preferrably one size above what they are looking for. The wide-format thumbnail should then be automatically regenerated. It should also be regenerated if the program supports color management, but it has found a thumbnail without a color space field.

A normal-sized old-specification thumbnail may be produced alongside any wide ones, but it is strongly suggested to avoid duplicating the larger sizes.

References

• Thumbnail Managing Standard;

• WebP Container Specification;

• smhasher — Hash function quality and speed tests evaluates MD5 as an excellent non-cryptographic hash function;

• RFC 3629 — UTF-8;

• IEC 61966-2-1:1999 — sRGB is "only" available commercially, but reduces to these characteristics;

• Apple's brief Display P3 definition and the corresponding DCI-P3 characteristics.

Change history

v0.1, 2021-12-29, Přemysl Eric Janouch

Preliminary draft.