From fa69935e67ab78e811c21f672d70b1576155eb33 Mon Sep 17 00:00:00 2001 From: Přemysl Eric Janouch Date: Wed, 29 Dec 2021 21:17:06 +0100 Subject: Document our thumbnails --- docs/wide-thumbnail-spec.adoc | 126 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/wide-thumbnail-spec.adoc diff --git a/docs/wide-thumbnail-spec.adoc b/docs/wide-thumbnail-spec.adoc new file mode 100644 index 0000000..cbd6a27 --- /dev/null +++ b/docs/wide-thumbnail-spec.adoc @@ -0,0 +1,126 @@ +Wide Thumbnail Managing Standard +================================ +Přemysl Eric Janouch +v0.1, 2021-12-29: Preliminary draft +:description: Wide-format thumbnail managment specification + +Introduction +------------ +This document is a follow-up to the +https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html[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: + +.Additional fields +[cols="1,2"] +|=== +| 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: + +.Color spaces +[cols="1,2"] +|=== +| 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 +---------- + - https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html[Thumbnail Managing Standard]; + - https://developers.google.com/speed/webp/docs/riff_container[WebP Container Specification]; + - https://github.com/rurban/smhasher[smhasher -- Hash function quality and speed tests] + evaluates MD5 as an excellent non-cryptographic hash function; + - https://datatracker.ietf.org/doc/html/rfc3629[RFC 3629 -- UTF-8, a transformation format of ISO 10646]; + - IEC 61966-2-1:1999 -- sRGB is "only" available commercially, but reduces to + https://www.color.org/chardata/rgb/srgb.xalter[these characteristics]; + - https://developer.apple.com/documentation/coregraphics/cgcolorspace/1408916-displayp3[Apple's brief Display P3 definition] + and the corresponding + https://www.color.org/chardata/rgb/DCIP3.xalter[DCI-P3 characteristics]. + +Change history +-------------- +v0.1, 2021-12-29, Přemysl Eric Janouch:: + Preliminary draft. -- cgit v1.2.3-70-g09d2