[gnuastro-commits] master 1560a54 022/113: Default NoiseChisel kernel in 3D changed to 1.5 pixels

[Mohammad Akhlaghi]

branch: master
commit 1560a54a92b48a401ad8a8c2bafc450e712cdac9
Author: Mohammad Akhlaghi <akhlaghi@gnu.org>
Commit: Mohammad Akhlaghi <akhlaghi@gnu.org>

    Default NoiseChisel kernel in 3D changed to 1.5 pixels
    
    Until now the default NoiseChisel kernel in 3D had a 2 pixel FWHM in the
    first two dimensions (similar to the 2D case). However, this mixes the 3D
    dataset's voxels (smooths) too much. Note how here, the shrinking of the
    dynamic range (and possibly skewing the distribution) of the dataset
    (signal+noise) is the primary factor. I currently feel that sampling is
    only important as it relates to the ratios between the different
    dimensions.
    
    I also noticed that in the manual, there was no discussion on the default
    3D kernel properties, so they were added.
---
 bin/noisechisel/kernel-3d.h | 140 +++++++++++++++-----------------------------
 bin/noisechisel/ui.c        |  17 +++++-
 doc/gnuastro.texi           |  33 ++++++++---
 3 files changed, 84 insertions(+), 106 deletions(-)

diff --git a/bin/noisechisel/kernel-3d.h b/bin/noisechisel/kernel-3d.h
index 6a3dbed..96a274b 100644
--- a/bin/noisechisel/kernel-3d.h
+++ b/bin/noisechisel/kernel-3d.h
@@ -1,98 +1,50 @@
-size_t kernel_3d_dsize[3]={7, 13, 13};
-float kernel_3d[1183]={0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+size_t kernel_3d_dsize[3]={5, 9, 9};
+float kernel_3d[405]={0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
 
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 1.485799e-07, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 2.746858e-07, 1.807235e-06, 3.431401e-06, 1.838885e-06, 
2.798509e-07, 0, 0, 0, 0,
-0, 0, 0, 0, 1.859928e-06, 1.146277e-05, 2.261949e-05, 1.195174e-05, 
1.743884e-06, 0, 0, 0, 0,
-0, 0, 0, 1.457355e-07, 3.317235e-06, 2.253982e-05, 4.076775e-05, 2.208206e-05, 
3.396871e-06, 1.474514e-07, 0, 0, 0,
-0, 0, 0, 0, 1.8064e-06, 1.195441e-05, 2.113626e-05, 1.198961e-05, 1.72606e-06, 
0, 0, 0, 0,
-0, 0, 0, 0, 2.834052e-07, 1.820066e-06, 3.449281e-06, 1.89521e-06, 
2.803539e-07, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 1.44856e-07, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 5.293481e-07, 1.391654e-06, 5.283476e-07, 0, 0, 0,
+0, 0, 5.023404e-06, 0.0001093707, 0.0003028791, 0.0001103754, 5.206822e-06, 0, 
0,
+0, 5.27038e-07, 0.0001140605, 0.002517939, 0.006957374, 0.002468025, 
0.0001131454, 5.31773e-07, 0,
+0, 1.481738e-06, 0.0002994444, 0.006708808, 0.01894199, 0.006776441, 
0.0003116253, 1.493134e-06, 0,
+0, 5.293459e-07, 0.0001081432, 0.002473192, 0.006704316, 0.002578867, 
0.0001105525, 4.866729e-07, 0,
+0, 0, 4.985141e-06, 0.000110672, 0.0002885369, 0.0001184523, 4.688276e-06, 0, 
0,
+0, 0, 0, 5.610833e-07, 1.336052e-06, 5.216995e-07, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
 
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 1.234796e-08, 9.878367e-08, 1.020775e-06, 9.878367e-08, 
1.234796e-08, 0, 0, 0, 0,
-0, 0, 0, 4.939184e-08, 7.326431e-06, 4.693479e-05, 8.266516e-05, 4.69633e-05, 
6.999201e-06, 4.939184e-08, 0, 0, 0,
-0, 0, 1.234796e-08, 6.85008e-06, 0.0001643393, 0.001056819, 0.001962634, 
0.001032768, 0.0001649413, 6.859012e-06, 1.234796e-08, 0, 0,
-0, 0, 9.878367e-08, 4.576423e-05, 0.001047376, 0.00684491, 0.01280988, 
0.006805513, 0.001082551, 4.551054e-05, 9.878367e-08, 0, 0,
-0, 0, 9.986172e-07, 8.921415e-05, 0.001990294, 0.01254342, 0.02374495, 
0.0126314, 0.001925766, 8.45066e-05, 1.011709e-06, 0, 0,
-0, 0, 9.878367e-08, 4.649093e-05, 0.001060791, 0.006822467, 0.01247382, 
0.007007569, 0.001065096, 4.461473e-05, 9.878367e-08, 0, 0,
-0, 0, 1.234796e-08, 7.275932e-06, 0.0001640168, 0.00106862, 0.001938186, 
0.001079752, 0.0001645134, 7.191654e-06, 1.234796e-08, 0, 0,
-0, 0, 0, 4.939184e-08, 6.87645e-06, 4.4285e-05, 8.624209e-05, 4.65561e-05, 
6.938224e-06, 4.939184e-08, 0, 0, 0,
-0, 0, 0, 0, 1.234796e-08, 9.878367e-08, 1.048286e-06, 9.878367e-08, 
1.234796e-08, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 3.462786e-07, 7.853481e-06, 2.153742e-05, 7.564613e-06, 3.611804e-07, 0, 
0,
+0, 3.52808e-07, 7.161698e-05, 0.001676089, 0.004618002, 0.001656355, 
7.414426e-05, 3.43867e-07, 0,
+0, 7.990315e-06, 0.001704389, 0.03857445, 0.1031222, 0.03779064, 0.001703231, 
7.975499e-06, 0,
+0, 2.231775e-05, 0.00473238, 0.1043504, 0.2858114, 0.10241, 0.004618072, 
2.193002e-05, 0,
+0, 7.621142e-06, 0.001647367, 0.03755038, 0.1036048, 0.03796006, 0.001672143, 
7.758124e-06, 0,
+0, 3.68421e-07, 7.659229e-05, 0.001695716, 0.004599371, 0.001670764, 
7.450273e-05, 3.481919e-07, 0,
+0, 0, 3.521386e-07, 7.924394e-06, 2.207155e-05, 7.889852e-06, 3.53245e-07, 0, 
0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
 
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 6.173979e-09, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 6.173979e-09, 1.975673e-07, 3.458353e-06, 6.472969e-06, 3.47083e-06, 
1.975673e-07, 6.173979e-09, 0, 0, 0,
-0, 0, 6.173979e-09, 7.902694e-07, 4.513072e-05, 0.0002927972, 0.0005428808, 
0.0002944311, 4.433255e-05, 7.902694e-07, 6.173979e-09, 0, 0,
-0, 0, 1.975673e-07, 4.542675e-05, 0.001045313, 0.006685175, 0.01239065, 
0.00679263, 0.001044551, 4.52873e-05, 1.975673e-07, 0, 0,
-0, 0, 3.391631e-06, 0.0002917077, 0.006763012, 0.0440967, 0.08055502, 
0.04359836, 0.006787267, 0.0002969475, 3.295347e-06, 0, 0,
-0, 6.173979e-09, 6.250698e-06, 0.0005457952, 0.01255168, 0.08104536, 0.150408, 
0.08023416, 0.01253388, 0.000535345, 6.40636e-06, 6.173979e-09, 0,
-0, 0, 1.580539e-06, 0.0002882469, 0.006713877, 0.04338823, 0.08082015, 
0.04357146, 0.006704987, 0.0002913436, 1.580539e-06, 0, 0,
-0, 0, 1.975673e-07, 4.445576e-05, 0.00105628, 0.006745212, 0.0125202, 
0.006786238, 0.001058999, 4.54068e-05, 1.975673e-07, 0, 0,
-0, 0, 6.173979e-09, 7.902694e-07, 4.506374e-05, 0.00029103, 0.0005455695, 
0.0002928559, 4.558354e-05, 7.902694e-07, 6.173979e-09, 0, 0,
-0, 0, 0, 6.173979e-09, 1.975673e-07, 3.41195e-06, 6.359724e-06, 1.580539e-06, 
1.975673e-07, 6.173979e-09, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 6.173979e-09, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 5.182329e-07, 1.397928e-06, 5.17901e-07, 0, 0, 0,
+0, 0, 4.812169e-06, 0.0001135803, 0.0003043477, 0.000109481, 4.974718e-06, 0, 
0,
+0, 5.377616e-07, 0.0001073098, 0.002424047, 0.006817353, 0.002492242, 
0.0001147361, 5.33439e-07, 0,
+0, 1.44089e-06, 0.0002933802, 0.006909565, 0.01873765, 0.006651767, 
0.0003042257, 1.366647e-06, 0,
+0, 5.166781e-07, 0.0001119049, 0.002454791, 0.006940499, 0.002578837, 
0.0001061706, 5.329928e-07, 0,
+0, 0, 4.656712e-06, 0.0001124511, 0.0003010639, 0.0001131462, 4.786908e-06, 0, 
0,
+0, 0, 0, 5.303103e-07, 1.363214e-06, 5.122773e-07, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
 
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 1.234796e-08, 9.878367e-08, 9.757257e-07, 9.878367e-08, 
1.234796e-08, 0, 0, 0, 0,
-0, 0, 0, 4.939184e-08, 6.978876e-06, 4.588304e-05, 8.4791e-05, 4.664944e-05, 
7.174984e-06, 4.939184e-08, 0, 0, 0,
-0, 0, 1.234796e-08, 7.018961e-06, 0.0001637559, 0.001060732, 0.001981034, 
0.0010486, 0.0001597786, 7.174912e-06, 1.234796e-08, 0, 0,
-0, 0, 9.878367e-08, 4.663123e-05, 0.001044997, 0.006716454, 0.01270765, 
0.006864154, 0.001047177, 4.60964e-05, 9.878367e-08, 0, 0,
-0, 0, 1.012701e-06, 8.26145e-05, 0.002013659, 0.0127906, 0.023479, 0.01250077, 
0.001970029, 8.642203e-05, 9.922311e-07, 0, 0,
-0, 0, 9.878367e-08, 4.552128e-05, 0.001030169, 0.006799623, 0.01275112, 
0.007000111, 0.001071859, 4.659725e-05, 9.878367e-08, 0, 0,
-0, 0, 1.234796e-08, 7.110504e-06, 0.0001573054, 0.001044423, 0.001932773, 
0.001080642, 0.0001619574, 6.927679e-06, 1.234796e-08, 0, 0,
-0, 0, 0, 4.939184e-08, 6.894978e-06, 4.457595e-05, 8.273318e-05, 4.60869e-05, 
7.289148e-06, 4.939184e-08, 0, 0, 0,
-0, 0, 0, 0, 1.234796e-08, 9.878367e-08, 9.978808e-07, 9.878367e-08, 
1.234796e-08, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 1.520727e-07, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 2.777842e-07, 1.819656e-06, 3.497153e-06, 1.862236e-06, 
2.800668e-07, 0, 0, 0, 0,
-0, 0, 0, 0, 1.814004e-06, 1.22698e-05, 2.187492e-05, 1.239061e-05, 
1.843132e-06, 0, 0, 0, 0,
-0, 0, 0, 1.385601e-07, 3.35185e-06, 2.165249e-05, 4.046146e-05, 2.121244e-05, 
3.392139e-06, 1.534694e-07, 0, 0, 0,
-0, 0, 0, 0, 1.827893e-06, 1.199963e-05, 2.301149e-05, 1.166906e-05, 
1.823535e-06, 0, 0, 0, 0,
-0, 0, 0, 0, 2.809536e-07, 1.730059e-06, 3.307363e-06, 1.8598e-06, 
2.946499e-07, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 1.439844e-07, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0,
+0, 0, 0, 0, 0, 0, 0, 0, 0};
diff --git a/bin/noisechisel/ui.c b/bin/noisechisel/ui.c
index d35b3ff..d8d9a62 100644
--- a/bin/noisechisel/ui.c
+++ b/bin/noisechisel/ui.c
@@ -417,7 +417,7 @@ ui_set_output_names(struct noisechiselparams *p)
 
        $ export GSL_RNG_SEED=1
        $ export GSL_RNG_TYPE=ranlxs2
-       $ astmkprof --kernel=gaussian-3d,2,5,0.5 --oversample=1 --envseed
+       $ astmkprof --kernel=gaussian-3d,1.5,5,0.5 --oversample=1 --envseed
 
    The resulting fits file was converted to text with the this C program to
    generate the `kernel-3d.h' header file (until ConvertType supports 3D
@@ -447,7 +447,18 @@ ui_set_output_names(struct noisechiselparams *p)
                  if(i % img->dsize[2]                 == 0 ) printf("\n");
                 if(i % (img->dsize[2]*img->dsize[1]) == 0 ) printf("\n");
               }
-             printf(i==(img->size-1) ? "%.7g": "%.7g, ", arr[i]);
+
+            // We cannot use `\b' here, since we are writing directly
+            // to the command-line, so we'll first write the number,
+            // then decide if any subsequent character (a comma)
+            // should be written.
+            printf("%.7g", arr[i]);
+
+            // The last element doesn't need a comma. In each line,
+            // the last character must not be a space, but for easy
+            // readability, the elements in between need a space.
+            if( i!=(img->size-1) )
+              printf("%s", ((i+1)%img->dsize[2]) ? ", " : ",");
            }
          printf("};\n");
 
