Version 0.0.1 July 2001 Jens Finke

jens@gnome.org

This paper describes a general way how to permanently store image thumbnails. Those thumbnails are often used in image cataloging programs, file managers, grafic programs and many other kind of applications. Unfourtunately there is no widely used standard for handling and saving scaled down versions of an image. This leads to the current situation where several thumbnails exist for every single image on the users harddisc. These can mostly only be used by the program which generated them. The purpose of this document is to provide a general method for this task and enable different programs to share their generated thumbnails as much as possible. The described handling can be integrated into helper liberaries which make this process completely transparent to the single application (eg. it could be integrated into the base libraries of GNOME and KDE). Place for permanent storing. Preserve informations about original image. Handle different thumbnail sizes. Handle thumbnail generation failures. The image format for thumbnails is the PNG format, regardless in which format the original image was saved. Two quality modes will be distinguished for thumbnails: high quality (with antialiased scaling) and low quality, where the abbrevations are hq and lq. The thumbnail name is concatenated from the original image name (including the suffix), the quality (either .lq or .hq) and the .png suffix. So the thumbnail name for portrait.jpeg in low quality would be portrait.jpeg.lq.png. For my_car.png in high quality it would be my_car.png.hq.png. The advantage of this method is, that you can easily check for high or low quality thumbnails by just adding the appropriate string to the orignal name. The most important thing is to assure that the thumbnail image contains always the same informations than the original image, only downscaled. The idea here is to explicitly set the modification time (mtime) of the thumbnail to the modification time of the original image. If those differ you know that the thumbnail is invalid. The good thing about this is that it also detects thumbnails which didn't set their mtime to the original mtime and regenerates them. If we would just use the time where the thumb is generated and do a image.mtime < thumb.mtime check, there are some circumstances where this check gives incorrect results. E.g. you can move another image over the original, where the mtime changes but is in fact lower than the thumbnail mtime. So this is bad. Additional to the mtime the permissions of the thumbnail should be set to the same as the ones of the original image. So if the user restricts the read permissions of the original image, other users can't see the thumbnails either, which is mostly the desired behaviour. Often it's useful to store also other informations about the image within the thumbnail, eg. file size or image dimensions. This avoids any need to open the original image to access further informations. The PNG format provides a mechanism to store random text strings together with the image. It uses a simple key/value scheme, where some keys are predefined like Title, Author and so on (see section 4.2.7 of the PNG standard). For a thumbnail PNG image the following keys are allowed: Width: The width of the original image. Height: The height of the original image. Size: Size in bytes of the original image. Software: This key is predefined by the PNG standard. It stores the program which generated the image. Maybe this is of any use. If the generation of a thumbnail fails (e.g. the image format is unknown or it is just too big, where 'too big' should be defined by the user somewhere) this information should be saved for the future to avoid trying it again and again. Instead, the program should create an empty file with the name of the original image suffixed by .failed. So every program should check for this kind of file before it generates a new thumbnail. Nearly every program uses different dimensions for their thumbnails and some even support multiple thumbnail sizes (eg. this is planned for Nautilus in the future). The proposed solution here is, that every program which implements this standard, has to support at least a specified set of thumbnail sizes and must not generate sizes of other dimensions. The problem of course is to find a sensible set of values. For now I suggest the following ones (width x height): 48x48 (very small), 64x64 (small), 96x96 (medium), 128x128 (large), 144x144 (extra large), 160x160 (super large). A programm doesn't need to generate a thumbnail for all sizes. Only for the one it actually needs. If a program want to use another thumbnail dimension, it can use a slightly bigger one from the above list and scale this down to the desired size. To not hide the generated thumbnails in obscure directories and thus don't make them locateable for the user, the directory for storing the thumbnails is named .thumbnails. The first place to search for a thumbnail is the .thumbnails directory in the directory where the original image lies. The overall thumbnail directory is ~/.thumbnails in the users home, which should be queried if the previous search fails. If you don't find the thumbnail you should create one and try to put it in ./.thumbnails in the original image directory or if this fails (e.g. lack of write-permissions) put it into ~/.thumbnails. If the thumbnail is stored in the global thumbnail directory in the users home, the filename must contain the whole escaped URI to the original image. So this directory is some kind of special, because it can contain tumbnails with a simple name and with full escaped URIs. Each .thumbnails directory has the same structure. For every thumbnail size there is a seperate directory with the name 'width'x'height': ./thumbnails/ ./thumbnails/48x48/ ./thumbnails/64x64/ ./thumbnails/96x96/ ./thumbnails/128x128/ ./thumbnails/160x160/ So you can find all medium sized thumbnails in high and low quality in the 96x96 directory. All the *.failed files, which indicate that the thumbnail couldn't be generated, should be directly written to the ./thumbnails directory. The described method should enable all programs to manage their thumbnails and to save them permanently. If a big group of programms do it this way they can also share these with each other, which is a big benefit for the user.