darktable page lede image
darktable page lede image

3.4.2. Grading group

The grading group contains every module to be used artistically and doing color and tones corrective and creative work (including chromatic adaptation / white balance)

3.4.2.1. split-toning

Overview
darktable's split-toning method creates a two color linear toning effect where the shadows and highlights are represented by two different colors. In the example image below you can see an original black and white image and one where a split-toning effect is applied with blue in shadows and a yellowish color in highlights.

Compared to traditional split-toning our module has more parameters to influence its behavior. We have parameter balance, which offsets the 50% gray level in your image – at your choice – more to the shadows or more to the highlights. Additionally, with parameter compression you can compress toning in the shadows and highlights and leave a gap in the mid-tones, which remain untouched by the effect.

The split-toning module does not convert images to black and white and has limited benefits on color images. So, if you want to do traditional split-toning, use the monochrome module (see Section 3.4.3.6, “Monochrome”) to make the image black and white before playing around with split-toning effect.

Usage
shadows and highlights color

These controls are used to set the color of the split-toning effect, you select the desired color and saturation for both shadows and highlights. Clicking on the colored squares will open a color selector dialog which offers you a choice of commonly used colors, or allows to define a color in RGB color space.

balance

This parameter represents the ratio of toning between shadows and highlights. For a value of 50% half of the lightness range in image is used for shadows toning and the other half for highlights toning.

compression

Compression is a percentage of total lightness range that is not affected by color toning. Default value is set to 33%; this is not the default behavior of an original split-toning which would be 0% compression. The choice of 33% as a default is to invite you experimenting with these parameters and how it extends the original split-toning method.

Examples

Original black and white image.
split-toning with blue shadows and yellow highlights.

3.4.2.2. Colorize

Overview
This module is an artistic feature that adds a solid layer of color to your image.
Usage

Several parameters control the effect of this module. Much more versatility can be reached if you apply blending and masks. (see Section 3.2.5, “Blending”).

hue

Selects the hue of the color layer.

saturation

Selects the color saturation of shadow tones.

lightness

Selects the lightness of the color layer.

source mix

This slider controls how the lightness of the input image is mixed in. If you set this to zero a uniformly colored plane will result.

3.4.2.3. Color zones

Overview
This module selectively modifies the colors in your image. It is highly versatile and allows every transformation possible in the LCh colorspace.
Usage

The horizontal axis represents the range of values you can work on. The vertical axis shows the modifications you can apply by designing a curve. For both horizontal and vertical axes you can work on lightness, saturation or hue.

You can click on any of the eight nodes on the curve and drag to adjust it vertically. A circle indicates how strong adjacent nodes will be affected. Use the scroll wheel of your mouse to change the circle diameter. You can also use the eight controlpoints (triangles which define the vertical value of the nodes) at the bottom to adjust the curve.

A color picker is activated by pressing and will show the picked values in the diagram. You can use an area sampling mode by using Ctrl+Click.

A second color picker can be used to directly change the curve based on the sampled area. A Click on will activate the action picker. Then, on the picture, a Ctrl+Click+Drag will create a positive curve for the sampled area and a Shift+Click+Drag a negative curve.

tabbed controls

You can define curves for each of the three channels lightness, saturation, and hue individually.

edit by area

Control the interaction mode with the curve. When edit by area is selected the nodes' axis coordinates are fixed. This is the default mode up to darktable version 2.6.

mask display

By clicking the pixels affected by the curve are displayed directly on center area.

select by

Defines the horizontal axis, i.e. the range of values you work on. You can choose between lightness, saturation, and hue (default). Changing this parameter resets any defined curve to a straight horizontal line.

process mode

Choose between a smooth (default) or strong processing mode which alter the final effect.

mix

Use this parameter to tune the strength of the overall effect.

interpolation method

The interpolation is the process by which a continuous curve is derived from a few punctual nodes. As this process is never perfect, several methods are offered that can alleviate the potential issues you may encounter with some nodes setups.

Arguably, the most visually pleasing method is the cubic spline. Since it gives smooth curves, the contrast in the image is better enhanced. However, this method is very sensitive to the nodes position, and can produce cusps and oscillations when the nodes are too close to each other, or when there are too many of them. This method works best when there are only 4 to 5 nodes, evenly spaced.

The centripetal spline is a method designed specifically to avoid cusps and oscillations, but as a drawback it will follow the nodes more loosely. It is very robust, no matter the number of nodes and their spacing, but will produce a more faded and dull contrast.

The monotonic spline is a method designed specifically to give a monotonic interpolation, meaning that there will be none of the oscillations the cubic spline may produce. This method is very suitable when you try to build an analytical function from a node interpolation (for example: exponential, logarithm, power, etc.). Such functions are provided as presets. It is a good trade-off between the two aforementioned methods.

3.4.2.4. Vibrance

Overview
Vibrance is a widely used term in image processing but the mechanism and end result differ from program to program. Vibrance in darktable saturates and brings down the lightness of the most saturated pixels to make the colors more vivid.
Usage

Vibrance only has one parameter which controls the amount applied.

vibrance

The amount of vibrance to apply to the image.

3.4.2.5. Velvia

Overview
The velvia module enhances image saturation. Its effect is tailored to increase saturation less on lower saturated pixels than on highly saturated pixels.
Usage
strength

This slider controls the strength of the effect.

mid-tones bias

Velvia can reduce its effect for mid-tones to avoid unnatural skin tones. The mid-tones bias slider controls this selectivity; reducing its value reduces mid-tone protection and makes the overall velvia effect stronger.

3.4.2.6. Color contrast

Overview
The color contrast module provides simplified control for changing the contrast or separation of colors between either green/magenta or blue/yellow axis.
Usage

