[gnuastro-commits] master 16419fda 11/23: astscript-rgb-faint-gray: following Gnuastro standards for HDU arguments

[Mohammad Akhlaghi]

branch: master
commit 16419fda8b4e01f2dd71184c78e23c1d4451c60c
Author: Raul Infante-Sainz <infantesainz@gmail.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    astscript-rgb-faint-gray: following Gnuastro standards for HDU arguments
    
    Until this commit, the way HDUs were specified was not the standard by
    Gnuastro. The origin of this is that the script was not originally part of
    Gnuastro. However, in order to include this into Gnuastro, this issue has
    to be fixed to follow the Gnuastro standards.
    
    With this commit, the way HDUs are specified has been changed. Now it
    follows the Gnuastro standards (i.e., multiple HDUs have to be provided,
    one for each input image, or alternatively, use --globalhdu).
---
 bin/script/Makefile.am       |   4 +-
 bin/script/rgb-faint-gray.sh | 103 ++++++++++++++++++-------------------------
 doc/gnuastro.texi            |  36 ++++++++-------
 3 files changed, 64 insertions(+), 79 deletions(-)

diff --git a/bin/script/Makefile.am b/bin/script/Makefile.am
index 4d1b7bdb..18bf03f2 100644
--- a/bin/script/Makefile.am
+++ b/bin/script/Makefile.am
@@ -42,12 +42,12 @@ astscript-fits-view.desktop: 
$(srcdir)/fits-view.desktop.desktop Makefile
 bin_SCRIPTS = astscript-fits-view \
               astscript-psf-unite \
               astscript-psf-stamp \
-              astscript-rgb-faint-gray \
               astscript-zeropoint \
               astscript-ds9-region \
               astscript-psf-subtract \
               astscript-sort-by-night \
               astscript-radial-profile \
+              astscript-rgb-faint-gray \
               astscript-psf-scale-factor \
               astscript-psf-select-stars \
               astscript-pointing-simulate
@@ -55,13 +55,13 @@ bin_SCRIPTS = astscript-fits-view \
 EXTRA_DIST = fits-view.sh \
              psf-unite.sh \
              psf-stamp.sh \
-             rgb-faint-gray.sh \
              zeropoint.sh \
              zeropoint.mk \
              ds9-region.sh \
              psf-subtract.sh \
              sort-by-night.sh \
              radial-profile.sh \
+             rgb-faint-gray.sh \
              psf-select-stars.sh \
              psf-scale-factor.sh \
              pointing-simulate.sh \
diff --git a/bin/script/rgb-faint-gray.sh b/bin/script/rgb-faint-gray.sh
index a440be8b..62fed84d 100644
--- a/bin/script/rgb-faint-gray.sh
+++ b/bin/script/rgb-faint-gray.sh
@@ -44,7 +44,7 @@ export LANG=C
 
 # Default option values (can be changed with options on the command-line).
 hdu=""
-hdus=""
+globalhdu=""
 
 # Minimum, zeropoint, and weight values
 minimum=""
@@ -125,9 +125,8 @@ experienced Gnuastro users and developers. For more 
information, please run:
 
 $scriptname options:
  Input:
-  -h, --hdus=STR          HDU/extensions (comma separated) for the R,G,B,K 
FITS images.
-  -H, --hdu=STR           Common HDU/extension for the (R,G,B,K) channel FITS 
images
-                          (this overrides -h or --hdus).
+  -h, --hdu=STR           HDU/extension for the inputs (R,G,B,K) channels.
+  -g, --globalhdu=STR/INT Use this HDU for all inputs, ignore '--hdu'.
 
   -m, --minimums=FLT      Minimum values (comma separated) to be mapped to 
black (zero).
   -M, --minimum=FLT       Common minimum value to be mapped to black (zero).
@@ -144,7 +143,7 @@ $scriptname options:
  Contrast and brightness
   -b, --brightness        Change the brightness of the final image (linear).
   -c, --contrast          Change the contrast of the final image (linear).
