GNU Astronomy Utilities


Next: , Previous: , Up: FITS files   [Contents][Index]


10.3.8.4 FITS header keywords

Each FITS extension/HDU contains a raw dataset which can either be a table or an image along with some header keywords. The keywords can be used to store meta-data about the actual dataset. The functions in this section describe Gnuastro’s high-level functions for reading and writing FITS keywords. Similar to all Gnuastro’s FITS-related functions, these functions are all wrappers for CFITSIO’s low-level functions.

The necessary meta-data (header keywords) for a particular dataset are commonly numerous, it is much more efficient to list them in one variable and call the reading/writing functions once. Hence the functions in this section use linked lists, a thorough introduction to them is given in Linked lists (list.h). To reading FITS keywords, these functions use a list of Gnuastro’s generic dataset format that is discussed in List of gal_data_t. To write FITS keywords we define the gal_fits_list_key_t node that is defined below.

Type (C struct): gal_fits_list_key_t

Structure for writing FITS keywords. This structure is used for one keyword and you don’t need to set all elements. With the next element, you can link it to another keyword thus creating a linked list to add any number of keywords easily and at any step during your program (see Linked lists (list.h) for an introduction on lists). See the functions below for adding elements to the list.

typedef struct gal_fits_list_key_t
{
  int                        kfree;   /* ==1, free name.      */
  int                        vfree;   /* ==1, free value.     */
  int                        cfree;   /* ==1, free comment.   */
  uint8_t                     type;   /* Keyword value type.  */
  char                    *keyname;   /* Keyword Name.        */
  void                      *value;   /* Keyword value.       */
  char                    *comment;   /* Keyword comment.     */
  char                       *unit;   /* Keyword unit.        */
  struct gal_fits_list_key_t *next;   /* Next keyword.        */
} gal_fits_list_key_t;
Function:
void
gal_fits_key_clean_str_value (char *string)

Remove the single quotes and possible extra spaces around the keyword values that CFITSIO returns when reading a string keyword. CFITSIO doesn’t remove the two single quotes around the string value of a keyword. Hence the strings it reads are like: 'value ', or 'some_very_long_value'. To use the value during your processing, it is commonly necessary to remove the single quotes (and possible extra spaces). This function will do this within the allocated space of the string.

Function:
void
gal_fits_key_read_from_ptr (fitsfile *fptr, gal_data_t *keysll, int readcomment, int readunit)

Read the list of keyword values from a FITS pointer. The input should be a linked list of Gnuastro’s generic data container (gal_data_t). Before calling this function, you just have to set the name and desired type values of each node in the list to the keyword you want it to keep the value of. The given name value will be directly passed to CFITSIO to read the desired keyword name. This function will allocate space to keep the value. If readcomment and readunit are non-zero, this function will also try to read the possible comments and units of the keyword.

Here is one example of using this function:

/* Allocate an array of datasets. */
gal_data_t *keysll=gal_data_array_calloc(N);

/* Use the array as a list.*/
for(i=0;i<N-2;++i) keysll[i].next=keysll[i+1];

/* Fill the datasets with a `name' and a `type'. */
keysll[0].name="NAME1";     keysll[0].type=GAL_TYPE_INT32;
keysll[1].name="NAME2";     keysll[1].type=GAL_TYPE_STRING;
...
...

/* Call this function. */
gal_fits_key_read_from_ptr(fptr, keysll, 0, 0);

/* Use the values as you like... */

/* Free all the allocated spaces. */
gal_data_array_free(keysll, N, 1);

If the array pointer of each keyword’s dataset is not NULL, then it is assumed that the space to keep the value has already been allocated. If it is NULL, space will be allocated for the value by this function.

Strings need special consideration: the reason is that generally, gal_data_t needs to also allow for array of strings (as it supports arrays of integers for example). Hence when reading a string value, two allocations may be done by this function (one if array!=NULL).

Therefore, when using the values of strings after this function, keysll[i].array must be interpretted as char **: one allocation for the pointer, one for the actual characters. If you use something like the example, above you don’t have to worry about the freeing, gal_data_array_free will free both allocations. So to read a string, one easy way would be the following:

char *str, **strarray;
strarr = keysll[i].array;
str    = strarray[0];

If CFITSIO is unable to read a keyword for any reason the status element of the respective gal_data_t will be non-zero. If it is zero, then the keyword was found and successfully read. Otherwise, it is a CFITSIO status value. You can use CFITSIO’s error reporting tools or gal_fits_io_error (see FITS Macros, errors and filenames) for reporting the reason of the failure. A tip: when the keyword doesn’t exist, CFITSIO’s status value will be KEY_NO_EXIST.

CFITSIO will start searching for the keywords from the last place in the header that it searched for a keyword. So it is much more efficient if the order that you ask for keywords is based on the order they are stored in the header.

Function:
void
gal_fits_key_read (char *filename, char *hdu, gal_data_t *keysll, int readcomment, int readunit)

Same as gal_fits_read_keywords_fptr (see above), but accepts the filename and HDU as input instead of an already opened CFITSIO fitsfile pointer.

Function:
void
gal_fits_key_list_add (gal_fits_list_key_t **list, uint8_t type, char *keyname, int kfree, void *value, int vfree, char *comment, int cfree, char *unit)

Add a keyword to the top of list of header keywords that need to be written into a FITS file. In the end, the keywords will have to be freed, so it is important to know before hand if they were allocated or not (hence the presence of the arguments ending in free). If the space for the respective element is not allocated, set these arguments to 0 (zero).

Important note for strings: the value should be the pointer to the string its-self (char *), not a pointer to a pointer (char **).

Function:
void
gal_fits_key_list_add_end (gal_fits_list_key_t **list, uint8_t type, char *keyname, int kfree, void *value, int vfree, char *comment, int cfree, char *unit)

Similar to gal_fits_key_list_add (see above) but add the keyword to the end of the list. Use this function if you want the keywords to be written in the same order that you add nodes to the list of keywords.

Function:
void
gal_fits_key_write_filename (char *keynamebase, char *filename, gal_fits_list_key_t **list)

Put filename into the gal_fits_list_key_t list (possibly broken up into multiple keywords) to later write into a HDU header. The keynamebase string will be appended with a _N (N>0) and used as the keyword name.

The FITS standard sets a maximum length for the value of a keyword. This creates problems with file names (which include directories). Because file names/addresses can become very long. Therefore, when filename is longer than the maximum length of a FITS keyword value, this function will break it into several keywords (breaking up the string on directory separators).

Function:
void
gal_fits_key_write_wcsstr (fitsfile *fptr, char *wcsstr, int nkeyrec)

Write the WCS header string (produced with WCSLIB’s wcshdo function) into the CFITSIO fitsfile pointer. nkeyrec is the number of FITS header keywords in wcsstr. This function will put a few blank keyword lines along with a comment WCS information before writing each keyword record.

Function:
void
gal_fits_key_write (fitsfile *fptr, gal_fits_list_key_t **keylist)

Write the list of keywords in keylist into the CFITSIO fitsfile.

Function:
void
gal_fits_key_write_version (fitsfile *fptr, gal_fits_list_key_t *headers, char *program_name)

Write or update (all the) keyword(s) in headers into the FITS pointer, but also the date, name of your program (program_name), along with the versions of CFITSIO, WCSLIB (when available), GSL, Gnuastro, and (the possible) commit information into the header as described in Output headers.

Since the data processing depends on the versions of the libraries you have used, it is strongly recommended to include this information in every FITS output. gal_fits_img_write and gal_fits_tab_write will automatically use this function.


Next: , Previous: , Up: FITS files   [Contents][Index]