Higher values increase color contrast, lower values decrease it. The effect of this module's sliders are similar to applying a steepened or flattened a- or b-curve in module tone curve (see Section 3.4.2.13, “Tone curve”).

green vs. magenta

Changes color contrast for green versus magenta.

blue vs. yellow

Changes color contrast for blue versus yellow.

3.4.2.7. Color correction

Overview
This module can be used to modify the global saturation, give a tint to the image or to split tone it.
Usage
color board

For split toning move the white dot to the desired highlight tint and then select a tint for shadows with the dark spot. For a simple global tint set both spots to the same color.

saturation

Use the saturation slider to correct the global saturation.

3.4.2.8. Fill light

Overview
This module allows local modification of the exposure based on pixel lightness.
Usage

Pushes exposure by increasing lightness with a Gaussian curve of a specified width, centered on a given lightness.

exposure

Sets fill-light exposure in [EV].

center

Sets the median lightness impacted by the fill-light. A color picker is activated by pressing . It shows the picked lightness value in the gradient bar, which helps find the desired center value. You can switch between point and area sampling mode from within the global color picker panel (see Section 3.3.6, “Global color picker”).

width

Sets the width of the Gaussian curve. This number is expressed in zones, with the whole dynamic range being 10 zones. As the Gaussian curve is symmetric, only even numbers can be entered.

3.4.2.9. Global tonemap

Overview
This module implements another approach to compressing the tonal range of an HDR image into the limited tonal range of a typical LDR output file. It offers several implementations of global tonemap operators.
Usage

Global tonemapping processes each pixel of an HDR image, without taking the local surrounding into account. This is generally faster than local tonemapping, as implemented in the tonemapping module but might lead to less convincing results with very high dynamic scenes. As an enhancement to the original operators, darktable can preserve detail of the input image, and transfer it back to the output image.

operator

Reinhard, Filmic and Drago global tonemap operators are available for use. Depending on the selected operator, different parameters can be adjusted. Some operators are fully self-adjusting, and do not require specific controls.

bias

Only offered for the Drago operator. This parameter influences the contrast of the output image. It is an essential parameter for adjusting the compression of high values and the visibility of details in dark areas. According to the original paper, a value of 0.85 is recommended as a starting point.

target

Only offered for the Drago operator. This is a scale factor to adjust the global image brightness to the brightness of the intended display. It is measured in cd/m 2 , and should match the according value of your output device. Higher values lead to a brighter image, while lower values lead to a darker image.

detail

Offered as an addition to all operators. This parameter controls how much detail is preserved and transferred back into the output image after tonemapping.

3.4.2.10. Zone system

Overview
This module is another way to change the lightness of your image, based on Ansel Adams' system. It allows modification of a zone's lightness taking into account the effect on the adjacent zones. It divides the lightness range into a user-defined number of zones.
Usage

Following the concept of Ansel Adams the lightness (based on the L channel from Lab) is divided into a number of zones ranging from pure black to pure white. These zones are displayed in a zonebar. The number of zones can be changed by mouse-scrolling on that bar (defaults to 10 zones).

The zonebar is split horizontally with the upper part showing the zones of the module's output and the lower part the according zones of the module's input. In its default state both parts are fully aligned. While the output zones are static you can left click and drag a control point in the input zones to modify the zonemapping. Shifting a control point proportionally expands the zones on one side and compresses the zones on the other side. Any already existing control point stays in place, effectively preventing changes to the zones beyond. Use right click to remove a control point.

The preview shows the image broken down in zones. When hovering above a zone on the zonebar, that zone – either from input or output – is highlighted on the preview.

Examples

The original image.
Here, the darker and lighter zones were compressed to increase contrast, then the upper parts of darker zones were expanded to increase their visual impact.

3.4.2.11. Shadows and Highlights

Overview
The shadows and highlights module allows adjustment to the tonal range of darker parts of an image (shadows) and lighter parts (highlights); it can bring back details in shadows and highlights by enhancing local contrast.
Usage
shadows

This slider controls the effect on shadows; positive values will lighten up shadows while negative values will darken them.

highlights

This slider controls the effect on highlights; negative values will darken highlights while positive values will lighten them up.

white point adjustment

By default the algorithm of this modules leaves black point and white point untouched. In some cases an image might contain tonal variations beyond the white point, i.e. above a luminance value of 100. A negative shift in the white point adjustment slider allows to bring these values down into the proper range so that further details in the highlights get visible.

soften with

This combobox chooses the underlying blurring filter, gaussian or bilateral. Try bilateral filter if you experience halos with gaussian blur.

radius

This slider controls the radius of the involved blurring filter. Higher values give softer transitions between shadows and highlights but might introduce halos. Lower values will reduce the size of halos but may lead to an artificial look. As said, bilateral filter is much less prone to halo artifacts.

compress

This slider controls how strong the effect extends to midtones; high values reduce the effect to the extreme shadows and highlights; low values cause strong adjustments also to midtones. You normally only need to touch this parameter if you want to limit the effects to the extreme shadows and highlights; increase the value in this case. At 100% this module has no visible effect any longer as only absolute black and absolute white are affected.

shadows color adjustment

This slider controls the color saturation adjustment made to shadows; high values cause saturation enhancements on lightened shadows; low values cause desaturation on lightened shadows. It is normally safe to leave this at its default of 100%. This gives a natural saturation boost on shadows – similar to the one you would also expect in nature if shadows would receive more light.

highlights color adjustment

This slider controls the color saturation adjustment made to highlights; high values cause saturation enhancements on darkened highlights; low values cause desaturation on darkened highlights. Often highlights do not contain enough color information to give convincing colors when darkened. You might need to play a bit with this parameter in order to find the best fitting value depending on your specific image; but be aware that sometimes results still might not be fully satisfying.

