STM Toolkit ----------- David Beynon (dave@spectral3d.co.uk) Introduction ------------ STM is a toolkit for working with high dynamic range images. It provides a number of common "tone mapping" operators, as well as a number of artistic effects and utility functions. STM is based around the idea of constructing image processing pipelines from small constituent parts. This has the disadvantage that it is difficult to get immediate results, but on the other hand it should be possible to achieve a great deal of control. STM is released as free software under the BSD license (see license.txt), and may be used for commercial or non commercial purposes under the terms of the license. Building -------- The current version is 0.5.0 Current versions of STM should build on both linux and macos-x platforms. The following libraries and utilities must be installed: - cmake, for the build system. - ilmbase and openexr, for exr image support. http://www.openexr.com/ - libpng, for png image support. http://www.openexr.com/ - libtiff, for hdr tiff loading. http://www.libtiff.org/ To get the latest version of the source code then you should install the "mercurial" source control system (http://www.selenic.com/) and type: hg clone http://www.spectral3d.co.uk/repo/stm To build on linux or mac type: cmake -f CMakeLists.txt make The build process will create a sub directory dist/ which will contain the executables "tonemap" and "test_module", a sub directory called "scripts/" containing number of files with a "cfg" extension, a file called "set_path" and a sub directory "lib/". The "set_path" file contains instructions to set environment variables to inform the executables of the location of the lib/ directory. For a "proper" installation this would be set up in the standard .profile and the libraries would reside in one of the standard locations. To test the build enter the dist directory and type the following: source path ./test_module compressor You should see something like the following: davidb@mirage:~/Projects/stm/dist$ ./test_module compressor attempting to load library /home/davidb/Projects/stm/dist/lib//libcompressor.so Loaded module compressor *** FILE LOADERS *** *** FILE SAVERS *** *** PROCESSORS *** Processor "Simple dynamic range compression." (compressor) Output: xyY Inputs (mandatory): 0: xyY, Inputs (optional): 1: Luminance, Parameters: min luminance: float = 1e-05 (1e-05,1e+20) max luminance: float = 1e+10 (1e-05,1e+10) discard dark: int = 5 (0,50) discard bright: int = 5 (0,50) contrast: float = 1 (0,20) gamma: float = 0.6 (0,20) compression function: enum = [2,gamma]([0,ashikhmin], [1,logarithmic], [2,gamma], [3,linear], ) normalise: boolean = true The information about inputs, outputs and parameters is necessary for setting up the config files described below. Running the software -------------------- The standard interface to STM is currently the command line tool "tonemap". This executable accepts the following arguments: tonemap -c [config] -i [input] -o [output] -t [threads] input and output are the file names of the images to be loaded and saved. Supported input types include "exr", "tiff" (floating point and logluv only) and png. Output types include "exr" and "png". The config argument refers to the name of an STM config file, which defines the process to be run. The "threads" argument specifies how many worker threads may be used by those processing modules which support parallel processing. The default value is 1. The command: ./tonemap -c simple.cfg -i AtriumNight.exr -o Atrium.png -t 4 will load the file "AtriumNight.exr", perform a simple tone mapping operation and write the file "Atrium.png". It will make use of 4 worker threads, which is probably a reasonable choice for a quad core machine. Config files ------------ An STM process consists of a number of processing modules which are connected together. Each module takes one or more images as input, and creates an image which is passed on for further processing. The software works out which order to perform the processing in. Each processing module lives in a numbered slot. The input image always goes in slot 0. The config file has 4 sections, labelled as PROCESSORS, DEPENDENCIES, PARAMETERS and OUTPUT. They must always be defined in this order. The PROCESSORS block describes which processors are to be loaded in which slots. # first load processors. Lines starting with # are comments. PROCESSORS: 1 = "photographic" 2 = "coltolum" # extract brightness channel. 3 = "mlfilter" # blur the brightness channel. This loads 3 processing modules into slots 1, 2 and 3. "photographic" is a tone mapping module which takes a high dynamic range image and an optional "local adaptation luminance" channel to increase contrast. "coltolum" converts a colour channel into a luminance channel, and "mlfilter" performs blurring on a luminance channel. The next section of the file looks like this: # Now add dependencies DEPENDENCIES: 1:0 <- 0 # slot 0 is populated by src 1:1 <- 3 # Take blurred luminance channel. 2:0 <- 0 # image -> luminance 3:0 <- 2 # luminance -> local adaptation This sets up a set of connections like this. source_image------------>------------\ \ \ \-->coltolum--->mlfilter--->photographic the executable will now perform the following operations. - load the image - run "coltolum" to extract a luminance channel. - run "mlfilter" to blur this channel. - feed the results of "mlfilter" and the source image into the "photographic" module. the next section, PARAMETERS, allows customisation of settings on the various modules. # Now set parameters PARAMETERS: # Set up compressor 1:"key" = 0.18 1:"contrast" = 1.3 # slightly enhanced contrast #set up filtering 3:"number of layers" = 4 # number of layers to blend together. 3:"tolerance" = 0.3 # Edge detection tolerance (turn down to stop halos) The final section is the "OUTPUT". It simply specifies which module should be treated as the last stage of the process and have its image saved. In this case we want the results of the "photographic" processor, so we use: OUTPUT: 1 Module list ----------- Dynamic range compression/tone mapping: - compressor : Various dynamic range compression functions. - logmap : Dragos "adaptive logarithmic" tone mapping. - photographic : Rheinhards photographic operator. - photoreceptor : Rheinhard and Devlins global operator. - filmic : "Filmic" film like compression. Tools for dealing with luminance channels: - coltolum : Converts a colour image to a luminance channel. This is a necessary first step for most local algorithms. - lummixer : Blends two luminance channels. - replacelum : Replaces a luminance channel. - contrast : Enhance local contrast of an HDR image without remapping. dynamic range. - smartcontrast : Enhance local contrast while avoiding gradient reversal artifacts. Tools to create Local Adaptation channels for local tone mapping. - mlfilter : Creates a local adaptation luminance image by blurring. - segment : Creates a local adaptation luminance image by segmentation. - bilateral : Creates a local adaptation luminance image by bilateral filtering. - mc_bilateral : Creates a local adaptation luminance image using a monte carlo approximation to a bilateral filter. - global : An infinite bilateral filter. Colour utilities: - chroma : Remove chroma noise from an image. Current implementation is very slow. - cropimage : Crop a colour image. - whitepoint : White balance modification. Artistic effects: - convolve_mono : Convolve image with a monochrome filter image. - motion_blur : Draw a line, which can be used as an input to convolve_mono. - rays : Draw a star, which can be used to create a star filter/lens flare effect in conjunction with the convolve_mono module. - lines : Streamline/contour scribbling module based on a bug in flic. File managagement: - exrloader : Load an OpenEXR image. - exrsaver : Save an OpenEXR image. - hdrloader : Load a Radiance HDR image. - pngloader : load a png file. - pngsaver : Save a png file. - pfmloader : load a pfm file. - pfmsaver : Save a pfm file. - tiffloader : Load an HDR tiff image. Does not currently handle LDR files. Experimantal/unfinished: - flic : Experimental line integral convolution module. Useful numbers -------------- CIE illuminant white points - handy in the whitepoint processor: D65 (noon daylight, sRGB) : <0.3127, 0.3290> D55 (cloudy daylight) : <0.3324, 0.3474> D50 (bright tungsten) : <0.3457, 0.3585> CIE A (tungsten) : <0.4476, 0.4074> CIE B (sunlight) : <0.3484, 0.3516> F1 (daylight fluorescent) : <0.3131, 0.3373> F2 (cool white fluorescent) : <0.3721, 0.3753> F3 (white fluorescent) : <0.4091, 0.3943> F4 (warm fluorescent) : <0.4402, 0.4033>