MarginalHacks.com DaveSource.com A l b u m 
 

Home

Themes/Examples

License

Download

Documentation

Praises

Credits

CHANGELOG

Contact


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. My thumbnails are cropped!
  15. I get: "album: No such file or directory"?
  16. I want CGI, I want other people to be able to add photos
  17. Why are my thumbnails stretched?
  18. My index pages are too large!
  19. I want you to split up my photo albums!
  20. I want thumbnails on my directories!



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 package that gives you Unixish tools on your Windows box.  Make
sure you choose to install Perl when you pick your CygWin packages.

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
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 image ALT tag 
(to see what an ALT tag does, move your mouse over the image example above).
(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
calculated)

(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 ffmpeg.org (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 ...

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:  My thumbnails are cropped!
No kidding, that's one of the reasons why I wrote album.

There are three ways to handle thumbnails:

1)  Have varying aspect ratios (different size rectangles)
2)  Stretch them to fit the same aspect ratio
3)  Crop them to fit the same aspect ratio.

I couldn't stand the way #1 and #2 look, and I couldn't find a tool that
did #3, so I wrote it myself.  It looked even better than I expected, with
the cropped areas not being very important, and with the cropping
directives, you can fix most of the other thumbnails.

If you don't want your thumbnails cropped, you have two options:

1)  Use the album option: -no_crop
2)  Use a different photo album generator.

I added the -no_crop option because it was easy to do, but it screws up
many of the themes which were written so that they expected all thumbnails
to be the same size.

If you must have -no_crop, then check out the No_Crop theme,
or modify another theme to support it.

I've realized since I've bought a digital camera that having different
aspect sizes isn't so bad with digital cams, since they use only two
aspect ratios (portrait/landscape).  So maybe someday I'll have time and
I'll make that situation work better.

15:  I get: "album: No such file or directory"?

1) Try specifying the full path to album, such as:

% ./album

Or

% /usr/local/bin/album

2) Make sure perl is installed according to the first line of album

3) If you save the perl scripts as text from IE, it may screwup the
   line breaks, save as source.

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

17:  Why are my thumbnails stretched?
If you used an older version of album (which had a previous thumbnail
geometry of 100x100) or if you specify a different thumbnail geometry,
then you will need to force album to regenerate any thumbnails that it
has already created:

  % album -force ...

It's slow, but you only need to do this once for each geometry change.

18:  My index pages are too large!
I get many requests to break up the index pages after reaching a certain
threshold of images.

The problem is that this is hard to manage - unless the index pages are
treated just like sub-albums, then you now have three major components
on a page, more indexes, more albums, and thumbnails.  And not only is
that cumbersome, but it would require updating all the themes.

And the reason I haven't done it yet is because there seems to be another,
easier solution - just break the images up into subdirectories before running
album.

If anyone has any good ideas or arguments for why the above is not a good
enough solution, please let me know.  While I don't have lots of free time,
I am looking for features to implement on album.

19:  I want you to split up my photo albums!
The most frequent feature request is that album generates multiple pages
of thumbnails if the number of images goes over a certain threshold.

This is actually difficult to do without rewriting all the themes, since
the themes don't know about navigating through these extra pages, it just
knows about directories and images.  I'm open to suggestions.

I plan on rewriting album soon and the next release will accomplish this.
If you don't want to wait, I have a tool that will move new images into
subdirectories for you and then runs album:
  in_album

20:  I want thumbnails on my directories!
Second most frequent feature request.  Coming with the next major release.


     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

     ^
     |

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