[gnuastro-commits] master 2cd1cec: Fits: new --datasum for print the given HDU's datasum

[Mohammad Akhlaghi]

branch: master
commit 2cd1cec20a2ac330a738801004a1354e4ddfc899
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    Fits: new --datasum for print the given HDU's datasum
    
    Until now it was only possible to do this with the `--write=datasum' option
    which would actually need write permissions on the input file. But when we
    don't have that write permission, it was useless.
    
    With this commit, the Fits program has a new `--datasum' option that will
    only need read permission. It will estimate the value and print it on the
    command-line (for easy checking in a shell script for example).
---
 NEWS              |  3 +++
 bin/fits/args.h   | 13 +++++++++++
 bin/fits/fits.c   | 27 +++++++++++++++++++++++
 bin/fits/main.h   |  1 +
 bin/fits/ui.c     | 66 ++++++++++++++++++++++++++++++++++---------------------
 bin/fits/ui.h     |  1 +
 doc/gnuastro.texi | 23 ++++++++++++++-----
 7 files changed, 104 insertions(+), 30 deletions(-)

diff --git a/NEWS b/NEWS
index 66fef15..820f3ad 100644
--- a/NEWS
+++ b/NEWS
@@ -7,6 +7,9 @@ See the end of the file for license conditions.
 
 ** New features
 
+  Fits:
+   --datasum: Calculate and print the given HDU's "datasum" to stdout.
+
 ** Removed features
 
 ** Changed features
diff --git a/bin/fits/args.h b/bin/fits/args.h
index b4c6584..1385df9 100644
--- a/bin/fits/args.h
+++ b/bin/fits/args.h
@@ -102,6 +102,19 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_MANDATORY,
       GAL_OPTIONS_NOT_SET
     },
