maskmanager.xml
<!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % darktable_dtd SYSTEM "../../dtd/darktable.dtd">
%darktable_dtd;
]>
<sect2 status="final" id="mask_manager">
<title>Mask manager</title>
<indexterm>
<primary>darkroom panels</primary>
<secondary>mask manager</secondary>
</indexterm>
<indexterm>
<primary>mask manager</primary>
</indexterm>
<sect3>
<title>Overview</title>
<para>
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.
</para>
</sect3>
<sect3>
<title>Usage</title>
<informaltable frame="none">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="6*"/>
<colspec colwidth="4*"/>
<tbody>
<row>
<entry>
In the top line of the masks manager panel you find buttons to create new shapes.
They are the same as in the <emphasis>drawn mask</emphasis> GUI (see
<xref linkend="drawn_mask"/> for more details).
</entry>
<entry>
<graphic fileref="darkroom/images/panel_maskmanager_1.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The lines below list all masks used and all individual shapes defined. The masks are noted
with a headline in the form <quote>grp levels</quote> 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
<inlinegraphic fileref="&masks_used;" scalefit="1" width="2%" align="center"/>
symbol to the right of the shape name.
</para>
</sect3>
<sect3>
<title>Shapes</title>
<para>
By default shapes receive an automatically generated name, consisting of the shape type
(<quote>brush</quote>, <quote>circle</quote>, <quote>ellipse</quote>, <quote>path</quote>,
<quote>gradient</quote>) 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
<quote>house front</quote> makes it easier to get the right shape, rather than something
like <quote>path #32</quote>.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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 <xref linkend="export_selected"/>).
</para>
</sect3>
<sect3>
<title>Masks</title>
<para>
Clicking on the name of a mask expands a list showing the individual shapes which
constitute that mask.
</para>
<informaltable frame="none">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="6*"/>
<colspec colwidth="4*"/>
<tbody>
<row>
<entry>
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.
</entry>
<entry>
<graphic fileref="darkroom/images/panel_maskmanager_2.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
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.
</para>
<para>
As order matters when combining shapes you may move each shape up or down if needed.
</para>
<para>
Each shape before being added can be inverted and is then depicted by the
<inlinegraphic fileref="&masks_invert;" scalefit="1" width="2%" align="center"/>
symbol.
</para>
</sect3>
<sect3>
<title>Set operators</title>
<informaltable frame="none">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="6*"/>
<colspec colwidth="4*"/>
<tbody>
<row>
<entry>
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 <quote>selected</quote> in a mask or shape if it has a
value higher than zero.
</entry>
<entry>
<graphic fileref="darkroom/images/panel_maskmanager_ex1.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
<row>
<entry></entry>
<entry>
<graphic fileref="darkroom/images/panel_maskmanager_ex2.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect4>
<title>union</title>
<informaltable frame="none">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="6*"/>
<colspec colwidth="4*"/>
<tbody>
<row>
<entry>
This is the default set operator. It is depicted by the
<inlinegraphic fileref="&masks_union;" scalefit="1" width="4%" align="center"/>
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.
</entry>
<entry>
<graphic fileref="darkroom/images/panel_maskmanager_ex3.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4>
<title>intersection</title>
<informaltable frame="none">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="6*"/>
<colspec colwidth="4*"/>
<tbody>
<row>
<entry>
This set operator is depicted by the
<inlinegraphic fileref="&masks_intersection;" scalefit="1" width="4%" align="center"/>
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 <quote>imprint</quote> the
path with a gradient.
</entry>
<entry>
<graphic fileref="darkroom/images/panel_maskmanager_ex4.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4>
<title>difference</title>
<informaltable frame="none">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="6*"/>
<colspec colwidth="4*"/>
<tbody>
<row>
<entry>
This set operator is depicted by the
<inlinegraphic fileref="&masks_difference;" scalefit="1" width="4%" align="center"/>
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 <emphasis>not</emphasis> in the added shape. This set operator can be
chosen if you want to <quote>cut out</quote> a region from within an existing
selection.
</entry>
<entry>
<graphic fileref="darkroom/images/panel_maskmanager_ex5.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4>
<title>exclusion</title>
<informaltable frame="none">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="6*"/>
<colspec colwidth="4*"/>
<tbody>
<row>
<entry>
This set operator is depicted by the
<inlinegraphic fileref="&masks_exclusion;" scalefit="1" width="4%" align="center"/>
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 <quote>exclusive or</quote>.
</entry>
<entry>
<graphic fileref="darkroom/images/panel_maskmanager_ex6.png" scalefit="1" width="80%" align="center" />
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
</sect3>
</sect2>
