[gnuastro-commits] master b4a75567: Library (fits.h): encoded datasum string

[Mohammad Akhlaghi]

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

    Library (fits.h): encoded datasum string
    
    Until now, Gnuastro's 'fits.h' library would only return the raw (integer)
    datasum value. But in some scenarios, having the fixed-length, ASCII
    encoded string which is available for the 'CHECKSUM' keyword in FITS is
    more useful.
    
    With this commit a function has been added to the library for this and the
    new '--datasum-encoded' option has been added to the Fits program.
---
 NEWS                |  6 ++++++
 bin/fits/args.h     | 13 +++++++++++++
 bin/fits/fits.c     | 17 +++++++++++++++--
 bin/fits/main.h     |  1 +
 bin/fits/ui.c       | 17 +++++++++--------
 bin/fits/ui.h       |  1 +
 doc/gnuastro.texi   |  8 ++++++++
 lib/fits.c          | 23 +++++++++++++++++++++++
 lib/gnuastro/fits.h |  4 ++++
 9 files changed, 80 insertions(+), 10 deletions(-)

diff --git a/NEWS b/NEWS
index 19246af7..28b23576 100644
--- a/NEWS
+++ b/NEWS
@@ -73,6 +73,11 @@ See the end of the file for license conditions.
     - collapse-sigclip-fill-median: Collapse dim. by filled sigma-clip. median.
     - collapse-sigclip-fill-number: Collapse dim. by filled sigma-clipped num.
 
+*** Fits
+  --datasum-encoded: new option that will return an ASCII encoded
+    16-character string for the value of the 'DATASUM' concept in FITS data
+    verification.
+
 *** Statistics
   --mad: Median Absolute Deviation (MAD) of input dataset.
   --madclip: MAD-clipping, showing intermediate results.
@@ -108,6 +113,7 @@ See the end of the file for license conditions.
   - gal_dimension_collapse_sclip_fill_mean: filled sigma-clipped mean
   - gal_dimension_collapse_sclip_fill_median: filled sigma-clipped median.
   - gal_dimension_collapse_sclip_fill_number: filled sigma-clipped number.
+  - gal_fits_hdu_datasum_encoded: the 16-character encoded sting datasum.
   - gal_fits_key_list_add_date: add 'DATE' to current list of keywords.
   - gal_fits_key_list_add_git_commit: add the Git commit information of the
     running directory to the input list of keywords (if built with libgit2).
diff --git a/bin/fits/args.h b/bin/fits/args.h
index 0461cc99..08a0dd89 100644
--- a/bin/fits/args.h
+++ b/bin/fits/args.h
@@ -63,6 +63,19 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_MANDATORY,
       GAL_OPTIONS_NOT_SET
     },
