Published On : 30 November 2018 |Last Updated : 11 March 2021 |7628 words|32.9 min read|14 Comments|

## #Abstract↑

darktable is an open-source software for raw photographs management and processing developped since 2009 for Linux desktops. Since then, it has been ported on Mac OS and Windows 7, 8, 10. After having used it for 7 years, I begun to develop in it 3 months ago. This article shows my work and results to improve the HDR-scenes handling in darktable, in a fashion that allows better color preservation for portrait photography.

The beginning of this article is mostly directed toward a general audience, until the section Controls, which provides a complete manual showing how to use the new filmic module. The next sections are mostly directed at scientists and technical audience.

[WARNING : DRAFT - WIP]

## #About HDR and dynamic range↑

Even though HDR is a big thing right now in the LED screen industry, and this term is wildly used to describe anything for marketing purposes, it is useful to recall what it is. The dynamic range is the interval of measurement between the sensor detection level (ground level) and its saturation level (ceiling level). Generalized to the eye and translated into human perception, it is the range of lightness between what is seen as pure black (no lightness) and what is seen as pure white (blinding lightness). For optical applications, this bounded range can be expressed in terms of 2-based logarithmic intervals, the exposure values (EV), also called stops in the photographic industry, that are believed to be evenly spaced in human vision.

While the dynamic range of the average human eye is estimated between 22 to 24 EV, consumers displays reach roughly 10 EV, and 8 bits JPEG files can, by design, encode no more than 8 EV. This has quickely become a problem with high-end DSLR reaching now almost 15 EV (Nikon D7200, D750, D810, D850, Sony A7 , A7 RIII, Hasselblad X1D, Pentax K1, 645z).

Although “HDR” in photography has often the meaning of multi-exposure stacking and tone mapping technic (to compensate for the low dynamic range of now outdated cameras), an high dynamic range can be generally defined as any source dynamic range that is higher than the dynamic range of the destination medium. That triggers the need to remap the input dynamic range to the output one in a fashion that prevents clipping and retain as much details as possible. This is a technical challenge, leading to some trade-offs, and can be done in two different (and perhaps combined) ways : [ref]Tone mapping, Yung-Yu Chouang, www.csie.ntu.edu.tw/~cyy/courses/vfx/10spring/lectures/handouts/lec04_tonemapping_4up.pdf[/ref]

1. with local tone mapping, using local contrast preservation algorithms, often resulting in halos and unrealistic pictures,
2. with global tone mapping, aiming at photographic tone reproduction, derived from Ansel Adam’s classic zone system, using global transfer functions, often resulting in color issues and local contrast compression.

darktable has 3 modules implementing such transformations (tonemapping, global tonemapping and base curve) but their problem is they come too soon in the pixel pipe (which has a fixed order of filter application), some before the input color profile, some others working in Lab color space, introducing non-linearities in the RGB signal that often make the colour editing tedious and unpredictable.

## #About darktable’s filmic module↑

The new Filmic module is a photographic tone reproduction filter aimed at reproducing the color and luminance response of analog film, dealing with dynamic range issues and gamut clipping issues (oversaturation in deep shadows and highlights). It derivates from the filmic module introduced into Blender by Troy James Sobotka, but differs in some aspects of the implementation and adds more features. The whole idea of tonemapping/dynamic range scaling implies that trade-offs have to be made to overcome the dynamic range shrinking. The choice that has been done here is to degrade the photography in a visually-pleasing way because traditionnal film has already shaped our visual aesthetics.

It works in three steps :

1. apply a parametric logarithmic shaper, used to rescale the RGB values in a perceptually uniform space,
2. create an “S” filmic tone curve to bring back the contrast and remap the logarithmic grey value to the display target value,
3. do a selective desaturation on extreme luminance values, to push the colors to pure black and pure white.

By design, it will compress the dynamic range and the gamut (by reducing the saturation in bright and dark areas) in a way that preserves the mid-tones and compresses more aggressively the extreme luminances. This is especially useful when doing portrait photography, where skin tones are usually close to the middle grey, but is will need an extra care in landscape photography, especially for sunset pictures where the sun is in the frame background.

The filmic curve it produces simulates the tone response of classic film, with a linear part in the middle (called the latitude), and curved parts at the extremities (a toe and a shoulder). This kind of curve is similar to the presets applied by cameras manufacturers in their in-camera JPEG processors, and that can be found in the base curve module of darktable. However, these curves are applied too soon in darktable’s pipe and are not parametric. Filmic will essentially fulfill the same needs with some additional sweeteners and more configuration

### #Place in the workflow↑

