[gnuastro-commits] master 92d3f204: MakeCatalog: --checkuplim now returns label's random tile center

[Mohammad Akhlaghi]

branch: master
commit 92d3f2044accfa83877ac30942079889d72a3a11
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    MakeCatalog: --checkuplim now returns label's random tile center
    
    Until now, when MakeCatalog was called with '--checkuplim', it would return
    the position of the first pixel of the random positioning of the label's
    tile. Estimating the width and height of the object (using '--min-x',
    '--max-x', '--min-y' and '--max-y') was annoying and would usually be
    forgotten usually (most commonly by myself!).
    
    As a result, when users would use these positions to place profiles (for
    example in upper-limit measurements of elliptical profiles) and wouldn't
    correct for the width, the randomly placed objects could fall over a
    detection!
    
    With this commit, this option now returns the center of the label's tile
    instead of the "first" pixel.
    
    This issue was discovered after a discussion with Teet Kuutma (initially I
    thought it is a bug because I had forgot that the reported position is the
    first pixel, not the center!)..
---
 NEWS                         |  7 +++++++
 bin/mkcatalog/upperlimit.c   | 31 ++++++++++++++++++-------------
 doc/announce-acknowledge.txt |  1 +
 doc/gnuastro.texi            | 16 ++++++++++++----
 4 files changed, 38 insertions(+), 17 deletions(-)

diff --git a/NEWS b/NEWS
index 9f0cf83b..16dc17fc 100644
--- a/NEWS
+++ b/NEWS
@@ -207,6 +207,13 @@ See the end of the file for license conditions.
     --sum-error: new name for '--brightnesserr'.
     --clumps-sum: new name for '--clumpbrightness'.
     --sum-no-river: new name for '--brightnessnoriver'.
+  --checkuplim: now returns the center of each label's tile, not the first
+    pixel (the bottom-left pixel position of the tile). The old behavior to
+    return the first pixel was un-intuitive, would require several manual
+    steps (to measure the minimum and maximum positions of each tile,
+    measure the width along each dimension and add it), and could lead to
+    confusing results when ignored. See the updated documentation of this
+    option for more on custom usage in special situations.
   - Using a hyphen to help in readability and usability:
        Old name                         New name
        ========                         ========
diff --git a/bin/mkcatalog/upperlimit.c b/bin/mkcatalog/upperlimit.c
index c6dac25e..0470e162 100644
--- a/bin/mkcatalog/upperlimit.c
+++ b/bin/mkcatalog/upperlimit.c
@@ -401,16 +401,17 @@ upperlimit_write_check(struct mkcatalogparams *p, 
gal_list_sizet_t *check_x,
 
 
   /* Write exactly what object/clump this table is for. */
-  gal_fits_key_list_title_add_end(&keylist, "Target for upper-limit check", 0);
+  gal_fits_key_list_title_add_end(&keylist, "Target for upper-limit "
+                                  "check", 0);
   mkcatalog_outputs_keys_numeric(&keylist, &p->checkuplim[0],
                                  GAL_TYPE_INT32, "UPCHKOBJ",
-                                 "Object label for upper-limit check target.",
-                                 NULL);
+                                 "Object label for upper-limit check "
+                                 "target.", NULL);
   if( p->checkuplim[1]!=GAL_BLANK_INT32 )
     mkcatalog_outputs_keys_numeric(&keylist, &p->checkuplim[1],
                                    GAL_TYPE_INT32, "UPCHKCLU",
-                                   "Clump label for upper-limit check target.",
-                                   NULL);
+                                   "Clump label for upper-limit check "
+                                   "target.", NULL);
 
 
   /* Write the basic info, and conclude the keywords. */
