Scripts for Managing Photographs

# QAlbum: Scripts for Digital Pictures

# QAlbum

The idea of these scripts is that each folder (directory of images) contains a descriptior file named `index.xml`, which lists the images, along with captions or other descritive information. This `index.xml` can be created and managed using various tools/scripts, or edited manualy with a text editor. Then running `qalbum` generates all the HTML pages, creating scaled images as needed. The resulting web pages can be uploaded to a web server, or browsed as-is from the file system. You can go back and edit the `index.xml`, and then re-run `qalbum` to get an updated web folder.

Here is an example page that illustrates many `qalbum` features, and here is the picture group file describing it.

## Features

There are a number of tools which do similar things. This one has some nice little extras:

- Uses JavaScript for some useful effects, but works fine without it.
- All the fancy features are implemented using fairly portable client-side JavaScript. No server support is needed. Everything works even if the web folder is burned to a CD-ROM, say.
- Keyboard navigation (if JavaScript is available).
- Can optionally scale the image to fill the browser windows. The image is automatically rescaled if the browser window is resized. This is nice for full-screen mode, for example. (This feature requires JavaScript.)
- A nice slider mode. (This also requires JavaScript.)
- Nice bookmarkable (and search-engine-friendly) URLs for everything. The browser's location-bar is kept up-to-date.
- The user can select between a number of styles for viewing each picture. The style is remembered between pictures, encoded in the URL.

## File naming convention

A suggested naming convention: Each `.jpg` file should follow this naming convention: `prefixNnX.jpg`, where `prefix` is name common to a group of files, and `Nn` is a serial number. (Hence `prefix` should not end in a digit.) The `X` is an optional code letter, for scaled/rotated images that are normlly generated automatically: Where `r` means the picture is right-side-up but rotated relative to the camera original; `p` is a page-size image (scaled and perhaps cropped and rotated so it is suitable for viewing in a web page by itself); and `t` means a thumbnail image (scaled to show multiple images per page).

## Suggested procedure

If you have a group of pictures you want to web-ify, this section gives suggested instructions for what to do.

### If needed, create a `lib` directory

