Astronomical image processing guide (How to list of info keywords?)

A great advantage of the FITS format is support of any arbitrary information included into an image file. A place for the info is reserved in header of the FITS file. Every FITS header must contain a set of records (lines) containing certain mandatory keywords. The set may be followed by records with any other keywords.

The mandatory keywords are: SIMPLE, EXTEND and END. All others are optional. The records of header has the fixed structure:

1-8 - keyword
9 - = equal's sign
10-x - value (various lengths)
x -80 - comment (every text following slash '/')

All records are 80-bytes long and there is no separator between ones. The special keywords COMMENT and HISTORY has no defined a structure and introduce any text string (continuation lines are not allowed). Recent recommendations to contents of the records adds physical units to numerical values as a part of comment. Any set of keywords is not widely used. It means that various utilities may used different keyword for the same entity.

The most common keywords are included in following (artificial) example:

SIMPLE = T / file does conform to FITS standard
BITPIX = 16 / number of bits per data pixel
NAXIS = 2 / number of data axes
NAXIS1 = 382 / length of data axis 1
NAXIS2 = 255 / length of data axis 2
EXTEND = T / FITS dataset may contain extensions
EXPTIME = 60.000 / [s] Exposure time
DATE-OBS= '2008-06-06T01:02:41.390' / UTC of exposure start
FILTER = 'R ' / filter
OBJECT = 'Star' / Object name
COMMENT This file was written by XXX.
END

We have more ways to handle with FITS header keywords. Practically, we will need to list of all keywords (as a variant of more or less command on unix's shell) or list of value of some specified record. Both situations can be easy coded. We introduce of utility FITSless which will print all keywords (full header) without any switches and a specified value when any keyword will presented, its value will be printed.

The values are usually different kinds (from computer point of view). For example, the observer's name will coded as a string, an exposure time will a real number, the date of start will a specially formatted string. To print the information, we will use only string representation, but in real code it will be better use of appropriate data type. Unfortunately, there is no simple way how to do it in Fortran, C and cFITSIO under recent versions of ones.

program FITSless

implicit none

integer :: status
! status ... FITS status (0=no error)

integer :: j,blocksize

character(len=666) :: name = 'image.fits'
! name .. fill with name of the image to open

character(len=666) :: keyword
! keyword to print the record

character(len=666) :: record
! header's record

character(len=666) :: value, comment
! record's value & comment

integer :: nhead, hpos
! number of records in header and current position

! get first command line parameter
call get_command_argument(1, keyword)

status = 0
call ftopen(25,name,0,blocksize,status)
if( status /= 0 ) stop 'File not found.'

! list specified keyword or full header
if( keyword /= ' ' ) then

write(*,*) 'List of a record specified by your keyword:'
write(*,*) '-------------------------------------------'

call ftgkys(25,keyword,value, comment, status)
! checking status of the operation
if( status == 0 ) then
write(*,*) trim(keyword),' = ',trim(value),' /',trim(comment)
else
write(*,*) 'Keyword "',trim(keyword),'" not found.'
end if

else

write(*,*) 'Full header list:'
write(*,*) '-----------------'

call ftghps(25,nhead,hpos,status)
do j = 1, nhead
call ftgrec(25,j,record,status)
write(*,*) trim(record)
enddo

end if

call ftclos(25,status)

end program FITSless

The code is self-explanatory, I recommend try this following experiments:

• try give as parameter an arbitrary text string or upper/lower case keywords
• process any printed information by some another text tool (sed, grep,..)
• play with listing of a record on given position in the header
• modify code to read an input file name by command-line parameters