It is instructive at this point to examine the contents of a FitsChanFitsChan after we have read a FrameSetFrameSet from it (17.4). The following would rewind our FitsChan and display its contents:
#include <stdio.h> char card[ 81 ]; ... astClear( fitschan, "Card" ); while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card );
The output, if we started with the example FITS header in 17.3, might look like this:
SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 BITPIX = -32 / Bits per pixel. NAXIS = 2 / Number of dimensions NAXIS1 = 300 / Length of x axis. NAXIS2 = 300 / Length of y axis. SURVEY = 'COBE DIRBE' BUNITS = 'MJy/sr ' ORIGIN = 'CDAC ' / Cosmology Data Analysis Center TELESCOP= 'COBE ' / COsmic Background Explorer satellite INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] PIXRESOL= 9 / Quad tree pixel resolution [6, 9] DATE = '27/09/94' / FITS file creation date (dd/mm/yy) DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) COMMENT COBE specific keywords DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) DATE-END= '25/09/90' / date of final data represented (dd/mm/yy)
Comparing this with the original, you can see that all the FITS cards that represent WCS information have been removed. They have effectively been ``sucked out'' of the FitsChan by the destructive read that astReadastRead performs and converted into an equivalent FrameSet. AST remembers where they were stored, however, so that if we later write WCS information back into the FitsChan (17.7) they will, as far as possible, go back into their original locations. This helps to preserve the overall layout of the FITS header.
You can now see why astRead performs destructive reads. It is a mechanism for removing WCS information from a FITS header while insulating you, as a programmer, from the details of the encoding being used. It means you can ensure that all relevant header cards have been removed, giving you a clean slate, without having to know which FITS keywords any particular encoding uses.
Clearing this WCS information out of a FITS header is particularly important when considering how to write new WCS information back after processing (17.7). If any relevant FITS cards are left over from the input dataset and find their way into the new processed header, they could interfere with the new information being written.27 The destructive read mechanism ensures that this doesn't happen.