photoindex is a simple Java program for consutructing HTML index
pages for directories containing pictures in JPEG format (and a few others:
see below). For each directory, the program creates a thumbnail for each
picture, and an entry in an HTML index page. These index pages and thumbnails
allow the pictures to be browsed conveniently using a Web browser, as clicking
the thumbnail loads the full picture. By pointing a Web browser at
`index.html' at the top of the directory hierarchy you can browse all the
pictures by their thumbnails. photoindex places the indexes
in files called
`index.html' in each directory in the hierarchy. This makes it possible to
point the browser at any directory in the set, not just at the top-level
directory.
I wrote this program to make it easier to browse photos captured with a digital camera. Although software to do this is supplied with most cameras it (a) is not very flexible and (b) usually only runs under Windows. photoindex is a Java program and should run on anything.
Because it can take a long time to process a large set of images,
photoindex checks the timestamps of the source pictures and the
generated files, and only updates the generated files if the source has
changed. This means that it is very fast to reprocess the directory
structure after adding new files. The simple, GUI-based programs
don't really deal very well with situations like adding a camera-full of
photos to an existing collection of many thousands. photoindex
was designed for exactly that set-up. Of course, it will work with
small collections as well, but you may find these are more readily handled
with the simpler tools that are available.
photoindex has no GUI, because it doesn't need one. It is
desgined to be set up, and then run once whenever new photos are added to
the collection. You should find that the sample configuration files
supplied in this distribution will work in most cases or, at least,
provide a good starting point.
photoindex is customizable using templates. It
reads the template and then inserts the generated index information,
thumbnail references, etc., into the template at places defined by
specific tags. Templates can be collection-wide or can be customized
down to the level of individual directories.
photoindex.props must now define which files
are to be indexed and thumbnailed. See the sample properties
file for an example of how this is done.
photoindex up
and running. Later sections describe how to configure and
customize it.
java -version at the
command line it should start up and tell you the version
number. Do not proceed if this stage does not work. If you
do not normally run Java apps at the command line, you may
find that you need to change the PATH environment variable
so that java can be found. Note that if you wish
to thumbnail video clips as well as photos, you need to have
the Java Media Framework (JMF) installed as well as the ordinary
Java runtime. You can get this from java.sun.com.
If you don't have JMF, but do have AVI files, etc., you must
configure photoindex photoindex3_dist.jar
to any convenient directory. It's a JAR file, so you can
unpack it by running jar xvf photoindex3_dist.jar.
Let's assume you have unpacked into /home/kevin/photoindex.
photoindex3.jar to a suitable
location for executable libraries. For example, on my system I
have put this into /usr/lib. On Windows system,
perhaps \windows\system would be a good place.
java -jar [path_to_photoindex3.jar], giving
the full path to the JAR file from step 3. For example:
java -jar /usr/lib/photoindex3 --version. It should
reward you by displaying the version number. Again, don't
proceed until this step works.
photoindex.props
and photoindex.html from the samples
directory of the distribution.
photoindex on this directory like this:
java -jar [path_to_photoindex3.jar] {photos_dir}
.
For example:
java -jar /usr/lib/photoindex3.jar /myphotos
. That's it. You should see a few messages saying
what's going on and, at the end, ``Errors: 0 Warnings: 0''
If anything goes wrong, you can increase the amount of
debugging output using the `-v' command-line switch. For example
java -jar /usr/lib/photoindex3.jar -v 2 /myphotos
.
index.html in the top level
of your photos directories. Point your Web browser at this file
and you should see the index. You should also be able to navigate
to other directories from here and see the thumbnails.
photoindex is a thumbnailing and indexing tool; it is not
designed to organize photos into directories. You can do this using any
file manager (e.g., Windows Explorer, Nautilus on Linux systems, etc).
Or you can simply ensure that when you upload photos from your camera
you put them straight into an appropriate directory. In any case,
photoindex assumes that your photos are organized into
directories.
photoindex can be configured to display a title for
each directory that is different from the directory's real name (see below).
For example, I may have a directory called `HOLS99', but display
it on the Web browser as `Holidays, 1999'. On the whole, however,
it makes sense to name your directories after their contents to start with.
However, Web browsers and servers tend to get a bit upset about directory
names with spaces in. So, instead of `Holidays, 1999', I would perhaps
call the directory `Holidays,_1999' with an underbar, rather than
a space. The same applies to filenames. My camera saves files with
names like `DSCF0026.JPG'. I normally rename then as soon as they are uploaded. Again, Web servers aren't keen on filenames that contain spaces, so I would replace them with an underbar.
Because the use of underbars to substitute for spaces is such a common
practice, photoindex has built-in support for this.
If the properties file (configuration file) contains the line
tidyFilenames=1, then the Web pages generated will show
spaces wherever there are really underbars. In addition, the filename
extension will be stripped from the end. So, for example,
`my_car.jpg' will display as `my car'. This does not change the filenames,
in merely changes the way the filenames are rendered in the Web index pages.
As for the directory organization itself, I tend to start with a directory for each year, and in each of these annual directories sub-directories for family, holidays, work, etc. It turns out that each annual directory contains about enough stuff to fill a CD-ROM, so I can back up each year onto CD. Other people like to organize by subject, rather than by date; this is, perhaps, more logical but when I tried this I found that the top-level (subject) directories were unbalanced: some had a few megabytes of stuff, and some had gigabytes. Thus it was difficult to back up onto CD.
photoindex doesn't care what your directory structure is
like, but it does have an impact on how easy it is to browse and
find things.
photoindex is designed to be run from the command line, with the
directory containing the photos specified as a parameter. The directory and
all its subdirectories are processed recursively.
usage: java -jar photoindex3.jar [options] {directory}
Make sure that photoindex3.jar is in the directory
from which you run the java command, or use the
full pathname to photoindex.jar.
If you are thumbnailing movie files as well as photos (see below)
you will need to make sure that the Java Media Framework JARs are
installed as well, and are findable by the Java runtime. The
default installation of JMF sorts this out automatically.
The program takes a number of command line switches; run it with the `-help' argument for full details. The most important switches are `-o' (overwrite) and `-v' (verbosity). The overwrite switch, if given, causes photoindex to rebuild everything, regardless of timestamp. This is useful if you have, for example, changed the required thumbnail size and what to regenerate all the thumbnails. The `-v' switch controls the amount of debugging output. It takes a number from 0 to 3. `-v 0' outputs nothing except fatal errors; `-v 3' outputs reams of debugging information. Other values are in between. The default is '-v 1'.
samples directory to get started.
photoindex looks for various application-specific tags in the
template, and substitutes them as follows:
photoindex_thumbails replaced with thumbnails of the images
photoindex_dirs replaced by links to subdirectories
and up-links to parent directories
photoindex_title replaced by the page title (see below)
photoindex_navigation replaced by the navigation links (see below)
Templates propagate down through the directory hierarchy, so if all index
pages are to have the same layout, it is only necessary to edit the template
for the top-level directory. If you want a particular directory to
have a different page layout, create a photoindex.html
in that directory. Don't forget that this new template will be
passed down to subdirectories as well.
photoindex takes few command-line arguments because (i) it
recognizes that most, if not all, configuration options may need to be set on
a per-directory basis, and (ii) configuration is likely to remain static
once the system has been set up.
photoindex reads the file photoindex.props, if it
exists, in each new
directory.
NB: you must have a properties file: there is no default. Copy
the one from the samples directory to get started.
Currently the following properties are recognized.
thumbnailwidth the width in pixels of a thumbnail
thumbnailheight the height in pixels of a thumbnail
thumbnailsacross the number of thumbnails shown in each row
on the index page
title page/directory title
showFilenames 1 = shows the filename for each thumbnail
0 = no filenames
tidyFilenames 0 = where filenames are used as titles,
show them exactly as found
1 = convert underbars to spaces, etc
extensions comma-separated list of file
extensions that correspond to files that
will be handled. Only the lower-case
version should be given: the upper-case
equivalents will be treated the same
sort 1 = sort indexes into alphabetical order
0 = indexes are in the order that the operating
system delivers filenames (date order on Linux)
videos list of extensions for files that are considered
to be `videos', and therefore get listed
in the video index
The properties in a given directory are inherited from the directory above
when it makes sense to do so. The `title' property is not inherited,
as this would lead to a situation where every directory must have a title;
in most cases you will probably want to have photoindex
base the title on the name of the directory.
As with the template photoindex.html, in most
cases you will want one photoindex.props file
in the top directory, and nowhere else. A sample is provided
with the distribution.
photoindex understands the concept of a page title, although it
does not process the title in any way. The title is either a string specified
in the properties file, or the last part of the file or directory name.
Therefore, if your directory names are sensible you may not need to specify
titles explicitly. If you say tidyFilenames=1 in
photoindex.props, the filenames are made into more elegant titles
by, for example, converting underbars to spaces.
When generating the index file, photoindex simply passes the page title to the
output in place of the `
Thumbnails can be requested to be any size -- within reason --
but here are a few things to watch out for.
Thumbnails of movies are displayed with a small `projector' icon in the corner to make them more recognizable as such.
In the properties file
Section index files are always called `index.html'; this could be problematic
if the Web server you plan to use does not offer `index.html' when the browser
links to a directory, However, all links generated by
As well as the section indexes, the program also writes some other
index files into the top-level directory (only). These are
as follows.
This is where embedding comes in. If we tell
There are a few things to watch out for, however. First, don't specify the
width and the height unless all your images have the same shape. Most
Web browsers are fairly dumb about this sort of thing. If you say that the
image should be 800x600, then the browser will make it 800x600 even if its
original dimensions were, for example, 600x800. The effect will not be
pleasing to the eye. Second, only still images are embeddable using the `img'
tag in HTML. You wont' be able to embed a movie that way. You may be
able to embed movies using a reference to a plug-in, but that's beyond the
scope of this document.
Filenames
photoindex can display the filename under each thumbnail; the
default is not to. It is only useful to display the filename if it makes
sense; camera-generated filenames are generally not meaningful. If you enable
this setting (showFilenames=1 in the
properties file) you might want
to reduce the number of thumbnails displayed across the page, as the filename
will make each thumbnail cell wider. Note also the the `showFilenames'
setting is
inherited by subdirectories, so you may need to re-disable it if you want
visible filenames in one directory but not in its subdirectories.
Thumbnails
photoindex creates thumbnail files whose names are the same as
the original files, but preceded by `thumbnail_'. To avoid thumbnailing
thumbnails produced by other programs, or by itself, photoindex will not
create a thumbnail for any file that has the string `thumbnail' in its file or
directory name. The thumbnailers attempt to keep the picture's aspect ratio
constant. Also, to increase speed, the thumbnail will be the nearest size
to that requested which is a submultiple of the original size. So, for
example, if the original is 512x512, and we ask for a thumbnail 100x100, we
will actuall get 128x128 (see below for why). Thumbnail sizes
are set in the properties file, and can be different for each directory.
Starting with version 3.0 of photoindex, the program can thumbnail movies:
it just extracts the first frame, and resizes it in the same way as for
stills. photoindex does not do this itself, it uses the
Java Media Framework
(JMF). At the time of writing, JMF is not part of a standard Java JDK
installation: you will need to download it and install it separately. If you
don't have movies, you needn't worry about this. It is possible that not all
AVI codecs will be supported: this depends on the JMF implementation, which is
platform specific. photoindex has been tested with JMF 2.1.1; the likelihoold
is that older versions won't work.
Configurable thumbnailing
New in this version of photoindex is support for
`configurable' thumbnailing. What this means is that you can specify
which thumbnailer is to be used with which file type. This means
that there is a bit of extra work to do when setting up the program,
but it offers much better flexibility.
photoindex.props we can now
specify which file extensions use which thumbnailer like this:
jpg_thumbnailerClass=com.kevinboone.jphotoindex.thumbnailers.JpgThumbnailer
That is, files with extension `.jpg' (or .JPG) are thumbnailed by
the specified Java class (if you aren't familiar with Java class names,
don't worry, it's not something that you could guess, anyway: names
for all the built-in thumbnailers are given below).
Do not attempt to thumbnail movie clips if you don't have JMF installed:
it won't work. If you want your clips to be accessible through the
browser, but don't want to install JMF, then enable the DefaultThumbnailer
for those file types. For example:
com.kevinboone.jphotoindex.thumbnailers.JpgThumbnailer.
This thumbnailer can process JPG images only.
com.kevinboone.jphotoindex.thumbnailers.JmfThumbnailer.
This thumbnailer passes the file to the JMF media player ant
asks it to grab the first frame. It then resizes it to the
requested thumbnail size. This thumbnailer should be able to
process AVI and MPG files which were encoded using codecs that the
JMF system understands. Most digital cameras use simple, non-proprietary
codecs so there should generally be no problem.
com.kevinboone.jphotoindex.thumbnailers.DefaultThumbnailer.
This thumbnailer can be used to `thumbnail' files that aren't
recognized by photoindex, but that you nevertheless
want in the indexes. For example, photoindex can't
process GIF images (yet), but a Web browser probably can. If you
map extension `gif' onto the DefaultThumbnailer, then GIF images
will be indexed in the usual way. However, no thumbnail is
generated: just a black square with the filename in the middle.
Obviously this thumbnailer is a last resort.
avi_thumbnailerClass=com.kevinboone.jphotoindex.thumbnailers.DefaultThumbnailer
Index files
photoindex generates a number of index files in
the directories that it searches.
photoindex are made to specific files, not to directories,
so the problem will only arise
if you want to link to one of your directories from another page.
You will only get a `video index' if the fullindex.html -- the full hierarchical index for the whole
directory structurevideoindex.html -- index of `video' images. These
are images whose filenames have extensions listed in the videos
key of the properties file photoindex.propsrecentindex.html -- index of recent additions.
videos property is
specified. You can list as many file extensions as you like as being
`videos'.
Embedding pages
When photoindex builds a page of thumbnails, it embeds
them into a Web page; the Web browser displays a Web page containing
references to images. When you click on a thumbnail, depending
on how photoindex is configured, one of two things
will happen. Either
Now, why would we want to get an emedded photo, and not a direct reference to
the photo? Here's why. I use my camera to take photos at a resolution of
1600x1200 pixels. With this resolution there is a bit of flexibility to zoom
and crop without loosing too much detail. However, my computer does not have a
screen resolution that will display 1600x1200 pixels. When the Web browser is
told to fetch an JPG image, it probably will not attempt to scale it to fit
the screen. Instead it will just display the top-left corner. This is a bit
of a nuisance. When I click a thumbnail I really want to see the whole picture
fit to the screen.
photoindex
to embed a photo, then it generates a new HTML page for each photo.
This HTML page will be called `xxx.jpg_embed.html', where `xxx' is the
original image filename. Inside this file there can be anything you
like, but probably it should be a piece of HTML that references
the real file. How do you know the real file name? You don't, but
the program does. So before it writes the file it inserts the
real filename into a specific place. If this is confusing, perhaps
an example might help. Suppose in photoindex.props
we have a line like this:
jpg_embed=<img src="<filename>" width="800" border="0">
This says that any thumbnail generated for a `.jpg' files should
not reference the .jpg file itself, but instead cause a
link to a page containing the text specified above. However,
in that text the tag `filename' is replaced by the real
filename. The effect of this is to tell the Web browser to
display the JPG file with a width of 800 pixels, which will
fit nicely on most screens. You could make it bigger if you
wanted.
Limitations
photoindex assumes that when it is started in a particular
directory it should index every subdirectory. This won't necessarily
be true.
NOTE - someone did give me a call, and I did look at fixing it.
You can now say `sort=1' in the photoindex.props
file, and get alphabetical order. Upper and lower case are
treated as equivalent, so `Fred' comes after `bill', which in
generally what you expect (but not what you get if you just sort
by ASCII codes). This facility has not been tested
very thoroughly, so your mileage may vary.
Revision history
V1.0, V1.1: never released
V1.2 Apr 2001: first stable version
V1.3 Feb 2002: enhancement release
- removed necessity to specify URL root
(because most browsers now process `..' in URLs
- added facility to embedd pictures in HTML, to control
size on screen
V3.0 July 2002: complete reimplementation. Now supports movie
thumbnailing as well as stills.
V3.0a July 2003: minor fixes to directory name formation that caused
problems on Windows systems. Fixed a bug that caused the program to crash
on encountering filenames with no extension
V3.0b Sept 2003: added sort facility
V3.0c Dec 2003: fixed a nasty bug in the slideshow facility, which had
the effect that the slideshow was incomplete if there were mixed
video clips and stills in the same directory
Legal stuff I have to say
photoindex is (c)2000-2003 Kevin Boone, and is distributed under
the terms of the GNU Public Licence. In short, this means that you may do with
it as you wish, provided that the original authorship is acknowledged and the
source code continues to be made available. I have made this simple program
available in the hope that it will be useful. There is absolutely no
warranty. However, if you would like to use it but can't get it to work, send
me a message at kb at kevinboone dot com and I'll see what I can
do.