[AIT logo]

Institut für Astronomie und Astrophysik

Abteilung Astronomie

Sand 1, D-72076 Tübingen, Germany
[Uni logo]



Table of Contents




Introduction

FITS (Flexible Image Transport Sytem) is a standardized data format which is widely used in astronomy. Information on the FITS format can be obtained from the NRAO FITS archive or from the FITS support office at Goddard. I note here only that FITS is a binary format, and so the binary option should be used when copying FITS files with FTP.

The IDL Astronomy Library contains a variety of procedures for reading, writing, and modifying FITS files. Information on how to use these procedures is given in http://idlastro.gsfc.nasa.gov/fitsio.html and is also briefly described here. There are four main types of FITS I/O procedures available in the Library:

  1. MRDFITS() will read all standard FITS data types into IDL arrays (for primary images and image extensions) or structures (for binary or ASCII tables). The procedure MWRFITS() will write an IDL structure to a FITS file, with many options available (binary or ASCII table, default generation of column names). These procedures were written by Tom McGlynn (USRA/Goddard). Further information on MRDFITS is available in the Appendix below.
  2. The procedure READFITS can be used to read FITS headers and arrays into IDL variables. Additional procedures in the fits_table directory are then required to interpret binary and ASCII tables. The FT* procedures in the /fits_table directory are used to interpret a FITS ASCII table, and the TB* procedures are used interpret FITS Binary table. The procedure WRITEFITS can be used to write a primary image, ASCII extension, or image extension (see the Appendix). The READFITS/WRITEFITS software currently cannot read variable length binary tables, or write any type of binary table.
  3. The directory fits_bintable contains IDL procedures for FITS I/O written by Bill Thompson (Goddard/ARC). This software can be used to read or write all types of FITS images and binary tables. The one limitation of these procedures is that they do not handle ASCII tables. Further information on these procedures is available in the LaTeX file fits_bintable.tex in the /text directory.
  4. The five procedures FITS_CLOSE, FITS_HELP, FITS_OPEN, FITS_READ, and FITS_WRITE were written by D. Lindler (ACC/Goddard) and are used by the STIS/NICMOS instrument teams on the Hubble Space Telescope (HST). These procedures are especially efficient for FITS files with many extensions, and they also recognize conventions used in HST FITS files that are not part of the standard FITS definition. Like READFITS/WRITEFITS, these procedures require further processing of binary and ASCII table, by using procedures in the fits_table directory. In particular, the procedure FTAB_EXT uses FITS_READ to provide a quick and easy extraction of FITS ASCII or Binary tables into IDL vectors. Besides the four main categories above, other FITS procedures are available to read/write FITS files on tape, or to convert between FITS and the STSDAS format (.hhh and .hhd files) used for HST data. (See pro/sdas/README for info on the STSDAS format.) This README file should be monitored for improvements in the FITS I/O package. A FITS header is a string array with 80 characters per line. Using the IDL PRINT command to display the header will result in a space between every line. The HPRINT procedure will display a FITS header without this extra space.

    The procedures FITS_INFO and FITSDIR use the non-standard system variables !TEXTUNIT and !TEXTOUT. These can be added to one's session using the procedure ASTROLIB.

    The available FITS I/O routines can be summarized as follows:

    1. Disk FITS <====> IDL variables
      • The procedure MRDFITS is a very generalized FITS reader that can read almost any type of FITS file, including random groups, and variable length binary tables. ASCII and binary columns are directly mapped into the tags of an IDL structure. MWRFITS() will write an IDL structure to a FITS file.
      • READFITS() will read a disk FITS file into IDL data and header arrays. It can handle REAL*4 and REAL*8 data and extensions but not random group FITS. READFITS() also has STARTROW and NUMROW keywords to read selected rows from a primary image or extension. Under Unix, READFITS() can directly read a gzip or Unix compress file. ASCII and binary tables require further processing with the FT* and TB* procedures in the fits_bintable directory. In particular, FTAB_EXT can be used to extract IDL vectors from a FITS binary or ASCII table.
      • WRITEFITS will write an IDL data and header array to a disk FITS file. It can handle all valid FITS formats except random groups. Use the /APPEND keyword to WRITEFITS to add a FITS extension to an existing FITS file (see the Appendix).
      • The procedure HEADFITS() can be used to read just the FITS header.
      • The procedure FXREAD in fits_bintable can be used as an alternative to READFITS for reading a primary array. It is a procedure rather than a function and has the ability to read a subarray or every nth pixel from the primary FITS array. The procedure FXWRITE in fits_bintable can be used as an alternative to WRITEFITS.
      • The procedure FITS_INFO displays info about FITS file(s) in a directory. The info include the number of extensions, and the size and type of each header or array. The procedure FITSDIR displays selected keywords from the primary headers in a set of FITS files.
      • The procedure RDFITS_STRUCT will read an entire FITS file into an IDL structure. Each header, image or spectra, or table is placed into a separate structure tag.
    2. FITS Tape <=====> Disk FITS
      The procedures FXTAPEWRITE and FXTAPEREAD are no longer available.

      Alternatively, a Unix FITS tape file can be copied to disk using dd, (as in dd if=/dev/tape of=file.fits bs=2880).


    MRDFITS - A multiple format FITS reader. V2.0

    The MRDFITS utility is intended to be a general purpose function allowing users to quickly read FITS files in all standard formats. MRDFITS returns an array or structure containing the data from the specified FITS extension. Header information may optionally be returned as a string array. MRDFITS currently supports the following FITS data types: MRDFITS uses the dynamic structure definition capabilities of IDL to generate a structure matching the characteristics of the FITS data and then reads the data into the structure. Some tailoring of the FITS data is possible: MRDFITS is called as a function similar to the old READFITS utility, e.g.,
        str = mrdfits(file, exten_no, header)
    
    where file is a file name, exten_no is the extension to be read (0 for the primary data array) and header is an optional variable in which the header information will be stored. A number of optional keyword parameters are available:
        /FSCALE and /DSCALE  cause scaling to single and double precision.
        COLUMNS=         allows users to specify the columns desired.
        RANGE=           allows users to retrieve only some rows.
        STRUCTYP=        gives the structure type for the structure
        TEMPDIR=         gives the directory for temporary files
        /SILENT          suppresses informative messages
        /USE_COLNUM          makes tag names of the form C#
        /NO_TDIM             disable processing of TDIM keywords.
        ERROR_ACTION=        action specified in on_error
    
    MRDFITS uses the EXECUTE function where possible but creates temporary procedures when complex structures are needed. The MRD_STRUCT function is used for the dynamic definition of structures.

    MRDFITS is largely a standalone utility, but does use the parameter parsing of FXPAR to find elements in a header. All I/O is done within MRDFITS. The IEEE_TO_HOST routine is called for to convert data to the local representation.

    Known limitations include:

    On Unix systems MRDFITS can handle files compressed with either the `standard' Unix compress utility or with the Gnu gzip utility. It assumes that files ending with .Z, .gz and .GZ are to be decompressed. Decompression is done using a sub-process and pipes so that no temporary file is created. In the future I anticipate implementing decompression on other architectures but the process will likely involve temporary files.

    V2.0 of MRDFITS includes the following enhancements:

    Please send comments and bug reports to:
        Tom McGlynn
        Compton Observatory Science Support Center
            mcglynn@grossc.gsfc.nasa.gov
        301-286-7743
    

    Writing an IMAGE Extensions with WRITEFITS

    The format of a FITS IMAGE extension duplicates that of a primary FITS array. Thus, unlike binary or ASCII tables extensions, a FITS IMAGE extension does not require any further interpretation after it has been read by READFITS with the EXTEN keyword. A FITS extension can be added to an existing FITS file by using WRITEFITS with the /APPEND keyword. Users need to make sure that (1) the primary FITS header includes an EXTEND keyword, and (2) the required keywords of the IMAGE extension header match those described in the defining document. One way to make sure that these criteria are met is to use the /EXTEND and /IMAGE keywords of the MKDHR procedure.

    For example, to create a FITS file with a dummy primary header (i.e. no primary array) and two IMAGE extensions containing the IDL arrays "im1" and "im2" to a file 'TEST.FITS'

            IDL> mkhdr,h,'',/EXTEN        ;Create a dummy header (NAXIS=0) and
                                          ;include an EXTEND keyword
    
        IDL> writefits,'test.fits','',h     ;Write the header to disk
                                                ;Since there is no primary image
                                                ;it is set to ''
    
        IDL> mkhdr,h1,im1,/IMAGE      ;Make a minimal IMAGE extension header h1
                                          ;appropriate to the array im1 using
                                          ;Additional header keywords can be added
                                          ;using SXADDPAR
    
    
        IDL> writefits,'test.fits',im1,h1,/app  ;Append to existing FITS file
    
            IDL> mkhdr,h2,im2,/IMAGE       ;Create IMAGE header for im2
    
        IDL> writefits,'test.fits',im2,h2,/APPEND    ;Append second extension
    



    Index of Subroutines

    CHECK_FITS Check that keywords in a FITS header array match the associated data
    FITS_ADD_CHECKSUM Add or update the CHECKSUM and DATASUM keywords in a FITS header
    FITS_ASCII_ENCODE() Encode an unsigned longword as an ASCII string to insert in a FITS header
    FITS_CLOSE Close a FITS data file
    FITS_HELP To print a summary of the primary data units and extensions in a FITS file. ;
    FITS_INFO Provide information about the contents of a FITS file
    FITS_OPEN Opens a FITS (Flexible Image Transport System) data file.
    FITS_READ To read a FITS file.
    FITS_TEST_CHECKSUM() Verify the values of the CHECKSUM and DATASUM keywords in a FITS header
    FITS_WRITE To write a FITS primary data unit or extension.
    FITSDIR Display selected FITS keywords from the headers of FITS files.
    FITSRGB_to_TIFF Combine separate red, green, and blue FITS images into TIFF format
    FXMOVE Skip a specified number of extensions in a FITS file
    FXPOSIT Return the unit number of a FITS file positioned at specified extension
    HEADFITS Read a FITS (primary or extension) header into a string array.
    MKHDR Make a minimal primary (or IMAGE extension) FITS header
    MODFITS Modify a FITS file by updating the header and/or data array.
    MRD_HREAD Reads a FITS header from an opened disk file or Unix pipe
    MRDFITS Read all standard FITS data types into arrays or structures.
    MWRFITS Write all standard FITS data types from input arrays or structures.
    RDFITS_STRUCT Read an entire FITS file (all extensions) into a single IDL structure.
    READFITS Read a FITS file into IDL data and header variables.
    SXADDHIST Procedure to add HISTORY (or COMMENT) line(s) to a FITS header
    SXADDPAR Add or modify a parameter in a FITS header array.
    SXDELPAR Procedure to delete a keyword parameter(s) from a FITS header
    SXPAR Obtain the value of a parameter in a FITS header
    WRITEFITS Write IDL array and header variables to a disk FITS file.

    Last modified by pro2html on 2008 November 09 at 04:11 UTC

    [Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]

    Jörn Wilms (wilms@astro.uni-tuebingen.de)
    Updated automatically