Examples

Original image exposed for the outer sunlit wall to avoid clipped highlights. As a consequence the interior of the barn has pitch black shadows.
Shadows get lightened; highlights are untouched; overall effect toned down a bit by blend mode normal and an opacity of 65%.
Resulting image.

3.4.2.12. Levels

Overview
A tool for adjusting black, white, and mid-gray points. This module is especially useful if the histogram of an image does not span the whole horizontal range, from pure black to pure white.
Usage

The levels tool offers two modes of operation: manual and automatic.

In manual mode the levels tool shows a histogram of the image, and displays three bars with handles. Dragging the handles modifies the tones in the image. Those bars control the black, middle gray and white points in absolute values of image lightness (the L value from Lab).

You can move the black and white bars to match the left and right borders of the histogram, which will make the output image span the full available tonal range. A previously flat looking image will get more contrast and pop.

Moving the middle bar will modify the middle gray tones. Shifting it left will make the image look brighter, shifting it right will make it darker. This is often referred to as a change of image gamma.

There are three color pickers in black, gray, and white, available by pressing the respectively colored icon. You can use them to sample the corresponding level directly from the image. You can switch between point and area sampling mode from within the global color picker panel (see Section 3.3.6, “Global color picker”).

The auto button autoadjusts the black and white point and puts the gray point exactly in the mean between them.

In automatic mode the module automatically analyses the histogram of the image, detects the left and right histogram borders, and lets you define the black point, the gray point and the white point in terms of percentiles relative to these borders.

Tip: Under certain conditions, especially highly saturated blue light sources in the frame, the levels module may produce black pixel artifacts. See the gamut clipping option (Section 3.4.1.11, “Input color profile”) on how to mitigate this issue.

mode

Set the mode of operation of this module. Defaults to manual.

black

Sets the black point in percentiles relative to the left border of the histogram (only automatic mode).

gray

Sets the gray point in percentiles relative to the left and right borders of the histogram after having applied the black point and white point corrections (only automatic mode).

white

Sets the white point in percentiles relative to the right border of the histogram (only automatic mode).

3.4.2.13. Tone curve

Overview
This module is a classic digital photography tool. darktable's tone curve can work in three different color spaces: RGB, XYZ or Lab.
Usage

In its default state, curves will be straight lines, defined by few anchor nodes. You can move the nodes to modify the curve. You can generate new nodes by clicking on the curve. With Ctrl+click you generate a new node at the x-location of the mouse pointer and the corresponding y-location of the current curve – this adds a node without risking to accidentally modify the curve. Up to 20 nodes per curve can be defined. To remove a node, move it out of the widget area.

A color picker is activated by pressing and will show the picked values in the graph. You can use an area sampling mode using with Ctrl+click. Numerical Lab values of input and output (see below) at the selected spot or area are shown on top left of the widget.

color spaces

Depending on the desired intent, you can apply the tone curve in four different color spaces:

  • Lab, linked channels,

  • Lab, separated channels,

  • XYZ, linked channels,

  • RGB, linked channels.

Lab is a perceptual color space that is designed to approximate the way human beings perceive colors and lightness, and representing the color information independently of the the lightness information. In Lab, separated channels, you get a fully independent control over the chrominance (a/b-channels) and the luminance (L-channel). In Lab, linked channels, only the luminance (L-channel) control is available. The color saturation correction will be automatically computed, for each pixel, from the contrast correction applied to the luminance channel. This works better in cases where a subtle contrast correction is applied, but gives increasingly inaccurate saturation correction as the contrast gets more dramatically enhanced.

XYZ is a linear technical color space designed to link the physiologic light response of human eyes to RGB spaces. As Lab, it separates the lightness from the color information, but it does so in a way that does not account for the role of the brain correction in human perception. The XYZ, linked channels, mode offers an alternative for Lab, linked channels. It works by applying the L-channel curve to all three channels in the XYZ color space. Look at blend mode coloradjustment if you want to tune the strength of automatic chroma scaling (see Section 3.2.5.4, “Blending operators”). This mode is known to produce a slight hue shift towards yellow.

RGB spaces are linear color spaces designed to capture and display images in additive synthesis. They are related to capture and display media and do not isolate color and lightness information. The RGB, linked channels, works in ProPhoto RGB and applies the L-channel curve to all three channels in the RGB color space. Adding contrast in RGB space is known to desaturate highlights and boost saturation in lowlights, but this has proven to be the most reliable way to edit contrast, and is the standard way to do it in most software. This mode makes the tone curve module behave the same way as the basecurve (see Section 3.4.1.5, “Base curve”), except the latter one works in camera RGB space.

Notice that the interface is controlled in Lab in all cases. This means that the middle gray coordinate is always 50% in the graph, no matter what color space is used. The same applies to the inset histogram displayed in the background of the curve. The controls are converted to the relevant color space before the corrections are applied – in RGB and XYZ, the middle-gray is therefore remapped from 50% to 18%.

L-channel curve

The tone curve in L-channel works on Lightness. For a better overview a lightness histogram is displayed in the diagram. When working in Lab, linked channels, RGB, linked channels or XYZ, linked channels, the L-channel curve is the only one available.

The horizontal line represents the input image pixels' lightness. The vertical line represents the lightness of the output image pixels. A straight line does not change anything. A point above the default diagonal increases the lightness, whereas a point under decreases it. Shifting the center of the curve upwards will lighten the image, shifting it downwards will darken the image. An S-like curve will enhance the contrast of the image.

a/b-channel curves