+    {
+      "datasum-encoded",
+      UI_KEY_DATASUMENCODED,
+      0,
+      0,
+      "16 character string encoding of '--datasum'.",
+      UI_GROUP_EXTENSION_INFORMATION,
+      &p->datasumencoded,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
     {
       "pixelscale",
       UI_KEY_PIXELSCALE,
diff --git a/bin/fits/fits.c b/bin/fits/fits.c
index af49352e..2a839b8f 100644
--- a/bin/fits/fits.c
+++ b/bin/fits/fits.c
@@ -348,7 +348,20 @@ fits_hdu_number(struct fitsparams *p)
 static void
 fits_datasum(struct fitsparams *p)
 {
-  printf("%ld\n", gal_fits_hdu_datasum(p->input->v, p->cp.hdu, "--hdu"));
+  char *out;
+
+  if(p->datasum)
+    printf("%ld\n", gal_fits_hdu_datasum(p->input->v, p->cp.hdu, "--hdu"));
+  else if(p->datasumencoded)
+    {
+      out=gal_fits_hdu_datasum_encoded(p->input->v, p->cp.hdu, "--hdu");
+      printf("%s\n", out);
+      free(out);
+    }
+  else
+    error(EXIT_FAILURE, 0, "%s: a bug! Please contact us at '%s' to fix "
+          "this bug! Both 'datasum' and 'datasumencoded' are zero",
+          __func__, PACKAGE_BUGREPORT);
 }
 
 
@@ -890,7 +903,6 @@ fits(struct fitsparams *p)
 
       /* Options that must be called alone. */
       if(p->numhdus)               fits_hdu_number(p);
-      else if(p->datasum)          fits_datasum(p);
       else if(p->pixelscale)       fits_pixelscale(p);
       else if(p->pixelareaarcsec2) fits_pixelarea(p);
       else if(p->skycoverage)      fits_skycoverage(p);
@@ -899,6 +911,7 @@ fits(struct fitsparams *p)
       else if(p->listimagehdus)    fits_certain_hdu(p, 1, 0);
       else if(p->listtablehdus)    fits_certain_hdu(p, 1, 1);
       else if(p->listallhdus)      fits_list_all_hdus(p);
+      else if(p->datasum || p->datasumencoded) fits_datasum(p);
 
       /* Options that can be called together. */
       else
diff --git a/bin/fits/main.h b/bin/fits/main.h
index 2cc9d524..d11c8cb9 100644
--- a/bin/fits/main.h
+++ b/bin/fits/main.h
@@ -64,6 +64,7 @@ struct fitsparams
   gal_list_str_t       *cut;   /* Copy ext. to output and remove.       */
   uint8_t           numhdus;   /* Print number of HDUs in FITS file.    */
   uint8_t           datasum;   /* Calculate and print HDU's datasum.    */
+  uint8_t    datasumencoded;   /* Calculate and print HDU's datasum.    */
   uint8_t        pixelscale;   /* Calculate and print HDU's pixelscale. */
   uint8_t  pixelareaarcsec2;   /* Return pixel area in arcsec^2.        */
   uint8_t       skycoverage;   /* Calculate and image coverage in WCS.  */
diff --git a/bin/fits/ui.c b/bin/fits/ui.c
index 7fe217ab..558a8b2a 100644
--- a/bin/fits/ui.c
+++ b/bin/fits/ui.c
@@ -469,9 +469,9 @@ ui_read_check_mode_extension(struct fitsparams *p)
   uint8_t stdoutcheck=0;
 
   if( p->remove || p->copy || p->cut || p->numhdus || p->datasum
-      || p->pixelscale || p->pixelareaarcsec2 || p->skycoverage
-      || p->hastablehdu || p->hasimagehdu || p->listtablehdus
-      || p->listimagehdus )
+      || p->datasumencoded || p->pixelscale || p->pixelareaarcsec2
+      || p->skycoverage || p->hastablehdu || p->hasimagehdu
+      || p->listtablehdus || p->listimagehdus )
     {
       /* A small sanity check. */
       if(p->mode!=FITS_MODE_INVALID)
@@ -479,10 +479,10 @@ ui_read_check_mode_extension(struct fitsparams *p)
               "cannot be called together");
 
       /* Some HDU options cannot be called with other options. */
-      stdoutcheck = ( p->numhdus + p->datasum + p->pixelscale
-                      + p->pixelareaarcsec2 + p->skycoverage
-                      + p->hastablehdu + p->hasimagehdu + p->listtablehdus
-                      + p->listimagehdus );
+      stdoutcheck = ( p->numhdus + p->datasum + p->datasumencoded
+                      + p->pixelscale + p->pixelareaarcsec2
+                      + p->skycoverage + p->hastablehdu + p->hasimagehdu
+                      + p->listtablehdus + p->listimagehdus );
 
       /* Make sure if an output file is needed. */
       if(stdoutcheck)
@@ -672,7 +672,8 @@ ui_fill_fits_headerll(gal_list_str_t *input, 
gal_fits_list_key_t **output,
       if(keyname)
         {
           if( !strcasecmp(keyname,"checksum")
-              || !strcasecmp(keyname,"datasum") )
+              || !strcasecmp(keyname,"datasum")
+              || !strcasecmp(keyname,"datasum-encoded"))
             needsvalue=0;
         }
 
diff --git a/bin/fits/ui.h b/bin/fits/ui.h
index 3889fc1e..67da4b1c 100644
--- a/bin/fits/ui.h
+++ b/bin/fits/ui.h
@@ -75,6 +75,7 @@ enum option_keys_enum
      automatically). */
   UI_KEY_TITLE        = 1000,
   UI_KEY_DATASUM,
