[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master f8b38ff 1/2: Fits: new '--skycoverage' option
|
From: |
Mohammad Akhlaghi |
|
Subject: |
[gnuastro-commits] master f8b38ff 1/2: Fits: new '--skycoverage' option to report image WCS coverage |
|
Date: |
Sun, 13 Sep 2020 18:59:26 -0400 (EDT) |
branch: master
commit f8b38ff841d712c269dba764b08259f87152fdc4
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Fits: new '--skycoverage' option to report image WCS coverage
Until now it was inconvenient to calculate the the relative coverage of an
image in the sky: where is its center, how big is it (on the sky) and
etc. You had to read the image size, construct a set of 4 coordinates of
the sides of the image, then use 'asttable' and the column arithmetic
operator 'img-to-wcs'.
With this commit, this process is now formalized inside the Fits program
with the '--skycoverage' option which will return two basic ways to
simplify the coverage of the image over the celestial sphere.
---
NEWS | 8 +++
bin/fits/args.h | 113 +++++++++++++++++++-------------
bin/fits/fits.c | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
bin/fits/main.h | 1 +
bin/fits/ui.c | 31 +++++----
bin/fits/ui.h | 4 +-
doc/gnuastro.texi | 103 ++++++++++++++++++++++-------
7 files changed, 369 insertions(+), 83 deletions(-)
diff --git a/NEWS b/NEWS
index ed8cd9e..5a17b58 100644
--- a/NEWS
+++ b/NEWS
@@ -30,6 +30,13 @@ See the end of the file for license conditions.
echo "113.64812416667 31.88732" \
| asttable -c'arith $1 degree-to-ra $2 degree-to-dec'
+ 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
+ format. This is paritcularly useful in combination with the new
+ 'astquery' option, to easily search the contents of external databases
+ within the image.
+
** Removed features
** Changed features
@@ -53,6 +60,7 @@ See the end of the file for license conditions.
+
* Noteworthy changes in release 0.13 (library 11.0.0) (2020-09-06) [stable]
** New features
diff --git a/bin/fits/args.h b/bin/fits/args.h
index 6de69dc..8d4a07e 100644
--- a/bin/fits/args.h
+++ b/bin/fits/args.h
@@ -31,11 +31,71 @@ along with Gnuastro. If not, see
<http://www.gnu.org/licenses/>.
/* Array of acceptable options. */
struct argp_option program_options[] =
{
- /* Input options */
{
0, 0, 0, 0,
- "HDUs (extensions):",
- UI_GROUP_EXTENSION
+ "HDU (extension) information:",
+ UI_GROUP_EXTENSION_INFORMATION
+ },
+ {
+ "numhdus",
+ UI_KEY_NUMHDUS,
+ 0,
+ 0,
+ "Print number of HDUs in the given FITS file.",
+ UI_GROUP_EXTENSION_INFORMATION,
+ &p->numhdus,
+ GAL_OPTIONS_NO_ARG_TYPE,
+ GAL_OPTIONS_RANGE_0_OR_1,
+ 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_INFORMATION,
+ &p->datasum,
+ GAL_OPTIONS_NO_ARG_TYPE,
+ GAL_OPTIONS_RANGE_0_OR_1,
+ GAL_OPTIONS_NOT_MANDATORY,
+ GAL_OPTIONS_NOT_SET
+ },
+ {
+ "pixelscale",
+ UI_KEY_PIXELSCALE,
+ 0,
+ 0,
+ "Return the pixel-scale of the HDU's WCS.",
+ UI_GROUP_EXTENSION_INFORMATION,
+ &p->pixelscale,
+ GAL_OPTIONS_NO_ARG_TYPE,
+ GAL_OPTIONS_RANGE_0_OR_1,
+ GAL_OPTIONS_NOT_MANDATORY,
+ GAL_OPTIONS_NOT_SET
+ },
+ {
+ "skycoverage",
+ UI_KEY_SKYCOVERAGE,
+ 0,
+ 0,
+ "Image coverage in the WCS coordinates.",
+ UI_GROUP_EXTENSION_INFORMATION,
+ &p->skycoverage,
+ GAL_OPTIONS_NO_ARG_TYPE,
+ GAL_OPTIONS_RANGE_0_OR_1,
+ GAL_OPTIONS_NOT_MANDATORY,
+ GAL_OPTIONS_NOT_SET
+ },
+
+
+
+
+ {
+ 0, 0, 0, 0,
+ "HDU (extension) manipulation:",
+ UI_GROUP_EXTENSION_MANIPULATION
},
{
"remove",
@@ -43,7 +103,7 @@ struct argp_option program_options[] =
"STR",
0,
"Remove extension from input file.",
- UI_GROUP_EXTENSION,
+ UI_GROUP_EXTENSION_MANIPULATION,
&p->remove,
GAL_TYPE_STRLL,
GAL_OPTIONS_RANGE_ANY,
@@ -56,7 +116,7 @@ struct argp_option program_options[] =
"STR",
0,
"Copy extension to output file.",
- UI_GROUP_EXTENSION,
+ UI_GROUP_EXTENSION_MANIPULATION,
&p->copy,
GAL_TYPE_STRLL,
GAL_OPTIONS_RANGE_ANY,
@@ -69,7 +129,7 @@ struct argp_option program_options[] =
"STR",
0,
"Copy extension to output and remove from input.",
- UI_GROUP_EXTENSION,
+ UI_GROUP_EXTENSION_MANIPULATION,
&p->cut,
GAL_TYPE_STRLL,
GAL_OPTIONS_RANGE_ANY,
@@ -77,57 +137,18 @@ struct argp_option program_options[] =
GAL_OPTIONS_NOT_SET
},
{
- "numhdus",
- UI_KEY_NUMHDUS,
- 0,
- 0,
- "Print number of HDUs in the given FITS file.",
- UI_GROUP_EXTENSION,
- &p->numhdus,
- GAL_OPTIONS_NO_ARG_TYPE,
- GAL_OPTIONS_RANGE_0_OR_1,
- GAL_OPTIONS_NOT_MANDATORY,
- GAL_OPTIONS_NOT_SET
- },
- {
"primaryimghdu",
UI_KEY_PRIMARYIMGHDU,
0,
0,
"Copy/cut image HDUs to primary/zero-th HDU.",
- UI_GROUP_EXTENSION,
+ UI_GROUP_EXTENSION_MANIPULATION,
&p->primaryimghdu,
GAL_OPTIONS_NO_ARG_TYPE,
GAL_OPTIONS_RANGE_0_OR_1,
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
- },
- {
- "pixelscale",
- UI_KEY_PIXELSCALE,
- 0,
- 0,
- "Return the pixel-scale of the HDU's WCS.",
- UI_GROUP_EXTENSION,
- &p->pixelscale,
- 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 14ce188..eab09c5 100644
--- a/bin/fits/fits.c
+++ b/bin/fits/fits.c
@@ -32,6 +32,7 @@ along with Gnuastro. If not, see
<http://www.gnu.org/licenses/>.
#include <gnuastro/fits.h>
#include <gnuastro/blank.h>
#include <gnuastro/pointer.h>
+#include <gnuastro/statistics.h>
#include <gnuastro-internal/timing.h>
#include <gnuastro-internal/checkset.h>
@@ -352,6 +353,196 @@ fits_pixelscale(struct fitsparams *p)
+/* Extract the dimension name from CTYPE. */
+static char *
+fits_wcs_dim_name(char *ctype)
+{
+ size_t i;
+ char *out;
+
+ /* Make a copy of the CTYPE value and set the first occurance of '-' to
+ '\0', to avoid the projection type. */
+ gal_checkset_allocate_copy(ctype, &out);
+ for(i=0;i<strlen(out);++i) if(out[i]=='-') out[i]='\0';
+
+ /* Return the output array. */
+ return out;
+}
+
+
+
+
+
+static void
+fits_skycoverage(struct fitsparams *p)
+{
+ fitsfile *fptr;
+ struct wcsprm *wcs;
+ int nwcs=0, type, status=0;
+ char *name=NULL, *unit=NULL;
+ gal_data_t *tmp, *coords=NULL;
+ double *x, *y, *z, min[3], max[3];
+ size_t i, ndim, numrows, *dsize=NULL;
+
+ /* Read the desired WCS. */
+ wcs=gal_wcs_read(p->filename, p->cp.hdu, 0, 0, &nwcs);
+
+ /* If a WCS doesn't exist, let the user know and return. */
+ if(wcs==NULL)
+ error(EXIT_FAILURE, 0, "%s (hdu %s): no WCS could be read by WCSLIB, "
+ "hence the sky coverage cannot be determined", p->filename,
+ p->cp.hdu);
+
+ /* Make sure the input HDU is an image. */
+ if( gal_fits_hdu_format(p->filename, p->cp.hdu) != IMAGE_HDU )
+ error(EXIT_FAILURE, 0, "%s (hdu %s): is not an image HDU, the "
+ "'--skycoverage' option only applies to image extensions",
+ p->filename, p->cp.hdu);
+
+ /* Get the array information of the image. */
+ fptr=gal_fits_hdu_open(p->filename, p->cp.hdu, READONLY);
+ gal_fits_img_info(fptr, &type, &ndim, &dsize, &name, &unit);
+ fits_close_file(fptr, &status);
+
+ /* Abort if we have more than 3 dimensions. */
+ if(ndim==1 || ndim>3)
+ error(EXIT_FAILURE, 0, "%s (hdu: %s): has %zu dimensions. Currently "
+ "'--skycoverage' only supports 2 or 3 dimensional datasets",
+ p->filename, p->cp.hdu, ndim);
+
+ /* Now that we have the number of dimensions in the image, allocate the
+ space needed for the coordinates. */
+ numrows = (ndim==2) ? 5 : 9;
+ for(i=0;i<ndim;++i)
+ {
+ tmp=gal_data_alloc(NULL, GAL_TYPE_FLOAT64, 1, &numrows, NULL, 0,
+ p->cp.minmapsize, p->cp.quietmmap, NULL,
+ NULL, NULL);
+ tmp->next=coords;
+ coords=tmp;
+ }
+
+ /* Fill in the coordinate arrays, Note that 'dsize' is ordered in C
+ dimensions, for the WCS conversion, we need to have the dimensions
+ ordered in FITS/Fortran order. */
+ switch(ndim)
+ {
+ case 2:
+ x=coords->array; y=coords->next->array;
+ x[0] = 1; y[0] = 1;
+ x[1] = dsize[1]; y[1] = 1;
+ x[2] = 1; y[2] = dsize[0];
+ x[3] = dsize[1]; y[3] = dsize[0];
+ x[4] = dsize[1]/2 + (dsize[1]%2 ? 1 : 0.5f);
+ y[4] = dsize[0]/2 + (dsize[0]%2 ? 1 : 0.5f);
+ break;
+ case 3:
+ x=coords->array; y=coords->next->array; z=coords->next->next->array;
+ x[0] = 1; y[0] = 1; z[0]=1;
+ x[1] = dsize[2]; y[1] = 1; z[1]=1;
+ x[2] = 1; y[2] = dsize[1]; z[2]=1;
+ x[3] = dsize[2]; y[3] = dsize[1]; z[3]=1;
+ x[4] = 1; y[4] = 1; z[4]=dsize[0];
+ x[5] = dsize[2]; y[5] = 1; z[5]=dsize[0];
+ x[6] = 1; y[6] = dsize[1]; z[6]=dsize[0];
+ x[7] = dsize[2]; y[7] = dsize[1]; z[7]=dsize[0];
+ x[8] = dsize[2]/2 + (dsize[2]%2 ? 1 : 0.5f);
+ y[8] = dsize[1]/2 + (dsize[1]%2 ? 1 : 0.5f);
+ z[8] = dsize[0]/2 + (dsize[0]%2 ? 1 : 0.5f);
+ break;
+ default:
+ error(EXIT_FAILURE, 0, "%s: a bug! Please contact us at %s to "
+ "fix the problem. 'ndim' of %zu is not recognized.",
+ __func__, PACKAGE_BUGREPORT, ndim);
+ }
+
+ /* For a check:
+ printf("IMAGE COORDINATES:\n");
+ for(i=0;i<numrows;++i)
+ if(ndim==2)
+ printf("%-15g%-15g\n", x[i], y[i]);
+ else
+ printf("%-15g%-15g%-15g\n", x[i], y[i], z[i]);
+ */
+
+ /* Convert to the world coordinate system. */
+ gal_wcs_img_to_world(coords, wcs, 1);
+
+ /* For a check:
+ printf("\nWORLD COORDINATES:\n");
+ for(i=0;i<numrows;++i)
+ if(ndim==2)
+ printf("%-15g%-15g\n", x[i], y[i]);
+ else
+ printf("%-15g%-15g%-15g\n", x[i], y[i], z[i]);
+ */
+
+ /* Get the minimum and maximum values in each dimension. */
+ tmp=gal_statistics_minimum(coords);
+ min[0] = ((double *)(tmp->array))[0]; gal_data_free(tmp);
+ tmp=gal_statistics_maximum(coords);
+ max[0] = ((double *)(tmp->array))[0]; gal_data_free(tmp);
+ tmp=gal_statistics_minimum(coords->next);
+ min[1] = ((double *)(tmp->array))[0]; gal_data_free(tmp);
+ tmp=gal_statistics_maximum(coords->next);
+ max[1] = ((double *)(tmp->array))[0]; gal_data_free(tmp);
+ if(ndim>2)
+ {
+ tmp=gal_statistics_minimum(coords->next->next);
+ min[2] = ((double *)(tmp->array))[0]; gal_data_free(tmp);
+ tmp=gal_statistics_maximum(coords->next->next);
+ max[2] = ((double *)(tmp->array))[0]; gal_data_free(tmp);
+ }
+
+ /* Inform the user. */
+ if(p->cp.quiet)
+ {
+ /* First print the center and full-width. */
+ for(tmp=coords; tmp!=NULL; tmp=tmp->next)
+ printf("%-15.10g ", ((double *)(tmp->array))[ndim==2 ? 4 : 8]);
+ for(i=0;i<ndim;++i) printf("%-15.10g ", max[i]-min[i]);
+ printf("\n");
+
+ /* Then print the range in coordinates. */
+ for(i=0;i<ndim;++i) printf("%-15.10g %-15.10g ", min[i], max[i]);
+ printf("\n");
+ }
+ else
+ {
+ printf("Input file: %s (hdu: %s)\n", p->filename, p->cp.hdu);
+ printf("\nSky coverage by center and (full) width:\n");
+ switch(ndim)
+ {
+ case 2:
+ printf(" Center: %-15.10g%-15.10g\n", x[4], y[4]);
+ printf(" Width: %-15.10g%-15.10g\n", max[0]-min[0], max[1]-min[1]);
+ break;
+ case 3:
+ printf(" Center: %-15.10g%-15.10g%-15.10g\n", x[8], y[8], z[8]);
+ printf(" width: %-15.10g%-15.10g%-15.10g\n", max[0]-min[0],
+ max[1]-min[1], max[2]-min[2]);
+ break;
+ default:
+ error(EXIT_FAILURE, 0, "%s: a bug! Please contact us at %s to fix "
+ "the problem. 'ndim' value %zu is not recognized", __func__,
+ PACKAGE_BUGREPORT, ndim);
+ }
+
+ /* For the range type of coverage. */
+ printf("\nSky coverage by range along dimensions:\n");
+ for(i=0;i<ndim;++i)
+ printf(" %-8s %-15.10g%-15.10g\n",
+ fits_wcs_dim_name(wcs->ctype[i]), min[i], max[i]);
+ }
+
+ /* Clean up. */
+ free(dsize);
+ wcsfree(wcs);
+}
+
+
+
+
static void
fits_hdu_remove(struct fitsparams *p, int *r)
@@ -483,6 +674,7 @@ fits(struct fitsparams *p)
if(p->numhdus) fits_hdu_number(p);
else if(p->datasum) fits_datasum(p);
else if(p->pixelscale) fits_pixelscale(p);
+ else if(p->skycoverage) fits_skycoverage(p);
/* Options that can be called together. */
else
diff --git a/bin/fits/main.h b/bin/fits/main.h
index cf99137..deb6149 100644
--- a/bin/fits/main.h
+++ b/bin/fits/main.h
@@ -63,6 +63,7 @@ struct fitsparams
uint8_t numhdus; /* Print number of HDUs in FITS file. */
uint8_t datasum; /* Calculate and print HDU's datasum. */
uint8_t pixelscale; /* Calculate and print HDU's pixelscale. */
+ uint8_t skycoverage; /* Calculate and image coverage in WCS. */
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 616b164..a75f5fa 100644
--- a/bin/fits/ui.c
+++ b/bin/fits/ui.c
@@ -322,7 +322,7 @@ ui_check_copykeys(struct fitsparams *p)
static void
ui_read_check_only_options(struct fitsparams *p)
{
- uint8_t stdoutcheck;
+ uint8_t stdoutcheck=0;
/* If any of the keyword manipulation options are requested, then set the
mode flag to keyword-mode. */
@@ -363,7 +363,7 @@ ui_read_check_only_options(struct fitsparams *p)
/* Same for the extension-related options */
if( p->remove || p->copy || p->cut || p->numhdus || p->datasum
- || p->pixelscale )
+ || p->pixelscale || p->skycoverage )
{
/* A small sanity check. */
if(p->mode!=FITS_MODE_INVALID)
@@ -371,22 +371,29 @@ ui_read_check_only_options(struct fitsparams *p)
"cannot be called together");
/* Some HDU options cannot be called with other options. */
- stdoutcheck = 0;
- stdoutcheck = p->numhdus + p->datasum;
+ stdoutcheck = p->numhdus + p->datasum + p->pixelscale + p->skycoverage;
- /* Make sure the output name is set. */
+ /* Make sure if an output file is needed. */
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, "'--numhdus', '--datasum', '--pixelscale' "
+ "or '--skycoverage' options cannot be called with any of "
+ "the '--remove', '--copy' or '--cut' options");
+
+ /* Make sure these options are called alone. */
+ if(stdoutcheck>1)
+ error(EXIT_FAILURE, 0, "'--numhdus', '--datasum', '--pixelscale' "
+ "or '--skycoverage' options cannot be called together, "
+ "only one at a time");
+
+ /* Make sure the HDU is given if any of the options except
+ '--numhdus' are called. */
+ if( stdoutcheck-p->numhdus && 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");
+ "'--datasum', '--pixelscale' or '--skycoverage' options. "
+ "Please use the '--hdu' (or '-h') option to select one");
}
else
{
diff --git a/bin/fits/ui.h b/bin/fits/ui.h
index 8b3dc16..81ed184 100644
--- a/bin/fits/ui.h
+++ b/bin/fits/ui.h
@@ -33,7 +33,8 @@ along with Gnuastro. If not, see
<http://www.gnu.org/licenses/>.
/* Option groups particular to this program. */
enum program_args_groups
{
- UI_GROUP_EXTENSION = GAL_OPTIONS_GROUP_AFTER_COMMON,
+ UI_GROUP_EXTENSION_INFORMATION = GAL_OPTIONS_GROUP_AFTER_COMMON,
+ UI_GROUP_EXTENSION_MANIPULATION,
UI_GROUP_KEYWORD,
};
@@ -72,6 +73,7 @@ enum option_keys_enum
UI_KEY_TITLE = 1000,
UI_KEY_DATASUM,
UI_KEY_PIXELSCALE,
+ UI_KEY_SKYCOVERAGE,
UI_KEY_OUTHDU,
UI_KEY_COPYKEYS,
UI_KEY_PRIMARYIMGHDU,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 0d73ae9..cb1c4b7 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -93,6 +93,9 @@ A copy of the license is included in the section entitled
``GNU Free Documentati
* Segment: (gnuastro)Segment. Segment detections based on signal structure.
* astsegment: (gnuastro)Invoking astsegment. Options to Segment.
+* Query: (gnuastro)Query. Access remote databases for downloading data.
+* astquery: (gnuastro)Invoking astquery. Options to Query.
+
* Statistics: (gnuastro)Statistics. Get image Statistics.
* aststatistics: (gnuastro)Invoking aststatistics. Options to Statistics.
@@ -384,7 +387,7 @@ Fits
Invoking Fits
-* HDU manipulation:: Manipulate HDUs within a FITS file.
+* HDU information and manipulation:: Learn about the HDUs and move them.
* Keyword manipulation:: Manipulate metadata keywords in a HDU
Sort FITS files by night
@@ -579,6 +582,10 @@ Invoking CosmicCalculator
* CosmicCalculator basic cosmology calculations:: Like distance modulus,
distances and etc.
* CosmicCalculator spectral line calculations:: How they get affected by
redshift.
+Query
+
+* Invoking astquery:: Inputs, outputs and configuration of Query.
+
Library
* Review of library fundamentals:: Guide on libraries and linking.
@@ -2709,7 +2716,7 @@ $ astfits xdf-f160w_detected.fits --copy=DETECTIONS
-odetections.fits
@end example
There are similar options to conveniently cut (@option{--cut}, copy, then
remove from the input) or delete (@option{--remove}) HDUs from a FITS file also.
-See @ref{HDU manipulation} for more.
+See @ref{HDU information and manipulation} for more.
@@ -8254,12 +8261,12 @@ Therefore as described in the paragraphs above, when no
explicit call to the @op
The operating mode and input/output options to Fits are similar to the other
programs and fully described in @ref{Common options}.
The options particular to Fits can be divided into two groups:
-1) those related to modifying HDUs or extensions (see @ref{HDU manipulation}),
and
+1) those related to modifying HDUs or extensions (see @ref{HDU information and
manipulation}), and
2) those related to viewing/modifying meta-data keywords (see @ref{Keyword
manipulation}).
These two classes of options cannot be called together in one run: you can
either work on the extensions or meta-data keywords in any instance of Fits.
@menu
-* HDU manipulation:: Manipulate HDUs within a FITS file.
+* HDU information and manipulation:: Learn about the HDUs and move them.
* Keyword manipulation:: Manipulate metadata keywords in a HDU
@end menu
@@ -8267,23 +8274,17 @@ These two classes of options cannot be called together
in one run: you can eithe
-@node HDU manipulation, Keyword manipulation, Invoking astfits, Invoking
astfits
-@subsubsection HDU manipulation
-Each header data unit, or HDU (also known as an extension), in a FITS file is
an independent dataset (data + meta-data).
+@node HDU information and manipulation, Keyword manipulation, Invoking
astfits, Invoking astfits
+@subsubsection HDU information and manipulation
+Each FITS file header data unit, or HDU (also known as an extension) is an
independent dataset (data + meta-data).
Multiple HDUs can be stored in one FITS file, see @ref{Fits}.
-The HDU modifying options to the Fits program are listed below.
-
-These options may be called multiple times in one run.
-If so, the extensions will be copied from the input FITS file to the output
FITS file in the given order (on the command-line and also in configuration
files, see @ref{Configuration file precedence}).
-If the separate classes are called together in one run of Fits, then first
@option{--copy} is run (on all specified HDUs), followed by @option{--cut}
(again on all specified HDUs), and then @option{--remove} (on all specified
HDUs).
+The general HDU-related options to the Fits program are listed below as two
general classes:
+the first group below focus on HDU information while the latter focus on
manipulating (moving or deleting) the HDUs.
-The @option{--copy} and @option{--cut} options need an output FITS file
(specified with the @option{--output} option).
-If the output file exists, then the specified HDU will be copied following the
last extension of the output file (the existing HDUs in it will be untouched).
-Thus, after Fits finishes, the copied HDU will be the last HDU of the output
file.
-If no output file name is given, then automatic output will be used to store
the HDUs given to this option (see @ref{Automatic output}).
+The options below print information about the given HDU on the command-line.
+Thus they cannot be called together in one command (each has its own
independent output).
@table @option
-
@item -n
@itemx --numhdus
Print the number of extensions/HDUs in the given file.
@@ -8293,6 +8294,48 @@ 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 --pixelscale
+Print the HDU's pixel-scale (change in world coordinate for one pixel along
each dimension).
+Without the @option{--quiet} option, the output of @option{--pixelscale} is
more human-friendly by printing the file/HDU name, number of dimensions, and
the units of each number along with the actual pixel scales.
+However, in scripts (that are to be run automatically), this human-friendly
format is annoying, so when called with the @option{--quiet} option, only the
pixel-scale value(s) along each dimension is(are) printed in one line.
+
+@item --skycoverage
+@cindex Image's sky coverage
+@cindex Coverage of image over sky
+Print the rectangular area (or 3D cube) covered by the given image/datacube
HDU over the Sky in the WCS units.
+The covered area is reported in two ways:
+1) the center and full width in each dimension,
+2) the minimum and maximum sky coordinates in each dimension.
+This is option is thus useful when you want to get a general feeling of a new
image/dataset, or prepare the inputs to query external databases in the region
of the image (for example with @ref{Query}).
+
+If run without the @option{--quiet} option, the values are given with a
human-friendly description.
+For example here is the output of this option on an image taken near the star
Castor:
+
+@example
+$ astfits castor.fits --skycoverage
+Input file: castor.fits (hdu: 1)
+
+Sky coverage by center and (full) width:
+ Center: 113.9149075 31.93759664
+ Width: 2.41762045 2.67945253
+
+Sky coverage by range along dimensions:
+ RA 112.7235592 115.1411797
+ DEC 30.59262123 33.27207376
+@end example
+
+With the @option{--quiet} option, the values are more machine-friendly (easy
to parse).
+It has two lines, where the first line contains the center/width values and
the second line shows the coordinate ranges in each dimension.
+
+@example
+$ astfits castor.fits --skycoverage --quiet
+113.9149075 31.93759664 2.41762045 2.67945253
+112.7235592 115.1411797 30.59262123 33.27207376
+@end example
+
+Note that this is a simple rectangle (cube in 3D) definition, so if the image
is rotated in relation to the celestial coordinates a general polygon is
necessary to exactly describe the coverage.
+Hence when there is rotation, the reported area will be larger than the actual
area containing data, you can visually see the area with the @option{--align}
option of @ref{Warp}.
+
@item --datasum
@cindex @code{DATASUM}: FITS keyword
Calculate and print the given HDU's "datasum" to stdout.
@@ -8303,11 +8346,19 @@ For more on the datasum feature of the FITS standard,
see @ref{Keyword manipulat
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.
+@end table
-@item --pixelscale
-Print the HDU's pixel-scale (change in world coordinate for one pixel along
each dimension).
-Without the @option{--quiet} option, the output of @option{--pixelscale} is
more human-friendly by printing the file/HDU name, number of dimensions, and
the units of each number along with the actual pixel scales.
-However, in scripts (that are to be run automatically), this human-friendly
format is annoying, so when called with the @option{--quiet} option, only the
pixel-scale value(s) along each dimension is(are) printed in one line.
+The following options manipulate (move/delete) the HDUs in one FITS file or to
another FITS file.
+These options may be called multiple times in one run.
+If so, the extensions will be copied from the input FITS file to the output
FITS file in the given order (on the command-line and also in configuration
files, see @ref{Configuration file precedence}).
+If the separate classes are called together in one run of Fits, then first
@option{--copy} is run (on all specified HDUs), followed by @option{--cut}
(again on all specified HDUs), and then @option{--remove} (on all specified
HDUs).
+
+The @option{--copy} and @option{--cut} options need an output FITS file
(specified with the @option{--output} option).
+If the output file exists, then the specified HDU will be copied following the
last extension of the output file (the existing HDUs in it will be untouched).
+Thus, after Fits finishes, the copied HDU will be the last HDU of the output
file.
+If no output file name is given, then automatic output will be used to store
the HDUs given to this option (see @ref{Automatic output}).
+
+@table @option
@item -C STR
@itemx --copy=STR
@@ -8343,7 +8394,7 @@ If we hadn't used @option{--primaryimghdu}, then the
zero-th extension of @file{
@end table
-@node Keyword manipulation, , HDU manipulation, Invoking astfits
+@node Keyword manipulation, , HDU information and manipulation, Invoking
astfits
@subsubsection Keyword manipulation
The meta-data in each header data unit, or HDU (also known as extension, see
@ref{Fits}) is stored as ``keyword''s.
Each keyword consists of a name, value, unit, and comments.
@@ -8690,7 +8741,7 @@ Here are some examples
@itemize
@item
-If you need to copy the files, but only need a single extension (not the whole
file), you can add a step just before the making of the symbolic links, or
copies, and change it to only copy a certain extension of the FITS file using
the Fits program's @option{--copy} option, see @ref{HDU manipulation}.
+If you need to copy the files, but only need a single extension (not the whole
file), you can add a step just before the making of the symbolic links, or
copies, and change it to only copy a certain extension of the FITS file using
the Fits program's @option{--copy} option, see @ref{HDU information and
manipulation}.
@item
If you need to classify the files with finer detail (for example the purpose
of the dataset), you can add a step just before the making of the symbolic
links, or copies, to specify a file-name prefix based on other certain keyword
values in the files.
@@ -18342,7 +18393,11 @@ However, remembering the exact URLs and interface of
each database is not easily
Gnuastro's Query program is designed to address these problems: it has a
common high-level interface for general operations that are common between its
recognized databases.
For example, importing a catalog of objects within a certain distance of a
given coordinate.
-@node Invoking astquery
+@menu
+* Invoking astquery:: Inputs, outputs and configuration of Query.
+@end menu
+
+@node Invoking astquery, , Query, Query
@subsection Invoking Query
Query provides a high-level interface to downloading subsets of data from
databases.