Procedures for reading and writing FITS files, including ASCII and Binary Tables, are provided:
Users should be careful to understand the differences in nomencalture between Dervish and FITS.
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
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:
When refering to an individual field within a Table, one of two command line options can be used:
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:
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:
Other list elements are keyed by the FITS header keyword. The complete FITS header is not included in the keyed list.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 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.
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.
MASKs are read from the Primary HDU.
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.
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:
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 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').
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).
REGIONs are written to the Primary HDU. The following options cannot be used when writing REGIONs:
MASKs are written to the Primary HDU. The following options cannot be used when writing MASKs:
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.