Most users will need to reconsider their workflow to fully take advantage of filmic.This module should be enabled after :

1. the white balance module, in order to work on balanced RGB ratios,
2. the exposure module, if needed, to recover as much dynamic range as possible in a linear way,
3. the demosaicing module, using high quality algorithms with color smoothing, to avoid artifacs in low-lights that could perturbate the auto-tuner of filmic (especially the black exposure).

Proper exposure settings can be checked prior to filmic use, using the global color picker Lab readings, and are achieved when :

1. no pixel has a luminance higher than 100 % (no clipping)
2. no pixel has a luminance lower than 0 % (as much as possible, that is not always possible)
3. white skins have an average luminance of 65-85 % in Lab space
4. black skins have an average luminance of 25-45 % in Lab space
5. tanned skins have an average luminance of 45-65 % in Lab space
6. non-human subjects have an average luminance around 50 % in Lab space (excepted deliberate use of low-key or high-key)

Color corrections should come after this module for better readability of the colors. This module can replace base curves, tone curves (to some extent), unbreak color profile, global tonemapping and shadows-highlights modules. It is not recommended to use it in combination with base curves, unbreak color profile and global tonemapping.

### #Use cases↑

#### #Samples↑

1. the classic darktable edit makes use of the Sony-like base curve and the tonemapping module (defaults parameters),
2. the default filmic output makes use of the filmic module only with default parameters, then grey sets at 1.28 % and latitude sets at 6.50 EV (settings as shown in the above screenshot),
3. the filmic variant 1 enables the chroma preservation in filmic and decrease the extreme saturation to 20 %.,
4. the filmic variant 2 is similar to the variant 1, with saturation decreased at 75 % in the color balance module,
5. the filmic variant 3 is similar to the variant 2, with a parametric mask excluding the highlights (feathering radius : 250, blur radius : 100, key luminance : 50, feathering guide : output image).

This shot was taken in July at around 2 p.m., under trees. The color recovery is quite challenging since there is direct sun light as well as green light reflected by the foliage and the grass, so the camera adjusted the white balance to revert the green cast by shifting the tint, making the direct sunlight look magenta. The white balance used here is the one set by the camera.

1. the classic darktable edit makes use of the Nikon-like alternate base curve and the tonemapping module (defaults parameters),
2. the default filmic output makes use of the filmic module only with default parameters and grey sets at 2.87 % and latitude at 6.14 EV,
3. the variant 1 enables the chroma preservation in filmic, with saturation set at 15 % in filmic and the saturation set at 65 % in the color balance module
4. the variant 2 is is the same as the previous but with the grey value adjusted to get a more natural skin tone (2.44 %), saturation at 12 %, latitude at 7 EV, and further editing in the color balance module, to remove the green color cast from the light reflected by the foliage and the grass.
5. the variant 3 derivates from the previous, increases the contrast at 1.555, reduces the latitude to 6.10 EV, the saturation to 10 %, and uses an extra RGB S curve in the tone curve module.

Note : you can download the JPEG files and import the darktable settings directly from their embedded XMP tags as if they were XMP sidecar files.

#### #Analyse↑

The sunset picture shows the advantages and the limits of the filmic module : while the local contrast is better preserved in shadows, with improved sharpness compared to the tone mapping version, the highlights get more compressed and heavily desaturated without the chroma preservation. There are several ways to overcome this issue :

• increase the saturation parameter above 100 %,
• use a parametric mask to exclude partially or totally the highlights.

The desaturation, while expected and desirable, is excessive in highlights with the default parameters. This can be compensated by adding more saturation in another module, color balance for example, or by using the chrominance preservation option in filmic (see below). In this case however, the problem is reverted and the saturation becomes excessive, so it needs to be dampened instead.

The chrominance preservation keeps more saturated colors, all over the dynamic range. Despite its goal to retain the original RGB ratios (relatively to the luminance), and therefore avoid hue shifting, the very bright areas of the sky shift nonetheless from orange to pink. The causes of this shift will be analysed in the section Discussion.

The second picture shows clearly the benefit of the filmic approach in portrait photography. The grey level is the key to get the right skin tone. The selective desaturation in highlights prevents the skin patch exposed to the direct sunlight from becoming either magenta or yellow, and the magenta highlights of the red dress shown in the classic darktable edit are avoided.

### #Comparison with other darktable’s tonemapping methods↑

#### #Samples↑

The method for the local contrast and base curve is taken from Johannes Hanika[ref]Local laplacian pyramid, J. Hanika. (2017). www.darktable.org/2017/11/local-laplacian-pyramids/[/ref]. The color of the dress is vivid red (not magenta).

