Image Masks
###########

Since Siril 1.5.0 image masks are supported, allowing image operations to be masked.
This can be used for example to apply a star mask to deconvolution operations to minimize
ringing, or to target a saturation boost on specific colours.

.. tip::
   Image masks only apply to single image operations - they are completely ignored for all
   sequence operations.

Masks can be 8-bit, 16-bit or 32-bit. There is a preference for the default mask bit
depth to use, though most mask creation operations allow specification of a bit depth.

.. tip::
   Within the documentation the convention is adopted where TRUE means the maximum mask
   value for the bit depth of the mask (255 for 8-bit masks, 65535 for 16-bit masks and
   1.0 for 32-bit floating point masks). FALSE refers to a zero mask value. Where the mask
   value of a pixel is TRUE, an applied image operation will be fully applied to the
   pixel; where it is FALSE, the image operation will leave the pixel completely unchanged.
   Intermediate values will blend the result of the image operation with the original image,
   so the image operation will be partly applied.

In the GUI, the mask can be toggled as active or inactive using a checkbutton built into
the Mask viewport tab. Image masks do apply to image operation commands as well but to
maintain the "stateless" approach to Siril commands, the `-mask` flag must be provided in
order to tell the command to obey the mask (the GUI checkbutton is ignored).

Mask Creation
=============
Image masks can be created in the following ways, both using the GUI and Siril commands:

* From the luminance or a channel of the current image. Luminance weighting can be based
  on human perception, evenly weighted or custom weights may be provided.
* From a separate file e.g. a star mask. The mask can be created based on image luminance
  or a channel, as with creation of a mask from the current image. Note that the width and
  height of the image used as a mask **must** match those of the image being masked.
* From chromaticity of the current image.
* From a freehand polygon drawn on the image (freehand polygons can be added to / removed
  from the image mask).
* From stars detected in the current image.
* From python scripts (via sirilpy interface). Python can specify both raster masks using
  ``set_image_mask()`` and vector masks using ``mask_add_polygon()`` and ``mask_subtract_polygon()``.

Within the GUI, image mask creation / deletion is achieved via a new submenu in the Right
Mouse Button menu. Operations on existing image masks are achieved through a new mask-specific
Right Mouse Button menu that presents when on the Masks tab of the main drawingarea.

Mask Manipulation
=================

Image masks can be manipulated in the following ways, both using the GUI and Siril commands:

* Autostretch the mask.
* Apply intensity thresholds the mask: the mask becomes TRUE between lo and hi values and
  FALSE everywhere else. This allows for setting the mask TRUE up to a certain value, TRUE
  above a certain value or TRUE in between certain values (and in conjunction with mask
  inversion, TRUE below a lo value and above a hi value and FALSE in between). A feathering
  range can also be specified. This feathers the mask over a range of pixel values above the hi
  and below the lo values to give a more gradual intensity-based mask: if a spatial feathering
  is required this can be achieved using the separate mask feathering functionality.
