photomolo, jpegcom, exifiron and jpegnail release notes

photomolo 1.2.4
generate thumbnails and HTML navigation for a collection of digital photographs in JPEG format
jpegcom 1.2.2
read or write the comments of JPEG images
exifiron 1.2.4
orientation correction and optimization of EXIF JPEG images
jpegnail 1.2.4
removal and insertion of thumbnail images in EXIF and JFIF images

Table of Contents

1 Motivation
2 Optimising image files with exifiron
3 Removing and embedding thumbnail images with jpegnail
4 Writing image comments with jpegcom
5 Creating thumbnails and HTML navigation with photomolo
6 Frequently Asked Questions
6.1 Why yet another image gallery program?
6.2 Why is there no graphical user interface?
6.3 Why only JPEG files are supported?
6.4 Where can I obtain the software?
7 Acknowledgements
7.1 Copyright information
7.2 Contributors
8 Version History

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 contains a TIFF-formatted APP1 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, e.g., with jpegnail.

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 and add 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 Removing and embedding thumbnail images with jpegnail

Some graphical file browsers can display embedded thumbnail images as image file icons. If no thumbnail is available, either no meaningful icon will be shown, or one has to be generated and stored somewhere, separately from the image file. It could be more practical to include a reasonably-sized thumbnail image with the image file itself. Digital cameras usually generate thumbnails of 160×120 pixels in size, while the file browser could benefit from slightly bigger icon sizes.

The jpegnail utility can remove most common variants of embedded thumbnail images in JFIF and EXIF image files. It can embed JPEG compressed thumbnail images in both types of files, with user defined resolution and compression quality. It has been tested with the Mac OS X Finder, which makes use of thumbnail images embedded in EXIF but not JFIF files. Note that unlike exifiron, jpegnail may corrupt malformed EXIF records further if they do not end in the thumbnail image data.

The desired size of the thumbnail images can be specified in three ways: as a bounding box, giving the maximum image width (-x) and height (-y), or as a fixed height or width, in which case the width or height will be varied according to the aspect ratio of the full image. By default, both parameters are zero, meaning that any existing thumbnails will be removed from the image files.

The scaling algorithm is linear interpolation, adapted from the pnmscale tool. You may obtain sharper images by using one of the filters implemented in ImageMagick.

4 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

The jpegcom tool can also be combined with GNU Recode in order to convert the comments of image files to another character set: jpegcom *.jpg | recode iso-8859-1..utf-8 | jpegcom. The command works if the character sets are supersets of IA5, also known as ASCII, and the image file names are not affected by the translation.

For details, please refer to the manual page or read the comments that jpegcom writes when you invoke it on a single image file.

5 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 -l /original images traverses the directory tree /original/images and creates the directory tree images with 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.

Since version 1.2, photomolo creates links to all files, not only images. Since version 1.2.4, the links are generated also for the files in the top-level directory.

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.

Since version 1.2.4, photomolo can invoke an external program for converting images to JPEG format. Please see the examples directory for conversion scripts for use with the -J option.

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

6 Frequently Asked Questions

6.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 may be difficult to install and configure. Does accomplishing a simple task 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 archived on permanent media, such as CD-R.
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.

6.2 Why is there no graphical user interface?

Graphical interfaces have not been standardised. If a graphical interface were 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 than a graphical one, since text files can be processed and generated with a large variety of programs and programming languages.

Some applications implement a graphical user interface in a client/server architecture, e.g., by combining an HTML browser and a HTTP server. One example is Gallery, whose functionality is similar to that of photomolo. However, a utility that relies that some server software is run in parallel with a browser, requires that a server is always installed and reachable, which can be problematic.

6.3 Why only JPEG files are supported?

The main reasons why photomolo does not support other image file formats, such as PNG or TIFF is the problem of representing the thumbnail images. For many bitmap image formats, there are more options than for JPEG. It may be difficult to select an efficient set of parameters for storing the thumbnail images.

JFIF is one of the most widely supported image file formats in browsers. Should the thumbnails of a TIFF picture be TIFF, or perhaps JFIF, to ensure that most browsers can display the thumbnail image? If JFIF is chosen, how should the thumbnail be named? In applications that recognise files by their names, a JFIF file file.tif would cause problems. Then again, file.jpg is not safe either, since there could exist both file.tif and file.jpg in the same directory.