#### #Analyse↑

##### #Luminance mapping↑

In terms of tonemapping, the only good results are given by the base curve (6) using the exposure fusion, the filmic module (7, 8) and the tone curve in RGB (9).

The tone curve approach (9) is a naive transfer function roughly similar to a logarithm (see curve displayed next). Although it gives a rather good tone mapping from afar, it does not retain well the local contrast in shadows. This is the very reason why most tonemapping algorithms use spatial filters to retain the high frequencies. This method also has the drawback of being fastidious to set, from the position of nodes. It is roughly similar to the filmic without chroma preservation (8), except for the lowlights.

The base curve with exposure fusion (6) gives a result very similar to the filmic module with chroma (7), but with more contrast in shadows due to the Nikon-like alternate curve having a toe in low-lights. However, since this module is at the beginning of the pixel pipe, it turns the raw RGB space into display-referred (non-linear) space too early, making further color edits more unpredictable. To get results similar to the base curve, with filmic, one should add an extra tone curve to get more contrast. However, the main drawback of the exposure fusion, that is not shown here, is the creation of halos along sharp contrasted edges, induced by the gaussian mask used for the fusion.

The filmic approach with chroma preservation (7) gives a slightly darker result than filmic without the chroma preservation (8), due to the extra-saturation that also affects human lightness perception. With chroma preservation, the saturation adjustment can be a bit tedious to set since there is no accurate model to generally remap the saturation according to the tonemapping intensity (see section Discussion).

## #Discussion↑

[WIP]

One major problem of tonemapping is the conservation of colors. The sub-problem remains yet to decide wether it is the photographic colors that should be preserved (as recorded or percieved on the scene), or the perceptual colors (as displayed on the output medium), which depend on the percieved luminance and various other parameters, depending on the color model used.

Mantiuk and al. (2009)

[ref]Color Correction for Tone Mapping, R. Mantiuk, A. Tomaszewska, W. Heidrich. (2009) www.cl.cam.ac.uk/~rkm38/pdfs/mantiuk09cctm.pdf[/ref]

conducted a study on saturation correction in tonemapping algorithms where they tried to use several color models (CIE LAB, CIE CAM02 and CIE LUV) to predict the color deviation happening during tonemapping. They found that none of these so-called “perceptual” non-linear color models were able to provide accurate prediction of color shifts, and that the actual perceptual color shifts were themselves non-linear when measured in these color spaces. They also tried to perform the tonemapping in CIE LAB space and got an oscillatory saturation shift. If that is so, it would mean that perceptual color models are flawed from their very premisses. Let us recall that ad-hoc empirical models are to be fitted against some datasets, in a descriptive manner, and then evaluated by their ability to provide accurate predictions against different datasets. From Mantiuk’s results, the quality of these models is subject to caution. However, Mantiuk conducted his study on a sample of 4 to 8 people aged from 23 to 38, so my guess is he recruted his students and fellow faculty members in the break room, which would be neither a significative nor an unbiased sample. However, Mantiuk has pointed out that the goal of the tonemapping algorithms he reviewed was to retain the photographic colors, in which the perceptual metrics provided in non-linear spaces are unefficient and inadequate.

## #Acknowledgements↑

I would like to thank Troy James Sobotka, who has been a great help and took a lot of his time to answer my questions during the development of this module. I thank Johannes Hanika, one-guy coding army who still takes time to answer every question after having developped darktable for 10 years,  Andreas Schneider/Cryptomilk and Mika/Paperdigits who proof-read the draft that led to this article, Nicolas Tissot and Andreas Schneider again for some of the raw pictures shown here, Minh-Ly who is kind enough to suffer me and has been providing her skin tones to test my algorithms for more than 2 years, the darktable.fr community, Andy Costanza and Luc Viatour, who have supported me during this project, Rawfiner, who has been a great help to get me started with the C language, Pascal Obry, who reviewed and merged my code week after week, Mathieu Moy, who spotted tricky bugs and mistakes, and finally Jean-Paul Gauche and Philippe Weyland, who are always the annoying and necessarly first ones to test and report things that don’t work, and whose suggestions have led to substantial improvements.

Permission is hereby granted to copy and translate the content, including text, calculations and pictures, of this article for educational purposes.

1. Raymond D. 07/12/2018 at 11:10 AM - Reply

Et léger renflement du melon ?

• Aurélien 09/12/2018 at 2:52 PM - Reply

