Describe auto_*_sigma settings and use std::optional

cpp/radler.cc

@@ -156,7 +156,7 @@ void Radler::Perform(bool& reachedMajorThreshold, size_t majorIterationNr) {
   double stddev = integrated.StdDevFromMAD();
   Logger::Info << "Estimated standard deviation of background noise: "
                << FluxDensity::ToNiceString(stddev) << '\n';
-  if (_settings.autoMask && _autoMaskIsFinished) {
+  if (_settings.auto_mask_sigma && _autoMaskIsFinished) {
     // When we are in the second phase of automasking, don't use
     // the RMS background anymore
     _parallelDeconvolution->SetRMSFactorImage(Image());
@@ -208,13 +208,12 @@ void Radler::Perform(bool& reachedMajorThreshold, size_t majorIterationNr) {
       _parallelDeconvolution->SetRMSFactorImage(std::move(rmsImage));
     }
   }
-  if (_settings.autoMask && !_autoMaskIsFinished)
+  if (_settings.auto_mask_sigma && !_autoMaskIsFinished)
     _parallelDeconvolution->SetThreshold(
-        std::max(stddev * _settings.autoMaskSigma, _settings.threshold));
-  else if (_settings.autoDeconvolutionThreshold)
-    _parallelDeconvolution->SetThreshold(
-        std::max(stddev * _settings.autoDeconvolutionThresholdSigma,
-                 _settings.threshold));
+        std::max(stddev * *_settings.auto_mask_sigma, _settings.threshold));
+  else if (_settings.auto_threshold_sigma)
+    _parallelDeconvolution->SetThreshold(std::max(
+        stddev * *_settings.auto_threshold_sigma, _settings.threshold));
   integrated.Reset();
 
   Logger::Debug << "Loading PSFs...\n";
@@ -222,14 +221,14 @@ void Radler::Perform(bool& reachedMajorThreshold, size_t majorIterationNr) {
       residualSet.LoadAndAveragePSFs();
 
   if (_settings.algorithm_type == AlgorithmType::kMultiscale) {
-    if (_settings.autoMask) {
+    if (_settings.auto_mask_sigma) {
       if (_autoMaskIsFinished)
         _parallelDeconvolution->SetAutoMaskMode(false, true);
       else
         _parallelDeconvolution->SetAutoMaskMode(true, false);
     }
   } else {
-    if (_settings.autoMask && _autoMaskIsFinished) {
+    if (_settings.auto_mask_sigma && _autoMaskIsFinished) {
       if (_autoMask.empty()) {
         _autoMask.resize(_imgWidth * _imgHeight);
         for (size_t imgIndex = 0; imgIndex != modelSet.size(); ++imgIndex) {
@@ -246,7 +245,8 @@ void Radler::Perform(bool& reachedMajorThreshold, size_t majorIterationNr) {
   _parallelDeconvolution->ExecuteMajorIteration(
       residualSet, modelSet, psfImages, reachedMajorThreshold);
 
-  if (!reachedMajorThreshold && _settings.autoMask && !_autoMaskIsFinished) {
+  if (!reachedMajorThreshold && _settings.auto_mask_sigma &&
+      !_autoMaskIsFinished) {
     Logger::Info << "Auto-masking threshold reached; continuing next major "
                     "iteration with deeper threshold and mask.\n";
     _autoMaskIsFinished = true;

cpp/settings.h

@@ -82,10 +82,40 @@ struct Settings {
    */
   double major_loop_gain = 1.0;
 
-  bool autoDeconvolutionThreshold = false;
-  bool autoMask = false;
-  double autoDeconvolutionThresholdSigma = 0.0;
-  double autoMaskSigma = 0.0;
+  /**
+   * @brief Sigma value for automatically setting the cleaning threshold.
+   *
+   * If set, Radler will calculate the standard deviation of the residual image
+   * before the start of every major deconvolution iteration, and clean up to
+   * this sigma value times the found noise standard deviation. The standard
+   * deviation is calculated using the medium absolute deviation, which is a
+   * robust estimator that is not very sensitive to source structure still
+   * present in the image.
+   *
+   * If unset, automatic thresholding is not used.
+   */
+  std::optional<double> auto_threshold_sigma = std::nullopt;
+
+  /**
+   * @brief Sigma value for automatically creating and applying mask images.
+   *
+   * If set, Radler performs these steps:
+   * # Radler starts cleaning towards a threshold of the given sigma value.
+   * # Once the sigma level is reached, Radler generates a mask using the
+   * positions and scale of each component (when using multi-scale cleaning).
+   * # Cleaning then continues until the final threshold value, as set using the
+   * @ref threshold or @ref auto_threshold_sigma values. During this final step,
+   * the generated mask constrains the cleaning.
+   *
+   * If unset, automatic masking is not used.
+   *
+   * Using auto masking has two advantages:
+   * - Radler generates and applies mask images in a single run.
+   * - Radler maintains scale-dependent masks, which improves multi-scale
+   * cleaning.
+   */
+  std::optional<double> auto_mask_sigma = std::nullopt;
+
   bool saveSourceList = false;
   size_t deconvolutionIterationCount = 0;
   size_t majorIterationCount = 20;