-  -g, --gamma             Gamma parameter for gamma transformation (non linear,
+  -G, --gamma             Gamma parameter for gamma transformation (non linear,
                           this overrides --brightness or --contrast)
 
  Color and gray parameters
@@ -245,12 +244,13 @@ while [ $# -gt 0 ]
 do
     case "$1" in
         # Input parameters.
-        -h|--hdus)          hdus="$2";                             check_v 
"$1" "$hdus";  shift;shift;;
-        -h=*|--hdus=*)      hdus="${1#*=}";                        check_v 
"$1" "$hdus";  shift;;
-        -h*)                hdus=$(echo "$1"  | sed -e's/-h//');   check_v 
"$1" "$hdus";  shift;;
-        -H|--hdu)           hdu="$2";                              check_v 
"$1" "$hdu";  shift;shift;;
-        -H=*|--hdu=*)       hdu="${1#*=}";                         check_v 
"$1" "$hdu";  shift;;
-        -H*)                hdu=$(echo "$1"  | sed -e's/-H//');    check_v 
"$1" "$hdu";  shift;;
+        -h|--hdu)     aux="$2";                             check_v "$1" 
"$aux"; hdu="$hdu $aux"; shift;shift;;
+        -h=*|--hdu=*) aux="${1#*=}";                        check_v "$1" 
"$aux"; hdu="$hdu $aux"; shift;;
+        -h*)          aux="$(echo "$1"  | sed -e's/-h//')"; check_v "$1" 
"$aux"; hdu="$hdu $aux"; shift;;
+
+        -g|--globalhdu)      globalhdu="$2";                                 
check_v "$1" "$globalhdu";  shift;shift;;
+        -g=*|--globalhdu=*)  globalhdu="${1#*=}";                            
check_v "$1" "$globalhdu";  shift;;
+        -g*)                 globalhdu=$(echo "$1"  | sed -e's/-g//');       
check_v "$1" "$globalhdu";  shift;;
 
         -m|--minimums)      minimums="$2";                             check_v 
"$1" "$minimums";  shift;shift;;
         -m=*|--minimums=*)  minimums="${1#*=}";                        check_v 
"$1" "$minimums";  shift;;
@@ -275,9 +275,9 @@ do
         -Q=*|--qbright=*)   qbright="${1#*=}";                         check_v 
"$1" "$qbright";  shift;;
         -Q*)                qbright=$(echo "$1"  | sed -e's/-Q//');    check_v 
"$1" "$qbright";  shift;;
 
-        -g|--gamma)          gamma="$2";                                 
check_v "$1" "$gamma";  shift;shift;;
-        -g=*|--gamma=*)      gamma="${1#*=}";                            
check_v "$1" "$gamma";  shift;;
-        -g*)                 gamma=$(echo "$1"  | sed -e's/-g//');       
check_v "$1" "$gamma";  shift;;
+        -G|--gamma)          gamma="$2";                                 
check_v "$1" "$gamma";  shift;shift;;
+        -G=*|--gamma=*)      gamma="${1#*=}";                            
check_v "$1" "$gamma";  shift;;
+        -G*)                 gamma=$(echo "$1"  | sed -e's/-G//');       
check_v "$1" "$gamma";  shift;;
         -c|--contrast)       contrast="$2";                              
check_v "$1" "$contrast";  shift;shift;;
         -c=*|--contrast=*)   contrast="${1#*=}";                         
check_v "$1" "$contrast";  shift;;
         -c*)                 contrast=$(echo "$1"  | sed -e's/-c//');    
check_v "$1" "$contrast";  shift;;
@@ -340,60 +340,40 @@ if [ x"$inputs" = x ]; then
 fi
 
 
-# Make sure three or four (for the gray background) inputs have been given.
+# Inputs. Make sure three or four inputs have been given.
 ninputs=$(echo "$inputs" | awk '{print NF}')
 if [ $ninputs != 3 ] && [ $ninputs != 4 ]; then
