TKAlbum

TKAlbum supports

• downloads from digital cameras that support the USB mass storage protocol,

• file handling, i.e., copying, moving, renaming, deleting, undeleting,

• image editing and viewing,

• transformation of images in a lossless way,

• inspection and modification of EXIF data in JPEG files,

• editing descriptive data for the album script, e.g., album and picture descriptions, orders of images, etc.,

• customization of the album script execution, and

• generation of HTML photo albums using the album script.

The nice thing about the album script is its simplicity and esthetics. Just store your photos in a directory (tree) and off you go. If you want a change in design, use a different theme and regenerate the album pages. If you want to annotate the photos, just add picture names and captions and regenerate the album pages. TKAlbum also supports multiple root albums (with associated profiles). One can also establish shared profiles so that a group of users can maintain a photo album.

1. PREREQUISITES

TKAlbum uses the following programs/systems:

• album (version 3.01 or more recent) by David Ljung Madison, a Perl script for generating HTML photo albums (http://marginalhacks.com/Hacks/album/). You need to have Perl (http://www.perl.com/) installed to run the album script.

• jhead (version 2.2 or more recent) by Matthias Wandel, a program that analyzes the EXIF data structure in JPEG files generated by digital cameras. A number of interesting information can be extracted, such as the date and time the picture was taken, the exposure time, focal length, aperture, dimension of picture, etc. Additionally, one can extract integral thumbnails (of dubious quality). (http://www.sentex.net/~mwandel/jhead/)

• jpegtran (version 6b), rdjpgcom, and wrjpgcom by the Independent JPEG Group. These programs implement lossless transformations of JPEG files and can read and write the comment field in JPEG files, respectively. (http://www.ijg.org/)

• Image Magick's tools convert, mogrify and display (version 5.5.7 or more recent). These programs can be used to convert, to display, and to edit image files having a wide range of different image formats. (http://www.imagemagick.org/)
• xzgv, a picture viewer. This program is used as the default picture viewer because it is much faster than Image Magick's display program. However, it is, of course, possible to use display instead of xzgv.

2. INSTALLATION

3. CUSTOMIZATION

3.1 Program Calls

If some of the component programs have not been installed, or are not in a place that is mentioned in the path variable, or if the programs have the wrong version, TKAlbum will complain on startup. Please go back and install the programs if you have not done it yet. If they are installed but TKAlbum just does not have an idea where, you can continue and change the path to the program under General options in the Options menu. If the version is wrong, you can continue at your own risk and come back later and update. The installation check is executed on each startup and after each General options dialog. This is also the place where the installation check can be disabled, again at your own risk.

You may want to consider substituting some of the component programs with other programs. For example, as an external viewer I use xzgv (with options "--zoom --fullscreen") instead of ImageMagick's display program, which is the default. Similarly, as an the image editor you may want to use gimp instead of ImageMagick's display. Note that it might be necessary to change the options for the program call under File options. Additionally, you can install the script fconvert (also in the distribution directory). It makes use of the netpbm programs and is a bit faster than convert on some files.

There are also a large number of other options one can change, too many to cover here. Just start the dialogs and inspect the dynamic help texts that pop up after half a second with the mouse in one area of the window. The dynamic help messages will also displayed when moving with the mouse in the main window and over menus and menu entries. If these dynamic help texts start to annoy you, you can disable them in the Help menu.

3.2 Interface to the Camera

If you do not know the type of your camera, consult the various sources that describe what camera supports which protocol, e.g. http://www.qbik.ch/ (USB support in general) and http://www.gphoto.org/. Another way to find out whether your camera supports the USB mass storage protocol is to plug your camera into a free USB port and watch /var/log/messages and /etc/fstab. If you have a recent Linux and the camera is right, you will see messages telling you how the camera can be mounted. If you do not have any SCSI hard disks, chances are that your camera can be mounted as /dev/sda1. Perhaps you have to add an entry to /etc/fstab and to provide a mount point. In my case the hot-plugging mechanism extended /etc/fstab and provided a user mountable device under /media/sda1.

If your camera is such a camera, you can now customize the Camera options and then you should be able to download pictures from your camera. Well, before you can do so, you have to tell TKAlbum where the root album is.

3.3 Setting up the Root Album

4. CREATING AND MAINTAINING ALBUMS

4.1 Setting up an Album

4.2 Previewing Pictures

First of all, an EXIF thumbnail is extracted from the JPEG file if possible (controlled by the Use EXIF thumbnail option under View options). This takes usually only a fraction of a second, but the quality leaves a lot to be desired. If the aspect ratio of the initially displayed thumbnail differs from the aspect ratio of the preview generated later on, then it is a good idea to enable the Adapt aspect ratio for EXIF thumbnails option.

Secondly, the image file is converted (running the Image-Magick tool convert in the background) to a PPM or GIF file, which is then loaded into TKAlbum and displayed. GIF files are smaller than PPM files, but the generation of PPM files is much faster (for this reason I recommend to leave the option Preview file type in the View options at ppm).

Thirdly, the picture is then internally cached in main memory so that the next time when one wants to preview the picture again, it can be displayed much faster. Of course, this sort of caching uses up main memory. In order to control this kind of caching, one can specify a maximum number of images that are cached internally using the Internal cache size option under View options. The default is 100 images corresponding to approx. 70 MB when using a preview size of 500x500.

Fourthly, the converted file is also cached externally on the hard disk so that the next time the program is started, the preview can be generated much faster. The latter feature is controlled by two options under View Options. Cache previews externally controls whether previews are cached on hard disks at all (default on). External cache size gives the maximum number of previews that are cached. Since the maximum size for a preview appears to be roughly 0.5 MB, it seems to be safe to set this value to 400 (which is the default), resulting in a 200 MB cache area.

4.3 Viewing Single Pictures and Slide Shows with an External Viewer

4.3 Generating a HTML Album Page

In addition to generating one album page, there are ways to generate an entire hierarchy of album pages or part thereof, which are described below in Section 4.6

4.4 Working on Your Pictures

If some of your pictures have to be rotated or flipped, you can use the commands in the Transformations menu. Note that these operations are lossless if applied to JPEG files. Furthermore, a small comment is put into the JPEG comment field that allows for reusing the EXIF thumbnail even if the original picture has been rotated or flipped.

You may have noticed that the thumbnails on the album pages are cropped so that they have all the same size & aspect ratio. This is, in fact, one of the highlights of the album script. Sometimes, however, the album script may just choose the wrong part of the picture. If you enable Show thumbnail cropping in the View menu, you can see which part of the picture will be selected for the thumbnail. You can change the cropping by using the Thumbnail menu.

4.5 Fine Tuning Your Album Pages

If you believe that the design of the HTML pages is a bit dull, then themes is what you are looking for. The design of your generated HTML pages follow the default theme. Other themes, e.g., the Blue theme that comes with the album distribution, can be selected (more themes can be downloaded from the album web site). Personally, I prefer to copy the theme directories into the root album and make them invisible by using the Album > Hide current album command. Such a theme can then by selected using the the Options > Album options dialog.

4.6 Executing the Album Script

• Strictly local generation (Meta-S): The album in the current directory will be (re-)generated without descending into sub-directories. Thumbnails and medium-sized previews will be regenerated only if the pictures they were generated from have changed. This is the right way to use the album script when just some local changes have been made. Note that there is no difference between strictly local and local if the current album does not contain sub-albums.

• Local generation (Meta-L): The albums are (re-)generated starting from the current album descending into sub-albums. Thumbnails and medium-sized previews will be regenerated only if the pictures they were generated from have changed. This is the right way to apply the album script if an entire sub-tree has been edited or inserted. If the current album is a new album, i.e., there exists no entry in the index file of the next higher album to the current album, then it is necessary to start the album script once in the the next higher directory in order to get the right navigation entries on the HTML pages.

• Global generation (Meta-G): All albums starting from the root album are (re-)generated. Again, thumbnails and medium-sized previews will be regenerated only if the pictures they were generated from have changed. This is the right way to call album after a theme change.

• Global generation & cleanup (Meta-P): Same as above. In addition obsolete thumbnails, medium-sized pictures, and HTML pages are deleted. There is also an option in the Album options dialog, where one can enable this behavior for every (re-)generation operation.

• Forced (re-)generation: Same as the corresponding operation above, however, all thumbnails and medium-sized pictures are regenerated. This kind of call is necessary if the geometry of the thumbnails or of medium-sized pictures has changed. It usually takes a considerable amount of time to do this for all pictures.

4.7 Multiple Root Albums

4.8 Shared Albums

The idea is to set up a dedicated Unix group for this purpose and make all users who shall be able to modify the albums members of this group. Then the initial album must be set up such that all files belong to the new group and the group write permission is set. In TKAlbum, the group name must be entered in the General options dialog in the field Group ID for shared work on albums. If this field contains a non-empty string, TKAlbum will make sure that all files generated in this album will belong to this group and have their group write permissions set, so that everybody from the group can delete and overwrite these files.

In order to guarantee that the users use all the same settings, they can also share the profile. Just save the profile in some directory of the owner of the shared album with the right write permissions and then use the Load profile for all other users to point to the same profile. Subsequent changes will then be propagated to all other users (when starting TKAlbum). In order to avoid the risk of creating confusion when many users start to modify the profile or the album concurrently, some basic locking mechanism exists (since version 0.7). Profile directories and root albums are write locked. Any users starting later will get a message saying that the profile directory or root album is locked and that the only way to continue is to switch to read-only mode. In particular, if a user loads a profile pointing to a root album that is locked by somebody else, changes to this profile will also not be recorded. This is done in order to prohibit concurrent changes to a shared profile.

5. PROBLEMS AND SOLUTIONS

One problem that has been reported is that TKAlbum does not deal properly with symlinks. As it turns out, it is not a good idea to use symlinks in an album structure. The reason is that the theme specific files are accessed from the HTML pages (generated by the album script) using relative paths. When one uses symlinks, such relative information will quickly lead to dangling references and the display of the HTML pages will look funny. Additionally, there is the problem that symlinks would make it much more difficult to maintain the hierarchical structure of the albums. For these reasons, the usage of symlinks in album structures is strongly discouraged and TKAlbum will complain if you use them.

Another problem is that TKAlbum ignores the per file captions, which are stored in files named <image>.txt. Since the album script considers these with a higher priority than the captions in captions.txt, captions entered in the TKAlbum will not have any effect if there are already per file captions. There will be a solution in the future.

If you encounter the problem that there are lock files prohibiting to work with an album or to use a profile directory although you believe that there shouldn't be any locks, you can manually delete these lock files (called .lock.no_img) in the profile directory (~/tkalbum) or root album. Of course, this is on your own risk.

6. CONTACT