Thumbnail Creation

File format

The image format for thumbnails is the PNG format, regardless in which format the original file was saved. To be more specific it must be a 8bit, non-interlaced PNG image with full alpha transparency (means 255 possible alpha values). However, every program should use the best possible quality when creating the thumbnail. The exact meaning of this is left to the specific program but it should consider applying antialiasing.

If the original file contains metadata affecting the interpretation of the image, it should be respected as much as possible. In particular, metadata specifying the orientation of the original image data should always be respected. The image data should be transformed as specified by the metadata before generating the thumbnail. JPEG files commonly have Exif orientation tags. TIFF files may also have Exif orientation tags, although this is less common. It is less critical, but still desirable, to respect other image metadata, such as white balance information.

Thumbnail Attributes

Beside the storage of the raw graphic data its often useful to provide further information about a file in its thumbnail. Especially file size, image dimension or image type are often used in graphic programs. If the thumbnail provides such information it avoids any need to access the original file and thus makes the loading faster.

The PNG format provides a mechanism to store arbitrary text strings together with the image. It uses a simple key/value scheme, where some keys are already predefined like Title, Author and so on (see section 4.2.7 of the PNG standard). This mechanism is used to store additional thumbnail attributes.

Beside the png format there is another internet standard which is important in this context: the URI mechanism. It is used to specify the location of the original file. Only canonical absolute URIs (including the scheme) are used to determine the original uniquely.

The following keys and their appropriate values must be provided by every program which supports this standard. All the keys are defined in the "Thumb::" namespace or if already defined by the PNG standard without any namespace.

Table 1. Required attributes.

Thumb::URIThe absolute canonical uri for the original file. (eg file:///home/jens/photo/me.jpg)
Thumb::MTimeThe modification time of the original file (as indicated by stat, which is represented as seconds since January 1st, 1970).

If it's not possible to obtain the modification time of the original then you shouldn't store a thumbnail for it at all. The mtime is needed to check if the thumbnail is valid yet (see Detect modifications). Otherwise we can't guarantee the content corresponds to the original and must regenerate a thumb every time anyway.

Table 2. Additional attributes.

Thumb::SizeFile size in bytes of the original file.
Thumb::MimetypeThe file mimetype.
DescriptionThis key is predefined by the PNG standard. It provides a general description about the thumbnail content and can be used eg. for accessability needs.
SoftwareThis key is predefined by the PNG standard. It stores the name of the program which generated the thumbnail.

There are surely some situations where further information are desired. Eg. the Gimp could save the number of layers an image has or something like this. So if an application wants to save more information it is free to do so. It should use a key in its own namespace (to avoid clashes) prefixed by X- to indicate that this is an extension. Eg. Gimp could save the layer info in the key X-GIMP::Layers.

However, regarding to the filetype there are some keys which are generally useful. If a program can obtain information for the following keys it should provide them.

Table 3. Filetype specific attributes.

Thumb::Image::WidthThe width of the original image in pixel.
Thumb::Image::HeightThe height of the original image in pixel.
Thumb::Document::PagesThe number of pages the original document has.
Thumb::Movie::LengthThe length of the movie in seconds.

With this approach a program doesn't have the guarantee that certain keys are stored in a thumbnail, because it may have been created by another application. If possible, a program should cope with the lack of information in such a case instead of recreating the thumbnail and the missing information.

Thumbnail Size

As already mentionend in the Thumbnail Directory section there exists two suggested sizes you can use for your thumbnails: 128x128 and 256x256 pixel. The idea is that if a program uses another size for it's previews it loads one of the two versions and scales them down to the desired size. Similar, when creating a thumbnail it scales the file down to 128x128 first (or 256x256), saves it to disk and then reduce the size further. This mechanism enables all programs to obtain their desired previews in an easy and fast way.

However, these are suggestions. Implementations should cope also with images that are smaller than the suggested size for the normal and large subdirectories. Depending on the difference between the actual and the desired size, they can either use the smaller one found in the cache and scale it down or recreate a thumbnail with the proposed size for this directory.

If a program needs a thumbnail for an image file which is smaller than 128x128 pixel it doesn't need to save it at all.


All sizes define just a rectangle area where the thumbnail must fit in. Don't scale every image to a rectangular thumbnail but preserve the ratio instead!