				TKAlbum


TKAlbum is a graphical user interface assisting in the generation and
maintenance of HTML photo albums. It uses the "album" script by David
Ljung Madison, 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. It supports you in
dowloading the pictures, rotating (and perhaps editing) them, moving
them around, and most importantly annotating them.

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

The most recent version of album also supports multiple root albums
(with associated profiles). In particular, one can establish shared
profiles so that a group of users can maintain a hierarchical photo
album.

1. PREREQUISITES

TKAlbum has been implemented using Tcl/Tk (version 8.3), 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.

TKAlbum uses the following programs:

- album (version 2.39) by  David Ljung Madison, a Perl script for
  generating HTML photo albums.
  (http://marginalhacks.com/Hacks/album/)

- jhead (version 1.8) 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) by the Independent JPEG Group. This program
  implements lossless transformations of JPEG files, which is
  important if you want to turn your images by 90 degrees.
  (http://www.ijg.org)

- rdjpgcom & wrjpgcom by the Independent JPEG group. These programs
  can be used to read and write the comment field in JPEG files.
  (http://www.ijg.org)

- Image Magick's tools convert, mogrify, and display (version
  5.4.2). 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)


2. INSTALLATION
    
The Image Magick tools and the tools by the Independent JPEG Group are
in wide spread use and you probably have them already or can install
them from the CD of your Linux distribution. If not, just check out
the URLs mentioned above. I also assume that you already have Tcl/Tk
8.3 (or later) installed. Again, if not, install it from your
distribution CD or download it from http://tcl.activestate.com/.

The two remaining programs are part of the distribution of TKAlbum and
are very easy to install (of course, you can also check out whether
there are more recent version):

1) Copy the "album" script (in the directory album) to a place which
   is part of the path variable, e.g., to /usr/local/bin or to your
   own binary directory ~/bin/. Type "album -h" in a shell to check
   whether album starts. If not, you probably have to change the first
   line of the album script to correctly point to the Perl
   interpreter. Or worse, you have to install Perl - which is not a big
   deal, though.

   Note that the ffmpeg program, which can be used to generate
   thumbnails from mpeg movies, is not included in this
   distribution. If you need it, you can find links on the album web
   site (see above).

2) Change into directory jhead-1.8, type "make" and copy the resulting
   executable file "jhead" to a place where one can easily execute it,
   e.g., /usr/local/bin or ~/bin. Try it out by applying jhead to some
   JPEG file that has been produced by a digicam.

3) Finally, copy tkalbum to a place where it can be easily
   executed. Note that the wish shell should be located at
   /usr/bin/wish for the script to work. Otherwise change the first
   line of the script. 

   You may also want to copy the manual page "tkalbum.1" to a place
   where it can be accessed, e.g., /usr/local/man/man1. However, you
   can read the manual page also from within TKAlbum.


3. CUSTOMIZATION

3.1 Program Calls

If everything worked out so far, 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 in the "General options"
dialog. 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.

There is 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

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

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 pictutres, delete
pictures, undeleted them, move them around, transform them, annotate
them, ...


4. CREATING AND MAINTAINING ALBUMS

4.1 Setting up an Album

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.

Now you should already be able to generate album pages by pressing
Meta-S or by selecting the entry "Strictly local generation" in the
"Album" menu. Inspect the result by loading the file "index.html" in
the picture directory into your favorite browser.

4.2 Fine Tuning Your Album Pages

Note that there are no annotations but the file names below the
thumbnails on the HTML page. 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. Additional header and footer lines can be added by using the
"Edit header & footer" command in the "Album" menu (or Meta-F).

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 by
setting the appropriate path in the "Album options" (more themes can
be downloaded from the album web site).

Finally, you may have noticed that the thumbnails on the album pages
are cropped so that they have all the same size & aspect ration. This
is, in fact, one of the highlights of the album script (but you can
disable this feature in the "Album generation options" if you
want). Sometimes, however, album 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.3 Executing the Album Script

There are a number of different ways to execute 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-album. 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 corrsponding 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.4 Multiple Root Albums

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 version of TKAlbums
offers such a possibility with the profile selection/load/save
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 new
profile" allows you to import a new profile setting and the "Save
profile as ..." entry gives you the possibility to branch off a new
album with associated settings. There is no way to get of an profile
inside of TKAlbum. However, once deleted, profiles will be forgotten.

4.5 Shared Albums

If there is more than 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 machine 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 gurantee that the users use all the same settings, they
can also share the profile. Just save the profile in the home
directory of the shared album and then use the "Load new profile" for
all other users to point to the same profile. Subsequent changes will
then be propagated to all other users (when starting TKAlbum). There
is, of course, the risk of creating confusion, when many users start
to modify the profile concurrently. However, as said above, the
assumption is that the users work (almost always) sequentially.


5. PROBLEMS AND SOLUTIONS

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. For this reason, 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.

6. CONTACT

You can reach me at bernhard.nebel@gmx.de




