Blending

module's output is passed to the next module in pixelpipe without additional reprocessing. No further controls are displayed.

reprocessing takes place with the chosen blend mode and opacity value – the same for all pixels. Additional controls to select blend mode and opacity value are displayed. The default blend mode is “normal” with an opacity of 100%.

reprocessing takes place with the chosen blend mode and opacity. Additional controls are displayed which allow you to draw a mask. If no mask elements are drawn all pixels have the same opacity, defined by the opacity slider. If you draw a mask element, e.g. a circle, the inner area of the circle will get maximum opacity, surrounded by a transition area or border with a gradual decay of opacity and the remaining image with an opacity of 0%. Different graphical shapes can be used. See Section 3.2.5.5, “Drawn mask” for further details.

reprocessing takes place with the chosen blend mode and opacity. Additional controls are displayed which allow you to adjust the opacity on a per-pixel basis determined by pixel values. In previous versions of darktable this was called “conditional blending”. See Section 3.2.5.6, “Parametric mask” for further details.

this option combines drawn and parametric masks and shows the full set of both controls. See Section 3.2.5.8, “Combining drawn and parametric masks” to learn how to best use this combination.

this option reuse a mask created in another module using a parametric mask possibly combined with a drawn mask. See Section 3.2.5.7, “Raster mask” for further details.

this item provides access to the available blending versions for the module and additional options specific to the blending operation.

This will probably be the most used blend mode. It just mixes input and output and, depending on the opacity value, it reduces the strength of a module's effect. Generally this is also the blend mode of choice if you want to apply a module's effect locally using masks.

This blend mode acts similarly to blend mode “normal”, except that input and output data are clamped to a particular min/max value range. Out-of-range values are effectively blocked and do not pass to the following modules. Sometimes this helps to prevent artifacts. However, in most cases (e.g. highly color saturated extreme highlights) it is better to let unbound values travel through the pixelpipe in order to properly deal with them at the right place (e.g. in module output color profile). Blend mode “normal” is most often the preferred choice.

This blend mode mixes lightness from the input and output images. Color data (chroma and hue) are taken unaltered from the input image.

This blend mode mixes chroma (saturation) from the input and output images. Lightness and hue are taken unaltered from the input image.

This blend mode mixes hue (color tint) from the input and output images. Lightness and chroma are taken unaltered from the input image. Caution: When modules drastically modify hue (e.g. when generating complementary colors) this blend mode can result in strong color noise.

This blend mode mixes color (chroma and hue) from the input and output images. Lightness is taken unaltered from the input image. Caution: When modules drastically modify hue (e.g. when generating complementary colors) this blend mode can result in strong color noise.

Only available with modules that work in the Lab color space; this blend mode mixes lightness from the input and output images, while color data are taken unaltered from the input image. In contrast to blend mode “lightness” this blend mode does not involve any color space conversion and does not clamp any data. In some cases this is less prone to artifacts in comparison to “lightness”.

Only available with modules that work in the Lab color space; this blend mode mixes Lab color channels a and b from the input and output images, while lightness data are taken unaltered from the input image. In contrast to blend mode “color” this blend mode does not involve any color space conversion and does not clamp any data. In some cases this is less prone to artifacts in comparison to “color”.

Only available with modules that work in the RGB color space; this blend mode mixes lightness from the input and output images, while color data are taken only from the input image. In contrast to blend mode “lightness” this mode does not involve clamping.

Only available with modules that work in the RGB color space; this blend mode mixes color from the input and output images, while lightness data are taken only from the input image. In contrast to blend mode “color” this mode does not involve clamping.

Some modules act predominantly on the tonal values of an image but also perform some color saturation adjustments, e.g. module levels and tone curve. The color adjustment blend mode takes the lightness only from output data and mixes colors from input and output enabling control of the module's color adjustments.

Clicking the symbol adds a brush stroke.

Start drawing by left-clicking into the canvas and moving the mouse while keeping the button pressed. The brush stroke is finalized once you release the mouse button. Brush size, hardness and opacity can be changed by scrolling, shift+scrolling, and Ctrl+scrolling, respectively, either before you start drawing or at any time during the operation. Likewise you can use keys [ | ] to decrease/increase brush size, { | } to decrease/increase hardness, and < | > to decrease/increase opacity.

