digitAlbum

Sample thumbnail

Introduction

When I bought my first digital camera (a Nikon 4500), I thought it would be nice to have an online (and offline) photo album, so I could show others my photos. There are huge numbers of album generators available, but none of them did quite what I wanted. One generator (album by David Madison) was based on the idea to have all thumbnails the same size, both landscape and portrait photos, which looked rather good. His album generator though could only be used to "pre-generate" all album files.

So, building from there, my own digitAlbum was born. It grew a bit more than I anticipated, and has now two methods of displaying thumbnails on a page, a slideshow mode, and a companion management interface to quickly add photos straight from the camera into one or more albums.

How does it work?

Regular vs irregular grid

No fuss

The scripts are based on the idea that you can put some images in a directory, and not bother any further if you want. (Usually you want to bother, in order to have nice captions, etc). Therefore the scripts will generate thumbnails (and medium size images) on the fly. These generated images are stored on the webserver, so when another user comes along, no files have to be created. If you change an image, the thumbnails will also be generated again.

Sub albums

A directory with images is considered to be an 'album'. An album can contain sub-albums (i.e. subdirectories). In the overview pages with thumbnails, sub-lbums get their own special thumbnail, showing tiny versions of the first four images in the sub-album.

Info files

For each directory encountered an album.info file is created, containing the names of the image files in the directory, and a default caption (name of the image without its extension). In this file, rating can be added (see below), and the order in which the images should be displayed can be changed by moving the image section around.

Regular vs irregular

You have a choice to display the thumbnails in a regular grid (where all thumbnails are the same size), or in a irregular grid (where the size of the thumbnail depends on the rating given to the image). The images are processed in the order they appear in the album.info file (which initially is the order they appear in the directory). For a regular grid, thumbnails are placed row after row. For an irregular grid, the scripts will try to find the first "free" position for the thumbnail depending to the size of thumbnail. The example to the right shows what happens when you have nine images and a grid of five cells wide.

Ratings

Images can be rated with a number from 1 through 4. The higher the rating, the nicer the image is assumed, to when using an irregular grid, images with rating 4 get the biggest thumbnails.

Rating selector

You can also decide to let the viewer have the option to select what images he or she gets to see depending on their rating. (See the ratingAction option below). In that case, at the bottom right hand corner of the album pages there will be a selector where the viewer can choose to see all images, or only the images with a rating of 2 and up, 3 and up or 4 and up.

Slideshow

You can also set a slideshow timer. When set, on the top-right corner of each page there will be a checkbox with which the user can enable the slideshow. On regular intervals the scripts will load the next image. The user can disable the slideshow at any time to take a longer look at an image.

Set-up

Installation

The software consists of a number of PHP-scripts, so your webserver should have PHP available. A recent (>= 4.x) should work ok.
Next, the scripts depend on a number of external programs to do the thumbnail creation. These are:
- montage - part of ImageMagick
- convert - idem
- jpegtran - only used by the management interface
- thumb - by David Madison; it can be downloaded from his website, and uses Perl and convert
Make sure these are on the webserver - if not, install them.
When this is all in place, put the digitAlbum scripts in a directory accessible by (and reachable through) the webserver.
Change the album.config.php file as required. These are the global settings, and most can be changed on a per-album basis. See the next section for all options.
Make sure the paths to external programs in the album.config.php file are defined correctly for your system.
Create a directory where you want to store your album(s), and either use the management interface (see below) to put some pictures in this directory, or copy them by hand.
If you have enabled aliases, you should now be able to browse the album using an URL like:
http://hostname/path/to/album.php?album=alias
If you are not using aliases, the URL will look like:
http://hostname/path/to/album.php?album=/path/to/album/directory
The first time you access an album, all thumbnails have to be generated, so it might take some time. If nothing happens, check either your PHP log (errors here are related to insufficient access rights for creating files and directories), or your webserver log (where the errors from the external programs are usually logged).

Configuration

The following options can be set in the configuration file:

