Windex: Build HTML Index for Bitmap Images
Introduction
Many Web authors find themselves becoming "image packrats"--they're
avid collectors of public domain icons, buttons, animated GIFs, clip
art, and images which might someday prove useful in a Web page they
compile. Digital camera users quickly accumulate image files, all
with obscure names assigned by the camera which have nothing to do
with their content. After you've collected a thousand images or more,
you quickly discover the work involved in finding an image in your
collection is often more than creating an equivalent image from
scratch. It's easy to save an image, but organising them into
coherent categories takes much more time, and is often deferred in
favour of more pressing matters. Frequently, image files have opaque
names like
button4.png which don't offer any clue as to
their contents. Consequently, you're often forced to exhaustively
search your collection for a suitable image.
Windex can make it much easier to find an image in your
collection. It scans a list of image files you specify on the
command line and prepares an HTML document which contains an index
of all those images with each shown as a small "thumbnail" view.
A client-side image map is included which allows you to click on
any image to display the full-size original image file or to
download it to a file on your own computer. The image at right
was created with windex from a collection of public domain
NASA images from the Apollo 17 lunar mission; try clicking on
one of the thumbnails to display the full image, then use your
browser's Back button to return to this document.
This page describes, in Unix manual page style,
a Perl program
available for downloading from this site
which automatically compiles an graphical index for a collection of
bitmap images. Also included in the archive is an accompanying
utility, windup, which scans
a list of image directories and invokes windex to
update indices for directories to which images have been
added since the last index was prepared.
To use the program
you must have Perl (version 4.0,
patch level 36 or later)
and the Netpbm
raster image toolkit, and the Independent JPEG Group's
JPEG
encoder and decoder
installed on your machine. This program makes extensive use of
Unix facilities; it is improbable in the extreme that it will
work on non-Unix systems without extensive modifications.
Windex
NAME
windex - create a Web HTML index for a collection of images
SYNOPSIS
windex [ options ] [ directory... ]
DESCRIPTION
windex is a
Perl script that takes a collection of image
files and creates an HTML index which contains one or more index
images showing small "thumbnail" views of the image files. The
index document contains client side image maps which link each
thumbnail to the original source image. Thus, you can browse a
collection of images, click on any you wish to view full-size,
then use the browser's "Back" button to return to the index or.
optionally, have the full-size images open in a separate
browser window.
windex excludes files with names of the form it generates,
so you can re-run it to update the index in a directory without
first deleting the old index files.
windex determines the file format by the file name
extension of the input files and then uses internal tables to
look up the commands it needs to convert the images to the ppm
format. Once in ppm format, windex uses various
netpbm commands to create the index images.
windex is particularly useful if you have lots of image
files in all sorts of different formats and you want to create an
index of all of them without converting them all to a common
format first. Of course, if the image is in a format your
browser can't display, you won't be able to view it by clicking
its thumbnail.
Besides perl, windex requires the Netpbm package,
and the Independent JPEG Group's encoder and
decoder (cjpeg and djpeg). It should not be
difficult to add filters to read other image formats as long as
there is a way to translate them to the ppm format.
OPTIONS
Switches that do not take arguments may be combined into a single
switch with other switches:
-abBlv. Switches that take arguments
must be followed by their arguments with a space in between:
-c 10
-r 5. The fancy way combine all these
switches is:
-abBlvc 10 -r 5. That is, you can
combine the switches together in any way you like so long as the
switches that take an argument are followed by said argument with
a space in between. If you don't want to get fancy, just specify
each switch by itself:
-a -b -B -c 10 -l -r 5 -v.
In all cases in which a switch does not take an argument,
-switch will turn the switch on, and +switch will
turn the switch off. For example, -l will turn labels
on, and +l will turn labels off. If a set of switches
are combined into a single switch that leads with either a
+ or a -, the + or - affects all the
switches in that set. If a switch that takes an argument is
specified with a leading +, it is assumed that you meant
-.
An argument of -- terminates the options list and signals
the beginning of the file list.
Default settings of the options are equivalent to explicitly
specifying "-a -B -i -S -u -w 120 -X 780 -x 120 -Y 780".
- ±a
- Make the index images fit into the size specified
by the -x and -y switches. Setting the
-x and -y switches to the size of your screen
will yield index images no larger than your screen. The
-r and -c switches will be ignored if the
-a switch is present because the number of rows and
columns is calculated dynamically and will probably change
from image to image unless the -i switch is specified
or all the source images are of the same size to begin with.
- ±B
- Add a border to each image in the index images.
This will make each thumbnail image 6 pixels larger in both
width and height. If the background is white, the border
will be white-black-white. If it is black, it will be
black-white-black. The background color may be selected
with the -W switch.
- ±b
- Use the basename of the file name instead of the
whole path name to the file in labels. This switch will be
ignored if the -l switch is not specified.
- -c n
- Make index images with n columns of
thumbnails. This switch is ignored if the -a switch
is specified. The default value is 7.
- -d dir
- Put the index images in dir when
completed. The default value is ".".
- -F file
- file will be used with
pbmtext as a font for labels. Each image's height will be
increased by the height of the characters in the font. This
switch will be ignored if the -l switch is not
specified. By default, pbmtext's internal font is used.
- -f format
- Encode the index images in
format. The default value is ".jpg" (JPEG).
- -H file
- Use file as the name for
the HTML index document which includes the index images and
their clickable image maps. The default is "index.html".
- -h n
- Make each image in the index images
a maximum of n pixels high. The aspect ratio of
the images will not be changed. This switch will be ignored
if the -X switch is also specified. The default
value is 120.
- -help
- This is a special case which will print out a
help message explaining windex's options. Any other
unrecognized switch will do the same.
- ±i
- Make all of the images the same size. The size of
the images is determined by the dimensions specified with
the -w and -h switches. Use of this switch
can create index images with lots of blank space between
images. This switch cannot be used with the -X or
-Y switches.
- ±l
- Attach a label containing the image's file name
below each image. This name may be truncated if the label
is wider than the image. The behavior of this switch can be
changed with the -b and -F switches.
- -L text
- Use text as the title
of the HTML index document. If text is more than
one word, it must be enclosed in quotes.
- -n file
- Take the file names from
file and add them to the ones specified on the
command line, if any. The file names in file must be one
per line. These file names will be processed after the file
names specified on the command line.
- -o n
- The output index image names will
begin with Index-n and increase from there.
The default value is 001.
- -p prefix
- Name the index images
prefix###.format, where ### is the number
of the index image and format is its format. The
default value is "Index-".
- -q n
- Quantize the index images down to
n colors. A value of 0 will turn off quantization.
The default value is 0.
- -r n
- Make the index images with
n rows of images. This switch is ignored if the
-a switch is specified. The default value is 7.
- ±S
- Sort the file names taken from the command line
(and, optionally, from the file specified with the -n
switch) into alphabetical order before making the index.
- ±s
- Don't output anything except warnings and fatal
errors.
- -t tempdir
- Use tempdir to hold
windex's intermediate files. windex tries to
minimize the amount of temporary space it needs, but its
disc space requirements can be large depending upon the
particular operation it is performing. If you have a tiny
/tmp directory, you'll want to use this option to aim
windex at a larger chunk of disc. The default value
is "/tmp".
- -T target
- Use target
as the browser target window for displaying full-size
images when the user clicks on an image in the index. The
default value of "" causes images to open in the same
window in which the index is displayed.
- ±u
- Delete duplicate entries in the list of image file
names. The first file with any particular name will make it
through, but following files with the same name will be
deleted from the file name list. The default is to delete
duplicate file names.
- ±v
- Cause all sorts of possibly interesting output to
be printed to the screen. The output includes the current
parameters of windex and all the shell commands it is
running. If you're having difficulty getting windex
to do what you want it to do, try using this switch to see
what windex is doing behind your back.
- -W
- Make the background white instead of black, which is
the default.
- -w n
- Make each image in the index images
a maximum of n pixels wide. The aspect ratio of the images
will not be changed. This switch will be ignored if the
-Y switch is also specified. The default value is
120.
- ±X
- This switch will make all the images the same
width. Their heights will be whatever they are when the
image comes out of pnmscale. The aspect ratios of the
images will not be changed. Wide images will be short and
tall images will be tall. This switch cannot be used with
the -i or -Y switches.
- -x n
- When used with the -a switch,
n specifies the width of the index images in
pixels. This switch will be ignored unless the -a
switch is specified. The default value is 780.
- ±Y
- This switch will make all the index images the same
height. Their widths will be whatever they are when the
image comes out of pnmscale. Wide images will be wide and
tall images will be skinny. The aspect ratios of the images
will not be changed. This switch cannot be used with the
-i or -X switches.
- -y n
- When used with the -a switch,
n specifies the height of the index images in
pixels. This switch will be ignored unless the -a
switch is specified. The default value is 780.
ENVIRONMENT
- TMPDIR, TEMPDIR
- These environment variables can be used to set the location of
windex's temporary directory. If both TMPDIR
and TEMPDIR are both set, a warning will be printed
and the value of TMPDIR will be used. If only one of them
is set, that one will be used. This value will be
overridden if the -t switch is used on the command
line.
- TMPDIR/icb-$$
- a temporary file for storing the border if the -i and -B switches are specified
- TMPDIR/ici#-$$
- temporary files for storing images before they are made
into rows
- TMPDIR/icp#-$$
- temporary files for holding expanded index images while
windex cuts images out of them
- TMPDIR/icr#-$$
- temporary files for storing rows before they are
assembled into index images
- TMPDIR/ict-$$
- a temporary file for storing labels and borders
BUGS
If a file name has "."s in it that do not come before a valid
file format extension, the file will be skipped because
windex will not be able to find decode commands in its
internal tables.
When in automatic sizing mode (-a), if a processed image
is larger than the specified dimensions of a sheet, this image
will appear all by itself, and the index will be larger than you
specified with -x and -y.
windex will fail if used on filenames that contain
whitespace.
SEE ALSO
basename(1),
perl(1),
pbm(5),
pgm(5),
ppm(5),
cjpeg(1),
djpeg(1)
ACKNOWLEDGEMENTS
This program was adapted from the
icontact
contact sheet creation utility developed by:
Mark Hanson
http://www.panix.com/~mbh/projects.html
who adds: "Bug reports, patches, suggestions, questions,
and money are all welcome."
icontact is: Copyright (C) 1992 Mark B. Hanson
windex is: Copyright (C) 1997 John Walker
Permission to use, copy, modify, and distribute this software and
its documentation for any purpose and without fee is hereby
granted, provided that both the above copyright notice and this
permission notice appear in all copies and in supporting
documentation. This software is provided "as is" without express
or implied warranty.
NAME
windup - Update image index when images are added to
directories
SYNOPSIS
windup [options] directory...
DESCRIPTION
windup is a
Perl script which examines the list
of directories given on the command line to determine, for each
directory, whether one or more images have been added since the
last time an index of images was created in the directory with
windex. If the directory's index is out of date (or if
it has never been indexed at all),
windex is invoked to
generate an up-to-date index.
OPTIONS
- -a
- Update indices for every directory regardless of
whether it contains an apparently-current index. If
you've added images to a directory with a command which
preserves the original date and time of the image files'
creation, windup may fail to detect them if none is
dated after the time the last index was made. The
-a option can be used to force rebuilding the
index in this situation.
- -n
- Show which directories need to be updated, but do
not actually rebuild their indices.
SEE ALSO
perl(1),
touch(1),
windex(1)
BUGS
windup judges an image index current if its last
modification date is more recent than any image file in the
directory. If you add images to a directory with a tool which
preserves their original date and time, and that date is prior
to that of the last index,
windup will fail to discover
that the new images have been added. If this happens, just
touch any image in the directory to reset its last modification
date and re-run
windup. Alternatively, you can use the
-a option to force
windup to rebuild indices of
all directories.
windup doesn't detect when an image is deleted from a
directory. Until the index is rebuilt (by running
windex manually or by using the -a option on
windup) clicking on the deleted image's thumbnail in the
index will generate a "document not found" error in the
browser.
Downloading, Technical Support and Questions
This software is utterly and absolutely unsupported. You are
entirely on your own in using this program. If Netpbm or
Perl is incorrectly installed or you're using an obsolete version, you
will doubtless encounter errors which will require patience and
experience with both Netpbm and Perl programming to resolve.
Every attempt has been made to permit
windex to be used as
a black box, but if the box pops open and gears and springs fly out
on your watch, I can't provide any assistance in setting things
right.
by John Walker
July 13, 2004