FITS Files Under Dervish: C API

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

  • shFitsRead
  • shFitsWrite
  • shFitsTypeName
  • shFitsTBLCOLcomply
  • Users should be careful to understand the differences in nomencalture between Dervish and FITS.

    shFitsRead

    _______________________________________________________________________________ NAME shFitsRead - Read a FITS file Header and Data Unit (HDU) SYNOPSIS (C Syntax) #include "shCFits.h" #include "shCTbl.h" RET_CODE shFitsRead ( HANDLE *handle, /* IN: Dervish handle to read in to */ char *FITSname, /* IN: FITS file specification */ DEFDIRENUM FITSdef, /* IN: Which default to apply */ FITSHDUTYPE FITStype, /* IN: FITS HDU type to read */ int hduWanted, /* IN: HDU to read (0-indexed) */ char *xtension, /* IN: XTENSION to read */ HDR **hdr, /* OUT: Dervish header */ int typeCheck, /* IN: Check data types (REGION) */ int typeRetain /* IN: Keep data types (REGION) */ ) RETURN VALUES SH_SUCCESS Success. The specified HDU was read properly from the FITS file. SH_CONFLICT_ARG Failure. The hduWanted and xtension arguments were both used, or the FITStype and handle type did not match. SH_NOT_SUPPORTED Failure. The handle (object schema) type is not sup- ported. SH_HEADER_IS_NULL Failure. The header vector (used by LIBFITS) could not be allocated. SH_FITS_OPEN_ERR Failure. The FITS file could not be opened. SH_FITS_NOEXTEND Failure. The FITS file does not contain the requested extension HDU. SH_TYPE_MISMATCH Failure. The HDU type and the FITStype are incompatible. SH_FITS_INV_FILE Failure. The FITS file structure is invalid. This includes an invalid FITS header or data area that does not match what is expected (for example, the file ends before the data does). SH_MALLOC_ERR Failure. Space could not be allocated for the FITS file specifi- cation. _______________________________________________________________________________ DESCRIPTION

    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:

    But, in all cases, any metacharacters and environment variables in the file specification (after any defaulting) are translated.

    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:

    The HDU to be read is selected by either the hduWanted or xtension parameter. These parameters conflict, so only one may be passed with a valid value to indicate which search is to take place. The default, if hduWanted is less than zero and xtension is passed as a zero address, is to behave as if hduWanted was passed as zero. This indicates that the Primary HDU is to be read. If hduWanted is positive, it indicates which HDU is to be read, by position (0-indexed). If xtension points to a character string, it is the HDU extension name which must match the XTENSION header keyword value. The first HDU extension matching this specification is read.

    Based on the handle, the following formats (object schemas) are understood:

    The reading of a FITS file is also controlled by the FITStype parameter. If not set to f_hduUnknown, it forces the reading of an ASCII Table (f_hduTABLE) or a Binary Table (f_hduBINTABLE). The corresponding handle type and HDU extension must match. For example, a REGION handle may not be used to receive a Binary Table (if FITStype is f_hduBINTABLE). FITStype is most useful for checking that the appropriate Table is being read, especially if the Table is located through hduWanted. The value of f_hduUnknown avoids this check.

    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.

    Reading REGIONs

    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.

    Reading MASKs

    MASKs are read from the Primary HDU.

    Reading ASCII and 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 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.

    Things to Sort Out

    shFitsWrite

    _______________________________________________________________________________ NAME shFitsWrite - Write a FITS file Header and Data Unit (HDU) SYNOPSIS (C Syntax) #include "shCFits.h" #include "shCTbl.h" RET_CODE shFitsRead ( HANDLE *handle, /* IN: Dervish handle to read in to */ char *FITSname, /* IN: FITS file specification */ DEFDIRENUM FITSdef, /* IN: Which default to apply */ FITSHDUTYPE FITStype, /* IN: FITS HDU type to write */ SHFITSPDU pduWanted, /* IN: Put out a PDU too? */ int append, /* IN: Boolean: append to file */ FITSFILETYPE FITSstd /* IN: SIMPLE=?/chk FITS compliance*/ ) RETURN VALUES SH_SUCCESS Success. The specified HDU was written properly to the FITS file. SH_INVARG Failure. An argument is invalid: pduWanted and/or FITSstd are not valid. SH_CONFLICT_ARG Failure. The append and pduWanted arguments were both used, or the FITStype and handle type did not match. SH_NOT_SUPPORTED Failure. The handle (object schema) type is not sup- ported. SH_FITS_OPEN_ERR Failure. The FITS file could not be opened. SH_FITS_INV_FILE Failure. The FITS file structure is invalid. This includes an invalid FITS header or data area that does not match what is expected (for example, the file length is not a multiple of the FITS record length). SH_MALLOC_ERR Failure. Space could not be allocated for the FITS file specifi- cation. _______________________________________________________________________________ DESCRIPTION

    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:

    But, in all cases, any metacharacters and environment variables in the file specification (after any defaulting) are translated.

    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 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 NONSTANDARD, 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 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').

    Writing HDRs

    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).

    Writing REGIONs

    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).

    Writing MASKs

    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.

    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 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.

    shFitsTypeName

    _______________________________________________________________________________ NAME shFitsTypeName - Return the name of a FITS Header and Data Unit Type SYNOPSIS (C Syntax) #include "shCFits.h" char *shFitsTypeName ( FITSHDUTYPE FITStype /* IN: FITS HDU type */ ) RETURN VALUES o Pointer to a static character string which is the FITS HDU type. _______________________________________________________________________________ DESCRIPTION

    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)').

    shFitsTBLCOLcomply

    _______________________________________________________________________________ NAME shFitsTBLCOLcomply - TBLCOL Table complies with FITS Standard? SYNOPSIS (C Syntax) #include "shCFits.h" RET_CODE shFitsTBLCOLcomply ( TBLCOL *tblCol, /* IN: Table to check */ FITSHDUTYPE FITStype, /* IN: FITS Extension type */ FITSFILETYPE *FITSstd /* IN: FITS compliant? */ ) RETURN VALUES SH_SUCCESS Success. The Table would result in a valid FITS HDU FITSstd indicates whether the HDU is FITS compliant. SH_NOT_SUPPORTED Failure. The FITS HDU type cannot be checked. SH_INVOBJ Failure. The Table itself is invalid (inconsistent). FITSstd still indicates whether the HDU is FITS compli- ant (by ignoring the Table inconsistencies). SH_INV_FITS_FILE Failure. The Table cannot be written as the requested HDU type without being an illegal FITS file (this is different than just non-compliance with the FITS Stan- dard). _______________________________________________________________________________ DESCRIPTION

    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.