---

12.3.11.5 FITS arrays (images)

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.

Function:
void
gal_fits_img_info (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.

Function:
size_t *
gal_fits_img_info_dim (char *filename, char *hdu, size_t *ndim) ¶

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.

Function:
gal_data_t *
gal_fits_img_read (char *filename, char *hdu, size_t minmapsize, int quietmmap) ¶

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).

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);
data->wcs=gal_wcs_read(filename, hdu, 0, 0, 0, &data->wcs->nwcs);

Function:
gal_data_t *
gal_fits_img_read_to_type (char *inputname, char *inhdu, uint8_t type, size_t minmapsize, int quietmmap) ¶

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.

Function:
gal_data_t *
gal_fits_img_read_kernel (char *filename, char *hdu, size_t minmapsize, int quietmmap) ¶

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.

Function:
fitsfile *
gal_fits_img_write_to_ptr (gal_data_t *input, char *filename) ¶

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.

Function:
void
gal_fits_img_write (gal_data_t *data, char *filename, gal_fits_list_key_t *headers, char *program_string) ¶

Write the input dataset into the FITS file named filename. Also add the headers keywords to the newly created HDU/extension along with your program’s name (program_string).

Function:
void
gal_fits_img_write_to_type (gal_data_t *data, char *filename, gal_fits_list_key_t *headers, char *program_string, int type) ¶

Convert the input dataset into type, then write it into the FITS file named filename. Also add the headers 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.

This is just a wrapper for the gal_data_copy_to_new_type and gal_fits_img_write functions.

Function:
void
gal_fits_img_write_corr_wcs_str (gal_data_t *data, char *filename, char *wcsstr, int nkeyrec, double *crpix, gal_fits_list_key_t *headers, char *program_string) ¶

Write the input dataset into filename using the wcsstr while correcting the CRPIX values.

This function is mainly useful when you want to make FITS files in parallel (from one main WCS structure, with just differing CRPIX). This can happen in the following cases for example:

• When a large number of FITS images (with WCS) need to be created in parallel, it can be much more efficient to write the header’s WCS keywords once at first, write them in the FITS file, then just correct the CRPIX values.
• WCSLIB’s header writing function is not thread safe. So when writing FITS images in parallel, we cannot write the header keywords in each thread.