The curves in the a and b channels work on color values and are available only in Lab, separated channels color space. The horizontal line represents the color channel value of the input image pixels. The vertical line represents the color channel value of the output image pixels. Positive a-values correspond to more magenta colors; negative a-values correspond to more greenish colors. Positive b-values correspond to more yellowish colors; negative b-values correspond to more blueish colors.

A straight line does not change anything. Shifting the center of the curve will give the image a color tint: shifting a-channel upwards gives a magenta tint; shifting b-channel upwards gives a yellow tint; shifting a-channel downwards gives a green tint; shifting b-channel downwards gives a blue tint.

Increasing/decreasing the steepness of the curves, without shifting its center, will increase/decrease the color saturation of the respective channel. With properly defined curves you can exert fine control on color saturation, depending on the input pixel's colors.

interpolation method

The interpolation is the process by which a continuous curve is derived from a few punctual nodes. As this process is never perfect, several methods are offered that can alleviate the potential issues you may encounter with some nodes setups.

Arguably, the most visually pleasing method is the cubic spline. Since it gives smooth curves, the contrast in the image is better enhanced. However, this method is very sensitive to the nodes position, and can produce cusps and oscillations when the nodes are too close to each other, or when there are too many of them. This method works best when there are only 4 to 5 nodes, evenly spaced.

The centripetal spline is a method designed specifically to avoid cusps and oscillations, but as a drawback it will follow the nodes more loosely. It is very robust, no matter the number of nodes and their spacing, but will produce a more faded and dull contrast.

The monotonic spline is a method designed specifically to give a monotonic interpolation, meaning that there will be none of the oscillations the cubic spline may produce. This method is very suitable when you try to build an analytical function from a node interpolation (for example: exponential, logarithm, power, etc.). Such functions are provided as presets. It is a good trade-off between the two aforementioned methods.

scale

The scale allows you to distort the graph display so that certain graphical properties emerge to help you draw meaningful curves. Notice that the scaling option only affects the curve display, not the actual parameters.

By default, the linear scale is used. This scale uses evenly spaced abscissa and ordinates axes.

The log scale will compress the high values and dilate the low values, on both the abcissa and the axis of ordinates, so that the nodes in lowlights get more space on the graph and can be controlled more clearly.

When using the logarithmic scale, a base of the logarithm slider appears that lets you control the amount of compression/dilatation operated by the scale. If you draw purely exponential or logarithmic functions from identity lines, setting this values defines the base of such functions.

Examples

Original image
Tone curve settings. Please note how the center node of our b-curve was shifted down to negative values. This gives the image its blue tint.
Resulting image

3.4.2.14. Contrast Brightness Saturation

Overview
This module offers a very basic tool for adjusting an image's contrast, brightness and saturation.
Usage

The module has sliders for each of the three affected attributes. In their neutral position (zero) the image remains unchanged. Shifting sliders left to negative values reduces contrast, brightness and saturation, respectively. Shifting right to positive values leads to an increase.

Much more versatility for contrast and brightness adjustment is offered by the tone curve, levels, and zone system modules (see Section 3.4.2.13, “Tone curve”, Section 3.4.2.12, “Levels”, and Section 3.4.2.10, “Zone system”). Likewise you may adjust color saturation in a more detailed way with the tone curve, color contrast, and color zones modules (see Section 3.4.2.13, “Tone curve”, Section 3.4.2.6, “Color contrast”, and Section 3.4.2.3, “Color zones”).

contrast

This slider adjusts the image's contrast.

brightness

This slider adjusts the image's brightness.

saturation

This slider adjusts the color saturation.

3.4.2.15. RGB Levels

Overview
A tool for adjusting black, white, and mid-gray points. This module is especially useful if the histogram of an image does not span the whole horizontal range, from pure black to pure white.
Usage

Depending on the desired intent, you can work in two different modes:

  • RGB, linked channels

  • RGB, independent channels

You can move the black and white bars to match the left and right borders of the histogram, which will make the output image span the full available tonal range. A previously flat looking image will get more contrast and pop.

Moving the middle bar will modify the middle gray tones. Shifting it left will make the image look brighter, shifting it right will make it darker. This is often referred to as a change of image gamma.

There are three color pickers in black, gray, and white, available by pressing the respectively colored icon. You can use them to sample the corresponding level directly from the image.

The auto button autoadjusts the black and white point and puts the gray point exactly in the mean between them.

The picker on the right of auto button autoadjusts based on a selected area on the picture.

Tip: Under certain conditions, especially highly saturated blue light sources in the frame, the levels module may produce black pixel artifacts. See the gamut clipping option (Section 3.4.1.11, “Input color profile”) on how to mitigate this issue.

mode

Set the mode of operation of this module. Defaults to RGB, linked channels.

black

Sets the black point in percentiles relative to the left border of the histogram.

gray

Sets the gray point in percentiles relative to the left and right borders of the histogram after having applied the black point and white point corrections.

white

Sets the white point in percentiles relative to the right border of the histogram.

preserve colors

Select one of the color preservation methods. The default mode is luminance.

3.4.2.16. RGB curve

Overview
This module is a classic digital photography tool. darktable's RGB curve works on RGB color space.
Usage

In its default state, curves will be straight lines, defined by few anchor nodes. You can move the nodes to modify the curve. You can generate new nodes by clicking on the curve. With Ctrl+click you generate a new node at the x-location of the mouse pointer and the corresponding y-location of the current curve – this adds a node without risking to accidentally modify the curve. Up to 20 nodes per curve can be defined. To remove a node, move it out of the widget area.

A color picker is activated by pressing and will show the picked values in the graph. You can use an area sampling mode using with Ctrl+click.

A second color picker can be used to directly change the curve based on the sampled area. A Click on will activate the action picker. Then, on the picture, a Ctrl+Click+Drag will create a positive curve for the sampled area and a Shift+Click+Drag a negative curve.