+  UI_KEY_DATASUMENCODED,
   UI_KEY_PIXELSCALE,
   UI_KEY_PIXELAREAONWCS,
   UI_KEY_PIXELAREAARCSEC2,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index ae73ef57..9a80e294 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -16080,6 +16080,11 @@ For more on @code{DATASUM} in the FITS standard, see 
@ref{Keyword inspection and
 
 You can use this option to confirm that the data in two different HDUs 
(possibly with different keywords) is identical.
 Its advantage over @option{--write=datasum} (which writes the @code{DATASUM} 
keyword into the given HDU) is that it does not require write permissions.
+
+@item --datasum-encoded
+Similar to @option{--datasum}, except that the output will be an encoded 
string of numbers and small-caps alphabetic characters.
+This is the same encoding algorithm that is used for the @code{CHECKSUM} 
keyword, but applied to the value of the @code{DATASUM} result.
+In some scenarios, this string can be more useful than the raw integer.
 @end table
 
 The following options manipulate (move/delete) the HDUs in one FITS file or to 
another FITS file.
@@ -39167,7 +39172,10 @@ Return the number of HDUs/extensions in 
@file{filename}.
 Return the @code{DATASUM} of the given HDU in the given FITS file.
 For more on @code{DATASUM} in the FITS standard, see @ref{Keyword inspection 
and manipulation} (under the @code{checksum} component of @option{--write}).
 For more on @code{hdu_option_name} see the description of 
@code{gal_fits_hdu_open}.
+@end deftypefun
 
+@deftypefun {unsigned long} gal_fits_hdu_datasum_encoded (char 
@code{*filename}, char @code{*hdu}, char @code{*hdu_option_name})
+Similar to @code{gal_fits_hdu_datasum}, but the returned value is always a 
16-character string following the encoding that is described in the FITS 
standard (primarily for the @code{CHECKSUM} keyword, but can also be used for 
@code{DATASUM}.
 @end deftypefun
 
 @deftypefun {unsigned long} gal_fits_hdu_datasum_ptr (fitsfile @code{*fptr})
diff --git a/lib/fits.c b/lib/fits.c
index 35b5acb4..733c2d3a 100644
--- a/lib/fits.c
+++ b/lib/fits.c
@@ -746,6 +746,29 @@ gal_fits_hdu_datasum(char *filename, char *hdu, char 
*hdu_option_name)
 
 
 
+/* Calculate the encoded datasum of the given HDU in the given file. */
+char *
+gal_fits_hdu_datasum_encoded(char *filename, char *hdu, char *hdu_option_name)
+{
+  char *out;
+  unsigned long datasum;
+
+  /* Allocate a 17 character string (the encoded string is by definition 16
+     characters long and we need a 17th one for '\0'). */
+  out=gal_pointer_allocate(GAL_TYPE_UINT8, 17, 0, __func__, "out");
+
+  /* Generate the datasum as an integer. */
+  datasum=gal_fits_hdu_datasum(filename, hdu, hdu_option_name);
+
+  /* Encode the 'datasum' and return the string. */
+  fits_encode_chksum(datasum, 0, out);
+  return out;
+}
+
+
+
+
+
 /* Calculate the FITS standard datasum for the opened FITS pointer. */
 unsigned long
 gal_fits_hdu_datasum_ptr(fitsfile *fptr)
diff --git a/lib/gnuastro/fits.h b/lib/gnuastro/fits.h
index 0de258e2..d2a89401 100644
--- a/lib/gnuastro/fits.h
+++ b/lib/gnuastro/fits.h
@@ -167,6 +167,10 @@ gal_fits_hdu_num(char *filename);
 unsigned long
 gal_fits_hdu_datasum(char *filename, char *hdu, char *hdu_option_name);
 
+char *
+gal_fits_hdu_datasum_encoded(char *filename, char *hdu,
+                             char *hdu_option_name);
+
 unsigned long
 gal_fits_hdu_datasum_ptr(fitsfile *fptr);