STM - A high dynamic range image processing toolkit.
Lewes Castle
Introduction:
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:
- Serve as a test bed for HDR algorithm development & evaluation.
- Allow construction of complex effects by combining simple components.
- Perform batch processing of HDR images, e.g. HDR webcam output.
- Produce a library & plugins suitable for use in other software.
At the moment STM only exists as a command line utility.
Architecture:
Basics
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.
Modules:
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:
- Loaders - load image files into the system.
- Savers - save image files.
- Processors - take one or more images as input, and create a new image.
- Generators - Generate an image to use as input for a processor.
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 http://www.spectral3d.co.uk/repo/stm
For further updates type:
$ hg pull http://www.spectral3d.co.uk/repo/stm
$ hg update
If you don't have mercurial, or have problems then the latest version may be
found here.
Build:
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.
Run:
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:
Ongoing:
As of 12 Jan 2012 the following tasks are ongoing:
- Improve large image support.
- Improve code commenting and documentation.
- Explore design of new HDR generation utility.
Future:
The following tasks are considered high priority, but have not yet been started:
- Develop HDR merge with clean ghost removal.
- Create multi grid equation solver for 2D poisson equation.
- Attempt to develop robust image alignment, or fall back on
align_image_stack
- Attempt to implement automatic "hero image" selection for saturated & dark
image regions without reintroducing ghosting artifacts.
- Work toward making STM more suitable to use in GUI app.
- Improve progress reporting, and make job cancellation easier.
- Add streaming processing mode for instant feedback with fast algorithms,
and port across some of the global operators.
- Add metadata/EXIF support.
- Begin work on a proper graphical application.
- Clean up colour space utilities, add adobe and other colour spaces.
- Improve TIFF support.
- Implement, improve or invent new algorithms.
Contact:
dave at spectral 3d dot co dot uk
Last updated 12 Jan 2012