* Blur the mask with a Gaussian blur.
* Change the mask bit depth.
* Clear the mask (remove it from the image).
* Feather the mask spatially (a linear feather is applied. If the mask contains intermediate
  values rather than only TRUE and FALSE, the mask will first be binarized so that it is TRUE for
  values above half the maximum and FALSE elsewhere.
* Invert the mask.
* Mask gradient. This computes the magnitude of the gradient, normalized so that the maximum
  gradient is scaled to TRUE.

Image mask operations create an undo state and can therefore be undone and redone in the same
way as image operations.

.. warning::
   As with image processing commands, mask processing commands do not create an undo state.

Image Mask Operation
====================
When an image mask exists and is required to be applied, it works as follows:

* A copy of the initial image is created in memory.
* The image operation is computed.
* The result is blended with the original according to the mask value.

.. tip::
   Note that this means that the mask is **not** used at intermediate stages in an image operation
   (for example, each iteration of Richardson-Lucy deconvolution does not have the mask applied
   to it, only the final result is masked into the original image).

Image Mask Visualization
========================
The image mask is visualized in two ways:

* If an image has an image mask, it is shown in an additional tab in the main viewing area.
  This also has a toggle in the popup menu attached to the Mask viewport tab which is used to
  enable / disable the mask for GUI operations.
* Optionally, the image mask can tint the view in the main image viewports with degrees of red,
  with FALSE mask values showing as fully red, TRUE mask values showing the untinted image and
  partially masked areas showing with a partial red tint. This behaviour can be toggled on and
  off in preferences as well as from the popup menu attached to the Mask viewport tab.

Image masks are compatible with the Region of Interest processing system, although this is only
noticeable if the "tint vport" option is disabled. When performing a ROI preview, the section of
the mask corresponding to the ROI will be applied to the pixels within the ROI.

Image masks are **not** currently saved when a file is saved. It is intended to revisit this
area in future.

Applicability of Image Masks
============================

The following operations support image masks:
---------------------------------------------

* Aberration Inspector - this doesn't update the image but if the "mask tints image" option
  is enabled, then the same tint will show in the aberration inspector.
* Asinh stretch
* CLAHE
* Curves stretch
* DDP (the ``ddp`` command - in case anyone still uses it...)
* Deconvolution (Richardson-Lucy, Split Bregman and Wiener)
* Denoise
* Edge preserving filters* Generalized Hyperbolic Transform stretches
* Gaussian blur
* Histogram stretches including autostretch
* Median filter
* Negative (``neg`` command) (Note: this does not apply to the GUI "negative view" button
  as that is just a preview mode, it doesn't affect the image data)
* Rotational Gradient (L-S filter) - the use case for this might be niche, but it's
  possible someone might want a "structural" comet with normal stars and background
* Saturation
* Simple image operation commands (``iadd``, ``idiv``, ``imul``, ``isub``, ``fmul``,
  ``fdiv``, ``addmax``, ``fill``, ``ffill`` and ``offset``)
* Starnet
* Subtractive Chromatic Noise Reduction (SCNR)
* Thresholding (threshlo, threshhi, thresh commands)
* Unpurple filtering (note, currently this has an optional built-in star mask feature but
  image masks are supported in addition, and both may be used together)
* Unsharp mask (the ``unsharp`` command)

Geometry operations do not update pixel values based on the mask but they do apply the
exact same geometric transformation to the mask as to the image, ensuring that the masked
area matches after the transformation and that the mask remains the same size as the
transformed image.

The following operations do **not** support image masks:
--------------------------------------------------------

* All sequence commands.
* Analysis functions (``cdg``, ``entropy``, ``bg``, ``bgnoise``, ``stat``, ``find_cosme``,
  ``find_cosme_hot``, ``psf``, ``histo``, intensity profiling) - these don't update the image
  at all, they just print stats or update the overlay).
* Astrometric and Catalogue analysis functions (Dynamic PSF, ``findstar``, plate solving,
  companion star finding) - these don't update the iamge at all, they just analyze it.
* Banding reduction (this addresses a sensor issue so it doesn't make sense to apply to only
  part of the image).
* Channel extraction (including Ha, Ha/Oiii, Green extraction and channel / CFA splitting) -
  these create new images and masks make no sense here.
* Colour Correction Matrix (this applies to all data from the sensor so it wouldn't make
  sense to apply to only part of the image).
* Cosmetic correction, fix_xtrans, grey_flat, calibrate_single (as above, these apply to
  the full image out of the sensor).
* Deconvolution PSF creation (this doesn't update the image, so masking would have no effect).
* Fourier Transform, Pixelmath, RGB composition, A Trous Wavelets - as above, these create
  new images and masks make no sense.
* mirrorx_single - no geometry operations apply the mask to pixel values but the others do
  update the mask geometry to match that of the image. In this case, the ``mirrorx_single``
  command applies to an image on file, which can't contain a mask.
* ``nozero`` command (removal of pure zero values is something that, if required, should apply
  to the entire image).
* Python: the ``pyscript`` command and Python scripts in general do not honour the image mask, but
  they can do their own masking and have access to the Siril image mask via the SirilInterface
  methods ``get_image_mask()``, ``set_image_mask()``, ``get_image_mask_state()``,
  ``set_image_mask_state()``, ``mask_add_polygon()`` and ``mask_subtract_polygon()``.
* (Spectro)photometric Color Calibration - these apply to entire images rather than parts of
  images.
* Synthetic star functions (star resynthesis, star desaturation) - these apply to an entire
  image. I think these don't need to be mask aware, but would entertain a challenge if a
  reasonable use case for masking them can be made.
* Utility commands, for example ``boxselect``- since these don't affect the pixeldata, masks are
  irrelevant.

Mask-related Commands
=====================

.. admonition:: Siril command line
   :class: sirilcommand
   
   .. include:: ../commands/mask_autostretch_use.rst

   .. include:: ../commands/mask_autostretch.rst

.. admonition:: Siril command line
   :class: sirilcommand
   
   .. include:: ../commands/mask_bitpix_use.rst

   .. include:: ../commands/mask_bitpix.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_blur_use.rst

   .. include:: ../commands/mask_blur.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_feather_use.rst

   .. include:: ../commands/mask_feather.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_fmul_use.rst

   .. include:: ../commands/mask_fmul.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_from_channel_use.rst

   .. include:: ../commands/mask_from_channel.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_from_color_use.rst

   .. include:: ../commands/mask_from_color.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_from_lum_use.rst

   .. include:: ../commands/mask_from_lum.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_from_stars_use.rst

   .. include:: ../commands/mask_from_stars.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_invert_use.rst

   .. include:: ../commands/mask_invert.rst

.. admonition:: Siril command line
   :class: sirilcommand

   .. include:: ../commands/mask_threshold_use.rst

   .. include:: ../commands/mask_threshold.rst