3.2.7. Drawn mask

Almost all darktable modules have the option to narrow down their effect by a drawn mask and thus allowing local adjustments.

3.2.7.1. Overview

With the drawn mask feature you can construct a mask by drawing directly on the image base. Different drawing operators, called shapes, are available and can be used alone or in combination. A flexible editing feature allows you to change single aspects of a shape, remove shapes or import shapes already defined in other modules.

Internally shapes are stored as vector graphics and rendered with the needed resolution during pixelpipe processing. Shapes are expressed in the coordinate system of the original image and transformed with all distorting modules. This way a shape will always work on the same image area regardless of warping or other modifications that may be applied.

3.2.7.2. Usage

To draw a shape you need to click on one of the shape symbols. You will automatically be moved into the edit mode in which you generate a new instance of the selected shape and afterwards change its properties.

You leave edit mode by clicking on the symbol. You can at any time go back to edit mode and do further adjustments by clicking the edit symbol again. In edit mode you can also remove a shape by right-clicking on it – the shape is removed from the current mask but it's still in the list of defined shapes.

If you ctrl-click on the edit mode symbol you enter a restricted edit mode. Certain actions like dragging a complete shape or changing its size are blocked. Only finetuning changes like dragging a node are allowed.

Currently five shapes are implemented.

brush

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.1, “GUI options” 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.1, “GUI options”) 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.
circle

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.
ellipse

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. Shift-click in the shape to toggle the gradual decay between equidistant and proportional mode.

An ellipse shape with controls and activated mask display.
path

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 scrolling when it is highlighted or 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.
gradient

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 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.4.13, “Dithering”)

A gradient with controls and activated mask display.
drawn mask

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.9, “Combining drawn and parametric masks”).

mask manager

More functionality to control the interaction of multiple shapes within a mask can be found in the mask manager panel (see Section 3.3.5, “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.