- all the current Dave Pointers. A l b u m 







Mailing List




Table Of Contents

  1. Overview
  2. Themes
  3. I want to use it on Windows!
  4. I want to use it on a Mac!
  5. Medium Size Images
  6. Captions
  7. Cleaning out unused thumbnails/html
  8. Hiding Files/Directories
  9. Cropping
  10. Digital Camera users
  11. mpeg/mpg Support
  12. Burning CDs (using file://)
  13. Indexing your entire album
  14. I want CGI, I want other people to be able to add photos
  15. How can I add EXIF information to my captions?

1:   Overview
First put all of your images into a directory.  You can organize them
into any number of subdirectories and each will become a sub-album (see
the example photo album).
If you also have non-images in your photo album directories, be sure
to use the '-known_images' option.

Then you run the "album" script on the top directory.

You can also re-run album on any of the subdirectories and it will
properly regenerate a portion of the entire album.

Album only generates thumbnails for new images or if images change, so
the first time you run album it may be slow.

You need ImageMagick to run album, see the Download page.

2:   Themes
If you want, you can specify a Theme to 
customize the look of your album.

To use a theme, download the theme .tar or .zip and unpack it.

Place the theme somewhere under the top of your web directory, but
don't put it inside your photo album directory, or else album will
try to make an album out of the theme directory.

Then call album with the -theme option:

  % album -theme <path to theme>

If you want to create a theme, see: Writing Themes

3:   I want to use it on Windows!
It's reported that Win95/98/2000/XP will run album with no problems if you
also install CygWin, which
is a great (though large) package that gives you Unixish tools on your Windows
box.  Make sure you choose to install Perl when you pick your CygWin packages.

There is a Win98 version of album (called album.98) which you should use
with Win95/98.  Other versions of Windows should use the regular album
script, unless:

If you don't want to do a CygWin install (which is pretty big), I managed
to get the album.98 version of album (see the Downloads page) working on
some systems using ActivePerl, but themes don't work yet.

You still need to install the ImageMagick tools, and make sure they
are in your path somewhere, you should be able to run "convert.exe -h"
from the CygWin prompt and get some usage output, not an error.

Some versions of Windows (2000/NT at least) have their own "convert.exe" in
the c:\windows\system32 directory (an NTFS utility?).  If you have this, then
you either need to edit your path variable, or else just specify the full path
to convert in your album script.

If you want help getting it working, let me know.

4:   I want to use it on a Mac!
It works fine on OSX, but you have to run it from a terminal window.  Just
install the script and ImageMagick tools, and type in the path to album,
any album options you want, and then the path to the directory with the
photos in them (all separated by spaces).

5:   Medium Size Images
Album can generate medium size pictures for web viewing, so you can still
keep your full-size photos and make them available, but not burden casual
viewers with larger photos.

Then the album index page will show the thumbnail size images, the image
HTML page will use the medium size photo, and clicking on the medium size
photo will give you the full-size "raw" photo.

You can use any options that convert uses:

% album -medium 600x400     Will generate medium size images that fit
                            within a 600x400 box (no cropping/stretching)

% album -medium 50%         Will generate medium size images that are 50%
                            the full-size image

Use -just_medium if you don't want to link to the full-size image at all.

6:   Captions
Images and thumbnails can have names and captions.
The default name is based on the filename, with the image type
removed and underlines converted to spaces:

"Kodi_Cow.gif"  =>  "Kodi Cow"

To add an optional caption, put the text in a file with the
same name as the image, but with the postfix of .txt:

caption example

Kodi_Cow.txt contains:
  "Kodi takes down a cow!"

People who use digital cameras often
have a collection of images whose
names are non-informative numbers.
You can either rename the image files,
or you can create a file called
captions.txt in each image directory.

Each line should be an image or
directory filename, followed by
a tab, followed by the new name.
You can also specify (separated by tabs),
an optional caption and then an
optional image ALT tag.
(To skip a field, use 'tab' 'space' 'tab')

001.gif		My first photo
002.gif		Mom and Dad	My parents in the grand canyon
003.gif		Angelina Jolie	My fiancee		Ouch!

The images and directories will also be sorted in the order they are found
in the caption file.  You can override this with -date_sort and -name_sort

If your editor doesn't handle tabs very well, then you can separate the
fields by double-colons, but only if the caption line doesn't contain any
tabs at all:

003.gif :: Angelina Jolie :: My fiancee :: Ouch!

Finally, you can create a header of text for an album page in 'header.txt'
and a footer in 'footer.txt'

Another option is to use caption_edit.cgi which allows you (or others) to edit
captions/names/headers/footers through the web.  (But note that unless you
secure the script, anyone can access/change your captions!)

7:   Cleaning out unused thumbnails/html
If you move images around but don't move the thumbnails or the image 
pages, you'll end up with a bunch of unused thumbnails in your 
thumbnail directory.  Use the -clean option, but only if you don't
have any non-images in your photo album!

8:   Hiding Files/Directories
You can ignore non-images with the -known_images option.

You can mark an image as a non-image by creating an empty file with
the same name with ".not_img" added to the end.

You can ignore a file completely by creating an empty file with
the same name with ".no_album" on the end.

You can avoid running album on a directory (but still include it in your
list of directories) by creating a file <dir>/.no_album

You can ignore directories completely by creating a file <dir>/.hide_album

The Windows version of album doesn't use dots for "no_album" and
"hide_album" because it's difficult to create ".files" in Windows.

9:   Cropping
You can specify the size of the thumbnails with the -geometry option.
If you change it, you might want to increase/decrease the number of
thumbnails that are put in each column with -columns, most themes
will respect this setting.

If you don't like the centered-cropping method that the album uses to 
generate thumbnails, you can give directives to album to specify 
where to crop specific images.  Just change the filename of the image
so it has a cropping directive before the filetype.  You can direct 
album to crop the image at the top, bottom, left or right.  As an 
example, let's say you have a portrait "Dave_And_Angelina.gif" that you 
want cropped on top for the thumbnail.  Rename the file to 
"Dave_And_Angelina.CROPtop.gif" and this will be done for you (you might 
want to -clean out the old thumbnail).  The "CROP" string will be 
removed from the name that is printed in the HTML.

10:  Digital Camera users
If you have a digital camera, chances are you have a collection of
photos that are the same aspect ratio (excluding photos taken sideways
that you've rotated).  In this case, set the -geometry of the thumbnails
to have the same aspect ratio as the camera, and you won't have any cropping
in your thumbnails.  If you have trouble with the math, just take a full-size
photo width and height and calculate Y:
  Y = (height * 100) / width

Then use the album option: -geometry Yx100  (substitute Y with the number

(Currently the album default is 133x100, which is the aspect ratio for
most digital cameras)

11:  mpeg/mpg Support
You can add mpeg/mpg movies to your photo collection and album can generate
thumbnails for you, but only if you install ffmpeg

If you are running linux on an x86, then you can just grab the binary,
otherwise get the whole package from (it's an easy install).

12:  Burning CDs (using file://)
If you are using album to burn CDs or you want to access your albums with
file://, then you don't want album to assume "index.html" as the default
index page since the browser probably won't.  Simple add the option:

  % album -index index ...

You can also look at winopen for windows users, you can have it
automatically launch the album in a browser.

13:  Indexing your entire album
To navigate an entire album on one page use the caption_index tool.
It uses the same options as album (though it ignores many
of them) so you can just replace your call to "album" with "caption_index"

The output is the HTML for a full album index.

See an example index
for one of my example photo albums

14:  I want CGI, I want other people to be able to add photos
First they need to be able to upload the photo to the album directory.
I suggest using ftp for this.  You could also write a javascript that
can upload files, if someone could show me how to do this I'd love to know.

Then they need to be able to remotely run album.  To avoid abuse, I
suggest setting up a CGI script that touches a file (or they can just
ftp this file in), and then have a cron job that checks for that
file every few minutes, and if it finds it it removes it and runs album.
[unix only]  (You will probably need to set $PATH or use absolute paths
in the script for convert)

If you want immediate gratification, you can run album from a CGI script
such as this one.

If your photos are not owned by the webserver (like on mine), then you
need to run through a setud script which you run from a CGI [unix only].
Put the setuid script in a secure place, change it's ownership to be the
same as the photos, and then run "chmod ug+s" on it.  Here are example
setuid and CGI scripts.  Be sure to edit them.

Also look at caption_edit.cgi which allows you (or others) to edit
captions/names/headers/footers through the web.

15:  How can I add EXIF information to my captions?
First you need 'jhead' installed.  You should be able to run jhead
on a JPG file and see the comments and information.

Then you need to create a format string for the EXIF information.
This string will be appended onto your image captions.
Any %keys% found in the format string where the key is an EXIF
key will be replaced in that string.  For example, if we
run jhead on an image, we might notice:
  Aperture     : f/4.0

We can then have an exif option such as:
  % album -exif "
F-Stop: %Aperture%" This will add an EXIF comment on a new line in the caption showing the F-Stop. The EXIF string is free form and can have unlimited EXIF keys. Run jhead on a jpeg for more info.

  • Created by make_faq from Marginal Hacks

  • These pages were, of course, generated by a perl script with this source