color spaces

Depending on the desired intent, you can apply the RGB curve in two different color spaces:

  • RGB, linked channels.

  • RGB, independent channels.

RGB spaces are linear color spaces designed to capture and display images in additive synthesis. They are related to capture and display media and do not isolate color and lightness information. The RGB, linked channels, works in ProPhoto RGB and applies the L-channel curve to all three channels in the RGB color space. Adding contrast in RGB space is known to desaturate highlights and boost saturation in lowlights, but this has proven to be the most reliable way to edit contrast, and is the standard way to do it in most software.

interpolation method

The interpolation is the process by which a continuous curve is derived from a few punctual nodes. As this process is never perfect, several methods are offered that can alleviate the potential issues you may encounter with some nodes setups.

Arguably, the most visually pleasing method is the cubic spline. Since it gives smooth curves, the contrast in the image is better enhanced. However, this method is very sensitive to the nodes position, and can produce cusps and oscillations when the nodes are too close to each other, or when there are too many of them. This method works best when there are only 4 to 5 nodes, evenly spaced.

The centripetal spline is a method designed specifically to avoid cusps and oscillations, but as a drawback it will follow the nodes more loosely. It is very robust, no matter the number of nodes and their spacing, but will produce a more faded and dull contrast.

The monotonic spline is a method designed specifically to give a monotonic interpolation, meaning that there will be none of the oscillations the cubic spline may produce. This method is very suitable when you try to build an analytical function from a node interpolation (for example: exponential, logarithm, power, etc.). Such functions are provided as presets. It is a good trade-off between the two aforementioned methods.

compensate middle grey

Will change the histogram display on the module, this option does not change the processing but may help editing the picture. It is activated by default.

3.4.2.17. Color balance

Overview
This module offers a versatile tool for adjusting an image's color balance. It can be used to revert parasite color casts or to enhance the visual atmosphere of a picture using color grading, a popular technique in the cinema industry.
Usage

The color balance allows you to shift colors selectively by luminance range: shadows, mid-tones, and highlights. It does so using two different methods:

  • lift, gamma, gain, the classic way, that allows a more separated control of shadows versus highlights,

  • slope, offset, power, the new standard defined by the American Society of Cinematographers Color Decision List (ASC CDL), more suited for scene-referred editing.

Three different control layouts can be accessed by clicking on the shadows label: A vertical view as shown on the screenshot above, a tabulated view presenting one of the three group at a single time and a columned view displaying all controls horizontally.

The master settings affect the whole image. They are not available in lift, gamma, gain (sRGB) mode. The slider ranges are limited to usual values ([50%; 150%] for saturations, [-50%; 50%] for contrast), but higher and lower values can be defined from keyboard inputs after a right-click on the corresponding slider.

Side note: although this module acts on RGB colors its location in pixelpipe puts it into the Lab color space. Accordingly the modules converts from Lab to RGB, does its color adjustments, and then converts back to Lab.

Mode

  • lift, gamma, gain (sRGB) is the legacy mode from darktable 2.4 and previous. In this mode, the color transformations are applied in sRGB color space encoded with the sRGB gamma (average gamma of 2.2).

  • lift, gamma, gain (ProPhotoRGB) is the same as the previous but works in ProPhoto RGB space, encoded linearly. In this mode, the RGB parameters are corrected in XYZ luminance (Y channel) internally so they affect only the color, and only the factors adjust the luminance.

  • slope, offset, power (ProPhotoRGB) applies the ASC CDL in ProPhoto RGB space, encoded linearly. Similarly to the previous mode, the RGB parameters are corrected in XYZ luminance internally. In this mode, the slope parameter acts as an exposure compensation, the offset acts as a black level correction, and the power acts as a gamma correction. All parameters will have some impact on the whole luminance range, but the slope will mostly affect the highlights, the offset will mostly affect the shadows, and the power will mostly affect the mid-tones.

For better efficiency, in slope, offset, power, it is recommended to set the slope first, then the offset, and finally the power, in this order. The name of the mode can be use as a mnemonic to remember the order.

In slope, offset, power mode, the shadows parameter has a far heavier effect than in lift, gamma, gain. Switching from the former to the latter, you should adapt the saturation in shadows, dividing by around 10.

Color control sliders

These parameters affect the user interface used for the shadows, mid-tones and highlights controls.

The RGBL controls allow direct access of the RGB parameters that will be sent to the algorithm and internally adjusted in XYZ luminance, depending on the mode used. They are the only ones stored in darktable's development history.

The HSL controls allow a more intuitive control, but are only an interface: the hues and saturations are computed dynamically from and to the RGB parameters and never stored. During the HSL to RGB conversion, the HSL lightness is always assumed to be 50%, so the RGB parameters are always balanced to avoid lightness changes. However, during the RGB to HSL conversion, the HSL lightness is not corrected.

As a consequence, editing in RGB, then in HSL, then again in RGB will not retain the original RGB parameters, but will normalize them so their HSL lightness is 50%. The difference is barely noticeable in most cases, especially using the modes that already correct the RGB parameters internally in XYZ luminance.

In both modes, additional factor sliders act on all RGB channels at once. Their effect is similar to the controls of the levels module (see Section 3.4.2.12, “Levels”) and affect only the luminance.

Input saturation

The input saturation is a saturation correction applied before the color balance. It can be used to dampen colors before adjusting the balance, to make difficult pictures easier to process. When you desaturate entirely the image, it creates a luminance-based monochrome picture that can be used as a luminance mask, to create color filters with the color balance settings, like split-toning or sepia effect (you might want to use blending modes then).

Output saturation

The output saturation is a saturation correction applied just after the color balance. It is useful once you have found a proper hue balance but find the effect too heavy, so you can adjust the global saturation at once instead of editing each channel saturation separately at the expense of possibly messing the colors.

