PhotoTrove

Introduction

PhotoTrove is a standalone program to build photo-gallery web sites out of original photographs. It does a number of things, such as:

• builds all the necessary HTML files
• creates the thumbnails
• creates a medium sized preview image (such as an 800x600)
• extracts some EXIF data and displays it
• adds user annotations (such as a title and description)
• links to or creates a full-sized image (can even be the original photo)
• allows one to build different sites (for different audiences) from the same input

There are a lot of configuration options, but a simple site can be built without entering any additional data, so you can get started quickly.

At the time of first publication (Aug 2003) PhotoTrove was not returned by a Google search!

License

This will be free for use, a key to get rid of the little link that is added to get back to this site will be available for a small fee.

Installing

For the first versions you will need to install the Python environment on your computer, along with a support package known as PIL, the Python Imaging Library.  The future plan (if this proves to be useful) is to convert it to either Java or C++. To install these things you should download their installers and then just following the installation instructions. I have written this using Python 2.3 (the latest at this time) but it may work with older versions of Python too. You can find the appropriate install packages here:

• PIL for Windows can be found prebuilt on this page, the link you want for Python 2.3 is this.
• Python is available for many platforms, this link gets you the pre-built version 2.3 for Windows.

You need to install Python first and then install PIL. A very useful package you might consider installing as well is the win32all extensions for the Windows platform.

Once you have done this you can install my PhotoTrove program which is in a zip file. Just unzip the contents of this to some handy directory and the installation is complete. You'll need to remember the path to this directory or else add it to your PATH environment variable, or set up a short cut.

Running

When running this for the first time, to see if the installation was successful, just start up and MSDOS console and in it CD to the directory where you unpacked the phototrove zip file and then type a command like:

phototrove.pyc -h

you should get some help output that looks something like:

E:\personal\thumbnailer>phototrove.pyc -h
Unknown command parameter:  -h