If you have a graphics tablet with pen pressure sensitivity, darktable can apply the recorded pen pressure to certain attributes of the brush stroke. See Section 8.4, “Darkroom” for more details.

On lifting the tablet pen or releasing the left mouse button the drawn figure is converted into a number of connected nodes which define the shape. A configuration option (see Section 8.4, “Darkroom”) controls how much smoothing is applied. A higher level of smoothing leads to less nodes – this eases subsequent editing at the expense of a lower initial accuracy.

Nodes and segments of a brush stroke can be modified individually. See the documentation on path below for more details.

Rendering a complex brush shape can consume a significant number of CPU cycles; consider to revert to the circle, ellipse or path shape if possible.

A brush stroke with controls and activated mask display.

Clicking the symbol adds a circle shape.

Click into the canvas to place the circle. Left-click and drag the circle to a different position if needed. Use the scroll wheel of your mouse while in the circle to change the diameter; scroll within the circle border to adjust the width of the gradual decay or shift+scroll anywhere in the shape for the same effect. With Ctrl+scroll you can adjust the opacity of the circle – this is best observed with the mask displayed by pressing the button.

A circle shape with controls and activated mask display.

Clicking the symbol adds an ellipse shape.

The general principle is the same as for the circle shape. In addition you get four nodes on the ellipse line. Click on the nodes to adjust the ellipse's eccentricity. Ctrl+click on them to rotate the ellipse or, alternatively, use Shift+Ctrl+scroll. Shift+click in the shape to toggle the gradual decay between equidistant and proportional mode.

An ellipse shape with controls and activated mask display.

Clicking the symbol adds a shape defined by a user defined closed path.

Left-click into the canvas to define path nodes; terminate the path by right-clicking after having set the last point. Per default nodes are connected by smooth lines. If you want a node to define a sharp corner, you can do so by creating it with Ctrl+click.

In the edit mode you can convert existing nodes from smooth to sharp corners and vice versa by Ctrl+clicking on them. You can insert additional nodes by Ctrl+clicking on one of the line segments. Single nodes can be deleted by right-clicking on them; make sure that the mouse pointer is over the desired node and the node is highlighted, or else you might accidentally remove the whole path.

The size of the complete shape can be modified by scrolling – analogous to the circle shape. The same holds true for the width of the border, i.e. the area with a gradual opacity decay, which can be changed by Shift+scroll from anywhere within the shape. Single nodes as well as path segments can be moved by mouse dragging. If a node is selected by clicking on it, a further control point appears – you can move it around to modify the curvature of the line and reset to default by right-clicking. Dragging one of the control points on the border adjusts the border width just in that part of the shape.

Consider to finetune a path in the restricted edit mode (see above), which allows you to adjust single nodes and segments without the risk of accidentally shifting or resizing the whole shape.

A path shape with controls and activated mask display.

Clicking the symbol adds a gradient to the mask. This does not generate a confined shape but produces a linear gradient extending the whole image.

Click into the canvas to define the position of the line where opacity is at 50%. The line has two anchor nodes which you can drag to change the rotation of the gradient.

Scrolling close to the center line curves the gradient.

Shift+scrolling close to the center line changes the steepness of the gradient. Dotted lines indicate the distance beyond which the opacity is 100% and 0%, respectively. Between these dotted lines the opacity changes linearly. The gradient is best seen and modified when the mask is displayed by pressing the button.

Depending on the module and the underlying image using a gradient shape might provoke banding artifacts. You should consider to activate the dithering module (see Section 3.4.1.1, “Dithering”)

A gradient with controls and activated mask display.

The number of shapes that are used in the current mask is displayed in the “drawn mask” field. Clicking on that field opens a dropdown box with all shapes that have already been defined in the context of the current image but are not yet used in the current mask. You can click on any of these items in order to add it to the current mask. The list also contains shapes once generated but no longer in use. This way you can even get back a deleted shape.

A polarity button ( and , respectively) allows the user to toggle between the normal and the inverted state of the drawn mask, i.e. the opacity values get inverted – 100% becomes 0% and vice versa. You need this feature when combining drawn and parametric masks (see Section 3.2.5.8, “Combining drawn and parametric masks”).

When “drawn mask” is selected there is an additional combobox to invert the mask by switching mask inversion “on” or “off”.

