photomolo and jpegcom release notes

# `photomolo` and `jpegcom` release notes

photomolo 1.0
  generate thumbnails and HTML navigation for a collection of digital photographs in JPEG format
jpegcom 1.0
  read or write the comments of JPEG images
exifiron 1.0
  orientation correction and optimization of EXIF JPEG images

## Copyright information

The `photomolo` utility was written from the scratch by Marko Mäkelä in 2003. The thumbnail images are decompressed and compressed with `libjpeg` from the IJG, and the scaling algorithm has been adapted from `pnmscale` by Jef Poskanzer.

The `exifiron` utility was written from the scratch by Marko Mäkelä in 2003. The algorithms for lossless JPEG image transformations have been adapted from `jpegtran` of the IJG, written by Thomas G. Lane and Guido Vollbeding, and JPEG files are read and written with `libjpeg` from the IJG.

The `jpegcom` utility was written from the scratch by Marko Mäkelä in 2003. The following statement applies to all three utilities:

> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

> This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

## Table of Contents

  1 Motivation
  2 Optimising image files with `exifiron`
  3 Writing image comments with `jpegcom`
  4 Creating thumbnails and HTML navigation with `photomolo`
  5 Frequently Asked Questions
    5.1 Why yet another image gallery program?
    5.2 Why is there no graphical user interface?
    5.3 Where can I obtain the software?

## 1 Motivation

If you have a digital camera, you probably have a large amount of JPEG files that you would like to publish as a photo album on a CD-R or on the World Wide Web.

Simply copying the image files is not adequate. Transferring and decompressing a high-resolution JPEG image can consume several seconds, and the images might not even fit in the screen at full resolution. It would be more convenient to preview the files at a lower resolution.

Another possible problem with a large collection of photographs is that you could forget where a particular image was taken, or what exactly is shown in it. Modern digital cameras usually provide some technical information, such as the time when the image was taken, in the time stamp of the file and in EXIF-formatted JPEG files.

Most file formats for digital pictures offer a possibility to embed textual comments in the files. JPEG is no exception. The documentation or metadata can make a much better browsing experience and enable many possibilities for searching images.

## 2 Optimising image files with `exifiron`

Contemporary digital cameras compress images with the JPEG method and store them in EXIF format, which is JFIF extended with a TIFF-formatted APP0 marker that contains metadata, such as camera settings and a thumbnail image.

It is possible to reduce the size of typical image files by five to ten per cent by removing the thumbnail image and by transforming the image data (DCT coefficients) from baseline JPEG to optimised progressive JPEG. These operations do not lose any information: the bitmap representation of the image is unaffected, and the thumbnail image can be reconstructed from the image data.

The EXIF block contains an Orientation tag that has eight possible values, indicating how the image data has been mirrored or rotated. Most JPEG image tools ignore this information. Thus, in order to avoid compatibility problems with EXIF-ignorant viewers, the image data should be flipped and rotated according to the Orientation information.

Last but not least, the EXIF block contains timestamps that indicate when the photograph was taken. In case the timestamp of the image file in the host file system does not reflect the time when the photograph was taken, the information can be restored from the EXIF block.

The `exifiron` program assists in all these tasks. It corrects the orientation of images—either automatically according to Orientation tags or as instructed by command line switches. It can remove thumbnail images and convert the image data between the baseline and progressive formats.

Typical usage scenarios of `exifiron` are as follows:

`exifiron *.jpg`
  Fully automated operation: shrink and correct the orientation of the files `*.jpg` and set the time stamps from the DateTime tags if available.
`exifiron -r 1.jpg 2.jpg`
  Rotate the files `1.jpg 2.jpg` counterclockwise by 90 degrees. The `-r` and `-R` flags are useful for processing portrait images.

## 3 Writing image comments with `jpegcom`

In JPEG images, textual comments can be embedded in the COM marker. The file may contain multiple such markers.

Not all utilities for creating or viewing JPEG images allow comments to be written. Enter `jpegcom`, a utility that allows you to edit image comments with the help of your favourite image viewer and text editor.

Because `jpegcom` was designed to be as simple and portable as possible, it lacks a graphical user interface. Instead, the tool is invoked from the command line. Typical usage is as follows:

1. invoke `jpegcom *.jpg > control.txt` to produce a template for commenting and renaming or copying the files
2. view the images `*.jpg` and add suitable comments to `control.txt`
3. invoke `jpegcom < control.txt` to embed the comments in the images

For details, please refer to the manual page or read the comments that `jpegcom` writes in the beginning of the control file.

## 4 Creating thumbnails and HTML navigation with `photomolo`

If the images have been divided into subdirectories of no more than a few dozen images, `photomolo` can create an efficient set of HTML documents for navigation. In each subdirectory containing the full-resolution images, `photomolo` creates one subdirectory for each selected thumbnail type. The thumbnail images and and the HTML documents will be written in these directories.

For instance, the command `photomolo -T .8/s8 -T .120/h120 -T .240/h240 images` traverses the directory tree `images` and creates three types of thumbnail images: shrunk to an eighth of the original resolution (in subdirectories named `.8`), or to 120 or 240 pixels of vertical resolution (`.120` and `.240`). You probably want to create a file `images/index.html` that links to `images/.8/index.html`, `images/.120/index.html`, and `images/.240/index.html`.

For future reference, you may want to write the `photomolo` command in a shell script or a batch file. Subsequent runs of the command will be much faster, since thumbnail images will only be generated if they do not exist or the timestamps do not match.

For more information, please refer to the manual page or invoke `photomolo -h`.

## 5 Frequently Asked Questions

### 5.1 Why yet another image gallery program?

There are many programs that generate HTML for browsing digital photographs. `photomolo` was written, because its author was unsatisfied with the existing software. The following design goals were set:

Small size
  Existing packages written in Perl, PHP, Python, Java or other languages depend on many libraries and programs that might not be installed everywhere. Does a simple utility really require several megabytes of software?
Compliance to standards
  The output produced by the tool must be valid HTML and CSS. It must work both with present and with future browsers, so that the output can be recorded on permanent media, such as CD-R.
Portability
  The software must be written in a standardised language (C, ISO 9899:1999) for a standardised run-time environment (POSIX, IEEE Std 1003.1-2001), so that it can easily be ported to contemporary and future computer systems. Small size and independence of large software packages helps here.
  - `jpegcom` does not depend on any external libraries.
  - `exifiron` and `photomolo` depend on the portable `libjpeg` library from the IJG.

### 5.2 Why is there no graphical user interface?

Graphical interfaces have not been standardised. If a graphical interface was developed, it would have to be adapted and tested on each of the currently available systems, and it might not work on future systems.

Also, a textual interface can be more powerful and flexible, since text files can be processed and generated with a large variety of programs and programming languages.

### 5.3 Where can I obtain the software?

The primary distribution site is http://www.funet.fi/pub/sci/graphics/packages/photomolo/.

The programs are freely available under the conditions of the GNU General Public License as C source code for all platforms and as executables for Microsoft Win32.