Ruby Photo Library

Home Page

Below is the README file for the Ruby Photo Library.

You can see an example of RPL's output (and of my first digital photography) here.

Ruby Photo Library

Clifford Heath (

(c) Copyright 2002 Clifford Heath.
You may use or abuse this code for any purpose, provided you don't
claim you wrote it or blame me for something it does or doesn't do.


These are tools for managing a library of photo albums, mainly for the
purpose of burning onto CD so family and friends can easily browse them.
They don't aim to provide flexible layout, just convenient navigation.
If someone wants to use their Ruby experience to show me a good way to
template the HTML code, or get ornate and use XSL etc, I'm listening!
I've only been using Ruby a short while, so have many tricks to learn.

Tools summary.

	Create or update resized versions of the original images.

        Generate HTML thumbnail sheets and individual photo pages for
        each size of each photo.

        Extract camera settings from the Nikon "info.txt" file and write
        any non-default settings into an appropriate file in the "info"
        directory. Probably not useful unless you're using a Nikon Coolpix.

        Small shell script to create a new album using the current date
        as a directory name.

Album layout.

Each album consists of an "albumtitle" file, one or more image directories,
and up to three optional directories containing text files, named
"caption", "info" and "epinfo".

The "albumtitle" file contains one line of text to be used in the HTML
page title and the heading on the index thumbnail sheets.

The image directories are named as NNNxMMM, where NNN and MMM are the
pixel width and height within which the images are expected to fit. The
directory with the largest width is regarded as the originals; these
won't ever be overwritten. The directory with the smallest width is used
for the thumbnail index sheets.

The caption directory contains text files usually containing only one line
of text each, which is placed above the image in the individual photo pages.

The info directory contains text files also, often multi-line, which is
placed below the image in the individual pages. I use this to store the
camera settings.

The epinfo directory contains text files, but these are added as hyper-links
below the info text. The directory is named after the "epinfo" tool that
comes with the "photopc" package. This tool extracts the Exif image data
from the images.


Usage: photothumb [ options ... ] [ album ... ]
	--size NNNxMMM	Create resized images that fit in specified size
	--verbose	Show progress details (resize commands)
	--help		Show this usage message

photothumb processes each album specified, or the current directory.

All directories named in the NNNxMMM format described above are enumerated,
and any new sizes are added as specified using the --size option. These
directories will be created if necessary.

For each original file (in the directory named with the largest width
value), the corresponding file in each other image directory must be
created or updated. If the target file exists with a modification time
more recent than the original, it is left alone. Otherwise photothumb uses
the "jpeginfo" command to extract the width and height of the original
image. The target output size is computed, as the biggest imag that
preserves the aspect ratio while fitting in the size limits of the target
directory.  The resize strategy depends on the exact ratio. The preference
is to use the "-scale" option of "djpeg" to perform scaling of 1/2, 1/4 or
1/8 first, since this is fast and loss-free. If more scaling is required,
"pnmscale" is used, followed in any case by "cjpeg" to produce the final
target image.

Usage: photoindex [ options ... ] [ album ... ]
	--across N		Number of thumbnail across (default 3)
	--down N		Number of thumbnail down (default 3)
	--background color	Background color (default black)
	--foreground color	Foreground color (default white)
	--link color		Link color (default blue)
	--vlink color		Visited link color (default dim blue)
	--nonlink color		Color of inactive link (default grey)
	--noalbum		Don't include albums link
	--verbose		Show progress details
	--help			Show this usage message

photoindex processes each album specified, or the current directory.

All image directories containing images are enumerated as for photothumb.

All non-text files in all image directories are enumerated. Non-text
currently means the file extension isn't "htm", "html" or "txt".

All related text files from "caption" and "info" directories are loaded
along with the "albumtitle" file.

Files having the same basename across all directories are presumed to be
different versions of the same file. An HTML navigation wrapper is generated
for each image file in each directory. This wrapper contains the caption,
links to the albums directory, to the next, previous, first and last files,
and to all versions of this file. Below the image is the "info" text and a
link to the epinfo file, if that exists.

A set of HTML thumbnail sheets is generated, each showing a 3x3 matrix
(or as requested) of thumbnails (this works well with my preferred
thumbnail size of 256x192).  The thumbnail sheets are named "index01.html",
"index02.html", etc.  Each has a next and previous link, as well as a link
to each of the others.  The title and heading for each sheet is taken from
the albumtitle file, with a page number added.

Future/Known problems.

The albumtitle file should be a formatted text file called "album" which
contains all the settings (color, layout, etc) for the album.

If the originals directory contains movie (*.mov) files etc, they aren't
correctly linked and cannot yet be thumbnailed.

Many other limitations, I'm sure you'll find them :-)