@@ -555,6 +556,7 @@ upperlimit_one_tile(struct mkcatalog_passparams *pp, 
gal_data_t *tile,
   float *V, *st_v, *uparr=pp->up_vals->array;
   size_t min[3], max[3], increment, num_increment;
   int32_t *O, *OO, *oO, *st_o, *st_oo, *st_oc, *oC=NULL;
+  size_t hw2, hw0=tile->dsize[0]/2, hw1=tile->dsize[1]/2;
   size_t maxfails = p->upnum * MKCATALOG_UPPERLIMIT_MAXFAILS_MULTIP;
   struct gal_list_sizet_t *check_x=NULL, *check_y=NULL, *check_z=NULL;
   size_t *rcoord=gal_pointer_allocate(GAL_TYPE_SIZE_T, ndim, 0, __func__,
@@ -579,6 +581,7 @@ upperlimit_one_tile(struct mkcatalog_passparams *pp, 
gal_data_t *tile,
   tarray=tile->array;
   gsl_rng_set(pp->rng, seed);
   pp->up_vals->flag &= ~GAL_DATA_FLAG_SORT_CH;
+  hw2 = tile->ndim==3 ? tile->dsize[2]/2 : GAL_BLANK_SIZE_T;
 
 
   /* Set the range of random values for this tile. */
@@ -603,7 +606,7 @@ upperlimit_one_tile(struct mkcatalog_passparams *pp, 
gal_data_t *tile,
       /* Set the tile's new starting pointer. */
       tile->array = gal_pointer_increment(p->objects->array,
                           gal_dimension_coord_to_index(ndim, dsize, rcoord),
-                                           p->objects->type);
+                                          p->objects->type);
 
       /* Starting and ending coordinates for this random position, note
          that in 'pp' we have the starting and ending coordinates of the
@@ -672,21 +675,23 @@ upperlimit_one_tile(struct mkcatalog_passparams *pp, 
gal_data_t *tile,
       else ++nfailed;
 
 
-      /* If a check is necessary, write in the values (in FITS
-         coordinates). */
+      /* If a check is necessary, put the center of the tile independent of
+         the values/labels (in FITS coordinates). Note that 'rcoord' is the
+         position of the first pixel of the tile, so we need to add half
+         the width of the tile (the 'hw*' variables). */
       if(writecheck)
         {
           switch(ndim)
             {
             case 2:
-              gal_list_sizet_add(&check_x, rcoord[1]+1);
-              gal_list_sizet_add(&check_y, rcoord[0]+1);
+              gal_list_sizet_add(&check_x, rcoord[1]+1 + hw1);
+              gal_list_sizet_add(&check_y, rcoord[0]+1 + hw0);
               break;
 
             case 3:
-              gal_list_sizet_add(&check_x, rcoord[2]+1);
-              gal_list_sizet_add(&check_y, rcoord[1]+1);
-              gal_list_sizet_add(&check_z, rcoord[0]+1);
+              gal_list_sizet_add(&check_x, rcoord[2]+1 + hw2);
+              gal_list_sizet_add(&check_y, rcoord[1]+1 + hw1);
+              gal_list_sizet_add(&check_z, rcoord[0]+1 + hw0);
               break;
 
             default:
diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index 7c39fd36..7e5eb3ca 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -7,6 +7,7 @@ Sepideh Eskandarlou
 Zohreh Ghaffari
 Giulia Golini
 Martin Kuemmel
+Teet Kuutma
 Samane Raji
 Elham Saremi
 Nafiseh Sedighi
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 240b7c63..e359e3a3 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -5776,7 +5776,7 @@ asttable lab_upcheck.fits --noblank=RANDOM_SUM \
 ## Have a look at the regions in relation with NoiseChisel's
 ## detections.
 ds9 r_detected.fits[INPUT-NO-SKY] -regions load ds9.reg
-ds9 r_detected.fits[DETECTIONS] -regions load ds9.reg
+ds9 r_detected.fits[DETECTIONS]   -regions load ds9.reg
 @end example
 
 In this example, we were looking at a single-exposure image that has no 
correlated noise.
@@ -25949,12 +25949,20 @@ Print a table of positions and measured values for 
all the full random distribut
 If only one integer is given to this option, it is interpreted to be an 
object's label.
 If two values are given, the first is the object label and the second is the 
ID of requested clump within it.
 
-The output is a table with three columns (its type is determined with the 
@option{--tableformat} option, see @ref{Input output options}).
-The first two columns are the position of the first pixel in each random 
sampling of this particular object/clump.
+The output is a table with three columns (whether it is FITS or plain-text is 
determined with the @option{--tableformat} option, see @ref{Input output 
options}).
+The first two columns are the pixel X,Y positions of the center of each 
label's tile (see next paragraph), in each random sampling of this particular 
object/clump.
 The third column is the measured flux over that region.
 If the region overlapped with a detection or masked pixel, then its measured 
value will be a NaN (not-a-number).
-The total number of rows is thus unknown, but you can be sure that the number 
of rows with non-NaN measurements is the number given to the @option{--upnum} 
option.
+The total number of rows is thus unknown before running.
+However, if an upper-limit measurement was made in the main output of 
MakeCatalog, you can be sure that the number of rows with non-NaN measurements 
is the number given to the @option{--upnum} option.
 
+The ``tile'' of each label is defined by the minimum and maximum positions of 
each label: values of the @option{--min-x}, @option{--max-x}, @option{--min-y} 
and @option{--max-y} columns in the main output table for each label.
+Therefore, the tile center position that is recorded in the output of this 
column ignores the distribution of labeled pixels within the tile.
+
+Precise interpretation of the position is only relevant when the footprint of 
your label is highly un-symmetrical and you want to use this catalog to insert 
your object into the image.
+In such a case, you can also ask for @option{--min-x} and @option{--min-y} and 
manually calculate their difference with the following two positional 
measurements of your desired label: @option{--geo-x} and @option{--geo-y} 
(which report the label's ``geometric'' center; only using the label positions 
ignoring any ``values'') or @option{--x} and @option{--y} (which report the 
value-weighted center of the label).
+Adding the difference with the position reported by this column, will let you 
define alternative ``center''s for your label in particular situations (this 
will usually not be necessary!).
+For more on these positional columns, see @ref{Position measurements in 
pixels}.
 @end table