-    echo "$scriptname: $ninputs inputs given, but 3 (or 4) inputs are 
necessary: one for each of the R,G,B,(K) channels respectively."
-    exit 1
-fi
-
-
-# If no HDU extension is given, let the user know.
-if [ x"$hdu" = x ] && [ x"$hdus" = x ]; then
-    echo "$scriptname: no input HDU extension(s) given."
-    echo "Run with '--help' for more information on how to run."
+    cat <<EOF
+$scriptname: $ninputs inputs given, but 3 (or 4) inputs are necessary: one for 
each of the R,G,B,(K) channels, respectively. Run with '--help' for more 
information on how to run.
+EOF
     exit 1
+else
+    rimage=$(echo $inputs | awk '{print $1}')
+    gimage=$(echo $inputs | awk '{print $2}')
+    bimage=$(echo $inputs | awk '{print $3}')
+    kimage=$(echo $inputs | awk '{print $4}')
 fi
 
 
-
-
-
-# Asign basic input variables
-# ---------------------------
-#
-# Images from the inputs from redder to bluer: R,G,B,K.
-rimage=$(echo $inputs | awk '{print $1}')
-gimage=$(echo $inputs | awk '{print $2}')
-bimage=$(echo $inputs | awk '{print $3}')
-kimage=$(echo $inputs | awk '{print $4}')
-
-
-# Make sure different HDUs have been provided properly
-if [ x$hdus != x ]; then
-    nhdus=$(echo "$hdus" | awk 'BEGIN{FS=","}{print NF}')
-    if [ $nhdus != $ninputs ]; then
-        echo "$scriptname: $ninputs HDUs '-h' or '--hdus' should be given 
(comma separated)."
-        exit 1
-    fi
-    # Set the different zeropoints in case they are three
-    rhdu=$(echo "$hdus" | awk 'BEGIN{FS=","}{print $1}')
-    ghdu=$(echo "$hdus" | awk 'BEGIN{FS=","}{print $2}')
-    bhdu=$(echo "$hdus" | awk 'BEGIN{FS=","}{print $3}')
-    khdu=$(echo "$hdus" | awk 'BEGIN{FS=","}{print $4}')
-fi
-
-# Use a common HDU if it is provided
-if [ x$hdu != x ]; then
-    nhdu=$(echo "$hdu" | awk 'BEGIN{FS=","}{print NF}')
-    if [ $nhdu != 1 ]; then
-        echo "$scriptname: a single value for '-H' or '--hdu' should be given."
+# HDU. If the user provides a globalhdu use it, otherwise check that HDU
+# number matches with input images
+if [ x"$globalhdu" != x ]; then
+    rhdu=$globalhdu
+    ghdu=$globalhdu
+    bhdu=$globalhdu
+    khdu=$globalhdu
+else
+    nhdu=$(echo "$hdu" | awk '{print NF}')
+    if [ x"$nhdu" != x"$ninputs" ]; then
+        cat <<EOF
+$scriptname: not enough HDUs. Every input FITS image needs a HDU (identified 
by name or number, counting from zero). You can use multiple calls to the 
'--hdu' ('-h') option for each input FITS image (in the same order as the input 
FITS files), or use '--globalhdu' ('-g') once when the same HDU should be used 
for all of them. Run with '--help' for more information on how to run.
+EOF
         exit 1
     fi
-    rhdu=$hdu
-    ghdu=$hdu
-    bhdu=$hdu
-    khdu=$hdu
+    rhdu=$(echo "$hdu" | awk '{print $1}')
+    ghdu=$(echo "$hdu" | awk '{print $2}')
+    bhdu=$(echo "$hdu" | awk '{print $3}')
+    khdu=$(echo "$hdu" | awk '{print $4}')
 fi
 
 
@@ -778,6 +758,9 @@ fi
 # If the user wants the black background image
 if [ x$black = x1 ]; then
 
+    # Change the output name to include the "black" word.
+    output=$(echo $output | sed -e's/gray/black/')
+
     # Make the color figure
     # ---------------------
     #
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 54318722..3acfea67 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -8938,7 +8938,7 @@ To start, it is important to provide the input images in 
the order of decreasing
 Let's run the script with its default options on the aligned SDSS M51 images:
 
 @example
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --output m51-default.pdf
 @end example
 
@@ -8952,7 +8952,7 @@ For each image it could be a diferent value, in that case 
you should provide com
 In this particular case, a minimum value of zero for all images is suitable: 
