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
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.
- downloads from digital cameras that support the USB mass storage protocol,
- file handling, i.e., copying, moving, renaming, deleting,
- 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.
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:
- 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
- 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.
The installation process is described in the file
you have to install all of the above components and then copy the
tkalbum script to a place where it can be executed.
3.1 Program Calls
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
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
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.
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 pictures, delete
pictures, undeleted them, move them around, transform them, annotate
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.
4.2 Previewing Pictures
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
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
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
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.
4.3 Generating a HTML Album Page
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
4.4 Working on Your Pictures
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.
4.5 Fine Tuning Your Album Pages
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 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
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-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
- 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
4.7 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 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.
4.8 Shared Albums
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
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. 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.
You can reach me under bernhard.nebel <at>
gmx.de. Encouragements, bug reports, wish lists, etc. are
welcome. When you send a bug report, please be as specific as