La prochaine fois que tu comptes spammer, imbécile, n’utilise pas le réseau de ton employeur (Thales Vélizy-Villacoublay). Maintenant, tout le monde sait qu’il y a un photographe frustré (et sans couilles) chez Thales qui utilise ses heures de bureaux pour dire de la merde en usurpant l’email pro de Raymond Depardon et de Chelsea Jacob, de chez Magnum photo. Tu veux qu’on joue à savoir ce que ta DRH en pense ?

2. Nicolas 16/12/2018 at 5:45 PM - Reply

Extrêmement informatif tout cela !
Maintenant, je sais ce que mon HDR en pense !
Bravo pour ces analyses, content de savoir que cette merveille existe sous Linux.

Bien à vous,
NV

3. Agustín 17/12/2018 at 7:56 AM - Reply

Thank you Aurélien for your great module and very detailed documentation !
I think it’s going to be a great time saver for my DT edits.
Would you happen to have simple recommendations for the color balance module also ?

Thanks again for sharing your hard work !!

4. François 26/12/2018 at 8:45 AM - Reply

Très joli jouet pour Noël, merci :) Je n’ai hélas sûrement pas les connaissances théoriques qui me seraient bien utiles pour mieux comprendre tout ce qui se passe, mais force est de constater qu’en lisant cette article rapidement une première fois et en jouant avec le module sur quelques photos un peu difficiles, j’arrive rapidement à obtenir un résultat bien plus plaisant et naturel qu’avec le mappage de tonalité ou les autres modules. Une arme de plus à l’arsenal de Darktable !

5. Sergio 30/12/2018 at 6:00 AM - Reply

Cannot reproduce the same curves of “Proper Settings” for the portrait cases, at least with darktable 2.6. Are you sure they are correct ?

• Aurélien 02/03/2019 at 5:44 PM - Reply

The curves display has been tweaked, in current software version, to show the curve in a way that always put the grey level in the center of the graph. But it’s just a readability improvement, the actual parameters don’t change. I guess I will have to update the screenshots.

6. yawfle 20/01/2019 at 1:03 AM - Reply

Thanks for the write-up. It looks like you have two “variant 3” in the sunset example and no “variant 2”.

• Aurélien 02/03/2019 at 5:42 PM - Reply

Thanks ! Indeed, I have to finish and correct that post. But there is still ongoing work on filmic v3 for now…

7. Sébastien 22/01/2019 at 4:19 AM - Reply

Ca en fait de la lecture ! Entre ce qui est proposé sur le site de Darktable et le tien il y a matière pour bien comprendre ce module ; un grand merci donc. J’ai commencé à passer un peu de temps avec ce module, il a l’air très, très intéressant, il semble proposer des réglages vraiment fins et c’est très appréciable.

Merci beaucoup.

8. Normand Fortier 31/01/2019 at 1:21 PM - Reply

Under “Place in the workflow” : “Proper exposure settings can be checked prior to filmic use, using the global color picker Lab readings”. Unfortunately I don’t think you can use the global color picker for that, as it measures values after conversion of the image to the display (monitor) color profile — see DT manual, section 3.3.4 : “The global color picker works in monitor color space and takes samples after the complete pixelpipe has been processed.”
https://www.darktable.org/usermanual/en/global_color_picker.html
I started a recent thread on this topic :
https://www.mail-archive.com/darktable-user@lists.darktable.org/msg06969.html
If you take a look you’ll see I am not the only one wondering about the implications of this, since it seems to affect the main histogram as well. An informed opinion from someone more knowledgeable than us would be greatly appreciated !

• Aurélien 02/03/2019 at 5:41 PM - Reply

That’s true, the global color picker was in display RGB space. While this was not super accurate, it still gave you a rough idea of what’s going on, as long as you don’t take the value for truth.

But this issue has been solved 2 weeks ago in darktable master, which allows you now to select the color space in which you want to see the histogram. This will come in darktable 2.8, possibly before in a 2.6.x minor update if it proves to be stable enough.

9. JacoTux 08/03/2019 at 5:06 PM - Reply

Bonjour,

Merci pour cet excellent module.

Dans les consignes d’utilisation de la saturation aux valeurs usuelles il est dit :
“more than 100 % with cancel the desaturation but not actually add more saturation”
Sans désaturation mais sans ajouter de saturation… c’est sous entendu par le biais du module “balance couleur” ?

10. Marco Giai-Coletti 15/03/2019 at 4:23 PM - Reply

Thank you for the Filmic module - you are a legend. It has made editing so easy and the results are unsurpassed. I use it with the zones module and I can achieve an amazing transition from highlights to shadows.

This site uses Akismet to reduce spam. Learn how your comment data is processed.