3.2.9. Combining drawn and parametric masks

This section describes how darktable combines individual masks to form the final mask of a module. Individual masks are the drawn mask and all the single channels of the parametric mask. The topic is rather advanced – if you don't want to go through all the theoretical details just jump down where we describe two typical use cases.

3.2.9.1. Overview

There are two main elements which control how individual masks are combined: the polarity setting of each individual mask, defined by the plus or minus buttons, and the setting in the combine masks combobox (see Section 3.2.5, “Blending”).

Masks can be regarded as grayscale images which take up values between 0 and 1.0 (or from 0% to 100%) for each pixel.

A straightforward way to combine masks is by multiplying the individual pixel values. The final mask will have a pixel value of 0 whenever one of the individual masks is 0 at that pixel location. The final mask can only reach a maximum pixel value of 1.0 if each and every of the individual masks has a value of 1.0 at that location. We call this way of combination exclusive. Any individual mask can exclude a pixel by setting its value to zero, regardless of what the other individual masks do. Once a pixel is excluded (its value is 0) by any mask there is no way to include it again by any other individual mask.

An alternative way to combine masks is the following: we first invert each individual mask  – calculating 1.0 minus its value – then we multiply these inverted masks and as a last step invert the final mask again. Now if one of the non-inverted individual masks has a value of 1.0 at a pixel location the final will also be 1.0. The final mask can only reach a pixel value of 0 if all the individual masks have a value of 0. We call this way of combination inclusive. Any individual mask can include a pixel by setting its value to 1.0, regardless of what the other individual masks do. Once a pixel is included (its value is 1.0) by any mask there is no way to exclude it again by any other individual mask.

These two combination methods alone would still be rather limiting. We gain maximum flexibility by allowing an additional inversion step for each individual mask. This is governed by the polarity buttons and that you find close to the individual channels. Toggling the polarity button of a mask inverts its values, i.e. it recalculates the pixel values to 1.0 minus the original value.

Finally within the combine masks combobox you may once again invert the final result to fit your needs by selecting the exclusive & inverted or inclusive & inverted options.

3.2.9.2. Usage

You will typically want to combine drawn and parametric masks to first select a certain region of your image – either by the drawn or the parametric mask – and use the other mask type to finetune your selection. Finetuning can either mean that you want to include further parts of the image, which are not included in the first place, or you want to exclude parts of the image that were previously included.

This gives two typical use cases:

Inclusive mode

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.

Exclusive mode

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.