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 a 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 and the Netpbm raster image toolkit 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 major 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. 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) Alternatives are “.png” and “.gif”.

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

FILES

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

ACKNOWLEDGEMENTS

This program was adapted from the icontact contact sheet creation utility developed by:

who adds: “Bug reports, patches, suggestions, questions, and money are all welcome.”

icontact is: Copyright © 1992 Mark B. Hanson
windex is: Copyright © 1997, 2004, 2007, 2020 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.

Windup

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.

Download windex.tar.gz (gzipped TAR archive)