make_album
----------

		David Burren
		david@burren.cx

	http://www.burren.cx/david/make_album.html

	Source:
		http://www.burren.cx/david/files/make_album.tar.gz
		http://www.burren.cx/david/files/example_album.tar.gz

	$Id: README,v 1.9 2000/09/14 20:41:36 davidb Exp $

This is a collection of Perl tools for organising images into HTML
"albums", reporting as much EXIF data as it can find.  It's not a
very polished product, but rather a set of tools I've been slowly
tweaking for months.  After more and more requests for copies, I've
finally packaged it up.

It's really a set of tools to be hacked on.  It's _not_ code I'm
particularly proud of (it is a set of routines which has grown
fairly haphazardly and I'm likely to do a fairly substantial
rewrite soon).  Comments are "sparse"...


Given a directory of images (JPEG or TIFF format) this will generate
a web page of thumbnails with links to the images resized to fit
various screen sizes.  In my environment I regard each generated
directory as an "album" which I eventually archive off to CD.

If the images include the camera's EXIF data (detailing things like
date, shutter speed, aperture, flash, etc) that is displayed with
the image, along with a short description and any copyright attribution.

Check the CHANGES file for new features.  Many of these are in the
parsing of the EXIF data.


It's all Perl, except for the use of mtools to access digicam cards,
and ImageMagick to manipulate graphics.  See http://mtools.linux.lu/
and http://www.imagemagick.org/

ImageMagick is used to manipulate JPEG and TIFF files, except for
parsing EXIF data which is done directly from Perl.  I took the
easy way out and simply call the ImageMagick programs via system().
Maybe I should rewrite it using PerlMagick, but at the moment I'm
looking at switching to using The Gimp for the graphics operations
(support for more file formats, proper Unsharp Masking, integration
into the rest of my environment, etc).


Because of the fact that each time you save an image as a JPEG you
lose quality, I've taken the extreme view that disk space is cheap
(most of my images end up archived to CD).
I generate a TIFF "master" version of each image (keeping the original
JPEG or TIFF in the "original" directory) and convert directly from
the master to each of the final JPEG images.

If you need to modify the image (for example rotating, cropping,
"levelling") do it to the master.  The original camera files are
untouched (they have the precious EXIF data from the camera).

If you want you can gzip the TIFF master files to save a bit of
space, as ImageMagick will gunzip them on the fly as required.


Directory structure:
--------------------
Each "album" is maintained in its own directory tree.  This was
designed to simplify archiving albums to CD.

	ALBUM/			Album source directory
	      config/			Control files
	      master/			TIFF files
	      original/			Original files (e.g. from digicam)
	      web/			Generated HTML and JPEG

Scripts:
--------
populate_master

	Usage:	populate_master [gz]

	Run from: Album source directory

	For each file in original/ this generates a TIFF file in master/
	(unless it exists already).  If the original file is newer than
	the master file, the master file is NOT overwritten, but the script
	issues a warning so you can sort it out.
	After carefully tweaking the naster file, it's a horrible feeling
	when you realise your work has just been overwritten...

	If the argument "gz" is given (or in fact anything matching /gz/)
	the TIFF files are created in gzipped form.

	Any file that does not have an entry in "config/setup" is added to
	that file, which is used by make_album.


make_album

	Usage:	make_album [thumbs]

	Run from: Album source directory

	Reads "config/setup" to determine which images to display, in
	which order, etc.  It then creates HTML and JPEG files under web/.

	"config/tours" describes the different sized "tours" that will be
	created.  For each tour the following fields are specified:

		Name		Short name
		Directory	Sub-directory of "web/" to place files in
		Vert size	Height (in pixels) images will be resized to
		Description	

	Note that you really should have one of the tours using the
	directory ".".  No check is currently made for this.

	Also, "config/attrib" contains a list of patterns and copyright
	attributions which will be attached to images matching the
	patterns.  The patterns are treated as Perl regexs.

	For example config files, see
		http://www.burren.cx/david/files/example_album.tar.gz

	config/setup is copied to web/setup (for later parsing by
	index_albums).


index_albums

	Isage:	index_albums [directory]

	Run from: directory above "web" dirs

	In a directory with subdirectories, makes a simple index.htm file
	with links to each subdirectory.
	If the directory has an index.html, index.htm, or default.htm,
	that is used as the target of the link.  Otherwise the directory
	itself is used.
	If a "setup" file exists in the subdirectory, it it parsed for a
	"Title" declaration which is added to the link.


new_imagedir

	Usage:	new_imagedir [name]

	Run from: anywhere

	This assumes that you keep your albums under $HOME/images/source/
	with the "web" directories under $HOME/images/web/.  It creates
	the source directory (with an "original" subdirectory and "web"
	as a symlink to the appropriate directory under images/web/
	which it also creates).

	If a name is not given, the current date (in YYYYMMDD form) is
	assumed.

	The name of the source directory is echoed to stdout.  I use this
	as follows: The C-shell alias
		alias ni 'cd `newimagedir \!*`'
	allows me to simply type "ni" to cd to a new directory each day,
	or "ni foo" to make an album called "foo".

	By splitting the source/ and web/ trees, I can easily archive the
	source/ files to CD and keep the smaller web/ files online.


ingest

	Usage: ingest [-c drive] [-v] [-d] [-p] dest_dir

	Run from: anywhere

	This is a quick way to read all the image files from a digicam's
	memory card.
	It uses the mtools package (http://mtools.linux.lu/) to access
	a DOS filesystem (e.g. on a CF card).  It will copy all the files
	to the specified destination directory, renaming them to include
	their folder name and avoid name collisions.

	The -c option allows you to specify the drive letter (configured
	in mtool's own config files).  The default drive is "F".

	If -d is specified, the files are deleted from the DOS filesystem
	after being copied and if the copy's size is correct.

	If -p is specified, the last operation performed is to find and
	remove ("prune") all empty directories on the DOS filesystem.

	-v forces verbose mode.


The IM_CACHE environment variable can be used to limit the memory
consumption of the ImageMagick utilities (it is passed to them
as "-cache").


The file "cameras.txt" (distributed with Max Lyon's Windows "Thumber"
software at http://tawba.tripod.com/thumber.htm) is used to determine
the "35mm equivalent" focal length of the cameras, as well as the ISO
rating of the camera.
That file is fairly well documented, and you should be able to work it out.
If you make any additions to it, please feed them back to maxlyons@erol.com.

The pathname of cameras.txt is taken from the CAMERAS_TXT environment
variable (defaulting to $HOME/lib/cameras.txt).

Actually, many newer cameras provide all the required detail in their EXIF
data (if we can work out the dimensions of the CCD we can calculate the
35mm equivalence - I've seen this with some Canon and Fuji cameras) and
an entry in cameras.txt is not required.  It's a fall-back for the older
cameras.