Thumbnail images can also be generated for other than image files, such as title pages of PDF documents. Such functionality is best implemented in a scripting language that can make use of existing software packages. The main design goal of photomolo is to be compact and efficient for one type of images.

6.4 Where can I obtain the software?

The primary distribution site is

The programs and this document 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.

7 Acknowledgements

The utilities in the photomolo package were written from the scratch by Marko Mäkelä in 2003.

With the exception of jpegcom, the tools read and write JPEG images using libjpeg from the IJG.

The algorithm for scaling images has been adapted from pnmscale by Jef Poskanzer.

7.1 Copyright information

The algorithms in exifiron for lossless JPEG image transformations have been adapted from jpegtran of the IJG, written by Thomas G. Lane and Guido Vollbeding.

The following statement applies to all utilities in the photomolo package:

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.

7.2 Contributors

Martin Schneider tested versions 1.0 and 1.1 on Win32.

Thomas Kaiser created a Mac OS X installer package. He made many suggestions regarding the exifiron tool, and provided me with sample images from Adobe Photoshop, making it possible to implement the colour space transformations in version 1.2.

Kwang brought it to my attention that on Win32, the standard library rename() will not rename over the top of existing files. The problem has been addressed in version 1.2.2.

Rob Clevenger reported that exifiron refuses to work with image files that have been downloaded with Apple's Image Capture or iPhoto. Apparently these programs manipulate the EXIF record, introducing inconsistencies such as a duplicate Orientation tag. Also, the Nikon E995 camera seems to allocate data for strings at the end of the EXIF record, making it hard to remove the embedded thumbnail. These problems have been addressed in version 1.2.2.

Axel Rose pointed out that thumbnail images can be larger than the original image. Since version 1.2.3, the thumbnail image size is limited to be at most the size of the original image.

Yann Borg reported that exifiron refuses to work with image files from Canon EOS 350D (firmware 1.0.2 from May 2005). Version 1.2.3 implements work-arounds for the erroneous Exif data produced by this camera.

Thomas Kaiser submitted two feature requests for version 1.2.4: a progress indicator for exifiron, jpegnail, and photomolo, and the ability for photomolo to invoke an external program to scale other than JPEG images.

Axel Rose suggested that photomolo should create the browsing directory hierarchy separately from the directory tree containing the full-size original images. This was implemented in version 1.2.4.

8 Version History

February 26, 2003: 1.0
Initial release comprising photomolo and jpegcom
April 10, 2003: 1.0.1
New utility: exifiron
May 1, 2003: 1.1
Improved handling of temporary files
May 3, 2003: 1.1.1
Fix fatal bug in Win32 exifiron.exe and jpegcom.exe: open image files in binary mode
October 10, 2003: 1.2
New utility: jpegnail
Improved scaling and colour space transformations
exifiron: when rotating an image, transpose all X and Y measures in the EXIF data
December 1, 2003: 1.2.1
jpegcom: skip comments properly everywhere
May 10, 2004: 1.2.2
jpegnail, exifiron: fixed bugs in error handling; do not abort on nonfatal errors in the EXIF data, but refuse to touch embedded thumbnail in case of major inconsistencies.
On Win32, temporary files could not always be renamed. Replaced rename() with MoveFileEx() or MoveFile().
July 31, 2005: 1.2.3
jpegnail, exifiron: Fixed bugs in error handling; try to save registers on stack before calling setjmp in order to set up the libjpeg error handler. Added option -n for skipping the computation of optimal Huffman codes.
jpegnail: added option -S for specifying directory containing thumbnail images to be embedded
jpegnail, photomolo: limit the thumbnail image size to the size of the original image
photomolo: improved HTML output and removed non-ASCII characters to make it work with all supersets of ASCII
February 24, 2006: 1.2.4
exifiron, jpegnail, photomolo: Added option -P to indicate progress.
photomolo: Added options -l and -L for creating a separate thumbnail directory tree with links to the full-size original files. Added option -J for invoking an external program to convert files to JPEG format, for computing thumbnail images.

Marko Mäkelä