@@ -792,7 +803,7 @@ ui_read_check_inputs_setup(int argc, char *argv[],
       else
         printf(p->kernel->ndim==2
                ? "  - Kernel: FWHM=2 pixel Gaussian.\n"
-               : "  - Kernel: FWHM=2 pixel Gaussian (half extent in "
+               : "  - Kernel: FWHM=1.5 pixel Gaussian (half extent in "
                "3rd dimension).\n");
     }
 }
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 52bbb43..2b8b30a 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -12234,11 +12234,12 @@ A convolution kernel can also be optionally given. If 
a value (file name)
 is given to @option{--kernel} on the command-line or in a configuration
 file (see @ref{Configuration files}), then that file will be used to
 convolve the image prior to thresholding. Otherwise a default kernel will
-be used. The default kernel is a 2D Gaussian with a FWHM of 2 pixels
-truncated at 5 times the FWHM. This choice of the default kernel is
-discussed in Section 3.1.1 of @url{https://arxiv.org/abs/1505.01664,
-Akhlaghi and Ichikawa [2015]}. See @ref{Convolution kernel} for kernel
-related options.
+be used. For a 2D image, the default kernel is a 2D Gaussian with a FWHM of
+2 pixels truncated at 5 times the FWHM. This choice of the default kernel
+is discussed in Section 3.1.1 of @url{https://arxiv.org/abs/1505.01664,
+Akhlaghi and Ichikawa [2015]}. For a 3D cube, it is a Gaussian with FWHM of
+1.5 pixels in the first two dimensions and 0.75 pixels in the third
+dimension. See @ref{Convolution kernel} for kernel related options.
 
 NoiseChisel defines two tessellations over the input (see
 @ref{Tessellation}). This enables it to deal with possible gradients in the