PhotoTrove v1 Copyright 2003 Stephen Vermeulen http://vermeulen.ca/phototrove.html
options are:
  -c html       (clean up the outputdir's html files, requires -o as well)

or:
  -i photodir   (required, local directory tree to scan for photos)
  -o outputdir  (required, local directory to write all output to
  -wh webhtmldir (web server root directory for html and other files, default=outputdir)
  -wp webphotodir (web server root directory for photo files, default=photodir)
  -g group name  (required, no default, the user group this will build html for)

  -f            (optional, forces rebuilding all thumbnails)
  -h             print this help message

E:\personal\thumbnailer>

if you don't get this far, then check your installation of Python and mayve seek some assistance.

Now the next test would be to try and produce some thumbnail pages. To do this you will need to prepare a directory (or even a directory tree) of photographs. For a first test I would just copy a handfull of photos (JPEG files) into a directory in the same place you installed the PhotoTrove files. Lets call this directory "photos" and then you can try a command like:

E:\personal\thumbnailer>phototrove.pyc -i photos -o testout -g test -wp ../photos -wh .

You should see a bunch of output scroll by, none of which is particularly important. Now if you look in the newly created "testout" directory you should find a bunch of JPG, thumbnail and HTML files. The starting point for the web site is the file: testout\index1.html, if you load that into your browser you should be able to navigate to all the photos that were in the "photos" directory. At this point its all going to look pretty plain, as we have not provided any auxillary data. You could actually stop here, copy the photos directory and the testout directory onto some web server account and those pages should pretty much work.

Customizing by Directory

PhotoTrove allows you to tailor the pages it generates on a directory by directory basis. If you like the built in defaults, then there's nothing further to do, but if you want to change things such as the number of row and columns on the thumbnail sheets, read on.

The additional information needed to customize the layout is read from some additional files you need to add to your source directory tree (i.e. the "photos" directory). These files are in XML format, which is rather unfriendly to an end user, so the plan is to write a GUI tool to allow you to browse the photo directories and maintain these additional files. One of the advantages of using XML for this is that it makes in feasible to write tools that can access this data, perhaps to populate it from an existing database.

To start with, add a copy of this file to your photos directory, it should be called "index.xml" (just copy and paste the following block of text into notepad and save it as photos\index.xml):

<?xml version="1.0"?>
<photodir 
thumb-quality="85" thumb-size="120 90" pic-size="640 480" pic-quality="65"
table-rows="4" table-cols="3" border="0" 
icon-up="&lt;img src=&quot;/extras/up.gif&quot;&gt;" 
icon-previous="&lt;img src=&quot;/extras/previous.gif&quot;&gt;" 
icon-next="&lt;img src=&quot;/extras/next.gif&quot;&gt;" group="test family sysop" 
copyright="This stuff is Copyright 2003 by Stephen Vermeulen" 
>

<web-title>Stephen's Family Album</web-title>
<title>&lt;center&gt;&lt;h3&gt;An assortment of photos&lt;/h3&gt;&lt;/center&gt;</title>
<dirtitle>Various Photos</dirtitle>
<description>
This collection of snapshots was taken with a Canon G1.
</description>

</photodir>

The first part of this is the photodir element and its various attribute tags. The tags are things like thumb-quality and copyright, they provide much of the information that PhotoTrove needs to do its formatting job. There are quite a lot of these tags (more that are not included above), we'll start by explaining what the ones in this example do.

thumb-quality: this tag is used to set the JPEG quality for the thumbnail sized images that are produced. Valid range is 1 ... 100. A higher number give you a cleaner image, but increases the file size, so the preview speed might go down. A number around the 65-80 range is probably optimal.

thumb-size: this tag is used to set the maximum dimensions (width and height) for the generated thumbnails. It is specified in pixels, large values are possible, but probably pointless. Typically one will make the width value greater than the height.  If you only supply one value, it will be used for both the width and height. If both the width and height are the same, then if the picture is in landscape orientation this will be its width, if the picture is in portrait (i.e. vertical) orientation, then this will be its height.

pic-size: this tag is used to set the maximum dimensions (width and height) for the medium sized pictures that are shown in the "details view" pages (these are the pages you get to by clicking on the thumbnails). These are specified in pixels, typical values for these would be "640 480" or "1024 768" (but some may want smaller pictures to speed up web viewing). If you only specify one value, then the program will use it for both the width and height, then if the picture is in landscape orientation this will be its width, or if the picture is in portrait (i.e. vertical) orientation, then this will be its height.

pic-quality: this tag is used to set the JPEG quality for the medium sized images that are produced. Valid range is 1 ... 100. A higher number give you a cleaner image, but increases the file size, so the web viewing speed will go down. A number around the 65-80 range is probably optimal. Since these pictures are quite a lot larger than the thumbnails there is much to be gained (in increasing viewing speed) by reducing the quality.

table-rows and table-cols are used to specify the number of row and columns that the thumbnail tables will contain. If you have directories with more photos than will fit in a single table then PhotoTrove will build additional tables and add the appropriate navigation links between them.

border: this tag is largely for testing purposes, when set to "1" it causes the borders of the HTML tables that are used to arrange the elements of the pages to be displayed. The plan is to add some additional tags to allow one to select which of the borders should be drawn (and probably in what colours). When set to "0" (zero) all these borders should be hidden.

icon-up: this tag is used to provide the HTML fragment that is placed on the pages wherever the go-up-a-directory navigation link appears. In this example it is used to replace the "Up" text with an image. The location of this image on the web server is "/extras/up.gif".

icon-previous: this tag is used to provide the HTML fragment that is placed on the pages wherever the previous-page navigation link appears. In this example it is used to replace the "<--Previous" text with an image. The location of this image on the web server is "/extras/previous.gif".

icon-next: this tag is used to provide the HTML fragment that is placed on the pages wherever the next-page navigation link appears. In this example it is used to replace the "Next-->" text with an image. The location of this image on the web server is "/extras/next.gif".

Note that these various icon- tags are HTML fragments, but because of the way XML parses files you need to write an "<" as "&lt;" and a ">" as "&gt;". There is another trick that can be used to get around this which will be shown later. Also, the various file names for these images are up to you, use whatever is appropriate for your images on your web server, I have used absolute paths for these files as that simplifies things greatly. Further, since these are all HTML fragments that just get inserted in an HTML anchor tag you could possibly do something rather clever here.

copyright: this tag is used to specify the copyright message you want to appear at the bottom of most pages. If you do not specify one then nothing will be displayed. Generally this is a message that contains the word "Copyright" or the special little © c-in-a-circle symbol (which you can get by typing "&copy;"), the year and the author's name. If you want, you can put other stuff in here. In fact, this can take an HTML fragment, just use the trick of replacing the "< >" characters with "&lt; &gt;".

After the tags a number of additional XML elements appear, these are used to add additional information for the various pages that are produced.

<web-title>: this is used to set the title that will be displayed in the web browser's title bar. This cannot contain any HTML markup tags. This must end with a </web-title> marker. The contents of this element are inherited by sub-directories.

<title>: this is used to set the title that will be displayed on each thumbnail page for this directory, this is an HTML fragment so you can include HTML markup commands if desired. This must end with a </title> marker.

<dirtitle>: this is used to provide a different version of the title (perhaps suitably abridged), this will be displayed in directory listing area of the index page of the parent directory alongside the name of the sub-directory to offer some guidance for the user. This must end with the </dirtitle> marker.

<description>: this is used to provide a longer description that will be placed on each of the thumbnail pages for this directory. This must end with the </description> marker.

Overriding Directory Files

A typical photo web site will have a number of sub-directories that will contain photos, perhaps grouped by topic or date. These sub-directories will inherit the layout settings of  their parent directories. At a minimum you will need to place an index.xml file into the top-most directory of the tree, this will establish the default settings for all the sub-directories within it. Then, as you see fit, you can override some of these settings by placing index.xml files that contain new values into certain sub-directories. When you do this to a sub-directory that contains other sub-directories, then those sub-directories will also get the overridden values. This technique can be used to impart a different look and feel to the pages of a particular area of the photo collection.

Customizing by File

PhotoTrove allows you to enter additional data about the various individual photographs you are including for display. This data is optional, you only need to provide it as you see fit, so its quite ok to not provide any additional data, just provide it for a few selected photographs or provide it on everything. You provide this additional data by creating an XML file for each picture that needs it. If a particular picture is called fred123.jpg then the XML file should be named fred123.xml and must be stored in the same directory as the picture file. An example file might be:

<?xml version="1.0"?>
<photo pic-quality="70" pic-size="800 600" keywords="hotel rome" index="i">

<title><![CDATA[<h3>Hotel Valle</h3>]]></title>
<description><![CDATA[This is the hotel we stayed in for the last two weeks of the trip.
<p>
It is located in central Rome about 300m down Cavour street from the
main train station (Termini) and about 100m up Cavour street from
the <b>Cavour metro</b> station. </p>
<p>It features: </p>
<ul>
<li>odd shaped rooms, no two alike</li>
<li>twisty passages, all the same</li>
<li>an elevator built for two, but rated for six</li>
<li>contential breakfast, with the <i>Worlds Worst Cornflakes</i></li>
<li>reasonable (and very negotiable) room rates</li>
<li>lots of great attractions and places to eat within a few minutes walk</li>
<li>air conditioners which mysteriously turnoff in the wee hours of the morning</li>
<li>shower stalls not suitable for the girth-challenged</li>
<li>laundry service in less than a week</li>
</ul>]]> 
</description>

</photo>

You may note that some of the tags in this file have the same name as those in the directory index.xml files. When this happens, the values provided by the picture's XML file override those provided by the directory file, for this one particular picture. The tags that appear in this example are:

pic-size: this tag is used to set the maximum dimensions for the medium sized pictures that are shown in the "details view" pages (these are the pages you get to by clicking on the thumbnails). These are specified in pixels, typical values for this would be "640 480" or "1024 768" (but some may want smaller pictures to speed up web viewing).

pic-quality: this tag is used to set the JPEG quality for the medium sized images that are produced. Valid range is 1 ... 100. A higher number give you a cleaner image, but increases the file size, so the web viewing speed will go down. A number around the 65-80 range is probably optimal. Since these pictures are quite a lot larger than the thumbnails there is much to be gained (in increasing viewing speed) by reducing the quality.

keywords: this is used to specify the index keywords that this picture should be indexed by. This is a space separate list of keywords.

index: this is  used to specify how the picture should appear in the index. If this is not present, then the picture will not be included in the index at all (even if keywords are supplied). See the Indexing section for more details.

Along with the various tags there are some additional data elements for pictures, these are:

<title>: this element is used to specify your title for the picture. It is an HTML fragment so can contain things like centering or font specifications. In the example I have used the XML "CDATA" method of encapsulating the contents so that I don't have to write "&lt;" wherever I want an "<". To do this you start your text with the characters <![CDATA[ and end it with ]]> . The title element must be finished by the </title> marker.

<description>: this element is used to enter an extended length description of the photo. In this example I have gone overboard to illustrate that you can use full HTML markup if you need to. The description will appear on the details page in a table cell. The description element must be finished by the </description> marker.

Indexing

PhotoTrove has the ability to create index pages as well as the thumbnails ordered by directory pages.

The index is composed of two types of pages, there is a main index page that is a large table that has a single link per keyword. And there is a set of keyword pages that have all the information (such as thumbnails or text links) about a particular keyword. This may get reworked in the future, depending on how practical this approach turns out to be.

Since indexes are global (i.e. there is only one index for the whole directory tree, not one per directory) the XML tags that tailor the index to your tastes are only specified in the top-most index.xml file. These tags can appear in other XML files, but they will be ignored. The following tags taylor the look of the index pages and may be added to the top-most index.xml file (as part of the photodir element):

index-main-columns="10"
index-keyword-layout="long"
index-image-layout="long"
index-text-layout="wide"

these tags are explained below:

index-main-columns: the number of columns to use in the keyword table on the main page of the index. Since table just contains the individual keywords it is practical to have a larger number of columns in this table than in the thumbnail pages.

index-keyword-layout: this controls the overall look of the keyword pages. If set to "long" then the table of thumbnail links will appear above the table of keyword-only links. If this is set to "wide" then the thumbnail links will appear beside the keyword based links.

index-image-layout: this controls the look of the cells within the table of thumbnail links. These cells can contain additional data (such as keywords, title, filename or description), as specified on a picture-by-picture basis. If this is set to "long" then the thumbnail image will be placed above this additional data in the table cell. If this is set to "wide" then the cell will have the thumbnail image on the left and the additional data will appear in the right half of the cell.

index-text-layout: this controls the look of the cells within the table of text-only links. These cells can contain additional data (such as keywords or description), as specified on a picture-by-picture basis. If this is set to "long" then the title and/or filename will be placed above this additional data in the table cell. If this is set to "wide" then the cell will have the title and/or filename on the left and the additional data will appear in the right half of the cell.

index-image-columns: this controls the number of columns to arange the thumbnail images and their associated information into.

index-text-columns: this controls the number of columns to arrange the text-only cells into.

Indexing Photos

To add an individual photo to the index all that you need to do is to decide on the keywords for the photo, decide on the appearance of the index entry, and add this information to the photo's XML file. This additional information is provided through a few more XML tags like:

keywords="hotel rome" index="i"

these tags are:
keywords: this is a space separated list of keywords that this photo should be indexed under.

index: this is a short set of single character flags that identify the information that should be provided about the photo in the index. The optional flags are:

• i: the thumbnail image of the photo should appear in the index
• t: the title of the photo should appear in the index
• f: the filelane of the photo should appear in the index (note this is the filename of the source photo, including the directory path)
• k: the other keywords for the photo should appear in the index (this information is displayed on a particular keyword's page, so in this example there are two keywords, and thus, on the "rome" page only the "hotel" keyword would be shown and visa versa)
• d: the description of this photo should be displayed on the index page
  

if both the "i" and "t" flags appear then the photo will be placed thumbnails section of the page, if "i" flag is not present then the photo will be linked to from within the text-only section of the keyword page. You will need to ensure that at least one of the "i", "t" or "f" flags are present for the photo to be included in the index at all.

Indexing Directories

A particular directory can also be added to the index by keyword. This uses the same tags as the photos, just add the appropriate tags to the index.xml file for that directory. Directories do not have a thumbnail image unless you use the icon-directory tag, so you should not normally include the "i" flag on the index tag. When you specify a thumbnail image to be used to represent the directory it will also be used in the contact sheet view where the directory name appears, so users can enter that directory by selecting its image. For practical purposes, the image you specify here needs to be one of the thumbnail images from within the directory itself; however, it is conceivable that you could either copy additional images into your output directory tree or specify images that are somewhere else (if you understand a lot about how URL linkages work within web sites). An example of this tag (in the 030601/index.xml file):

icon-directory="./030601/Img_1823.thumbnail"

note the prescence of the "." at the start (this is needed to get the browser, which will be in the parent directory (i.e. the directory above where the Img_1823.thumbnail is located) to put together the right URL).

The index tag for a directory is not passed on to the photos within it as the default, you must specify the index tag in each photo's XML file as well.

Access Control

PhotoTrove has the ability to build seperate web-ready directory trees from the same set of source directories and files. The reason for this is so that one can easily set up a few different views of a single large photo collection for different classes of users. For example I would like to have four different groups:

1. internal, this group will have access to all the images, so that we can edit and search them and when we really want to bore someone we can show them all 1500 pictures from the last trip to Hawaii rather than just the 100 best photos. This photo set will have links to the original photos directly. A significant (like 90%) quantity of these photos will have no auxillary information.
   
2. family, this group will have access to an edited (i.e. much less boring) set of photographs, most of these will have some form of description or title attached.
   
3. work, this group of photos are of interest to people I work with, fun thing like pictures of client signing acceptance test documents, the interiors of hotels I stayed at...
4. public, this group of photos are of general interest to the world, in this set I might not have the large size images included (or I might have them at about a 70% quality rather than 100%).

Now your typical web server software (for example the excellent Apache) without doing anything fancy, has only a very coarse access control system. In Apache's case it readily allows you to give passwords to individual users, then assign these users to groups and to make certain directory trees require the user supply a name and password (and hence be included in a particular group) before serving files from them. Because of this I found it easiest to just set things up so that PhotoTrove would produce a stand-alone web directory for each group of user. Then all you need to do on the web server side of things is decide on which groups you want and when you add users to your system, just assign them to a particular group (or possibly groups), then just set up the initial directory for each of the groups views of your collection and assign it the right web server group requirements.

All of this is done by the group tag in the various directory's index.xml files. There are additional considerations for assigining access on a file-by-file basis, this is explained later. What you do is add a tag like:

group="internal family work public"

to your top level photos\index.xml file. This will allow the groups called internal, family, work and public to have access to all the files within this directory.

Now, if you do not put any group tags in any of your sub-directories, then these groups will all be allowed to access these directories as well. If you place a group tag in a sub-directory that looks like:

group="internal work"

then this sub-directory (and all of its child directories) will only be available to members of either the internal or work groups.

When you run PhotoTrove one of the command line parameters you need to include is the "-g" which specifies the name of the group that the output directory is being prepared for. So to prepare the web pages for the "work" group you place:

-g work

on the command line. Note that PhotoTrove can only prepare the files for one group at a time. Also note that you need to specify a different output directory for each group.

You may have noticed that in the initial example when PhotoTrove was being run for the first time that you had to specify a group name on the command line, even though there were no groups defined in the top level index.xml file. The reason this works is that until a group list is specified for some directory in the tree, any group is considered to be allowed.

Tailoring the Presentation by Group

It is possible to even give different groups distinctive views of your web pages. This is possible by creating index.xml files with multiple photodir elements in them. Since the group list is an attribute of a particular photodir element, what you can do is duplicate this element, and then change the group list, along with whatever other tags need customizing for this particular group. This way you could preserve your web bandwidth by setting the various JPEG quality setting to a lower number for the public group than for your family group. Here is what this might look like:

<?xml version="1.0"?>
<file>
<photodir 
group="internal family"
thumb-quality="85" thumb-size="140 100" pic-size="640 480" pic-quality="75"
table-rows="4" table-cols="3" border="0" 
icon-up="&lt;img src=&quot;/extras/up.gif&quot;&gt;" 
icon-previous="&lt;img src=&quot;/extras/previous.gif&quot;&gt;" 
icon-next="&lt;img src=&quot;/extras/next.gif&quot;&gt;" group="test family sysop" 
copyright="This stuff is Copyright 2003 by Stephen Vermeulen" 
>

<web-title>Stephen's Family Album</web-title>
<title>&lt;center&gt;&lt;h3&gt;An assortment of photos&lt;/h3&gt;&lt;/center&gt;</title>
<dirtitle>Various Photos</dirtitle>
<description>
This collection of snapshots was taken with a Canon G1.
</description>

</photodir>

<photodir 
group="public"
thumb-quality="65" thumb-size="100 75" pic-size="320 200" pic-quality="60"
full-size="0"
table-rows="5" table-cols="4" border="0" 
icon-up="&lt;img src=&quot;/extras/up.gif&quot;&gt;" 
icon-previous="&lt;img src=&quot;/extras/previous.gif&quot;&gt;" 
icon-next="&lt;img src=&quot;/extras/next.gif&quot;&gt;" group="test family sysop" 
copyright="This stuff is Copyright 2003 by Stephen Vermeulen" 
>

<web-title>Stephen's Web Album</web-title>
<title>&lt;center&gt;&lt;h3&gt;An assortment of photos&lt;/h3&gt;&lt;/center&gt;</title>
<dirtitle>Photos</dirtitle>
<description>
Here are some photos from my collection.
</description>

</photodir>
</file>

You'll notice that I have made the quality less and the images smaller for the "public" group, as well I have increased the number of thumbnails per page for the public group (since their thumbnails are smaller), and told PhotoTrove not to provide the "public" group with links to the full sized images. This sort of technique can be particularly useful if your internal group is served across a local area network, so that bandwidth is not an issue for them.

Also note that an exclosing element (the <file></file> pair) around the multiple <photodir> elements appears to be necessary for good XML. The older versions of the parser seemed to not need this.

File Specific Access Control

Background

There will be times when (because of the way you have chosen to organize your master collection) you have a directory that contains files that two or more mutally exclusive groups would like to see. For example you might just file things by date and on one particular day you took photos of both the family and company BBQs, but you would like to show just the family pictures to the family group and the company pictures to the work group. You can do this by just splitting this one directory into two and sorting the photos appropriately. But that messes up your neat filing system.

Another example, which is largely why I wrote this, is that you may have two or three different views of the same set of photos, where these views are ranking based. In my case I would like to have:

1. an internal group that is available primarily for use over my home LAN, which has access to everything (which means that there are a lot of near duplicates and other rejects...)
2. a family group that is web available to family members, but to save space and bandwidth on the web server (not to mention reducing boredom) this is a "best-of" collection, where probably only 1 photo in 20 makes the grade
3. a public group that is a "very-best-of" collection, probably only 1 photo in 100 makes the grade, and the material is of things that are of general interest to the web at large, this is accessible to the whole web.
   

Once you start doing this sort of thing it becomes difficult to start moving all the material around, and you start to find you need to make copies of certain photos, ...  As well, if you have a large existing collection (say 5000 photos) and you want to accomplish something in a reasonable amount of time (say getting you "public" group set up), then if you only had to flag those photos that were the very best (say the top 50-100) you could probably do this in a day or so.

Configuring

Now you understand the sort of reasoning that led me to write this function, here is how to use it. You will need to create an XML file for each picture that needs special treatment. In this file you will add a group tag (on the photo element) that identifies the groups that are allowed to see this picture. Remember that there is already some restriction to the groups that are allowed to navigate to the particular directory that the photo is in, so what you are doing is to further restrict access to this particular photo. For example, if the directory has the tag: group="internal family work" and there was a picture in it that you did not want the work group to have access to, you would set that photo's tag to: group="internal family".

Now, say you have the situation where you have a directory which has a lot of photos in it, but only a few of these should be published to some of the groups (this is the case you're going to see a lot of if you have something like my group structure). For example you have made the directory accessible to internal, family and public, but only a few of the pictures really should be made available to the family and public groups. If you were to use the above approach you would have to add XML files to almost every photo, just to restrict access to just the internal group, and that could be a lot of work.  What you need is the concept of a default group list. This is set up in the directory's index.xml file, with the tag: default-group="group name list", by setting the default group tag as: default-group="internal" then for this example, all the photos that do not have XML files with a group tag in them will only be available to the internal group. And those photos you want to make available to the family or public groups will need an XML file with a group tag in it. If most of the files in the directory should be available to family members but only some to the public, then by setting the tag to default-group="internal family" you only need to set the group tag on those few photos which should be shown to the public (use group="internal public" or group="internal family public" depending on if the family should see the public pictures) and those photos which should not be shown to the family (use group="internal").

Insert a note on setting up Apache here

Adding Watermarks

PhotoTrove can automatically add "watermark" text to the photos in selected directories. This is useful for adding a copyright notice to the individual medium and full sized pictures. The watermark message is just simple unformatted text (no HTML tags are allowed) that will get superimposed on the picture in the bottom left corner. It is written twice, slightly offset, in two different colours, thus forming a "drop-shadow" sort of effect, and helping make it visable against most pictures. Watermarking obviously will modify the photographs, so in the case of the full sized photos, turning watermarking on will cause a copy of them to be made and placed into the output directory (thus you cannot have watermarking and still save disk space by linking back to the original photos). The attributes for watermarks are:

watermark-text: use this to specify the text that you want to show in the watermark. This is also the attribute that enables watermarking for this directory and any sub-directories. If you want to turn off watermarking in a particular sub-directory just specify the empty string (i.e. set this attribute as watermark-text="").

watermark-font: this can specify a true type font to be used to render the watermark. To find these on a Windows system look in your windows system directory, in a subdirectory called "fonts" there should be some. They have a ".ttf" file extension. You could also just start some program like Word and see what true type fonts it has access to.

watermark-size: this is used to specify the size of the watermark (i.e. the height) in pixels.

watermark-medium-size: this is used to specify the size of the watermark (in pixels) on the medium sized pictures. Since these pictures may often be quite small, by setting this to "0" no watermark will be placed on the medium sized pictures.

watermark-colour: this is the foreground colour of the text.

watermark-backcolour: this is the background colour of the text.

Additional Notes

Here are additional notes, some of this is not advanced material, it just did not fit in well with the examples in the preceeding text.

More on the Command Line

The most complicated thing about the command line arguments is what to specify for the web directory related parameters. This will depend on how your web server's directory tree is set up. Typically you are going to be preparing the directory tree on one computer (where your original files are located or locally accessible) and then uploading the resulting output directory to the web server. On the web server there will probably be some directory path above the place that you put the output directory that some of the links (particularly those using the index) need to know about. Lets say this path is something like "/home/users/fred/wwwroot". Now lets say you have your original photo directory on your PC on the D: drive in a directory called "d:\files\photos". Furthermore, you are writing the HTML output to the E: drive on your PC in a directory called "e:\temp\public" (possibly because the group is the called "public"). The appropriate command would be something like:

E:\personal\thumbnailer>phototrove.pyc -i d:\files\photos -o e:\temp\public -g public -wp /home/users/fred/wwwroot -wh /home/users/fred/wwwroot

But say (for complex reasons outside your control) you arrange to place the full sized images in the directory /home/users/fred/bigphotos, then you would change the -wp parameter to read: -wp /home/users/fred/bigphotos. And in this case you would not need to use the deep-copy XML option to place a copy of the full sized images into the output directory.

You can force all files to be rebuilt in the output directory by including a "-f" on the command line. Note this does not specifically delete the contents of any directories first. Also note that this will not override any "force" tags that have been including in the XML files.

While playing with the HTML layout options you might want to delete the current set of HTML files from the output directory before rebuilding them. You can do this by including the "-c html" parameter on the command line.

To really make PhotoTrove build a fresh copy of all the output files your best bet is to delete that directory tree.

The debug command line switch is a "-d" followed by a word composed of one of more of the following letters:

• a for access control
• f for file handling
• m for miscellaneous
• t for thumb nail processing
• r for rejection pattern processing
• b for reBuilding progress (useful to see which directories are being rebuilt or skipped)
  

if you want to tun on debugging for several of these at once you try a word like "-d fat".  If you want to see more debugging of a particular type, they you add another letter of that type, so "-d fatt" should show more detailed thumbnail debugging messages than just "-d fat".

Rebuilding of subdirectories

As you get PhotoTrove to process larger directory trees you will find that processing times can get quite large. While the largest portion of the processing time comes from the time taken to prepare images (thumbnails, medium and full sizes), even once these are up to date and you are just regenerating the HTML files (the contact sheets, the detailed view pages and the keyword indices) a large directory tree can take some time. Quite often the reason you are re-running PhotoTrove is to build HTML pages for some new directories that you are adding to the collection, and so, if it did not have to re-process all the existing directories that had not changed, things would be faster. To suspend processing of a particular sub-directory tree, use the rebuild="no" directory tag (in the index.xml file for that directory). When this is set, then by default PhotoTrove will not rebuild the HTML (or other) files within that tree. Note, that this can lead to the HTML within that tree becoming out of date (if you make changes within it).

By default PhotoTrove will rebuild only the HTML files within the directories that do not have a rebuild="no" directory tag. Also, PhotoTrove will no longer rebuild the keyword index files unless the appropriate command line argument is supplied (as doing this rebuild requires PhotoTrove to visit all the files in the system). The net result of this is that new additions to your collection will not show in the index until you tell it to redo the index.

When PhotoTrove rebuilds the contact sheet and details HTML files for a particular directory it will still rebuild any thumbnail, medium or full sized images that are missing. If the force=1option is active for the directory it will rebuild all these files.

The command line flag that controls the rebuilding behaviour is the "-r" flag, it takes an additional keyword (e.g. "-r all") to determine what will be rebuilt (if you do not supply a "-r" flag, then only the directories that are allowed to be rebuilt will be processed and no index files will be changed). The following table summarizes what will happen with different options:

command line parameter	contact sheets and details pages rebuilt?	keyword index rebuilt?	thumbnails images rebuilt?	medium size images rebuilt?	full size images rebuilt?	which directories are affected	overall expected effect
-r all	yes	yes	yes	yes	yes	all	rebuilds everything, even in rebuild="no" sub-directories
-r index	yes	yes	no	no	no	all	rebuilds contact sheets, details pages and keyword indices, even in rebuild="no" sub-directories
-r contact	yes	no	no	no	no	all	rebuilds contact sheets and details pages but not keyword indices, even in rebuild="no" sub-directories
none given (default action)	yes	no	no	no	no	only allowed directories	rebuilds contact sheets and details pages but not keyword indices. Only in rebuild="yes" subdirectories.

Note that by "all directories" it is meant that PhotoTrove will process the contents of all directories allowed by access control for the specified group.

This command setup allows you to have a number of directories (which you infrequently change) that are "protected" from additional processing by the rebuild="no" tag, then on those occasions when you do need to rebuild the overall index or the HTML within these directories (contact sheets and details pages) you can force this to happen without having to change all the appropriate XML files.

Also, the keyword index is no longer rebuilt each time PhotoTrove is run, except when the appropriate command line arguments ("-r index" or "-r all" are supplied).

The rebuild all command (-r all) has the same effect as having force="1" and rebuild="yes" on all directories (its just a convenience feature so save you from having to edit a bunch of XML files). Everything will be rebuilt. If you are running this you might want to consider deleting your output directory tree to make sure there are no stale files (i.e. output files for which the input files no longer exist, having been renamed, moved or deleted) left over.

Directory XML Tags

Here are some other directory index.xml tags that have not been covered in the preceeding:

parent-url: use this to specify where up-directory link on the top-most page points, you'll probably want to set it to the URL for the rest of your web site. It defaults to pointing back to the PhotoTrove page.

full-size-quality: use this to specify the JPEG quality of the full sized images (for example when they are created by adding a watermark or when deep copying is allowed), this can also be used to prepare a set of full-size but substantially smaller images from the originals to save on web bandwidth or storage space.

force: use this to force the rebuilding of this directory and its children, including the recreation of any image files (thumbnails etc.). To speed things up, if PhotoTrove finds a thumbnail already exists in the output directory it will not spend the time to remake any of the images. This defaults to force="0", if you set force="1" then it will recreate those images, even if they exist (you might want to do this if you have just changed the thumbnail size, or the watermark, but the change does not show up).

deep-copy: use this to prepare an output directory that includes copies of the full sized images (rather than trying to save space by linking back to the originals). This defaults to deep-copy="0", setting it as deep-copy="1" will cause the copies to be made.

full-size: use this to allow links from the details page to the full sized image. By default this is set as: full-size="1", but setting it to full-size="0" will prevent PhotoTrove from making links to the full sized images. When you set this to one no full sized images should be created, even if you set deep-copy to one as well.

left-margin and right-margin: use these to reserve some space (in pixels) between the borders of the browser and the contents of the pages. This can be used to position the page's contents on top of some background image (perhaps one that has a frame like design) to give the illusion that the pictures are on some printed page.

body: to add a background image to your pages you can use the body tag like this:

body='background="/extras/background.gif" bgcolor="#ffffff" text="#000000" link="#0000ff" vlink="#0000ff" alink="#0000ff"'

where background.gif is the name of the image to use as a page background. Note: since you need to put quotation marks around the full contents, if this contains double quote marks then you need to use single quote marks for the outer quotations.

extensions: if you have various non-image type files in your source directories that PhotoTrove should not attempt to process, then include this directory tag, to tell PhotoTrove to only look at .jpg and .jpeg files you would set: extensions=".jpg .jpeg", the matching is case insensitive.

icon-directory: use this to specify the URL fragment to an image that will be used to represent the directory on the index pages and the contact sheet pages. If you set this, they you can set index="i" to have the directory appear in the images area of the index pages.

reject-pattern: use this to specify a regular expression that would match any files or directories you do not want PhotoTrove to include. For example, if you are a Macintosh UNIX user and have subdirectories named "resource.frk" all over the place you can prevent PhotoTrove from including these by specifing: reject-pattern="resource\\.frk". Note the obvious "resource.frk" will appear to work, but as a "." is the regular expression wild card for match any single character at this point it would also reject a file or directory called "resourceZfrk", which probably would not bother you. You need to put the "\\" pre-fix in the string to escape the wild character. If you wanted to reject all "*.txt" files you would use the pattern ".*\\.txt". Pattern matching is case insensitive. If you don't want any rejection you can set the pattern to the empty string with a line like: reject-pattern="". The pattern of the parent directory becomes the default for its children, so if you set it in the top most index.xml file it will take effect throughout. For more information on regular expressions see this URL. If you want to reject several patterns you include them in the one string, place each in a set of "( )" characters and separate then with "|" bars, like: reject-pattern="(adam)|(stephen)|(resource\\.frk)". Personally, I am not keen on regular expressions I much prefer the old wildcard syntax from AmigaDOS.

The thumb-align and thumb-valign tags to control the layout of thumbnail images within the contact sheet table cells. By default these are set to thumb-halign="center" and thumb-valign="top". The thumb-halign controls horizontal alignment of the image in the cell, valid values are left, right or center. The thumb-valign controls vertical alignment of the image in the cell, valid values are top, bottom or center.

You can now dress up the table of thumbnail images (or else make it really ugly) on the contact sheet pages using the following tags:

File XML Tags

The following XML tags can be used in the <photo> element of the XML files for individual photos: pic-quality, full-size-quality, pic-size, pic-rotate, keywords and index. As well the following elements are understood: description and title. All of these have been described with the exception of pic-rotate. If you have taken some pictures while holding the camera in portrait orientation, and you have not already rotated the original, then by setting this to 90 it will cause the thumbnail, medium and full-sized images to be rotated counter clockwise 90 degrees, setting to -90 will cause the rotation to be 90 degrees clockwise. This will not affect the original photo file.

The alt-text tag can be used to set the HTML IMG ALT text for images, normally this does not appear as visable text in a browser, but it may be accessible from the "properties" menu on the image.

Release Notes

v1 - 5/Aug/03 initial test release
v2 - 7/Aug/03 enabled antialias mode in thumbnail and medium sized picture generation, now allow the background image to appear on detailled view pages,  made the <body> element into a tag so that it can be passed on to child directories, fixed a bug in the generation of links from the index page to thumbnail pages.
v3 - 8/Aug/03 added the access control system to individual files, and the allowable file extensions tag
v4 - 9/Aug/03 added the watermark-medium-size tag for font size on the medium pictures, added a link from main index there back to the main page, revised the watermark positioning code to be a 3% offset from the bottom left corner, removed a debug message that appeared on thumbnail pages that did not have titles
v5 - 17/Aug/03 now an empty extensions tag will cause PhotoTrove to process all files. Fixed up linking back to the index pages, so now will work with file-based browsing. Switched to using the new EXIF support from PIL v1.1.4, so now the exif.pyc file should no longer be needed. Changed the name to PhotoTrove. Added the debug command line switch "-d". Added the alt-text tag to the photo XML files.
v6 - 17/Aug/03 added a sort to the directory listing that is used to drive the processing, so now the sub directory and file lists should always appear sorted.
v7 - 17/Aug/03 added code to convert palletized images (like GIFs) into RGB mode so they can be written as JPEGs.
v8 - 17/Aug/03 added icon-directory tag to the directory XML so that a thumbnail can be specified for a directory.
v9 - 17/Aug/03 this should fix the problem with trying to get EXIF data from files that are not JPEGs.
v10 - 22/Aug/03 added the reject-pattern tag to allow rejection of directories or files that match the pattern. Fixed a number of issues with corrupted or zero length files. Added new command line flag "-r" for controlling the rebuilding of the directory tree.
v11 - 23/Aug/03 now outputs an index.html file which is a duplicate of the index1.html file, apparently this makes life easier when setting up a web server.
v12 - 29/Aug/03 changed the pic-size and thumb-size to take both a width and a height, so these look something like pic-size="640 480" now. It is ok to just provide a single dimension still - in which case both width and height get set to it. This was primarily done so that the thumbnail sheets would have a more uniform layout (as the dimensions of each cell in the table would be the same - if you only choose to display the image in the cell). Added the thumb-halign and thumb-valign tags to control the layout of thumbnail images within the contact sheet table cells. By default these are set to thumb-halign="center" and thumb-valign="top". Added tags to control the layout and background colouring of the cells in a contact sheet, look for the thumb-bgcolor, -padding, -spacing and contact-bgcolor, -frame, -rules, -border tags above.

Additional Suggestions for Improvement

This section lists some suggestions for improvement in PhotoTrove that have been received from other users. There's no promise that I'll do any of these things, but unless I've specifically stated I'm not going to do something, there is a chance that I'll address these in some future version.

• Option to display file name. In which view? Thumbnail or detail? Should this include the directory? 
  In both. I'd like to be able to mimic the output from ACDSee as much as 
  possible. I don't think it needs to include the directory as this may change 
  depending on where the end result is put.

• Option to hide individual picture titles on the thumbnail set

• Option to set thumbnail title size (so H3 isn't forced)

• Option to make the numbering of index pages padded out. For example: 
  index001 rather than just index1. For sorting and generic pattern matching.

• Option to select which EXIF tags are printed on the intermediate sized 
  picture page.

• Option to change appearance of EXIF text properties on the intermediate 
  sized picture page (e.g. bold for the category entry.)

• Option to recurse all subdirectories and dump all photos into the same web 
  page (i.e. linked to the appropriate thumbnails in each subdirectory.) Uniqueness of names isn't important in this case, as the HTML index merely 
  links to the subdirectories where the thumbnails and originals are.
  
  The rationale for this is so that I can get a complete listing of all the 
  pictures in the library in a single set of linked pages. The way it's 
  designed at the moment, all photos in different directories have their own 
  grouping (either by index or directory.)

• Add option to group Previous/Up/Next icons/text together or force the 
  tables to be the same size always. It's annoying to have to move the mouse 
  left and right depending on whether the next photo is a landscape or portrait.

• Automatically ignore any subdirectories with no valid files in them.

• Add keywords to directory XML; for example, I may have directories over 
  several years that show the same place, but I don't want to add XML files to 
  each and every photo in order to get them cross-indexed.

• Sometimes the indexing on names is not consistent. For example "NEXT" on 
  A0182.HTML takes me to A0181.HTML. I was rather expecting a sorted list.

• I want to colour specific cells, such as the copyright, description or 
  title. It would also be interesting to colour specific thumbnail squares 
  rather than cycling or all.

• I'd like to move the thumbnail description text to below the graphics, 
  rather than above.

• Remove the extra <P> tag when closing the previous/up/next navigation 
  table as you then immediately close the cell. Under IE this generates a 
  spurious linefeed.

• Multiple columns for the subdirectory listings. With a wide screen, it's a 
  bit annoying to have to scroll waaaaay down. Personally, I'd be averse to 
  having these all concatenated in one cell separated by " | "

• Leave the "Previous" or "Next" text present when there isn't one; then 
  just don't link it to anything. It'll look more consistent and the user will 
  understand.

• Add a signature brush to provide a better way of adding the copyright information
  

Examples of Other Photo Albums and Software

• Mel & Drew's travel diary, is quite a nice layout
• TZO photo sharing software
• Some web page backgrounds made from flower photographs
• Photos, a Web-based photo database for storing metadata about digital photos so you can find them again later.
• Simulacra is a new photo gallery creator, a sample page is here
• Ami - Music Photographer has an interesting layout concept
• A review of Picasa and Hello, photoalbum and sharing software
• Electric Shoebox from Constant Time Software
• SWiSH Pix allows you to make a flash presentation out of you still pictures
• Pixory is a photo sharing application. "Pixory allows you to store your photos on your own pc but to access, compose into albums, and share them anywhere on the internet. It's your personal online photo sharing service, running on your computer using your broadband internet connection. Pixory is a client and a server, a lightweight web application for browsing photo collections on your hardrive; an album server to your friends and family or anyone on the internet. It simplifies accessing and organizing photo collections on your home network."
• BrilliantPhoto, photo album software with some sharing support
• Picasa, photo album software
• World-Wide Media eXchange, a GPS location index photo archive project
• Java Picture Organizer
• 93 Photo Street is a package that allows you to associate photos with locations on a map, reviewed here
• a review of JASC's Paint Shop Photo Album 5
• WebShots is a photo sharing site
• Clouds, a collaborative photo mosaic idea, might be good but the site got Slashdotted.
• Photo ShowOff is an HTML photo album generator
• A slashdot artical that mentions several of the popular photo-sharing sites, along with some of the APIs that they are using to allow photos and information to be added.
• Phanfare, a site featuring background upload and "unlimited storage for personal use", but there are bandwidth limits and its in the range of $7/month or $55/year
• The Gallery is a web based, open source, photo album written with PHP
• jBrout is another photo manager
• Venrock funds Simple Star, a photo sharing company
• Nat's World, this is a teaching game that is created from photographs
• Redbug Technologies has their Mapwing which makes virtual reality tours out of photographs
• Gallery 2.0 has been released (Sept'05)
• MrBass has some recommendations on other photo albums
• Avvenu, is an online photo sharing service, described here
• WCatalog, a media web cataloging application written in Python
• pynakotheka, a Python script to make static HTML pages for photo albums
• Qurio, PC-based photo sharing software
• PhotoStack
• pynakotheka
• EverPlay, is an attempt at standardizing consumer produced digital media (such as photos) and meta data
• Flickr and Zooomr photo sharing sites
• Slashdot discusses a photo management project called LowFat
• Engal is a simple photo gallery for TurboGears, more discussion here.
• The Stock Artists Alliance press release on metadata for photographs
• imgSeek, a photo collection and manager with content-based search. This uses wavelets to allow for image feature recognition based searches.
• Peter Bengtsson's photo album
• The FireFox crop circle, an example of Gallery in action
• Tabblo, a photosharing site. Here's some more notes on it, Wired magazine had a mini-review and comparison of it to Buzznet, Flickr, Webshot and Zoomr.
  
• Maxtor's Fusion NAS device has a built in web server that looks like it is designed to address the photo sharing market
• Fotomaps is a map-view centric photo web presentation system
• Monoslideshow, is a Flash image viewer intended for online use
• MediaPro from iView is image management software for annotating, organizing and distributing digital files.
  

back to vermeulen.ca home