---

12.3.11.3 FITS HDUs ¶

A FITS file can contain multiple HDUs/extensions. The functions in this section can be used to get basic information about the extensions or open them. Note that fitsfile is defined in CFITSIO’s fitsio.h which is automatically included by Gnuastro’s gnuastro/fits.h.

Function:
fitsfile *
gal_fits_open_to_write (char *filename) ¶

If filename exists, open it and return the fitsfile pointer that corresponds to it. If filename does not exist, the file will be created which contains a blank first extension and the pointer to its next extension will be returned.

Function:
size_t
gal_fits_hdu_num (char *filename) ¶

Return the number of HDUs/extensions in filename.

Function:
unsigned long
gal_fits_hdu_datasum (char *filename, char *hdu, char *hdu_option_name) ¶

Return the DATASUM of the given HDU in the given FITS file. For more on DATASUM in the FITS standard, see Keyword inspection and manipulation (under the checksum component of --write). For more on hdu_option_name see the description of gal_array_read in Array input output.

Function:
unsigned long
gal_fits_hdu_datasum_encoded (char *filename, char *hdu, char *hdu_option_name) ¶

Similar to 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 CHECKSUM keyword, but can also be used for DATASUM.

Function:
unsigned long
gal_fits_hdu_datasum_ptr (fitsfile *fptr) ¶

Return the DATASUM of the already opened HDU in fptr. For more on DATASUM in the FITS standard, see Keyword inspection and manipulation (under the checksum component of --write).

Function:
int
gal_fits_hdu_format (char *filename, char *hdu, char *hdu_option_name) ¶

Return the format of the HDU as one of CFITSIO’s recognized macros: IMAGE_HDU, ASCII_TBL, or BINARY_TBL. For more on hdu_option_name see the description of gal_array_read in Array input output.

Function:
int
gal_fits_hdu_is_healpix (fitsfile *fptr) ¶

Return 1 if the dataset may be a HEALpix grid and 0 otherwise. Technically, it is considered to be a HEALPix if the HDU is not an ASCII table, and has the NSIDE, FIRSTPIX and LASTPIX.

Function:
fitsfile *
gal_fits_hdu_open (char *filename, char *hdu, int iomode, int exitonerror, char *hdu_option_name) ¶

Open the HDU/extension hdu from filename and return a pointer to CFITSIO’s fitsfile. iomode determines how the FITS file will be opened using CFITSIO’s macros: READONLY or READWRITE.

The string in hdu will be appended to filename in square brackets so CFITSIO only opens this extension. You can use any formatting for the hdu that is acceptable to CFITSIO. See the description under --hdu in Input/Output options for more.

If exitonerror!=0 and the given HDU cannot be opened for any reason, the function will exit the program, and print an informative message. Otherwise, when the HDU cannot be opened, it will just return a NULL pointer. For more on hdu_option_name see the description of gal_array_read in Array input output.

Function:
fitsfile *
gal_fits_hdu_open_format (char *filename, char *hdu, int img0_tab1, char *hdu_option_name) ¶

Open (in read-only format) the hdu HDU/extension of filename as an image or table. When img0_tab1 is 0(zero) but the HDU is a table, this function will abort with an error. It will also abort with an error when img0_tab1 is 1 (one), but the HDU is an image. For more on hdu_option_name see the description of gal_array_read in Array input output.

A FITS HDU may contain both tables or images. When your program needs one of these formats, you can call this function so if the user provided the wrong HDU/file, it will abort and inform the user that the file/HDU is has the wrong format.