FITS Files Under Dervish: Tcl API

Procedures for reading and writing FITS files, including ASCII and Binary Tables, are provided:

  • fitsDirGet
  • fitsRead
  • fitsWrite
  • Users should be careful to understand the differences in nomencalture between Dervish and FITS.

    TBLCOL Handles

    To read an ASCII or Binary Table in columnar (TBLCOL) format, Dervish provides a TBLCOL object schema. A handle, to an empty Table, can be created with either C or Tcl routines, such as handleNewFromType. They can be destroyed with, for example, handleDelFromType (do not use handleDel as it only frees the handle memory and not the memory used by the Table):

        dervish> set myTbl [handleNewFromType TBLCOL]
        h1
        dervish> fitsRead $myTbl m51.fits -xtension BINTABLE
        dervish> handleDelFromType $myTbl
    

    The Dervish header associated with a TBLCOL Table can be accessed with a handle expression. Consider an example where `h3' is the handle to a TBLCOL Table:

        dervish> hdrGetLine h3.hdr AUTHOR
    

    Defaulting File Specifications

    Tcl commands which take a file specification as a parameter usually expand the file specification based on the handle type involved. The file specification is prefixed with a default directory path and suffixed with a default file extension. These defaults come from dirSet's list of defaults. Any metacharaceters and environment variables in the expanded file specification are also substituted (expanded).

    The choice of which defaults from dirSet are applied are based on the handle type. If no handle is involved, the Tcl command uses the same defaults (for example, as in fitsDirGet). The selection of a dirSet default based on the handle type is as follows:

    Most Tcl commands allow the -dirset option to override the selection of which of dirSet's defaults are applied. The choices are:

    In addition, NONE indicates that no file expansion with defaults is to take place. Still, the substitution (expansion) of metacharacters and environment variables is done.

    Specifying Fields: -col and -field

    When refering to an individual field within a Table, one of two command line options can be used:

    fitsDirGet

    _______________________________________________________________________________ NAME fitsDirGet - Get a directory of a FITS file's header and data units(HDU) SYNOPSIS (Tcl Syntax) fitsDirGet <file> [-dirset defaultType] ARGUMENTS file The FITS file specification. -dirset Indicate which default type is to be used for expanding the FITS <file> specification. If -dirset is not specified, the default type is REGION_FILE. RETURN VALUES TCL_OK Success. Successful completion. The interp result string contains the directory in a Tcl list of keyed lists. TCL_ERROR Failure. The interp result string contains an error message. _______________________________________________________________________________ DESCRIPTION

    The headers in the FITS file are read and a directory of the header and data units (HDUs) is returned. By default, the FITS file specification is expanded with a default directory (path) and file extension from dirSet's REGION_FILE defaults. The default file expansion can be overridden with the -dirset option.

    fitsDirGet's result is a Tcl list of keyed lists. Each list element, corresponding to an HDU, is a keyed list with the following information:

    {HDUn {{TYPE {Primary}} {NAXIS 3}}} {HDUo...} where HDUn indicates the position (0-indexed) of the HDU within the FITS file. You can access information about each HDU by its position within the FITS file. For example:
        dervish> set fitsDir [fitsDirGet m51.fits]
        {{HDU0 {{TYPE {Primary}} {NAXIS 2}}} {HDU2 {{TYPE {BINTABLE}} ...}}}
        dervish> keylget fitsDir HDU2.NAXIS
        2
    

    The TYPE specifies the type of HDU:

  • Primary
  • Random Groups
  • TABLE (ASCII Table)
  • BINTABLE (Binary Table)
  • Other list elements are keyed by the FITS header keyword. The complete FITS header is not included in the keyed list.

    fitsRead

    _______________________________________________________________________________ NAME fitsRead - Read a FITS file header and data unit (HDU) SYNOPSIS (Tcl Syntax) fitsRead <handle> <file> [-dirset defaultType] [-ascii | -binary] [-hdu n | -xtension name] [-checktype] [-keeptype] ARGUMENTS handle The handle into which the FITS HDU will be read. The handle must be described by an object schema. The schema implicitly indicates which format an HDU should be read. file The FITS file specification. -dirset Indicates which default type is to be used for expanding the FITS <file> specification. If -dirset is not specified, the default type is based on the handle type. -ascii Indicates that a FITS ASCII Table extension (TABLE HDU) is to be read. -ascii conflicts with -binary. -binary Indicates that a FITS Binary Table extension (BINTABLE HDU) is to be read. -binary conflicts with -ascii. -hdu n Read the nth HDU in the FITS file. The value must be a positive integer (it's 0-indexed). If -xtension is not present, the def- ault is to read the primary HDU (equivalent to -hdu 0). -hdu conflicts with -xtension -xtension name The header must match the specified extension. The first HDU matching the XTENSION name will be read. -xtension conflicts with -hdu. -checktype REGION <handle> only. Indicates that if the type of the extant REGION is not the type in the FITS file (HDU), abort the read with an error. -keeptype REGION <handle> only. Indicates that the pixels in the FITS PDU are to be cast to the type of the extant REGION when being read in. RETURN VALUES TCL_OK Success. Successful completion. The interp result string contains the <handle> expression. TCL_ERROR Failure. The interp result string contains an error message. _______________________________________________________________________________ DESCRIPTION

    A specified header and data unit (HDU) is read from the FITS file. By default, the FITS file specification is expanded with a default directory (path) and file extension based on the handle type. The default file expansion can be overridden with the -dirset option.

    The way an HDU is read is affected by the HDU position in the FITS file, the handle object schema type, and the expected HDU type (as specified by -ascii or -binary). The setting of the Primary Data Unit's (PDU) SIMPLE keyword does not affect reading. The HDUs are read as if all Dervish extensions to the FITS Standard were permitted.

    The following FITS HDU types can be read:

    The default, if -hdu and -xtension are not present, is to read the primary HDU (first HDU in the FITS file). Support for ASCII Tables, Random Groups, and any future FITS extensions is not available. The handle argument implicitly specifies how the FITS HDU should be read. The following formats (object schemas) are understood:

    The reading of a FITS file is also controlled by the -ascii and -binary options. When present, they force the reading of an ASCII Table or Binary Table, respectively. If either is present, the corresponding handle type and HDU extension must match. For example, a REGION handle may not be used to receive a Binary Table (if -binary were present). Using -ascii or -binary is most useful for checking that the appropriate Table is being read, especially if the -hdu option is used to indicate which HDU to read.

    Reading REGIONs

    REGIONs are read from the Primary HDU.

    -checktype and -keeptype options are valid only with REGION handles. -checktype forces the checking of the FITS file pixel data type against the pixel data type associated with the extant REGION. If the data types differ, the reading of the FITS PDU into the REGION is aborted.

    The presence of the -keeptype option indicates that the pixel data type of the extant REGION is to be retained. Pixel values from the FITS file are converted to the pixel data type of the REGION. If the FITS file pixel value does not fit in the range of values permitted by the REGION pixel data type, the read in pixel value is set to the maximum/minimum possible value for the REGION pixel data type (for example, this can occur when reading 32-bit integers into 16-bit integers). If the REGION does not have a data type associated with it, the data type of the pixels in the FITS file is used.

    Reading MASKs

    MASKs are read from the Primary HDU.

    Reading ASCII or Binary Tables

    ASCII and Binary Table data is converted to the data type specified by the TFORMn keyword. It is aligned based on the format (general object schema or one of the special formats). Scaling and zeroing are applied only when changing the "signedness" of an integer data type for Binary Tables. If TSCALn and TZEROn are not applied, they are saved for reference by the user.

    If the heap area is used by a Binary Table, the data in the heap area is converted and aligned (based on the `P' data type specified by the TFORMn keyword). As with Table data (Record Storage Area) per se, scaling and zeroing are applied only for changing the "signedness" of an integer heap data type (even though the FITS Standard indicates that TSCALn and TZEROn are not defined for heap). The Table array descriptors are modified to reflect changes in placement and alignment of the heap area data.

    Things to Sort Out

    fitsWrite

    _______________________________________________________________________________ NAME fitsWrite - Write a FITS file header and data unit (HDU) SYNOPSIS (Tcl Syntax) fitsWrite <handle> <file> [-dirset defaultType] [-ascii | -binary] [-pdu option] [-standard {T|F}] [-extend] [-append] ARGUMENTS handle The handle from which the FITS HDU will be written. The handle must be described by an object schema. The schema implicitly indicates the format in which the HDU will be written out. file The FITS file specification. -dirset Indicates which default type is to be used for expanding the FITS <file> specification. If -dirset is not specified, the default type is based on the handle type. -ascii Indicates that <handle> is to be written to a FITS ASCII Table extension (TABLE HDU). -ascii conflicts with -binary. -binary Indicates that <handle> is to be written to a FITS Binary Table extension (BINTABLE HDU). -binary conflicts with -ascii. -pdu Indicates whether a Primary HDU is written. The options are NONE and MINIMAL. If NONE is specified, no PDU is written. MINIMAL indicates that a minimal PDU for handling FITS exten- sions is written. -pdu conflicts with -append. -standard Indicates whether the HDU is to be FITS compliant. -standard set to a `true' value causes the HDU to be tested for FITS compliance. -standard also controls the value of the FITS SIMPLE keyword if the PDU is written. Accepted `true' values are `1', `true', `on', and `yes'. Accepted `false' values are `0', `false', `off', and `no'. These may be abbreviated and are case-insensitive. If -standard is not specified, the default type is `true'. -extend Indicates that the Primary HDU contain the FITS keyword EXTEND set to `T'. -extend conflicts with -append and -pdu NONE. -append Append the FITS HDU to the <file>. If the <file> does not exist, it will be created. -append conflicts with -pdu and -extend. RETURN VALUES TCL_OK Success. Successful completion. The interp result string contains the <handle> expression. TCL_ERROR Failure. The interp result string contains an error message. _______________________________________________________________________________ DESCRIPTION

    A specified header and data unit (HDU) is written to a FITS file. By default, the FITS file specification is expanded with a default directory (path) and file extension based on the handle type. The default file expansion can be overridden with the -dirset option.

    The following FITS HDU types can be written:

    Support for Random Groups and any other FITS extensions is not available. The handle argument implicitly specifies which FITS extension HDU should be written. The following formats (object schemas) are understood:

    The writing of a FITS file is also controlled by the -ascii and -binary options. Either is necessary when writing from a TBLCOL object schema to an ASCII or Binary Table (respectively). If either option is present, the handle type must match. For example, a REGION handle may not be written to a Binary Table extension HDU (if -binary were present).

    The -extend option indicates that the FITS keyword EXTEND be set to `T'. It can only be used when a Primary HDU is written by fitsWrite. This occurs if -pdu is specified with an option other than NONE or a REGION is written.

    The -append option indicates that the HDU being written out be appended to the FITS file. Only FITS extensions can be appended, that is, handles that must be written as the Primary Data Unit (PDU) cannot be appended (such as REGIONs and MASKs). If the file does not exist initially, or is zero-length, then a PDU can be written out also with the -pdu option. The MINIMAL option value will cause a minimal PDU to be written that will allow FITS readers to access the extension HDU being written (the FITS EXTEND keyword is set to `T').

    The -standard option performs two related functions:

    If -standard is false, no checks are made to see whether the resulting HDU (that's being written out) will comply with the FITS Standard. Furthermore, if the HDU being written is the PDU, then the FITS SIMPLE keyword is set to be false (`F').

    If -standard is true, the object schema pointed to by the handle is first checked to see if a FITS compliant HDU can be written. If not, fitsWrite returns with a failure status. If the resulting and FITS compliant HDU is also the PDU, the FITS SIMPLE keyword is set to be true (`T').

    Writing HDRs

    HDRs are written to the Primary HDU (they may not be -appended as an extension header). The following options cannot be used when writing HDRs:

    The HDR (Dervish headers) is checked to see whether it would form a legal FITS Primary header without and following data. If necessary, the FITS keywords SIMPLE, BITPIX, NAXIS, and END will be inserted (temporarily).

    Writing REGIONs

    REGIONs are written to the Primary HDU. The following options cannot be used when writing REGIONs:

    Additionally, fitsWrite does not provide support for regWriteAsFits's -naxis option. Instead, the number of axes is set to 2, unless the REGION is empty (the number of rows and columns are both zero).

    Writing MASKs

    MASKs are written to the Primary HDU. The following options cannot be used when writing MASKs:

    Writing ASCII or Binary Tables

    Table data is converted to the appropriate form based on the FITS HDU type -- whether it's an ASCII Table or a Binary Table. The mapping of object schema data types of the in-memory data is the reverse of the mappings used when reading in ASCII or Binary Tables. The -standard option affects the writing of Tables through a possible flip of the "signedness" of unsupported FITS integer data types.

    FITS ASCII Table data is written with printable ASCII characters (though it is possible for character string object schemas (of type STR) to contain non-printable characters). The field size is predetermined, based on the data type. The size of a character string field (type STR) is based on the dimensions of the in-memory Table field. Character strings are blank padded on the right to fill the size of the field.

    Some FITS keywords are not permitted in the FITS header, depending upon the resulting TFORMn data type. For example, `A' data types under ASCII Tables may not have TSCALn and TZEROn keywords. If the corresponding values are present in the field, they are not written to the FITS header, nor is any warning issued.