More functionality to control the interaction of multiple shapes within a mask can be found in the mask manager panel (see Section 3.3.7, “Mask manager”). Here you can give individual names to your shapes which will help you to keep track of your shapes. You can also select individual shapes for editing – a helpful feature if your masks happens to contain several shapes with overlapping control elements.

Each tab selects a data channel – real or virtual. Blending performed in Lab color space have data channels for L, a, b, C (chroma of LCh) and h (hue of LCh). Blending performed in (display referred) RGB color space have data channels for g (gray), R, G, B, H (hue of HSL), S (saturation of HSL), and L (lightness of HSL). Blending performed in (scene referred) RGB color space have data channels for g (gray), R, G, B, Jz (luminance component of JzCzhz), Cz (chrominance component of JzCzhz) and hz (hue component of JzCzhz). Consult for example Wikipedia's article on color spaces for a deeper look.

Each tab may provide two sliders for its data channels: one for the input data that the module receives and one for the output data that the module produces prior to blending. The slider for the output data is hidden by default and can be shown using the “show output channels” menu item in the blending menu.

The “boost factor” slider allows to extend the range of values that may be targetted by the parametric mask sliders. It may be used in scene referred editing where luminance values may go beyond 100% to target highlights. This slider is only available for channels where it is meaningful.

You can inspect the image data corresponding to an individual color channel by holding down the Shift key while entering the respective slider with the mouse cursor. The center image changes to display the selected color channel either in graycale values or in false colors, depending on the corresponding preference setting in “darkroom options” (see Section 8.4, “Darkroom”). You may additionally hold down the ctrl key which lets you see the resulting mask overlaid to the image. When leaving the slider the image goes back to normal after a short delay.

With the color channel slider you construct a trapezoidal opacity function. For this purpose there are four markers per slider. Two triangles above the slider mark the range of values where opacity is 1. Two triangles below the slider mark the range values where opacity is zero. Intermediate points between full and zero opacities are given a proportional opacity.

The filled triangles, or inside markers, indicate the closed (mostly narrower) edge of the trapezoidal function. The open triangles, or outside markers, indicate the open (mostly wider) edge of the trapezoidal function. The sequence of the markers always remains unchanged: they can touch but they can not switch position.

A polarity button ( and , respectively) to the right of the slider switches between range select and range de-select function modes with visual confirmation provided by exchanging the upper and the lower triangle markers. These two types of trapezoidal functions are represented graphically in the following images.

Range select function	Range de-select function
A trapezoidal function that selects a narrow range of values for blending.	A trapezoidal function that de-selects a narrow range of values from blending.

In their default state all markers are at their extreme positions, maximum left and maximum right, respectively. In this state a range select function selects the whole range of values giving an “all at 100%” mask. Starting from there one can move the sliders inwards to gradually take out more an more parts of the image except of the remaining narrow range.

A range de-select function per default deselects the whole range of values, giving an “all-zero” mask as a starting point. Moving the sliders inwards gradually extends the mask more and more except of the remaining narrow range.

For more information on the polarity feature read Section 3.2.5.8, “Combining drawn and parametric masks”.

Control buttons help you when designing a parametric mask.

With the color picker button you can select a probe from your image. The corresponding values for the real and virtual data channels are then displayed within each color channel slider. You can switch between point and area sampling mode from within the global color picker panel (see Section 3.3.6, “Global color picker”).

With the invert button you can toggle the polarities of all channels (including a potentially activated drawn mask) and change the method how channels are combined into the final mask. More on that topic can be found in Section 3.2.5.8, “Combining drawn and parametric masks”.

With the reset button you can put all settings back to their default state.

When either a “parametric masks”, or the combination of “drawn and parametric mask” is active an additional combobox is shown that controls how the individual masks are combined to form the final mask. This option also allows to invert the final mask. Details on the combination of individual masks can be found in Section 3.2.5.8, “Combining drawn and parametric masks”.

If there is a mask in another module it will appear in the drop-down menu of the raster mask. You can easily identify the mask by the name of the module it was defined in.

For this mode you set the “combine masks” combobox to inclusive and make sure that all polarity buttons of all the individual channels and of the drawn mask are set to negative ( ). Your starting point is a mask where all pixels have a value of zero, i.e. no pixel is selected. You now adjust the parametric mask sliders to bring more and more pixels into the selection or you draw shapes on the canvas to select specific areas of your image.

