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 Fits. 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 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).
Print the number of extensions/HDUs in the given file. Note that this option must be called alone and will only print a single number. It is thus useful in scripts, for example, when you need to do check the number of extensions in a FITS file.
For a complete list of basic meta-data on the extensions in a FITS file, do not use any of the options in this section or in Keyword inspection and manipulation. For more, see Invoking Fits.
Print 1 (on standard output) if at least one table HDU (ASCII or binary) exists in the FITS file.
Otherwise (when no table HDU exists in the file), print 0.
Print the names or numbers (when a name does not exist, counting from zero) of HDUs that contain a table (ASCII or Binary) on standard output, one per line. Otherwise (when no table HDU exists in the file) nothing will be printed.
Print 1 (on standard output) if at least one image HDU exists in the FITS file.
Otherwise (when no image HDU exists in the file), print 0.
In the FITS standard, any array with any dimensions is called an “image”, therefore this option includes 1, 3 and 4 dimensional arrays too. However, an image HDU with zero dimensions (which is usually the first extension and only contains metadata) is not counted here.
Print the names or numbers (when a name does not exist, counting from zero) of HDUs that contain an image on standard output, one per line. Otherwise (when no image HDU exists in the file) nothing will be printed.
In the FITS standard, any array with any dimensions is called an “image”, therefore this option includes 1, 3 and 4 dimensional arrays too. However, an image HDU with zero dimensions (which is usually the first extension and only contains metadata) is not counted here.
Print the names or numbers (when a name does not exist, counting from zero) of all HDUs within the input file on the standard output, one per line.
Print the HDU’s pixel-scale (change in world coordinate for one pixel along each dimension) and pixel area or voxel volume. Without the --quiet option, the output of --pixelscale has multiple lines and explanations, thus being more human-friendly. It prints the file/HDU name, number of dimensions, and the units along with the actual pixel scales. Also, when any of the units are in degrees, the pixel scales and area/volume are also printed in units of arc-seconds. For 3D datasets, the pixel area (on each 2D slice of the 3D cube) is printed as well as the voxel volume. If you only want the pixel area of a 2D image in units of arcsec\(^2\) you can use --pixelareaarcsec2 described below.
However, in scripts (that are to be run automatically), this human-friendly format is annoying, so when called with the --quiet option, only the pixel-scale value(s) along each dimension is(are) printed in one line. These numbers are followed by the pixel area (in the raw WCS units). For 3D datasets, this will be area on each 2D slice. Finally, for 3D datasets, a final number (the voxel volume) is printed. As a summary, in --quiet mode, for 2D datasets three numbers are printed and for 3D datasets, 5 numbers are printed. If the dataset has more than 3 dimensions, only the pixel-scale values are printed (no area or volume will be printed).
Print the HDU’s pixel area in units of arcsec\(^2\). This option only works on 2D images, that have WCS coordinates in units of degrees. For lower-level information about the pixel scale in each dimension, see --pixelscale (described above).
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 Query).
If run without the --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:
$ 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
With the --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.
$ astfits castor.fits --skycoverage --quiet 113.9149075 31.93759664 2.41762045 2.67945253 112.7235592 115.1411797 30.59262123 33.27207376
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 --pixelareaonwcs option of Fits.
Currently this option only supports images that are less than 180 degrees in width (which is usually the case!). This requirement has been necessary to account for images that cross the RA=0 hour circle on the sky. Please get in touch with us at mailto:bug-gnuastro@gnu.org if you have an image that is larger than 180 degrees so we try to find a solution based on need.
Calculate and print the given HDU’s "datasum" to stdout.
The given HDU is specified with the --hdu (or -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 DATASUM keyword in the HDU.
For more on DATASUM in the FITS standard, see Keyword inspection and manipulation (under the checksum component of --write).
You can use this option to confirm that the data in two different HDUs (possibly with different keywords) is identical.
Its advantage over --write=datasum (which writes the DATASUM keyword into the given HDU) is that it does not require write permissions.
Similar to --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 CHECKSUM keyword, but applied to the value of the DATASUM result.
In some scenarios, this string can be more useful than the raw integer.
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 Configuration file precedence). If the separate classes are called together in one run of Fits, then first --copy is run (on all specified HDUs), followed by --cut (again on all specified HDUs), and then --remove (on all specified HDUs).
The --copy and --cut options need an output FITS file (specified with the --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 Automatic output).
Copy the specified extension into the output file, see explanations above.
Cut (copy to output, remove from input) the specified extension into the output file, see explanations above.
Remove the specified HDU from the input file.
The first (zero-th) HDU cannot be removed with this option. Consider using --copy or --cut in combination with primaryimghdu to not have an empty zero-th HDU. From CFITSIO: “In the case of deleting the primary array (the first HDU in the file) then [it] will be replaced by a null primary array containing the minimum set of required keywords and no data.”. So in practice, any existing data (array) and meta-data in the first extension will be removed, but the number of extensions in the file will not change. This is because of the unique position the first FITS extension has in the FITS standard (for example, it cannot be used to store tables).
Copy or cut an image HDU to the zero-th HDU/extension a file that does not yet exist. This option is thus irrelevant if the output file already exists or the copied/cut extension is a FITS table. For example, with the commands below, first we make sure that out.fits does not exist, then we copy the first extension of in.fits to the zero-th extension of out.fits.
$ rm -f out.fits $ astfits in.fits --copy=1 --primaryimghdu --output=out.fits
If we had not used --primaryimghdu, then the zero-th extension of out.fits would have no data, and its second extension would host the copied image (just like any other output of Gnuastro).
JavaScript license information
GNU Astronomy Utilities 0.22 manual, February 2024.