Images (or multi-dimensional arrays in general) are one of the common data formats that is stored in FITS files. Only one image may be stored in each FITS HDU/extension. The functions described here can be used to get the information of, read, or write images in FITS files.
void(fitsfile *fptr, int *type, size_t *ndim, size_t **dsize, char **name, char **unit) ¶Read the type (see Library data types (type.h)), number of dimensions, and size along each dimension of the CFITSIO fitsfile into the type, ndim, and dsize pointers respectively.
If name and unit are not NULL (point to a char *), then if the image has a name and units, the respective string will be put in these pointers.
size_t *(char *filename, char *hdu, size_t *ndim, char *hdu_option_name) ¶Put the number of dimensions in the hdu extension of filename
in the space that ndim points to and return the size of the dataset
along each dimension as an allocated array with *ndim elements.
For more on hdu_option_name see the description of gal_array_read in Array input output.
gal_data_t *(char *filename, char *hdu, size_t minmapsize, int quietmmap, char *hdu_option_name) ¶Read the contents of the hdu extension/HDU of filename into a Gnuastro generic data container (see Generic data container (gal_data_t)) and return it.
If the necessary space is larger than minmapsize, then do not keep the data in RAM, but in a file on the HDD/SSD.
For more on minmapsize and quietmmap see the description under the same name in Generic data container (gal_data_t).
For more on hdu_option_name see the description of gal_array_read in Array input output.
Note that this function only reads the main data within the requested FITS extension, the WCS will not be read into the returned dataset.
To read the WCS, you can use gal_wcs_read function as shown below.
Afterwards, the gal_data_free function will free both the dataset and any WCS structure (if there are any).
data=gal_fits_img_read(filename, hdu, -1, 1, NULL);
data->wcs=gal_wcs_read(filename, hdu, 0, 0, 0, &data->wcs->nwcs,
NULL);
gal_data_t *(char *inputname, char *inhdu, uint8_t type, size_t minmapsize, int quietmmap, char *hdu_option_name) ¶Read the contents of the hdu extension/HDU of filename into a Gnuastro generic data container (see Generic data container (gal_data_t)) of type type and return it.
This is just a wrapper around gal_fits_img_read (to read the image/array of any type) and gal_data_copy_to_new_type_free (to convert it to type and free the initially read dataset).
See the description there for more.
gal_data_t *(char *filename, char *hdu, size_t minmapsize, int quietmmap, char *hdu_option_name) ¶Read the hdu of filename as a convolution kernel.
A convolution kernel must have an odd size along all dimensions, it must not have blank (NaN in floating point types) values and must be flipped around the center to make the proper convolution (see Convolution process).
If there are blank values, this function will change the blank values to 0.0.
If the input image does not have the other two requirements, this function will abort with an error describing the condition to the user.
The finally returned dataset will have a float32 type.
For more on hdu_option_name see the description of gal_array_read in Array input output.
fitsfile *(gal_data_t *input, char *filename, gal_fits_list_key_t *keylist, int freekeys) ¶Write the input dataset into a FITS file named filename and return the corresponding CFITSIO fitsfile pointer.
This function will not close fitsfile, so you can still add other extensions to it after this function or make other modifications.
In case you want to add keywords into the HDU that contain the data, you can use the second two arguments (see the description of gal_fits_key_write).
These keywords will be written into the HDU before writing the data: when there are more than roughly 5 keywords (assuming your dataset has WCS) and your dataset is large, this can result in significant optimization of the running time (because adding a keyword beyond the 36 key slots will cause the whole data to shift for another block of 36 keywords).
void(gal_data_t *input, char *filename, gal_fits_list_key_t *keylist, int freekeys) ¶Write the input dataset into the FITS file named filename.
Also add the list of header keywords (keylist) to the newly created HDU/extension
The list of keywords will be freed after writing into the HDU, if you need them later, keep a separate copy of the list before calling this function.
For the importance of why it is better to add your keywords in this function (before writing the data) or after it, see the description of gal_fits_img_write_to_ptr.
void(gal_data_t *input, char *filename, gal_fits_list_key_t *keylist, int type, int freekeys) ¶Convert the input dataset into type, then write it into the FITS file named filename.
Also add the keylist keywords to the newly created HDU/extension along with your program’s name (program_string).
After the FITS file is written, this function will free the copied dataset (with type type) from memory.
For the importance of why it is better to add your keywords in this function (before writing the data) or after it, see the description of gal_fits_img_write_to_ptr.
This is just a wrapper for the gal_data_copy_to_new_type and gal_fits_img_write functions.
void(gal_data_t *input, char *filename, char *wcsstr, int nkeyrec, double *crpix, gal_fits_list_key_t *keylist, int freekeys) ¶Write the input dataset into filename using the wcsstr while correcting the CRPIX values.
For the importance of why it is better to add your keywords in this function (before writing the data) or after it, see the description of gal_fits_img_write_to_ptr.
This function is mainly useful when you want to make FITS files in parallel (from one main WCS structure, with just a differing CRPIX), for more on the arguments, see the description of gal_fits_img_write.
This can happen in the following cases for example:
GNU Astronomy Utilities 0.23 manual, July 2024.