@@ -12350,10 +12351,24 @@ quantile threshold (see @option{--qthresh}). The 
convolved image is also
 used to define the clumps (see Section 3.2.1 and Figure 8 of
 @url{https://arxiv.org/abs/1505.01664, Akhlaghi and Ichikawa [2015]}).
 
-The @option{--kernel} option is not mandatory. If no kernel is provided, a
-2D Gaussian profile with a FWHM of 2 pixels truncated at 5 times the FWHM
-is used. This choice of the default kernel is discussed in Section 3.1.1 of
-Akhlaghi and Ichikawa [2015].
+To build any kernel in one command (for input into this option), you can
+use MakeProfile's @option{--kernel} option, see @ref{MakeProfiles output
+dataset}.
+
+The @option{--kernel} option is not mandatory. If no kernel is provided and
+the input is a 2D image, a 2D Gaussian profile with a FWHM of 2 pixels
+truncated at 5 times the FWHM is used. This choice of the default kernel is
+discussed in Section 3.1.1 of Akhlaghi and Ichikawa [2015].
+
+For a 3D cube, when no file name is given to @option{--kernel}, a Gaussian
+with FWHM of 1.5 pixels in the first two dimensions and 0.75 pixels in the
+third dimension will be used. The reason for this particular configuration
+is that commonly in astronomical applications, 3D datasets don't have the
+same nature in all three dimensions, commonly the first two dimensions are
+spatial (RA and Dec) while the third is spectral (for example
+wavelength). The samplings are also different, in the default case, the
+spatial sampling is assumed to be larger than the spectral sampling, hence
+a wider FWHM in the spatial directions, see @ref{Sampling theorem}.
 
 @item --khdu=STR
 HDU containing the kernel in the file given to the @option{--kernel}