+    {
+      "datasum",
+      UI_KEY_DATASUM,
+      0,
+      0,
+      "Calculate HDU's datasum and print in stdout.",
+      UI_GROUP_EXTENSION,
+      &p->datasum,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
 
 
 
diff --git a/bin/fits/fits.c b/bin/fits/fits.c
index 6ecb6d6..fc69e6d 100644
--- a/bin/fits/fits.c
+++ b/bin/fits/fits.c
@@ -272,6 +272,31 @@ fits_hdu_number(struct fitsparams *p)
 
 
 static void
+fits_datasum(struct fitsparams *p)
+{
+  int status=0;
+  fitsfile *fptr;
+  unsigned long datasum, hdusum;
+
+  /* Read the first extension (necessary for reading the rest). */
+  fptr=gal_fits_hdu_open(p->filename, p->cp.hdu, READONLY);
+
+  /* Calculate the checksum and datasum of the opened HDU. */
+  fits_get_chksum(fptr, &datasum, &hdusum, &status);
+  gal_fits_io_error(status, "estimating datasum");
+
+  /* Close the file. */
+  fits_close_file(fptr, &status);
+
+  /* Print the datasum */
+  printf("%ld\n", datasum);
+}
+
+
+
+
+
+static void
 fits_hdu_remove(struct fitsparams *p, int *r)
 {
   char *hdu;
@@ -400,6 +425,8 @@ fits(struct fitsparams *p)
       /* Options that must be called alone. */
       if(p->numhdus)
         fits_hdu_number(p);
+      else if(p->datasum)
+        fits_datasum(p);
 
       /* Options that can be called together. */
       else
diff --git a/bin/fits/main.h b/bin/fits/main.h
index 6b50be2..b6631b4 100644
--- a/bin/fits/main.h
+++ b/bin/fits/main.h
@@ -61,6 +61,7 @@ struct fitsparams
   gal_list_str_t    *copy;     /* Copy extensions to output.            */
   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   primaryimghdu;     /* Copy/cut HDU into primary HDU.        */
   uint8_t    printallkeys;     /* Print all the header keywords.        */
   uint8_t            date;     /* Set DATE to current time.             */
diff --git a/bin/fits/ui.c b/bin/fits/ui.c
index ca86eee..56d2ae7 100644
--- a/bin/fits/ui.c
+++ b/bin/fits/ui.c
@@ -321,58 +321,74 @@ ui_check_copykeys(struct fitsparams *p)
 static void
 ui_read_check_only_options(struct fitsparams *p)
 {
+  uint8_t stdoutcheck;
+
   /* If any of the keyword manipulation options are requested, then set the
      mode flag to keyword-mode. */
   if( p->date || p->comment || p->history || p->asis || p->delete
       || p->rename || p->update || p->write || p->verify || p->printallkeys
       || p->copykeys || p->datetosec )
     {
-      /* Set the mode. */
-      p->mode=FITS_MODE_KEY;
-
       /* Check if a HDU is given. */
       if(p->cp.hdu==NULL)
-        error(EXIT_FAILURE, 0, "a HDU (extension) is necessary for keywrod "
+        error(EXIT_FAILURE, 0, "a HDU (extension) is necessary for keyword "
               "related options but none was defined. Please use the "
               "`--hdu' (or `-h') option to select one");
 
       /* If Copy keys has been given, read it and make sure its setup. */
       if(p->copykeys)
         ui_check_copykeys(p);
+
+      /* Currently `datetosec' must be called alone. */
+      if( p->datetosec
+          && (p->date || p->comment || p->history || p->asis || p->delete
+              || p->rename || p->update || p->write || p->verify
+              || p->printallkeys || p->copykeys) )
+        error(EXIT_FAILURE, 0, "`--datetosec' cannot currently be called "
+              "with any other option");
+
+      /* Set the operating mode. */
+      p->mode=FITS_MODE_KEY;
     }
 
   /* Same for the extension-related options */
-  if( p->remove || p->copy || p->cut || p->numhdus)
+  if( p->remove || p->copy || p->cut || p->numhdus || p->datasum )
     {
       /* A small sanity check. */
       if(p->mode!=FITS_MODE_INVALID)
         error(EXIT_FAILURE, 0, "extension and keyword manipulation options "
               "cannot be called together");
 
-      /* Unlike the rest of the HDU-related options, `--numhdus' must be
-         called alone. */
-      if(p->numhdus==1 && (p->remove || p->copy || p->cut) )
-        error(EXIT_FAILURE, 0, "`--numhdus' option must be called alone (it "
-              "cannot be called with other extension or keyword options)");
-
-      /* Set the operating mode. */
-      p->mode=FITS_MODE_HDU;
+      /* Some HDU options cannot be called with other options. */
+      stdoutcheck = 0;
+      stdoutcheck = p->numhdus + p->datasum;
 
       /* Make sure the output name is set. */
-      if(p->cp.output)
-        gal_checkset_writable_remove(p->cp.output, 1, p->cp.dontdelete);
+      if(stdoutcheck)
+        {
+          /* Make sure the other HDU-related options aren't called. */
+          if(p->remove || p->copy || p->cut)
+            error(EXIT_FAILURE, 0, "`--numhdus' or `--datasum' options "
+                  "must be called alone");
+
+          /* Make sure the HDU is given for the datasum option. */
+          if( p->datasum && p->cp.hdu==NULL )
+            error(EXIT_FAILURE, 0, "a HDU (extension) is necessary for the "
+                  " `--checksum' or `--datasum' options. Please use the "
+                  "`--hdu' (or `-h') option to select one");
+        }
       else
-        p->cp.output=gal_checkset_automatic_output(&p->cp, p->filename,
-                                                   "_ext.fits");
-    }
+        {
+          if(p->cp.output)
+            gal_checkset_writable_remove(p->cp.output, 1, p->cp.dontdelete);
+          else
+            p->cp.output=gal_checkset_automatic_output(&p->cp, p->filename,
+                                                       "_ext.fits");
+        }
 
-  /* Currently `datetosec' must be called alone. */
-  if( p->datetosec
-      && (p->date || p->comment || p->history || p->asis || p->delete
-          || p->rename || p->update || p->write || p->verify
-          || p->printallkeys || p->copykeys || p->mode==FITS_MODE_HDU) )
-    error(EXIT_FAILURE, 0, "`--datetosec' cannot currently be called with "
-          "any other option");
+      /* Set the operating mode. */
+      p->mode=FITS_MODE_HDU;
+    }
 
   /* If no options are given, go into HDU mode, which will print the HDU
      information when nothing is asked. */
diff --git a/bin/fits/ui.h b/bin/fits/ui.h
index 4249fb4..8f06f79 100644
--- a/bin/fits/ui.h
+++ b/bin/fits/ui.h
@@ -70,6 +70,7 @@ enum option_keys_enum
   /* Only with long version (start with a value 1000, the rest will be set
      automatically). */
   UI_KEY_TITLE        = 1000,
+  UI_KEY_DATASUM,
   UI_KEY_OUTHDU,
   UI_KEY_COPYKEYS,
   UI_KEY_PRIMARYIMGHDU,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index ceec2d8..684a165 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -8026,6 +8026,19 @@ It is thus useful in scripts, for example when you need 
to do check the number o
 For a complete list of basic meta-data on the extensions in a FITS file, don't 
use any of the options in this section or in @ref{Keyword manipulation}.
 For more, see @ref{Invoking astfits}.
 
+@item --datasum
+@cindex @code{DATASUM}: FITS keyword
+Calculate and print the given HDU's "datasum" to stdout.
+The given HDU is specified with the @option{--hdu} (or @option{-h}) option.
+This number is calculated by parsing all the bytes of the given HDU's data 
records (excluding keywords).
+This option ignores any possibly existing @code{DATASUM} keyword in the HDU.
+For more on the datasum feature of the FITS standard, see @ref{Keyword 
manipulation} (under the @code{checksum} component of @option{--write}).
+
+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 doesn't require write permissions.
+
+
+
 @item -C STR
 @itemx --copy=STR
 Copy the specified extension into the output file, see explanations above.
@@ -8246,12 +8259,12 @@ $ astfits test.fits -h1 --write=/,"My keywords"   \
 @cindex CFITSIO
 @cindex @code{DATASUM}: FITS keyword
 @cindex @code{CHECKSUM}: FITS keyword
-When nothing is given afterwards, the header integrity 
keywords@footnote{Section 4.4.2.7 (page 15) of 
@url{https://fits.gsfc.nasa.gov/standard40/fits_standard40aa-le.pdf}} 
@code{DATASUM} and @code{CHECKSUM} will be written/updated.
-They are calculated and written by CFITSIO.
-They thus comply with the FITS standard 4.0 that defines these keywords.
+When nothing is given afterwards, the header integrity keywords @code{DATASUM} 
and @code{CHECKSUM} will be calculated and written/updated.
+This is calculation and writing is done fully by CFITSIO.
+They thus comply with the FITS standard 
4.0@footnote{@url{https://fits.gsfc.nasa.gov/standard40/fits_standard40aa-le.pdf}}
 that defines these keywords (its Appendix J).
 
-If a value is given (for example @option{--write=checksum,my-own-checksum,"my 
checksum"}), then CFITSIO won't be called to calculate these two keywords and 
the value (as well as possible comment and unit) will be written just like any 
other keyword.
-This is generally not recommended, but necessary in special circumstances 
(where the checksum needs to be manually updated for example).
+If a value is given (e.g., @option{--write=checksum,MyOwnCheckSum}), then 
CFITSIO won't be called to calculate these two keywords and the value (as well 
as possible comment and unit) will be written just like any other keyword.
+This is generally not recommended, but necessary in special circumstances (for 
example when the checksum needs to be manually updated).
 
 @code{DATASUM} only depends on the data section of the HDU/extension, so it is 
not changed when you update the keywords.
 But @code{CHECKSUM} also depends on the header and will not be valid if you 
make any further changes to the header.