numCols - the number of columns in the thumbnail pages; when using an irregular grid, the number of smallest-size thumbs on a row
showTitle - set to true when the album title should be shown or false if not
showCount - set to true when for a sub-album the number of images in the sub-album should be shown alongside the caption or false if not
albumPrefix - if set, the value of this option is prefixed to all sub-album captions
infoFile - name of the file to store album info in; defaults to album.info
aliasFile - see aliases section
aliasesOnly - see aliases section
editCode - if set, you can use the regular scripts to modify image captions and ratings. For example, if you set editCode to the value forsure, you can use the URL:
http://hostname/path/to/album.php?album=alias1&edit=forsure
to go into edit mode. The default value is allowed
mWidth and mHeight - the size of the medium images. When a thumbnail is clicked, the medium size imag is shown first, and when the medium image is clicked, the full size image is shown. If the full size image is smaller than these values, no medium size image is generated
mediumStrict - Set to true when you want all medium images to fit in the medium size rectangle (i.e. when set to false, portrait images will get mWidth height and mHeight width)
cssURL - the URL of the CSS file to use
imgSuffix - array containg image suffixes which are allowed in an album. If you need to change this, also modify image.php
ratingAction - RATING_IGNORE, RATING_SELECTOR, RATING_SIZES
thumbSizes - when using an irregular grid, use these sizes for the four thumbnail sizes (one per allowed rating value). Each sub-array contains regular thumbnail width, panorama thumbnail width and thumbnail height. If you change this, experiment to get nice looking results (each step up should allow room for the whitespace between two adjacent smaller size thumbnails) for the whitespace between two thumbnails)
slideShow - if set, a checkbox is added to the album pages with which a slideshow can be started. Set the value to the number of milliseconds between each image
srcBase - see management interface section
dstBase - see management interface section
optimizeOnCopy - when using the management interface, and when PATH_JEPGTRAN is defined, the copied images will be optimized using the -optimize option of jpegtran when set to true. This will significantly reduce thumbnail size for the images when there was EXIF data in the original image. Note that the EXIF data will be stripped when set to true.
mimgsWidth and mimgsHeight - the maximum size of the main image shown in the management interface screen. The larger the better for comparison between images, butif set to larger than wouldfit on your screen, there will be a lot of scrollbar action involved...

Configuration overrides

Some of these options can be overriden a per-album basis, by adding entries to the album.info file for that album. For example, to change the numCols or a specific album, add the line in bold to the album.info file (and add the [Album] section if it does not exist yet):

[Album]
...
numCols=8
...

Aliases

You have the choice to use aliases for album locations, or to use absolute file paths. If the aliasFile option is set, the scripts will try to expand the first element in the album parameter using the aliases file. An aliases file looks like:

[aliases]
alias1=/some/directory
alias2=/another/directory

When the user now requests

http://hostname/path/to/album.php?album=alias1/subalbum

the scripts will expand the album parameter into /some/directory/subalbum. When the aliasesOnly option is set, the uses has to use an alias. If it is not set, the user could also have requested

http://hostname/path/to/album.php?album=/some/directory/subalbum

directly.

Look and feel

The scripts generate table with CSS-class indicators on the table, its rows, the cells and the labels. Customize the look-and-feel by changing the example album.css file.

Panoramas

To make the software create appropriate space in the thumbnail pages for panorama photos, add the line in bold to the section for that image:

[pano-harbour.jpg]
caption=View on the harbour
panorama=yes
rating=3

Management interface

The mimgs.php script can be used to easily transfer images from your camera to an online album.

Selection of directories

On the first page you have to enter the directory where the 'original' images are stored, and the directory where the albums are stored (or to be created). For both you have to choice to enter the (full) path by hand, or to select one of the subdirectories of the srcBase and dstBase configuration options.

If you have large directories with many images, and you are in the 'middle' of organizing that directory, you can optionally enter the filename of the image where you want to start in the source directory.

Main interface

If the directories have been entered, press 'continue' to go the main management interface.

Note: the original images are always shown in their original size here, so if you have a high resolution camera, you might need a large desktop...

At the center of the screen the current image is shown, and to the left and to the right are shown (if any) the previous five and next five images as thumbnails (Note: to keep things as smooth as possible, for these thumbnails the EXIF-thumbnail from the original image is used; no thumbnails are created).

Beneath the image, there a number of entry fields:

