[gnuastro-commits] master 0a8324f 059/113: MakeProfiles kernel option can be elongated in 3rd-dimension

[Mohammad Akhlaghi]

branch: master
commit 0a8324f7d8279ca56c189d9df580c64ab29ad83a
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    MakeProfiles kernel option can be elongated in 3rd-dimension
    
    Until now, when using the `--kernel' option, it was only possible to have
    the third dimension be at most as extended as the first two. However,
    during my tests on MUSE datasets, cases came up that it would be useful to
    have the kernel extended in the third dimension more than the first two.
    
    With this commit, the last value of the 3D kernel profiles can be a value
    larger than 1 and in such cases, the kernel will be elongated in the third
    dimension (bullet-shaped). The description of this option for the book has
    also been modified.
---
 bin/mkprof/ui.c   | 42 ++++++++++++++++++++++--------------------
 doc/gnuastro.texi | 32 ++++++++++++++++++++++----------
 2 files changed, 44 insertions(+), 30 deletions(-)

diff --git a/bin/mkprof/ui.c b/bin/mkprof/ui.c
index 86250c0..6e3ffb9 100644
--- a/bin/mkprof/ui.c
+++ b/bin/mkprof/ui.c
@@ -424,21 +424,6 @@ ui_parse_kernel(struct argp_option *option, char *arg,
                       kernel->size, kernel->size>1?"s are":" is");
 
 
-      /* If we want a 3D kernel, the last value (axis ratio) must be
-         positive and smaller and equal to 1. Note that we have already
-         checked for everything to be positive, so it can't be negative at
-         this point.
-
-         IMPORTANT NOTE: a `point' profile can have a kernel parameter list
-         of zero elements. So we need to make sure there are actually
-         numbers in the list also. */
-      if(kernel->flag==3 && kernel->size && darray[kernel->size-1]>1.0f)
-        error(EXIT_FAILURE, 0, "%g (last value in the list of kernel "
-              "parameters `%s') is interpretted as the kernel axis ratio "
-              "along the third dimension. Hence it must not be larger than 1",
-              darray[kernel->size-1], arg);
-
-
       /* Our job is done, return NULL. */
       return NULL;
     }
@@ -1063,7 +1048,7 @@ static void
 ui_prepare_columns(struct mkprofparams *p)
 {
   double *karr;
-  float r, n, t;
+  float r, n, t, q2;
 
   /* If the kernel option was called, then we need to build a series of
      single element columns to create an internal catalog. */
@@ -1115,10 +1100,27 @@ ui_prepare_columns(struct mkprofparams *p)
       p->t[0]  = t;
       if(p->ndim==3)
         {
-          p->z[0]  = 0.0f;
-          p->p2[0] = 0.0f;
-          p->p3[0] = 0.0f;
-          p->q2[0] = p->kernel->size ? karr[ p->kernel->size - 1 ] : 0.0f;
+          /* Parameters for any case. */
+          p->z[0] = 0.0f;
+          q2      = p->kernel->size ? karr[ p->kernel->size - 1 ] : 0.0f;
+
+          /* 3rd-dim axis ratio > 1: Set the major axis in the direction of
+             the 3rd dimension (90 degree rotation for all three
+             rotations). Also set the two axis ratios to the inverse of the
+             requested value. */
+          if(q2>1.0)
+            {
+              p->q1[0] = p->q2[0] = 1/q2;
+              p->p1[0] = p->p2[0] = p->p3[0] = 90.0;
+            }
+
+          /* 3rd-dim axis ratio <=1: No extra rotation is necessary and
+             `q2'can simply be put in the respective column. */
+          else
+            {
+              p->q2[0] = q2;
+              p->p2[0] = p->p3[0] = 0.0;
+            }
         }
     }
   else
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index cbca5a0..9a3684f 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -18374,21 +18374,26 @@ the FWHM.
 
 This option may also be used to create a 3D kernel. To do that, two small
 modifications are necessary: add a @code{-3d} (or @code{-3D}) to the
-profile name (for example @code{moffat-3d}) and add a fraction (value
-between 0 and 1) to the end of the parameters for all profiles except
-@code{point}. The fractional value is the axis ratio in the third
-dimension. The main reason behind the fractional value is that commonly in
-3D astronomical datasets the third dimension doesn't have the same nature
-as the first and second.
+profile name (for example @code{moffat-3d}) and add a number (axis-ratio
+along the third dimension) to the end of the parameters for all profiles
+except @code{point}. The main reason behind providing an axis ratio in the
+third dimension is that in 3D astronomical datasets, commonly the third
+dimension doesn't have the same nature (units/sampling) as the first and
+second.
 
 For example in IFU datacubes, the first and second dimensions are angular
 positions (like RA and Dec) but the third is in units of Angstroms for
 wavelength. Because of this different nature (which also affects the
 processing), it may be necessary for the kernel to have a different extent
-in that direction@footnote{So far, only cases where the third dimension
-extent must be less than the first two have been useful for us. If you need
-it to be larger, then please contact us and we will implement it.}. For
-example, let's have a look at the two examples above but in 3D:
+in that direction.
+
+If the 3rd dimension axis ratio is equal to @mymath{1.0}, then the kernel
+will be a spheroid. If its smaller than @mymath{1.0}, the kernel will be
+button-shaped: extended less in the third dimension. However, when it is
+larger than @mymath{1.0}, the kernel will be bullet-shaped: extended more
+in the third dimension. In the latter case, the radial parameter will
+correspond to the length along the 3rd dimension. For example, let's have a
+look at the two examples above but in 3D:
 
 @table @option
 @item --kernel=moffat-3d,3,2.8,5,0.5
@@ -18402,6 +18407,13 @@ A spherical Gaussian kernel with FWHM of 2 pixels and 
truncated at 3 times
 the FWHM.
 @end table
 
+Ofcourse, if a specific kernel is needed that doesn't fit the constraints
+imposed by this option, you can always use a catalog to define any
+arbitrary kernel. Just call the @option{--individual} and
+@option{--nomerged} options to make sure that it is built as a separate
+file (individually) and no ``merged'' image of the input profiles is
+created.
+
 @item -x INT,INT
 @itemx --naxis=INT,INT
 The number of pixels along each dimension axis of the output in FITS