[gnuastro-commits] master c70f16c 2/2: Crop: new option to write crop in primary (0-th) HDU

[Mohammad Akhlaghi]

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

    Crop: new option to write crop in primary (0-th) HDU
    
    Until now, like all programs, Crop would leave the first (0-th) HDU empty
    of data (only for keeping metadata) and write the cropped image into the
    next HDU. This is suggested by the FITS standard and is good for storing
    meta data like configuration parameters. But in some scenarios (especially
    when feeding into non-Gnuastro programs that only accept input in the 0-th
    extension), this can be annoying.
    
    With this commit the Crop program has a new option called '--primaryimghdu'
    (same name of similar option in the Fits program). When this option is
    given, the output crop will be written into the primary extension.
    
    This was relatively easy to do for Crop in particular because Crop doesn't
    use the default Gnuastro library function to write FITS files, *and* Crop
    doesn't have too much configuration and writes its basic metadata in the
    same extension as the data (it only has an output of one extension). For
    other programs this will be more tricky to implement.
---
 NEWS               |  5 +++++
 bin/crop/args.h    | 13 +++++++++++++
 bin/crop/main.h    |  1 +
 bin/crop/onecrop.c |  7 +++++--
 bin/crop/ui.h      |  1 +
 doc/gnuastro.texi  | 10 +++++++++-
 6 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/NEWS b/NEWS
index 6666289..32268ab 100644
--- a/NEWS
+++ b/NEWS
@@ -49,6 +49,11 @@ See the end of the file for license conditions.
      - 'makenew': new operator to create an empty (zero-valued) new dataset
        with given dimension and size (given as operands).
 
+  Crop:
+   --primaryimghdu: Write the final cropped image into the primary (or
+     0-th) extension of the output FITS file, so the output only has
+     one extension.
+
   Fits:
    - New '--skycoverage' option will report the area of the input image in
      RA/Dec, both in units of center/width, and box minimum/maximum
diff --git a/bin/crop/args.h b/bin/crop/args.h
index e721395..aabb716 100644
--- a/bin/crop/args.h
+++ b/bin/crop/args.h
@@ -90,6 +90,19 @@ struct argp_option program_options[] =
 
     /* Output. */
     {
+      "primaryimghdu",
+      UI_KEY_PRIMARYIMGHDU,
+      0,
+      0,
+      "Write crop in primary/zero-th HDU of output.",
+      GAL_OPTIONS_GROUP_OUTPUT,
+      &p->primaryimghdu,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
+    {
       "noblank",
       UI_KEY_NOBLANK,
       0,
diff --git a/bin/crop/main.h b/bin/crop/main.h
index 07ffed5..ab05ba5 100644
--- a/bin/crop/main.h
+++ b/bin/crop/main.h
@@ -85,6 +85,7 @@ struct cropparams
   size_t               hendwcs;  /* Header keyword No. to end read WCS.   */
   int                     mode;  /* Image or WCS mode.                    */
   uint8_t       zeroisnotblank;  /* ==1: In float or double, keep 0.0.    */
+  uint8_t        primaryimghdu;  /* ==1: write in primary/0-th HDU.       */
   uint8_t              noblank;  /* ==1: no blank (out of image) pixels.  */
   char                 *suffix;  /* Ending of output file name.           */
   gal_data_t    *incheckcenter;  /* Value given to '--checkcenter'.       */
diff --git a/bin/crop/onecrop.c b/bin/crop/onecrop.c
index 2cb337f..142096d 100644
--- a/bin/crop/onecrop.c
+++ b/bin/crop/onecrop.c
@@ -554,8 +554,11 @@ onecrop_make_array(struct onecropparams *crp, long 
*fpixel_i,
      generally everything from 1). */
   if(fits_create_file(&ofp, outname, &status))
     gal_fits_io_error(status, "creating file");
-  fits_create_img(ofp, SHORT_IMG, 0, naxes, &status);
-  fits_close_file(ofp, &status);
+  if(crp->p->primaryimghdu==0)
+    {
+      fits_create_img(ofp, SHORT_IMG, 0, naxes, &status);
+      fits_close_file(ofp, &status);
+    }
 
 
   /* Create the output crop image. */
diff --git a/bin/crop/ui.h b/bin/crop/ui.h
index daf22aa..e1b4261 100644
--- a/bin/crop/ui.h
+++ b/bin/crop/ui.h
@@ -71,6 +71,7 @@ enum option_keys_enum
   UI_KEY_POLYGONOUT,
   UI_KEY_POLYGONSORT,
   UI_KEY_CHECKCENTER,
+  UI_KEY_PRIMARYIMGHDU,
 };
 
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index bd6e5c7..6105e9f 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -10845,6 +10845,10 @@ One case where this might be helpful is when besides 
the science images, you wan
 So in one run, you can set the input images to the science images and 
@option{--suffix=_s.fits}.
 In the next run you can set the weight images as input and 
@option{--suffix=_w.fits}.
 
+@item --primaryimghdu
+Write the output into the primary (0-th) HDU/extension of the output.
+By default, like all Gnuastro's default outputs, no data is written in the 
primary extension because the FITS standard suggests keeping that extension 
free of data and only for meta data.
+
 @item -b
 @itemx --noblank
 Pixels outside of the input image that are in the crop box will not be used.
@@ -10883,7 +10887,7 @@ on how many crops were requested, see @ref{Crop modes}:
 @itemize
 @item
 When a catalog is given, the value of the @option{--output} (see @ref{Common 
options}) will be read as the directory to store the output cropped images.
-Hence if it doesn't already exist, Crop will abort with an error of a ``No 
such file or directory'' error.
+Hence if it doesn't already exist, Crop will abort with an ``No such file or 
directory'' error.
 
 The crop file names will consist of two parts: a variable part (the row number 
of each target starting from 1) along with a fixed string which you can set 
with the @option{--suffix} option.
 Optionally, you may also use the @option{--namecol} option to define a column 
in the input catalog to use as the file name instead of numbers.
@@ -10893,6 +10897,10 @@ When only one crop is desired, the value to 
@option{--output} will be read as a
 If no output is specified or if it is a directory, the output file name will 
follow the automatic output names of Gnuastro, see @ref{Automatic output}: The 
string given to @option{--suffix} will be replaced with the @file{.fits} suffix 
of the input.
 @end itemize
 
+By default, as suggested by the FITS standard and implemented in all Gnuastro 
programs, the first/primary extension of the output files will only contain 
meta data.
+The cropped images/cubes will be written into the 2nd HDU of their respective 
FITS file (which is actually counted as @code{1} because HDU counting starts 
from @code{0}).
+However, if you want the cropped data to be written into the primary (0-th) 
HDU, run Crop with the @option{--primaryimghdu} option.
+
 The header of each output cropped image will contain the names of the input 
image(s) it was cut from.
 If a name is longer than the 70 character space that the FITS standard allows 
for header keyword values, the name will be cut into several keywords from the 
nearest slash (@key{/}).
 The keywords have the following format: @command{ICFn_m} (for Crop File).