Contrast and Contrast fulcrum

The contrast slider allows to increase the luminance separation. The fulcrum value defines the luminance value that will not be affected by the contrast correction, so the contrast will roll over the fulcrum. Luminance values above the fulcrum will be amplified almost linearly. Luminance values below the fulcrum value will be compressed with a power function (creating a toe). This correction comes after the output saturation and is applied on all RGB channels separately, so hues and saturations might not be preserved in case of dramatic settings (shadows might be resaturated, highlights might be desaturated, and some color shift is to be expected).

Shadows, Mid-tones, Highlights

Depending on the mode set, the shadows settings will control either the lift or the offset, the mid-tones ones will control either the gamma or the power, and the highlights ones will control either the gain or the slope. Parameters are transferred as is when you change the mode.

In RGBL mode, the RGB sliders range is limited to [-0.5; 0.5]. In HSL mode, the saturation sliders range is limited to [0%; 25%]. Values outside of these bounds can be defined from keyboard input after right-click on the slider.

Optimize luma

The color-picker close to the optimize luma label will select the whole image and optimize the factors for shadows, mid-tones and highlights so the average luminance of the picture is 50% Lab, the maximum is 100% and the minimum is 0%, at the output of this module. This is essentially an histogram normalization, similar to what the levels module can achieve. The optimizer is accurate only when used in slope, offset, power mode. It works only fairly in the other modes.

In case you want more control, you can define three control patches using the color-pickers in front of each factor slider, to sample luminance in selected areas. The shadows color-picker samples the minimum luminance, the mid-tones one samples the average, and the highlights one samples the maximum luminance. The most sensitive parameter is the mid-tones factor, since selecting a slightly different area can lead to dramatic parameter changes. Using the factors color-pickers alone, without triggering the luma optimization, will allow to perform adjustments without general optimization, but each parameter is always computed accounting from the two others. Once patches are selected, the label becomes optimize luma from patches. To reset one patch, you can just redo the selection. Patches are not saved in the parameters and are kept only during the current session.

It is important no note that the luminance adjustment performed targets only the output of the color balance module and does not account for other luminance adjustments performed in modules coming later in the pixelpipe (filmic, tone curve, color zones, levels, global tonemapping, etc.). Using the color balance to remap the luminance globally on the image is not recommended because it does not preserve the original colors, and modules such as tone curves or filmic are better suited for this purpose. Luminance adjustments in color balance are better suited for local correction, in combination with color adjustments, for color-grading with masks.

Neutralize colors

In an image where some areas are exposed to direct sunlight and some areas are exposed to reflected light (shadows), or when several artificial light sources are present simultaneously, shadows and highlights often have different color temperatures. These images are particularly difficult to correct since no general white balance will match all the colors at once. The color neutralization optimizer aims at helping you find the complementary color for shadows, midtones, and highlights so all the color casts are reverted, and the average color of the picture is a neutral grey.

Similarly to the luma optimization, the color-picker next to the neutralize colors label will trigger a general optimization over the whole picture. This works fairly in landscape photography, or any photography with a full spectrum of colors and luminances. For night and events photography, this will most likely fail and you will need to input manually the sampling areas with the color-pickers in front of each hue slider. For the highlights sample, use a color exposed to spotlights that should be neutral white or light grey. For the shadows sample, use a color exposed to ambient light that should be neutral black or dark grey. For the mid-tones sample, use a color exposed by both ambient and spot lights.

The success of the optimization depends on the quality of the samples. Not every set of samples will converge to a good solution, you need to ensure the color patches you choose are really neutral color in real life. In many cases the optimizer will output the correct hue but an excessive saturation that will need some extra tweaking. In some cases, no valid optimization will be delivered and you will need to reset the saturation parameters and start over, or simply stop after the patches selection. Notice that in the auto-optimization the maximum saturation is 25% which might not be enough in very few cases but will avoid inconsistent results in most.

If you select color patches from the hues color-pickers, without triggering the optimization, the software will only perform one round of optimization and stop so it allows you to control each luminance range separately and avoid divergence of the solution in corner cases. The hue and saturation corrections are computed accounting for the two other luminance ranges and the three factors, and will always output the complementary color of the selected area. If you want to reinforce the color of the area instead, you can then add 180° to the computed hue. Once patches are selected the label becomes neutralize colors from patches. To reset one patch you can just redo the selection. Patches are not saved in the parameters and are kept only during the current session. The parameters found by the automatic neutralization are accurate only in slope, offset, power mode, but can work to some extent in lift, gamma, gain too.

Examples

Several presets are provided in the module to help you understand how it can be used.

The teal/orange color-grading preset is a very popular look in cinema and a good showcase model. It is meant to be used with two instances and masks: the first instance will exclude skin tones and will shift neutral colors toward teal blue. The second will partially revert the first one and add more vibrance on skin tones only. Together they will help creating separation between subjects and backgrounds. The masking and blending parameters will need to be tweaked to suit every picture, though.

Other presets provide Kodak film emulations. In the same way you can recreate any film look you like with color balance.

3.4.2.18. Channel mixer

Overview
This module is a powerful tool to manage channels. It accepts red, green and blue channels as an input. As output it provides red, green, blue, gray, hue, saturation and lightness channels.
Usage

First select your output channel and then set the amount each input channel feeds into that output channel. Among its many uses, this module can be used to see the RGB channels individually: use the gray destination and put the value 1 on the input channel you want to see and 0 on the others.

Examples

