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.
shFitsRead is a generic FITS reader, invoking other routines to read specific types of FITS header and data units (HDUs) into Dervish object schemas. A specified HDU is read from the FITS file. The FITS file specification can be expanded with a default path (directory) and extension, as set with shDirSet. If DEF_NONE is passed, no defaulting will be applied. If DEF_DEFAULT is passed, the default path and extension are based on the handle type:
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 FITStype). 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:
Based on the handle, the following formats (object schemas) are understood:
hdr is an optional argument. If a null address is passed, no value is returned. If a non-null address is passed, the address of the Dervish header associated with the handle is returned.
REGIONs are read from the Primary HDU.
typeCheck and typeRetain parameters are used only with REGION handles. typeCheck (corresponding to shRegReadAsFits's checktype parameter) 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 typeRetain parameter (corresponding to shRegReadAsFits's keeptype parameter) 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 the 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. The array descriptor offset will still be the 0-indexed byte offset of the first element of the array, measured from the start of the heap area.
shFitsWrite is a generic FITS writer, invoking other routines to write specific types Dervish object schemas to FITS header and data units (HDUs). A specified header and data unit (HDU) is written to a FITS file. The FITS file specification can be expanded with a default path (directory) and extension, as set with shDirSet. If DEF_NONE is passed, no defaulting will be applied. If DEF_DEFAULT is passed, the default path and extension are based on the handle type:
The following FITS HDU types can be written:
The writing of a FITS file is also controlled by the FITStype
parameter. FITStype must be compatible with the handle
type.
For example, a REGION handle may not be written to a
Binary Table extension HDU (if FITStype were
f_hduBINTABLE
).
Usually, the handle type is adequate to select the FITS HDU type,
thus a FITStype value of f_hduUnknown
is adequate.
But, TBLCOL handles require either
f_hduTABLE
or f_hduBINTABLE
to write an
an ASCII or Binary Table respectively.
Setting the append parameter to a true value 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 pduWanted parameter being something
other than SH_FITS_PDU_NONE
.
The SH_FITS_PDU_MINIMAL parameter 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 FITSstd parameter performs two related functions:
If FITSstd is STANDARD, the object schema pointed to by the handle is first checked to see if a FITS compliant HDU can be written. If not, shFitsWrite 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 FITStype must be either f_hduPrimary
or
f_hduUnknown
).
pduWanted must be SH_FITS_PDU_NONE
.
The HDR (Dervish headers) is checked to see whether it would form a legal FITS Primary header without any following data. If necessary, the FITS keywords SIMPLE, BITPIX, NAXIS, and END will be inserted (temporarily).
REGIONs are written to the Primary HDU; they cannot be appended to an existing FITS file. Additionally, shRegWriteAsFits's naxis parameter is not supported. The number of axes is defaulted to 2, unless the REGION is empty (both the number of rows and the number of columns are zero).
MASKs are written to the Primary HDU; they cannot be appended to an existing FITS file. Additionally, the FITSstd parameter is ignored -- no FITS compliance testing is performed.
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 FITSstd parameter 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.
The FITS header type is converted to a string value.
shFitsTypeName allows Dervish users to use consistent names for FITS
HDU types.
This value is usually the header and data unit (HDU) extension name, such as
TABLE for an ASCII Table.
But, some HDUs do not have explicit extension names, such as
`Primary' and `Random Groups'.
An explicitly unknown header type, f_hduUnknown
, is distinguished
from an invalid or unrecognized header type (`(unknown)'
vs. `(invalid)'
).
The TBLCOL Table is checked to see if it would result in a FITS compliant HDU. The testing is affected by the type of HDU (FITStype parameter). The result, FITSstd, is either STANDARD or NONSTANDARD.
It is important to note that shFitsTBLCOLcomply tests the potential for a TBLCOL Table to be rendered FITS-compliant rather than actually being FITS-compliant. This subtle distinction applies when writing Binary Tables whose integer object schemas do not translate directly to a FITS-compliant data type. In such cases, the Table writer attempts to use the FITS community convention of setting TSCALn and TZEROn to flip the "signedness" of the data type.
FITSstd is an optional argument. If a null address is passed, no value is returned.