Description - The description of the image as will be shown beneath the image in the album;
Subfolder - Where to put the image. If not filled in, the image is copied to the destination directory as specified on the first page;
Mark as - Add one or more entries delete=yes, print=yes and edit=yes into the album.info file. Delete and print are currently not used (but could be used to quickly find which images you to print for example). Edit is only used to give the table cell in which the image is displayed in the albums a different CSS-class name. I use it to mark the images I want to post-process with Photoshop - with my CSS file, these images get a slightly lighter table cell background;
Rotate - If one of the values is checked, the image will be rotated before it is copied to the destination directory;
Rating - The rating to use for the image.

Cropping images

If you click with mouse on the image, and drag the mouse, a rectangle will be drawn on top of the image. This rectangle is then used to crop the image before it is copied to the destination directory. Once drawn, the rectangle cannot be modified. Go to another image and back to remove the rectangle and try again.

EXIF data

If you hove the mouse over the image, a summary of the EXIF data from the image is shown (if present). This also works for the thumbnails, and can be used to compare images.

Maneuvering between images

There are five ways to go to another image:

The 'do it' button - this will apply any rotation or crop, and copy the current image to its destination directory. The album.info file in the destination directory will be updated with information on the copied image. The next image will be shown;
The 'next' button - this will ignore any input you have made, and go to the next image;
The 'goto' hyperlinks - these will jump directly to the specified image, ignoring any input;
The 'preview' hyperlinks - these will open the selected image in a separate window, so two or more images can be compared more easily;
The 'next folder' button - this will return to the first page, where new source and destination directories can be selected.

Static albums

The staticalbum script can be used to generate a 'static' album, i.e. one that does not require PHP anymore, and can for example be put on a CD. First, make sure that the first line of the script points to your PHP executable.

staticalbum recognizes the following arguments:

--srcdir /some/dir - create a static album for all images in the /some/dir directory;
--dstdir /some/dir - name of directory where the static album will be generated;
--imagesonly - Create thumbnails only, not HTML files (this can also be used to pre-create all thumbnails for use with the regular scripts, if for example you do not want the webserver to create files);
--noimages - Just create HTML files, do not create any thumbnails;
--createinfo - Create the necessary album.info files. Note that these are not used by the static album, so they would be either for reference, or could be used to pre-create album.info files;
--nocss - Do not create a local copy of the CSS file, keep the reference to an external CSS file as defined in the album.config.php file.
--title - Title of album on initial page
--regular - Force use of a regular grid (ignoring global settings)
--irregular - Force use of an irregular grid (ignoring global settings)

An example for creating a static version of an album would then look like:

$ staticalbum --nocss --srcdir /home/herman/album --dstdir /tmp/staticalbum

The script will output the progress as it works its way through all images.

FAQ

The file sizes of the thumbnails are very large!
The way the thumbnails are generated, the so-called EXIF-data is also copied to the thumbnails. In the EXIF-data there can be a thumbnail generated by the camera, and this makes the thumbnail file size larger than necessary. If you want to fix this, either remove EXIF-data from the images before putting them in an album, or remove the EXIF-data from the generated thumbnails. The --optimize option of the jpegtran will do this.

Known issues

The following are known issues, bugs, etc:

The static album generated by staticalbum behaves slightly different in slideshow mode: each next page loaded will always be an image page - album pages are skipped

Download

The latest version of digitAlbum is available as a ZIP-file. The ZIP-file contains all scripts and this documentation.

Version history

1.00

initial version

1.01

corrected count of images in subalbum when an [Album] section exists
fixed minor bug for filenames with spaces and other special characters

1.02

added check for existence of gettext functions
made paths to external programs easier to configure

1.03

PATH_JPEGTRAN can now also be defined as an empty string; convert will be used

1.04

new option to determine if -optimize option of jpegtran should be used when copying images
new options to determine maximum size of image to show in management interface, which now also supports non 4:3 images

1.05

fixed bug with album thumb sizes when using irregular grids
fixed bug with rowspans for irregular grids
fixed bug with inbalanced table cells
added options showCount and albumPrefix

License and credits

digitAlbum is released as e-mail-ware: please send me an e-mail if you use the program. If you are really ecstatic about digitAlbum, I have a wish list at Amazon.

All of this is inspired by the album script written by David Ljung Madison (see his album website).

The idea for the irregular grid came from Jeroen van Dalen.