For skin tones the blue channel tends to represent detail, with red tending to also have smoother tones than green. Therefore tonal rendering is controlled by how we blend of the three input channels.
Here a monochrome portrait is produced by simply selecting the grey channel as output. A smooth skin tone is achieved by reducing the blue channels input and also emphasizing the red channels input relative to green. An RGB mix of 0.9, 0.3, -0.3 was used together with an 0.1 EV exposure increase to lighten the image.
In this example an RGB mix of 0.4, 0.75, -0.15 uses more green than red, bringing back some features. We still reduce the blue channel in the mix to de-emphasize unwanted skin texture.

Table of mixing values for some b/w films

Classic black and white films have different characteristic color responses. Select gray as output mixing channel, and try out the values suggested below for your favorite film type.

Film Type Red Green Blue
AGFA 200X 0.18 0.41 0.41
Agfapan 25 0.25 0.39 0.36
Agfapan 100 0.21 0.40 0.39
Agfapan 400 0.20 0.41 0.39
Ilford Delta 100 0.21 0.42 0.37
Ilford Delta 400 0.22 0.42 0.36
Ilford Delta 3200 0.31 0.36 0.33
Ilford FP4 0.28 0.41 0.31
Ilford HP5 0.23 0.37 0.40
Ilford Pan F 0.33 0.36 0.31
Ilford SFX 0.36 0.31 0.33
Ilford XP2 Super 0.21 0.42 0.37
Kodak T-Max 100 0.24 0.37 0.39
Kodak T-Max 400 0.27 0.36 0.37
Kodak Tri-X 400 0.25 0.35 0.40
Normal Contrast 0.43 0.33 0.30
High Contrast 0.40 0.34 0.60
Generic B/W 0.24 0.68 0.08

3.4.2.19. Graduated Density

Overview
This module aims at simulating a graduated density filter, in order to correct exposure and color in a progressive manner.
Usage

The module uses a gradient to modify the exposure and the color cast of the image in a non-homogeneously manner.

This module is known to provoke banding artifacts under certain conditions; you should consider to activate the dithering module (see Section 3.4.1.1, “Dithering”).

density

Set the density of the filter in [ev]. A low value underexposes slightly whereas a high value creates a strong filter.

It is expressed as [ev] that is equivalent to f-stops. Lens filters are often referred as ND2, ND4, ND8 and so on. Each time you add an [ev] you double the ND. So ND2 is 1 ev, ND4 is 2 ev, and so on. You can also express it in optical density or transmittance. The table below sums up the different approach for the most common filters:

ND [ev] or f-stop absorbance transmittance
ND2 -1 0.3 50%
ND4 -2 0.6 25%
ND8 -3 0.9 12.5%
ND400 -9 2.7 0.195%

compression

Set progressiveness of the gradient. A low value creates a smooth transition, whereas a high value makes the transition abrupt.

hue

Set the hue to add a color cast to the gradient.

saturation

Set the saturation to add a color cast to the gradient.

position

You can set the position of the gradient directly on the image by moving the white line. For fine tuning, you can also use the rotation slider. Negative values turn clockwise.

Examples

Here is an example that shows various options of darktable's graduated density filter:

This is the original image with a pretty overexposed sky, use it as reference for the changes below...
And now we have added a neutral ND8 filter which does a pretty good job on the image..
And at last, we added an orange colored filter rotating it -180 degrees, applying it on water/trees for a more artistic use of the filter.

darktable's graduated density filter is a powerful tool. Nevertheless, hardware filters have some advantages over a pure software solution. With a physical GND filter you can in fact reduce the dynamic range of your scene to make it better fit the limits of your camera sensor.

In this example a hardware GND filter (Hitech ND0.6, soft edge) helped to prevent over-exposure in the sky and tree tops, while at the same time getting a well exposed image of the ground. A rather disturbing element is the decay of brightness in the tree trunks from bottom to top.
darktable's graduated density filter together with the parametric mask feature (see Section 3.2.5.6, “Parametric mask”) comes in handy. We can add a brightness gradient that is just inverted in relation to the hardware filter. As we only want to compensate the unnatural decay of brightness in the tree trunks, we combine the module with a suited blend mask.
The resulting image.

Tip: If you know you intend to use the graduated density filter before actually making a shot with your camera you might want to underexpose by one or two thirds of an f-stop to make sure detail remains in the highlights. When all detail has truly been blown out the graduated density filter cannot produce a pleasing results, this is a limitation that is inherent to digital postprocessing. For instructions on how to intentionally underexpose, please consult your camera's manual, look for exposure compensation.

3.4.2.20. Tone equalizer

Overview
The Tone Equalizer module is designed to replace the Base Curve module, the Shadows/Highlights module, and the Zone System module. It allows us to brighten or darken up to 9 different ranges of luminosity within our image.
Usage

It is recommended that you look at all 3 tabs (Simple, Advanced, Masking) before attempting to use the Tone Equalizer module.

The 9 sliders on the Simple tab (see screenshot above) correlate to the 9 control points which appear across the centre of the graph on the Advanced tab.

The histogram which appears on the Advanced tab does not represent your image. It represents the mask which the Tone Equalizer is creating for your image. This is an important distinction to understand. The aim is to get that histogram extended as far as possible to the left and right sides of the graph.

To do that, we go to the Masking tab, and adjust the Mask Exposure Compensation and Mask Contrast Compensation sliders. Selecting each eye dropper will allow the Tone Equalizer module to select the most appropriate values for you. Having done that, check the histogram in the Advanced tab again. It should now be fairly evenly distributed across the graph.

Now, you can Click+drag the control points (on the Advanced tab) to increase or decrease any part of the tonal range of your image. Adjust control points on the left side to brighten/darken shadow tones. Adjust control points on the right side to brighten/darken highlight tones. Alternatively, you can use the Simple tab and control the adjustment through the use of your mouse wheel over the image.

the cursor

