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