The `lib` directory contains files that are shared between albums - currently two JavaScript files and `help.html`. The directory can be anywhere, if you explicitly specify the `--libdir=directory` when running `make-xml.sh`. However, if you use `../lib`, `../../lib`, or `../../lib` (relative to the album you're working on) then the scripts will find it automatically. So create a directory named `lib` next to your top-level album. When you run `qalbum` later, it will copy the necessary files over.

### Generate initial overview files

I assume the `qalbum` script is in your path. (Alternatively, you can type the full path instead iof just `qalbum`.)

Start by putting the `.jpg` files in the desired directory. Then `cd` to that directory.

Run the `qalbum` script as follows. If you follow the naming convention given below, you can do:

    qalbum new "Title" image1.jpg ... imageN.jpg

Here `"Title"` is the name you want on the title page of your overview page, and `image1.jpg ... imageN.jpg` are the image you want to display.

You can leave out the `image1.jpg ... imageN.jpg` list. In that case `qalbum` will make a list from all the `.jpg` files in the directory which have the form `prefixNN.jpg` (i.e. without the `X` code letter). The images will be sorted by the `NN` sequence numbers - not alphabethically.

Either way, this creates an initial `index.xml`. It also creates an initial set of web pages. If the current directory is `/home/me/vacation`, then you can view the web pages and images by pointing your browser at `file:/home/me/vacation/index.html`.

### Unrotating rotated picture

Some cameras (including my current Canon A540) can detect their orientation (i.e. if the camera is rotated), and write that into the saved file. The `qalbum` script can detect this (at least for the Canon A540!), and automatically takes care of the rotation. If you have such a camera, you can skip this section.

Suppose when viewing `index.html`, a picture is rotated 90 degrees counter-clockwise (to the left). In that case, edit `index.xml` to add in the corresponding `<picture>` section:

    <original rotated="left"/>

If the picture is rotated 90 degrees clockwise (to the right), instead add the following:

    <original rotated="right"/>

Then run:

    qalnum

This creates rotated copies of the files you specified as `<orginal rotated="xxx">`, and also edits `index.xml` for you. If the original file was named `xxxNN.jpg`, the rotated file will be named `xxxNNr.jpg`.

Check `index.html` with a browser to see if you got it right. If you didn't, re-edit `index.xml`. For any picture that was rotated the wrong way, delete the rotated file:

    rm xxxNNr.jpg

Re-run `qalbum`. Check again; continue until all the pictures are right way up.

## Format of the picture-group file

A picture-group file is an xml file, which looks rather like an html file, but with different tags (element names). Also the syntax is more strict: For example, for every start tag (such as `<text>`) you have to include the end tag (e.g. `</text>`), and they have to be properly nested. Also, attribute values (such as in `width="1280"`) have to be quoted (with single or double quotes).

The `<group>` element:
  Each picture-group file contains a single `<group>` element. Each `<group>` must contain `<title>` element, fullowed by any number of `<date>`, `<picture>`, `<text>`, and `<row>` elements.

The `<title>` element:
  This must appear in `<group>` element (usually at the start), and contains the title of the folder. It should be a short phrase describing the pictures in the group. It is used for the HTML `<title>` of the overview page, and can contain whatever HTML markup is legal for that.

The `<picture>` element:
  Each `<picture>` element describes one image. It must have an `id` attribute, which is used to name the web page generated for that picture. The `<picture>` must contain an `<image>` element, and may optionally contain `<caption>`, `<text>` (zero or more), `<date>`, and `<original>` elements. (Old `index.xml` may also contain `<full-image>` and `<small-image>` elements.)

The `<image>` element:
  This contains the name of the actual `jpg` image file. This is normally the original, un-rotated, un-scaled image downloaded from the camera. (In old `index.xml` files, this is used for the scaled medium-sized image, and `<full-image>` is the large un-scaled file.)

The `<full-image>` element:
  This only appears in old `index.xml` files, where it contains the name of the large unscaled image file.

The `<small-image>` element:
  This only appears in old `index.xml` files, where it contains the name of the thumbnail-sized scaled image file.

The `<date>` element:
  Each `<picture>` may also have a `<date>` element specifying when the picture was taken. The format is not free-form; I suggest (and the `qalbum` script generates) `YYYY/MM/DD`. (Unfortunately, ISO format `YYYY-MM-DD` is awkward for ranges.) The `<date>` can appear in a `<picture>`, or at `<group>` level; in the latter case it applies to all following `<picture>` until overridden.

The `<caption>` element:
  Each `<picture>` may in addition have a short `<caption>`. This is used as a short description of the picture in the overview page, and it is used as the page title in the picture page. It can contain HTML markup.

The `<text>` element:
  This can appear either in a `<group>` or in a `<picture>`. In both cases, it can contain aribitrary HTML markup, and is formatted as a paragraph. (Multiple `<text>` elements translate to multiple HTML paragraphs.) Any `<text>` elements at `<group>` level (i.e. not in a `<picture>`) are displayed on the overview page, the slider, and the next following picture page. Any `<text>` elements inside a `<picture>` are only displayed on that picture's page, not the overview page.

The `<original>` element:
  This is used to mark an image that was rotated. It has n attribute `rotated`, which value is either `"left"` (if the original camara image is rotated 90 degrees left) or `"right"` (the original was rotated right).

The `<outtake>` element:
  This is used to name alternative but presumably inferior images. It has the form:

      <outtake img="filenameNN.jpg"/>

  or

      <outtake img="filenameNN.jpg">descriptive-text</outtake>

  The elements are ignored, except in the information page of the enclosing `<picture>`, which contains links to the outtake images. This allows the interested viewer to look at alternate images, without cluttering up the normal view. Note that you would remove `<picture>` elements for outtake pictures, and instead place `<outtake>` elements in the selected (non-outtake) `<picture>` elements.

The `<row>` element:
  This is seldom used, but can be used to ensure that a group of `<picture>` are all displayed on the same row in the overview page. Each `<group>` has one or more `<row>` elements, where each `<row>` contains one or more `<picture>` elements. The `<row>` element has no semantic meaning, but it is used to group together those `<picture>` elements that should be shown next to each other (on the same row) of the overview page. If you leave out `<row>` elements, the pictures will be displayed 3 in a line, except that if there are 4 pictures they will be displayed as 2+2.

## Installing: Files to download and dependencies

These scripts have been run using the Qexo (Kawa XQuery) XML processor. There is an (old) article that explains how it works.

### Requirements

- Most of `qalbum` is pure Java, except for a small `bash` wrapper, and should run on any system with JDK 1.4. However, I have made no attempt to run `qalbum` on anything except GNU/Linux system (specifically Fedora). It should work fine on any-Unix-like OS. If you try to get this working on Windows, I'd like to hear about it.

- You need a Java implementation, specifically one that has the `javax.imagio` classes added in JDK 1.4.

- You need Kawa (version 1.9.0 or the latest from SVN); see the instructions for getting Kawa.

- You need the `jpegtran` program installed in your path. This is used to loss-lessly rotate images when needed. This could probably be replaced by pure Java code, but I haven't done so yet.

- You also need Dawn Oakes's metadata-extractor, but this is included in the `qalbum` distribution for convenience.

### Download

Get `qalbum.tgz` from `ftp://ftp.gnu.org/pub/gnu/kawa/`.

### Installation

Extract `qalbum.tgz` into a suitable directory.

In that directory create a `kawa.jar` link:

    cd qalbum && ln -s /my/path/to/kawa-1.9.0.jar kawa.jar

You might want to create a symlink from some directory on your `$PATH` to the `qalbum/qalbum` script.

That should be it. The `qalbum` script is smart enough to chase symlinks and find the needed helper files. It assumes either of the environment variables `JAVA` or `JAVA_HOME` has been set, or `java` is in your `$PATH`.

### Home page

The `qalbum` home page.

## Author and license stuff

These scripts were written by Per Bothner `<Per Bothner>`.

You are free to use these for your own images (personal or business). I of course make NO WARRANTY; if they should happen to destroy your critical files, I'm sorry, but you should have been more careful.

If you use `qalbum` for you pictures, I would appreciate hearing about it.

Please do not redistribute the scripts in a product or as part of some other software distribution without permission. ( I expect you to customise the scripts for your own use; if you make significant enhancements, I would appreciate hearing about it.

Last modified: Mon Dec 18 15:46:29 PST 2006