---------------------------------------------------------------------------
File: README.imgutil
Author: Richard Smith (rss@idiom.com)
Version: 1.0
Date: January 30, 2003
---------------------------------------------------------------------------
This is the README file for the "imgutil" package. This package is
designed to be useful to digital camera users who need a quick, easy
way to organize and view their pictures. The package is is designed
to work on a Linux system where Perl and an Apache web server with PHP
are already up and running.
Although written for Linux, the imgutil package will work on other
Unix variants and even Windows as long as the underlying software has
been installed.
This README assumes you have a basic familiarity with Unix systems and
know how to get around on the command-line. A basic understanding of
Perl, the Apache web server and PHP is also assumed.
---------------------------------------------------------------------------
INSTALLATION:
- You MUST have a recent version of Perl installed.
- You MUST have both Apache and PHP installed.
- You MUST have the ImageMagick toolkit installed. If you are using
Linux the RPM should have come with your distribution. If not you
can download it from imagemagick.org.
- After unpacking the imgutil package you should pick a permanent
location for it such as "/usr/local/imgutil" and copy the entire
contents there (or simply move and rename the package directory).
- There is an "imgutil" shell script in the "bin" directory of this
distribution. You must edit this script so that the $IMG_UTIL_HOME
variable points to the location of this distribution. You must then
either include $IMG_UTIL_HOME/bin in your path, or copy imgutil into
a directory in your path.
- The "imgutil" shell script also includes a variable for the location
of the ImageMagick binaries (actually I only use the "mogrify"
command). By default the ImageMagick RPM will install the binaries
under "/usr/X11R6/bin" but if it's somewhere else please edit the
$IMAGEMAGICK_HOME variable accordingly.
- The "bin" directory also includes a binary called "jhead" that has
been compiled for Linux (RedHat 7.3 to be exact). If you need it
for another platform you must download the source and compile it.
It is available from this URL:
http://www.sentex.net/~mwandel/jhead/
- The "php" directory includes a file called "img_utils.inc". This
file must be copied into the "lib/php" directory under your Apache
installation directory.
- There is also an "img.php" script that is the key to making your
image directories browseable. Edit your httpd.conf file so that
this file will be automatically parsed when you access your image
directory:
DirectoryIndex index.html index.shtml img.php
---------------------------------------------------------------------------
IMAGE LIBRARY LAYOUT AND CONVENTIONS:
This section is a little lengthy but you should familiarize yourself
with it before going forward.
- This package implements a particular method and philosophy for
organizing digital image files. It imposes a specific directory
layout for a "library" of images as well as a naming convention on
the image files themselves.
- This package is based on the idea of designating one or more
directories on your hard disk as "image libraries". Within each
library are many subdirectories that hold the actual images, one for
each event or day's worth of shooting. This is something you have
to do anyway; all this package does is wrap a structure around it.
Here is an example:
/export/h1/img/ <- top level for all image libraries
|
|_2001/ <- image library for 2001
| |
| |_2001_0101/ <- image directory for new year's day 2001
| |_2001_0110/ <- image directory for Jan 10 2001
| |_2001_0120/ <- etc...
|
|_2002/ <- image library for 2002
| |
| |_2002_0107/ <- image directory for Jan 07 2002
| |_2002_0120/ <- etc...
|
|_2003/ <- etc...
- This structure is intended to provide a foundation for organizing
and managing images so that browsing, retrieving, and backing up of
images becomes a simple and straightforward process even after your
library grows to include several thousand of images and takes up
many gigabytes of disk space.
- One of the central problems of working with digital images is that
the jpeg files that come straight from the camera are too big.
Scaling down the images to convenient "thumbnails" is a critical
task. The system implemented here allows for three levels of
thumbnails. Here's what an individual image directory looks like:
2003_0107/ <- image directory
|
|_Img <- full-size images go here
|_Tn0 <- level 0 thumbnails (smallest)
|_Tn1 <- level 1 thumbnails
|_Tn2 <- level 2 thumbnails (largest)
- When you need to load new images into your library, all you do is
create a new image directory and put the images there. The imgutil
script will create the subdirectories, rename the images, and create
thumbnails according to a fixed naming convention.
- Here's how the naming convention works: With most Canon digital
cameras the image file has a name like "IMG_9870.JPG". The "9870"
is a sequential number assigned by the camera. The imgutil script
will combine this number with the date the image was taken. So for
example let's say you took a bunch of pictures on January 7, 2003.
When you load them and run imgutil the following will happen:
- "IMG_9870.JPG" will get renamed to "img_2003_0107_9870.jpg" and
placed in the directory "2003_0107/Img" under your image library
directory.
- The "small" thumbnail will be called "tn0_2003_0107_9870.jpg" and
will be placed in the "2003_0107/Tn0" directory.
- The "medium" thumbnail will be called "tn1_2003_0107_9870.jpg" and
will be placed in the "2003_0107/Tn1" directory.
- The "large" thumbnail will be called tn2_2003_0107_9870.jpg and
will be placed in the "2003_0107/Tn2" directory.
- There is also an "Exif" directory which contains the EXIF "metadata"
from your images. This is useful if you want to see what your camera
settings (i.e. shutter speed and aperture) were when you review your
images.
---------------------------------------------------------------------------
USAGE:
- When you first create your image library, there are few things you
need to do to set it up:
- From your Apache "htdocs" directory, you must create a symbolic
link to the image library directory.
- Look in the "php" directory and copy the "img.php" script to your
image library directory. You can edit this file to customize it
with the name of your image library plus a few other defaults you
can change.
- Create a directory called "Text" which will be used to hold some
data about your image library.
- Here's a summary of what it should look like:
/export/h1/img/ <- top level for all image libraries
|
|_2003/ <- top level for 2003 image library
|
|_2003_0130/ <- your first image directory
|_img.php <- php script
|_Text/ <- special directory used by scripts
- When it comes time to load images, create a directory and put your
images there. I recommend the date convention (YYYY_MMDD) but this
is not a requirement.
- Now you must "cd" up one level to the library directory and run the
"imgutil" command. It will run a few other scripts that will create
sub-directories, rename images, and create thumbnails.
- If everything worked you can now access the directory from your web
browser and see the images show up as a screen full of thumbnails,
which you can click on to view a detailed page about each image.
- One last detail is that you can create a file called "toplevel.txt"
in your "Text" directory. The format is as follows:
2003_0130 Pictures around the house, mostly of my cat
2003_0131 Day trip to San Francisco
Regardless of what directory naming convention you use, the
directory must be the first "token" and everything after that is the
description.
---------------------------------------------------------------------------
FOR MORE INFORMATION:
To see if there is a more recent version of this package, please visit
my web site:
http://www.rssnet.org
For more information about ImageMagick, please visit:
http://www.imagemagick.org/
For more information about the jhead program, please visit:
http://www.sentex.net/~mwandel/jhead/
If you want to try some other open-source image-browsing web
applications, here are a few good ones:
Pekka Saarinen's Exhibit Engine:
http://photography-on-the.net/ee/
Gallery:
http://gallery.menalto.com/
---------------------------------------------------------------------------
VERSION HISTORY:
1.0 (January 30, 2003): Initial Release. I consider the scripts to be
in a "late beta" stage at this point even though I've been using them
myself for more than a year.
---------------------------------------------------------------------------
Copyright (C) 2003, Richard S. Smith.
This package may be freely copied, mirrored, modified, etc. If you
want to create and distribute your own version of this package, I have
just two requests:
1. That this README file remain intact and be distributed along with
any modified version.
2. That you consider sending your mods back to me so I can make my
package as up-to-date and useful as possible, in the "Open-Source"
tradition.
---------------------------------------------------------------------------
End of "README.imgutil"
---------------------------------------------------------------------------