STM - A high dynamic range image processing toolkit.

Lewes Castle


STM is a modular High dynamic range image processing toolkit, mostly written in C++. It supports a variety of tone mapping operators, and has a plugin architecture to make it easy to extend with more algorithms, file formats and special effects.

The main purposes of the project are as follows:

At the moment STM only exists as a command line utility.



The essential idea of STM is to connect together simple image processing operations into a tone mapping "pipeline". This is defined by a "configuration file".

A simple pipeline that takes a high dynamic range image and converts it into something suitable for display might look like this:

A simple pipeline that compresses dynamic range can br found in the file simple.cfg

Simple dynamic range compression is sufficient for a lot of scenes, but it does result in a loss of local contrast and detail. One way to get details back is to use "local" tone mapping techniques. These derive a "local adaptation" image from the brightness channel of the source image, and use that to modify the result. A simple example of this can be found in the file local.cfg.


STM employs a modular plugin architecture, which allows new file formats and image processing algorithms to be added and removed on demand. In general these can be divided into 4 types:

A list of modules can be found here.

Configuration files.

An STM configuration file specifies a set of actions to be performed on an image. Each process may take the results of another process as its input, and in turn pass its output to other processes. An STM configuration file describes what these processes are and how they are connected together.

Getting started:

Download source:

The source is currently available in a Mercurial repository, located here. To download an up to date copy type:
$ hg clone
For further updates type:
$ hg pull
$ hg update

If you don't have mercurial, or have problems then the latest version may be found here.


The current version requires cmake to build. In order to compile on linux type cmake -f CMakeLists.txt, followed by make. You will need libtiff, libpng and openexr to be installed on linux. The windows port is currently unfinished, and lacks support for most of the file formats handled by linux. This situation should improve soon.

The stm executables will be placed in the subdirectory dist/, and libraries in . The environment variables LD_LIBRARY_PATH and STM_MODULE_PATH should point at the dist/lib/ directory. On OS-X the variable DYLD_LIBRARY_PATH should be set instead of LD_LIBRARY_PATH. A small utility script is included to set paths for testing.


To process an image the tonemap executable is used:

~/stm/dist/$ . set_path
~/stm/dist/$ ./tonemap -i foo.tif -o bar.png -c simple.cfg -t 1

This command loads the image foo.tif, applies the commands defined in simple.cfg and saves the result in bar.png. The -t argument specifies the number of worker threads available for parallel processing. By default it will use as many threads as there are available processors or cores.

Code Documentation

Doxygen documentation can be found here.

Future work:


As of 12 Jan 2012 the following tasks are ongoing:


The following tasks are considered high priority, but have not yet been started:


dave at spectral 3d dot co dot uk
Last updated 12 Jan 2012