@option{--minimums=0,0,0} or @option{--minimum=0}.
 
 @example
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 --output m51-min0.pdf
 @end example
 The difference with respect to the default image is not too much given the 
homogeneity of the input images.
@@ -8964,7 +8964,7 @@ The estimated values are displayed at the end of the 
script's execution.
 Let's decrease @option{--qbright} by an order of magnitude in order to improve 
the display of the very bright regions.
 
 @example
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --qbright 1.481888e-02 \
                       --output m51-min0-qbright.pdf
@@ -8975,7 +8975,7 @@ Now, decrease the parameter @option{--stretch} to present 
the areas around very
 This allows you to reveal fainter regions, such as outer parts of galaxies, 
spiral arms, stellar streams, and similar structures.
 
 @example
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --qbright 1.481888e-02 \
                       --stretch 1.481888e-04 \
@@ -8991,7 +8991,7 @@ In order to have a shorter acommand-line examples, in 
what follow we will use th
 Let's use the @option{--black} option to create a black background images.
 
 @example
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --black \
                       --output m51-min0-gray.pdf
@@ -9009,7 +9009,7 @@ There is also another similar option that separates the 
black and gray regions,
 Start by reducing @option{--colorval} to 50.0 (the default is 99.5) to display 
fewer regions in color (only the very bright regions):
 
 @example
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --colorval 50.0 \
                       --output m51-min0-gray-colorval.pdf
@@ -9046,7 +9046,7 @@ To modify the color balance of the output image, you can 
weigh the three channel
 For example, by using @option{--weights 1,1,4}, you give four times more 
weight to the blue channel than to the red and green channels:
 
 @example
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --weights 1,1,4 \
                       --output m51-min0-gray-bluer.pdf
@@ -9068,12 +9068,12 @@ To illustrate the impact of adjusting image contrast, 
we will generate an image
 
 @example
 ## Default contrast
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --output m51-min0-gray-default.pdf
 
 ## Increased contrast
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --contrast 3 \
                       --output m51-min0-gray-contrast.pdf
@@ -9087,13 +9087,13 @@ Lower gamma values will enhance faint structures, while 
higher values will empha
 
 @example
 ## Using gamma 0.3
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --gamma 0.3 \
                       --output m51-min0-gray-gamalow.pdf
 
 ## Using gamma 2.0
-$ astscript-rgb-faint-gray i.fits r.fits g.fits --hdu 1 \
+$ astscript-rgb-faint-gray i.fits r.fits g.fits -g1 \
                       --minimum 0.0 \
                       --gamma 2.0 \
                       --output m51-min0-gray-gamahigh.pdf
@@ -34252,12 +34252,14 @@ A full description of each option is given below:
 
 @table @code
 @item -h
-@itemx --hdus=STR,STR,STR,[STR]
-HDU/extensions (comma separated) for each R, G, B, and K FITS images.
+@itemx --hdu=STR/INT
+Input HDU name or counter (counting from 0) for each input FITS file.
+If the same HDU should be used from all the FITS files, you can use the 
@option{--globalhdu} option described below.
 
-@item -H
-@itemx --hdu=STR
-Common HDU/extension for the (R, G, B, K) channel FITS images (this overrides 
-h or --hdus).
+@item -g
+@itemx --globalhdu=STR/INT
+Use the value given to this option (a HDU name or a counter, starting from 0) 
for the HDU identifier of all the input FITS files.
+This is useful when all the inputs are distributed in different files, but 
have the same HDU in those files.
 
 @item -m
 @itemx --minimums=FLT,FLT,FLT,[FLT]
@@ -34344,7 +34346,7 @@ Change the contrast of the final image.
 This is applied at the same time as @option{--brightness}, see above.
 The transformation is: 
@mymath{\rm{output}=\rm{contrast}\times{image}+brightness}.
 
-@item -g
+@item -G
 @itemx --gamma=FLT
 Gamma exponent value for a gamma transformation.
 This transformation is not linear: @mymath{\rm{output}=\rm{image}^{gamma}}.