SourceFiles.org - Use the Source, Luke

Back to files

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <title>TKAlbum README</title>
</HEAD><BODY BGCOLOR="#FFFFFF">

<center>
<h1>TKAlbum</h1>
</center>

TKAlbum is a graphical user interface assisting in the generation and maintenance of HTML photo albums. It uses the album script, the jhead tool, the jpegtran utility, and the Image Magick tools to generate hierarchically organized HTML photo albums. One can tell the story also the other way around: TKAlbum is the GUI for the album script that gives you the functionality you missed when working with the album script.

TKAlbum supports
<ul>
<li> downloads from digital cameras that support the USB mass storage protocol,

<li> file handling, i.e., copying, moving, renaming, deleting, undeleting,

<li> image editing and viewing,

<li> transformation of images in a lossless way,

<li> inspection and modification of EXIF data in JPEG files,

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

<li> customization of the album script execution, and

<li> generation of HTML photo albums using the album script. </ul>

The photos are stored in albums, which are organized in a hierarchical manner, i.e., an album can contain pictures and sub-albums. There exists one designated root album. Albums are implemented as directories, which contain the pictures and sub-albums, together with additional descriptive data and some cached data. The album script is used to generate HTML files and thumbnails from this structure, which can be viewed with any web browser. All pictures in one album are displayed as thumbnails on one HTML page. 
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.

<h2>1. PREREQUISITES</h2>

TKAlbum has been implemented using Tcl/Tk (version 8.4), which you probably already have or which you can easily install if you have a recent Linux distribution. It is also possible to install Tcl/Tk under Windows and Mac, but I haven't tried to run TKAlbum under these operating systems. Since the current implementation contains a number of platform specific features, it is probably non-trivial to port TKAlbum to Windows or to the Mac.

