darktable page lede image
darktable page lede image

3.3.7. Mask manager

3.3.7.1. Overview

The masks manager panel is the central place where you manage all masks and shapes within the context of the current image. Here you create, delete and change shapes or give them unique names. You can add shapes to and remove shapes from a mask, and you define how multiple shapes interact within a mask.

3.3.7.2. Usage

In the top line of the masks manager panel you find buttons to create new shapes. They are the same as in the drawn mask GUI (see Section 3.2.5.5, “Drawn mask” for more details).

The lines below list all masks used and all individual shapes defined. The masks are noted with a headline in the form grp levels indicating the module in which they are used. The list of masks is followed by a list of all individual shapes which have been generated in the context of the given image. If a shape is in use by any of the masks it is marked by the symbol to the right of the shape name.

3.3.7.3. Shapes

By default shapes receive an automatically generated name, consisting of the shape type (brush, circle, ellipse, path, gradient) and a number that is incremented automatically. You can replace these automatically generated names by more meaningful ones. Double-clicking on the existing shape name prompts you for a new one. Giving a meaningful name is a good habit, especially if you are going to use the same selection in different masks. A name like house front makes it easier to get the right shape, rather than something like path #32.

Clicking on the shape name shows the selected shape in the center canvas with all its controls. This is a convenient way to edit the properties of a specific shape. Especially if there are so many shapes within a mask that their controls overlap and make it difficult to hit the right target.

Right-clicking on a shape name gives you a drop-down menu with the options to remove the current shape or to remove all shapes currently not in use.

All shapes ever defined for the current image are kept in the list unless you remove them explicitly. If you have worked a lot with shapes on one image, this list can get quite long. All settings – with all defined shapes – are part of the XMP tags of an image and are included in exported files. If the list of shapes is very long the needed space to store all shapes might exceed the given limits of certain file formats, like JPEG. In that case storing the XMP tags might fail during export. This is normally not a problem – however, you can no longer rely on the exported file to contain your full history stack (see Section 2.3.14, “Export selected”).

3.3.7.4. Masks

Clicking on the name of a mask expands a list showing the individual shapes which constitute that mask.

Right-clicking on the shape name opens a drop-down menu. Here you define the way that the individual shapes interact to form the mask. You can also remove shapes from that mask.

Masks are constructed by adding the shapes in the order that they are listed from top to bottom. Each shape adds to the mask by using at your choice one out of four logical set operators.

As order matters when combining shapes you may move each shape up or down if needed.

Each shape before being added can be inverted and is then depicted by the symbol.

3.3.7.5. Set operators

We use as an example a combination of a gradient followed by a path to demonstrate the effect of the set operator which we apply to the path shape. As a convention we say that a pixel is selected in a mask or shape if it has a value higher than zero.
 
union
This is the default set operator. It is depicted by the symbol left to the shape name. The shape adds to the existing mask in such a way that the resulting mask contains the pixels that are either selected in the existing mask or in the added shape. In overlapping areas the maximum value is taken.
intersection
This set operator is depicted by the symbol left to the shape name. The shape adds to the existing mask in such a way that the resulting mask contains only pixels that are selected in both, the existing mask and the added shape. In overlapping areas the minimum value is used. In the given example we use this operator to imprint the path with a gradient.
difference
This set operator is depicted by the symbol. In the non-overlapping area the existing mask is unchanged. In the resulting mask pixels get selected only if they are selected in the existing mask but not in the added shape. This set operator can be chosen if you want to cut out a region from within an existing selection.
exclusion
This set operator is depicted by the symbol. The resulting mask has all pixels selected that are either selected in the existing mask and not in the added shape or vice versa. This is equivalent to an exclusive or.