In the opposite case you set the “combine masks” combobox to exclusive and make sure that all polarity buttons are set to positive ( ). Your starting point is a mask with all values at 1.0, i.e. all pixels selected. You now gradually change the parametric mask sliders to exclude parts of your image as needed or you directly draw shapes on the canvas to specifically exclude these areas.

For your convenience you find in the parametric masks GUI a toggle button that inverts all channel polarities and toggles between inclusive and exclusive mode in the “combine masks” combobox.

For novice users it is recommended to stick to these two use cases. This implies that you should decide beforehand how you want to construct your mask. Advanced users will find their way to take advantage of the many possible combinations of polarities and mask combination modes.

Mask feathering smoothens a drawn or parametric mask non-uniformly such that the mask's edges are adjusted automatically to match the edges of the image. This mask smoothing is guided either by the module's input image or by its output (before blending), depending on what is selected in the “feathering guide” combobox. The feathering is particularly sensitive to this choice for edge-modifying modules, i.e., modules for sharpening or blurring an image.

The “feathering radius” slider adjusts the strength of the feathering effect. Feathering works best if the drawn and/or parametric mask's edges already match approximately some edges in the guiding image. The larger the “feathering radius” the better the feathering algorithm can align mask edges to more distant edges of the image. If this radius is too large, however, the feathered mask may overshoot. This means it cover regions that the user actually wants to exclude. Feathering is turned off if the feathering radius is set to 0.

Blurring the mask creates a softer transition between blended and unblended parts of an image and avoids artifacts. The mask blur slider controls the radius of a gaussian blur applied to the final blend mask. The higher the radius, the stronger the blur – or set to 0 for an unblurred mask. Gaussian blur is always applied after feathering if both kinds of mask adjustment are activated. This order allows to smooth sharp edges or artefacts that may result by feathering.

The strength of the module's effect is determined by the mask's local opacity. Feathering and blurring the mask may result in a mask with reduced opacity, which implies a reduced effect. Therefore, the “mask opacity” slider allows to readjust the mask opacity. If the opacity is decreased (negative slider values) least opaque parts are affected stronger than most opaque parts. Contrary, if the mask opacity is increased (positive slider values) most opaque parts are affected stronger than least opaque parts. As a consequence, completely opaque portions of the mask always remain opaque and completely transparent portions remain transparent. This is to ensure that regions which have been excluded from or included to a module's effect by setting the mask's opacity to 0% or 100% remain excluded or included even if the mask opacity is adjusted by this slider.

This slider increases or decreases the mask contrast. This means it allows to modify the transition between opaque and transparent mask parts.

Sometimes it is useful to visualize the module's effect without the mask taking action. You can do so by clicking on the symbol, which will temporarily deactivate the mask – the selected blend mode and opacity remain in effect. Switch this button on and off to see if the mask is acting on the image as intended.

Clicking on the symbol will display the current mask as a yellow overlay over a black-and-white version of your image. Solid yellow indicates an opacity of 100%; a fully visible gray background image without yellow overlay indicates an opacity of 0%.

It can be rather tedious to create a drawn mask by hand, which matches precisely a particular object or person in an image. In this example, we want to enhance the color contrast of the lion sculpture shown in the left image above without affecting the background. For this purpose, a rough selection of the sculpture is created by a drawn mask. See the second image above, where the “displays mask” feature is active. Note that the mask is rather fuzzy and it does not match precisely the lion sculpture. Adjusting the feathering radius, the mask opacity and the mask contrast leads to a well matching mask with little effort. In the third image above the feathering radius has been adjusted to 50, a blur radius of 5 was chosen to smooth the mask to some degree. The mask opacity and the mask contrast have been increased to 0.3 and 0.5, respectively, to further enhance the mask. The last image above shows the final result, where the color enhancement via the color contrast module (see Section 3.4.2.6, “Color contrast”) is restricted to the lion sculpture due to the mask.

Mask feathering works in this example particularly well because the sculpture in the original image is well separated from the blurry background. The distinct edge at the border of the sculpture guides the feathering mask adjustment to match the shape of the sculpture. Note that feathering can be applied to drawn masks as well as to parametric masks.