TKAlbum uses the following programs/systems: <ul>
<li> album (version 3.01 or more recent) by David Ljung Madison, a Perl script for generating HTML photo albums (<a href="http://marginalhacks.com/Hacks/album/">http://marginalhacks.com/Hacks/album/</a>;). You need to have Perl (<a href="http://www.perl.com/">http://www.perl.com/</a>;) installed to run the album script.

<li> 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).
(<a href="http://www.sentex.net/~mwandel/jhead/">http://www.sentex.net/~mwandel/jhead/</a>;)

<li> 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. (<a href="http://www.ijg.org/">http://www.ijg.org/</a>;)

<li> 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. (<a href="http://www.imagemagick.org/">http://www.imagemagick.org/</a>;)

<li> 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.
</ul>

<h2>2. INSTALLATION</h2>

The installation process is described in the file <a
href="INSTALL.html">INSTALL.html</a>. Basically, you have to install all of the above components and then copy the tkalbum script to a place where it can be executed.

<h2>3. CUSTOMIZATION</h2>

<h3>3.1 Program Calls</h3>

If you have successfully installed TKAlbum and all the component programs, you can now start TKAlbum and customize it by setting the appropriate options.

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.

<h3>3.2 Interface to the Camera</h3>

The next important part is the customization of the interface to your digital camera, provided you have a camera that supports the USB mass storage protocol and your Linux supports it (as all more recent versions do). If you do not have such a camera, you probably want to disable the Camera download functionality completely, which can be done by clicking on the appropriate check button in the General options menu entry (well, I probably add support for cameras supported by gphoto in the near future -- if somebody wants it and tells me what to do).

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.

<h3>3.3 Setting up the Root Album</h3>

Before you can do anything productive with TKAlbum, you have to tell it where your root album is. Use the Set root album entry in the File menu to do so. The root album is the album which contains all other albums directly or indirectly, and it may contain pictures as well. Now you can download pictures from your camera, preview them, see what album's thumbnail cropping does to your pictures, delete pictures, undeleted them, move them around, transform them, annotate them, ...

<h2>4. CREATING AND MAINTAINING ALBUMS</h2>

<h3>4.1 Setting up an Album</h3>

Albums are organized hierarchically. Check out David Ljung Madison's web pages at http://marginalhacks.com/Hacks/album/, which contain some examples. In order to get a first idea, put a few photos in a directory below you root album or in the root album itself and use the Open album menu entry in the File menu to point to this directory. You can preview your pictures and see some information about your pictures in the center area of the window.

<h3>4.2 Previewing Pictures</h3>

Previewing pictures is one of the most CPU intensive tasks because pictures have to be converted to the right picture format and resolution. TKAlbum is designed to make previewing as fast as possible.

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.

<h3>4.3 Viewing Single Pictures and Slide Shows with an External Viewer</h3>

If it is not clear, whether you want to retain a picture or throw it away, it is probably a good idea to have a look at it using a higher resolution. The command Meta-X starts an external viewer. As the default, xzgv is used with te arguments --full --zoom, which means that a fullscreen picture is shown and the picture is zoomed accordingly. If more than one picture is selected, xzgv is started with the list of files. In this case, one can present a slide show, where the Space key advances and key b returns to the previous picture. Similarly, if no file or directory is selected or the current directory is the only selected item, xzgv is started with all files in the directory.

###################>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

<h3>4.3 Generating a HTML Album Page</h3>

Now you should already be able to generate an album page by pressing Meta-S or by selecting the entry Strictly local generation in the Album menu. Inspect the result by pressing Meta-B. This command starts Mozilla and loads file index.html in the current directory. If you want to start a different browser, use the General Option menu to change the field Browser. If there is no way to send a remote command to the browser the Browser remote field should be left empty. Otherwise, include @f at the point where the filename should be mentioned.

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

<h3>4.4 Working on Your Pictures</h3>

Note that there are no annotations but the file names below the thumbnails on the HTML page generated by the step described above. The annotations are controlled by the various text fields in the TKAlbum window. Just fill some text into the fields Picture Name, Picture Captions, and AltTag for some pictures, regenerate the album, and see how it affects the generated album page. Additional header and footer lines can be added by using the Edit header & footer command in the Album menu (or Meta-F).

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.

<h3>4.5 Fine Tuning Your Album Pages</h3>

You do not like how the pictures are ordered? The Album menu contains an entry called Sort that can be used to sort the entries according to different criteria. Furthermore, the order of the pictures can also be changed manually using the the two arrow buttons to the left of the directory listing.

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 <a href="http://marginalhacks.com/Hacks/album/">album web site</a>). 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.

<h3>4.6 Executing the Album Script</h3>

There are a number of different ways to execute the album script:

<ul>
<li> 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 <i>strictly local</i> and <i>local</i> if the current
       album does not contain sub-albums.

<li> 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.

<li> 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.

<li> 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 <i>Album options</i> dialog,
       where one can enable this behavior for every (re-)generation
       operation.

<li> 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.

</ul>

<h3>4.7 Multiple Root Albums</h3>

Of course, everything can be forced to fit under one root album. However, if things are quite diverse (i.e., one may want to use different themes) and/or the albums should be made public at different places on the web, it would be great to have different root albums perhaps with different settings. The most recent versions of TKAlbum offers such a possibility with the profile selection/load/create functionality in the Options menu. In the Select profile menu entry you can choose between all the profiles (incl. possibly different root albums) that are known to TKAlbum. The Load profile allows you to import a new profile setting and the Create new profile entry gives you the possibility to branch off a new album with associated settings. There is no way to get rid of an profile inside of TKAlbum. However, once deleted, profiles will be forgotten.

<h3>4.8 Shared Albums</h3>

If there is more than one user contributing to an album, one may want some support for shared maintenance of an album. TKAlbum provides some form of such support. The main assumptions are that all users work on one file system and that they start TKAlbum sequentially, i.e., they are not working concurrently.

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.

<h2>5. PROBLEMS AND SOLUTIONS</h2>

Since I finished the implementation of TKAlbum only recently, there are probably still a number of bugs. Use the program with caution. If you find bugs, please tell me.

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.

<h2>6. CONTACT</h2>

You can reach me under <tt>bernhard.nebel <at> gmx.de</tt>. Encouragements, bug reports, wish lists, etc. are welcome. When you send a bug report, please be as specific as possible.
</html>