tclFitsIo TCL Routines

FITS I/O for the SDSS has a few wrinkles in it following from the fact that our primary data are 16-bit UNSIGNED data. FITS does not supply an unsigned type, only the BZERO and BSCALE mechanism. However, certain systems, like the data acquisition system do not have the time to transform unsigned data into standard FITS by performing the required transformations. Therefore, DERVISH supports unsigned data in the following ways:

1) Standard FITS. BZERO and BSCALE are used. As an example, for 16-bit unsigned data, BZERO is 32768. BSCALE is 1.0. Each pixel is transformed when written or when read.

2) Non-standard FITS. SIMPLE is set to F. The header contains the UNSIGNED and SDSS keywords, indicating that the data are actually unsigned, and should not be transformed.

In DERVISH, regions have headers. While these are similar to FITS headers, they are logically a different thing. The region header is loaded from the FITS header when a FITS file is read, and translated to a FITS header when a region is written.

It is an error to have the following keywords in a header bound to the region structure. These keywords are filtered out by the FITS reader. The FITS writer will add the appropriate keywords (from this group) to the header before writing the FITS file.

SIMPLE BITPIX NAXIS NAXIS1 NAXIS2 BZERO BSCALE UNSIGNED SIGNED SDSS END For each routine, valid values for the dirset option can be found in shCFitsIo.h. If any of these values are used, then the defaults (defined by dirSet) for directory, file extension or both, will be added to the passed in FITS file specification before the file is opened.
  • regReadAsFits
  • regWriteAsFits
  • hdrReadAsFits
  • hdrWriteAsFits
  • 
    
    

    regReadAsFits

    Read a Unix-resident disc file (in FITS format) into a region. In cases where the FITS data being read in is not of the same size as that already contained by the region (number of rows are different and/or number of columns times pixel type size is different), the pixel storage area and the pixel vector array are deleted and remalloced to be of the correct size. In these cases, if the region has an associated mask, the mask data storage area and the mask vector array are deleted and remalloced also. The region and mask structures themselves are not deleted, but the appropriate fields within them are updated. For example, region h1 contains data of type TYPE_U16 with 2048 rows and 2048 columns. The following table will illustrate when the pixel storage (and vector array) will be deleted and remalloced based on the data being read in from a FITS file. (The * represents any number.)

          FITS            ROW         COLUMN               PIXEL STORAGE AND  
        DATA TYPE        NUMBER       NUMBER                VECTOR DELETED??
    ---------------------------------------------------------------------------
        TYPE_U16          2048         2048                      NO
        TYPE_S16          2048         2048                      NO
        TYPE_U16          1024         1024                      YES
        TYPE_U16          2100         2100                      YES
        TYPE_U8            *            *                        YES
        TYPE_S8            *            *                        YES
        TYPE_U32           *            *                        YES
        TYPE_S32           *            *                        YES
        TYPE_FL32          *            *                        YES
    
    
    

    Data may not be read into a subregion. The region may have no subregions. In addition the mask may not be a submask or have submasks.

    TCL: regReadAsFits <region> <file> [-dirset defaultType] [-checktype] [-keeptype] [-pipe] [-tape] <region> Name of destination region. <file> FITS file to read. [-dirset] Optional Switch. The type of default file specifi- cation to be applied to <file>. The default is as if -dirset REGION_FILE were present. [-checktype] Optional Switch. If present, give an error if the type of the region is not the type implied by the FITS file. [-keeptype] Optional Switch. If present, the pixels in the FITS file are cast to the type of the region while being read in. If the read in pixel value is greater/lesser than that allowed by the region type (this occurs for example when reading in signed 32 bit data into a signed 16 bit region), set the pixel value to the maximum/minimum allowed value dictated by the new region type. The region remains the same data type that it started. Otherwise the region is changed to the data type of the pixels in the FITS file. [-pipe] Optional Switch. If present then the value of <file> is taken to be the read end of an open pipe descriptor. [-tape] Optional Switch. If present then the value of <file> is the name of the tape device from which to read. Returns: TCL_OK Successful completion. The Interp result string will contain <region>. TCL_ERROR Error occurred. The Interp result string will contain the error string.
    
    
    
    

    regWriteAsFits

    Writes a region into a Unix-resident disc file (in FITS format). SIMPLE, NAXIS, BITPIX, NAXIS1, NAXIS2, BZERO, BSCALE and END are automatically generated. It is an error for these keywords to be present in the present in the header associated with the region structure. Masks are not written.

    TCL: regWriteAsFits <region> <file> [-dirset defaultType] [-standard [d:T|F]] [-naxis 2] [-pipe] [-tape] <region> Name of source region. <file> FITS file to write. [-dirset] Optional Switch. The type of default file specifi- cation to be applied to <file>. The default is as if -dirset REGION_FILE were present. [-standard] Optional switch. If set to T, a standard FITS file is written. If set to F, a non-standard (SIMPLE=F) file is written. The default is T. [-naxis] Optional switch. The explicit value for the NAXIS keyword in the FITS header. It may be 1 if the number of rows in the region is 1. It may always be set to 2. The default is 2 for regions with data. For regions without data (nrow = ncol = 0), the default is 0.. [-pipe] Optional Switch. If present then the value of <file> is taken to be the read end of an open pipe descriptor. [-tape] Optional Switch. If present then the value of <file> is the name of the tape device to which to write. RETURNS: TCL_OK Successful completion, a null string is returned. TCL_ERROR Error occurred. The Interp result explains the error.
    
    
    

    hdrReadAsFits

    Read a Unix-resident disc file (in FITS format) into a header. The header is not edited in any way.

    TCL: hdrReadAsFits <header> <file> [-dirset defaultType] [-pipe] <header> Name of destination header. <file> FITS file to read. [-dirset] Optional Switch. The type of default file specifi- cation to be applied to <file>. The default is as if -dirset REGION_FILE were present. [-pipe] Optional Switch. If present then the value of <file> is taken to be the read end of an open pipe descriptor. [-tape] Optional Switch. If present then the value of <file> is the name of the tape device from which to read. Returns: TCL_OK Successful completion. The Interp result string will contain <region>. TCL_ERROR Error occurred. The Interp result string will contain the error string.
    
    
    
    

    hdrWriteAsFits

    Writes a header into a Unix-resident disc file (in FITS format). If the -reg option is not used, then the following keywords must exist in the header in order to make it a FITS standard header -

  • SIMPLE
  • BITPIX
  • NAXIS and appropriate NAXISnn
  • END
  • If the -reg option is specified, the values for these keywords and others (as documented for region reading) will be inserted automatically into the header. The values for SIMPLE and NAXIS can be entered manually by the user through command line options.

    TCL: hdrWriteAsFits <header> <file> [-dirset defaultType] [-reg region] [-standard [d:T|F]] [-naxis 2] [-pipe] <header> Name of source header. <file> FITS file to write. [-dirset] Optional Switch. The type of default file specifi- cation to be applied to <file>. The default is as if -dirset REGION_FILE were present. [-reg] Name of source region. [-standard] Optional switch. If set to T, a standard FITS file is written. If set to F, a non-standard (SIMPLE=F) file is written. The default is T. [-naxis] Optional switch. The explicit value for the NAXIS keyword in the FITS header. It may be 1 if the number of rows in the region is 1. It may always be set to 2. The default is 2 for regions with data. For regions without data (nrow = ncol = 0), the default is 0.. [-pipe] Optional Switch. If present then the value of <file> is taken to be the read end of an open pipe descriptor. [-tape] Optional Switch. If present then the value of <file> is the name of the tape device to which to write. RETURNS: TCL_OK Successful completion, a null string is returned. TCL_ERROR Error occurred. The Interp result explains the error.