The cursor in the Tone Equalizer contains a lot of information. You'll see some cross hairs, with what appears to be a single grey circle in the middle. But it's not a single circle. It's 2 concentric circles. The outer circle will always represent the tonal value under the mouse pointer, as it was before any adjustment was made. The inner circle will show the tonal value under the mouse pointer after any adjustment has been made. So if the inner circle is brighter than the outer circle, it means a brightening adjustment has been made to that part of the tonal range of the image. If the inner circle is darker than the outer circle, then that tonal range has been darkened.

You will also notice that there is an arc which either climbs, or descends, from the left side cross hair. This is another way of showing you whether a positive or negative adjustment has been made for any given tonal range under the mouse at its current location.

There is also a text box near the right side cross hair which also shows what adjustments have been made, but in numeric text form.

display exposure mask

At the bottom of the module, you'll see Display Exposure Mask and to the right of that, an icon . Click on this icon to see the mask which the Tone Equalizer has generated for your image.

The idea behind this mask is to create smooth transitions between tonal ranges, so as to avoid creating halos. Yet, the mask is also able to create well defined edges for high contrast areas of the image. Having this mask displayed will assist in understanding the follow parameters:

preserve details mode

There are several different filters that can be used to smooth the mask. If preserve details is disabled, the mask is not smoothed. Guided filter blurs the mask smoothing more shadows than highlights, which is sometimes desirable if you lighten the shadows a lot, but may result in loss of local contrast in highlights if you darken them. Eigf blurs the mask in a way that is independent from exposure: highlights and shadows will be blurred more uniformly. Guided filter averaged and eigf averaged will perform the geometric mean of the result of the filter and the original mask: details will not be as preserved as without the average, but the averaging will reduce halos.

If you increase this to 2, a second mask is calculated using the first mask as an input. As a result, the new mask is more fuzzy than when there was only one instance of the mask. Progressively higher values will diffuse the mask even further.

filter diffusion

This defaults to a value of 1, meaning there is one instance of the mask generated.

If you increase this to 2, a second mask is calculated using the first mask as an input. As a result, the new mask is more fuzzy than when there was only one instance of the mask. Progressively higher values will diffuse the mask even further.

smoothing diameter

With lower values, the transition between dark areas of the mask and lighter areas of the mask will be more pronounced. As this value is increased, those transitions become smoother/softer.

edge refinement/feathering

Higher values will force the mask to follow high contrast edges more closely. Lower values will give smoother gradients, but may introduce some halos.

Compress shadows/highlights presets

The module comes with several presets to compress shadows and highlights. For each of these presets, 2 variants are proposed, one with guided filter (gf) and one with exposure independent guided filter (eigf). Depending on the image, one or the other may give better results. In both case, these presets preserve middle-grey so that you do not have to adjust global exposure before and after toneequalizer.

3.4.2.21. Tonemapping

Overview
This module compresses the tonal range of HDR images, so they fit into the limits of a normal, low dynamic range image, using Durand's 2002 algorithm. darktable can import HDR images if they come in OpenEXR, RGBE or PFM format or as a DNG generated by darktable's HDR creation mechanism (see Section 2.3.8, “Selected image(s)”).
Usage

The underlying algorithm uses a bilateral filter to decompose an image into a coarse base layer and a detail layer. The contrast of the base layer is compressed, while the detail layer is preserved, then both layers are re-combined.

contrast compression

Sets the contrast compression level of the base layer. A higher compression will make the image fit a lower dynamic range.

spatial extent

Sets the spatial extent of the bilateral filter. Lower values cause the contrast compression to have stronger effects on image details.

3.4.2.22. White balance

Overview
This module is used to set the white balance. You have three ways to interact with it: (a) Set up tint and temperature, (b) define the value of each channel, or (c) choose from predefined white balances.
Usage
tint

Alter the color tint of the image, from magenta (value < 1) to green (value > 1). The channel sliders will be updated when you adjust this parameter.

temperature

Set the color temperature (in Kelvin). The channel sliders will be updated when you adjust this parameter. darktable derives the color temperature from the Exif data using some model assumptions. The value given is not meant to be authoritative. In the end only the updated channel values determine how the image is modified.

red, green and blue channels

Set the channel values on a scale from 0 to 8.

preset

Select a preset white balance.

camera white balance (default) White balance reported by the camera.
camera neutral Essentially sets temperature to 6502K. The actual math: it computes such white balance channel multipliers, so that pure white color in camera colorspace is converted into pure white color in sRGB D65. (pure white color here means having the same equal value for each channel = 1.0)
spot white balance Select a square area in your image containing mostly grey pixels. The white balance is calculated based on the selected area.
camera presets Camera specific white balance presets. Examples: direct sunlight, flash, cloudy, shade and a number of indoor lighting options.

finetune

Some cameras offer additional finetuning parameters if one of the camera presets is selected. Depending on camera white balance, can be adjusted in steps within a certain range. The adjustments are usually towards yellow (value < 1) or blue (value > 1).

Notes

The history in the database and associated XMP file, and in a style, does not contain the temperature and tint. Instead it holds values related to the three RGB coefficients which can be set in the white balance module. The relationship between these two sets of values - RGB and temp/tint - depends on camera characteristics. Therefore applying white balance in a style made with one camera model to another camera model will in general give a different temp/tint, and your image might look different to what you expected. Consider doing all white balancing explicitly in the module.

The mathematical relationship between the two sets of values is not straightforward. Colour balances can be set using the RGB sliders which have no corresponding setting in terms of temperature and tint (this mainly happens when very high temperature values are calculated from the slider values). Therefore be aware that editing white balance using temp/tint on an image previously made using the RGB sliders may give odd results, at least if high temperature values are involved.