FXREAD
Name
FXREAD
Purpose
Read basic FITS files.
Explanation
Read an image array from a disk FITS file. Optionally allows the
user to read in only a subarray and/or every Nth pixel.
Use
FXREAD, FILENAME, DATA [, HEADER [, I1, I2 [, J1, J2 ]] [, STEP]]
Inputs
FILENAME = String containing the name of the file to be read.
Opt. Inputs :
I1,I2 = Data range to read in the first dimension. If passed, then
HEADER must also be passed. If not passed, or set to -1,-1,
then the entire range is read.
J1,J2 = Data range to read in the second dimension. If passed, then
HEADER and I1,J2 must also be passed. If not passed, or set
to -1,-1, then the entire range is read.
STEP = Step size to use in reading the data. If passed, then
HEADER must also be passed. Default value is 1. Ignored if
less than 1.
Outputs
DATA = Data array to be read from the file.
Opt. Outputs:
HEADER = String array containing the header for the FITS file.
Keywords
/COMPRESS - If this keyword is set and non-zero, then then treat
the file as gzip compressed. By default FXREAD assumes
the file is gzip compressed if it ends in ".gz"
NANVALUE = Value signalling data dropout. All points corresponding to
IEEE NaN (not-a-number) are set to this value. Ignored
unless DATA is of type float or double-precision.
EXTENSION = FITS extension. It can be a scalar integer,
indicating the extension number (extension number 0
is the primary HDU). It can also be a scalar string,
indicating the extension name (EXTNAME keyword).
Default: 0 (primary HDU)
PROMPT = If set, then the optional parameters are prompted for at the
keyboard.
AVERAGE = If set, then the array size is reduced by averaging pixels
together rather than by subselecting pixels. Ignored unless
STEP is nontrivial. Note: this is much slower.
YSTEP = If passed, then STEP is the step size in the 1st dimension,
and YSTEP is the step size in the 2nd dimension. Otherwise,
STEP applies to both directions.
NOSCALE = If set, then the output data will not be scaled using the
optional BSCALE and BZERO keywords in the FITS header.
Default is to scale, if and only if BSCALE and BZERO are
present and nontrivial.
NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the
optional HEADER array will not be changed. The default is
to reset these keywords to BSCALE=1, BZERO=0. Ignored if
NOSCALE is set.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXREAD, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
NODATA = If set, then the array is not read in, but the
primary header is read.
Calls
GET_DATE, IEEE_TO_HOST, FXADDPAR, FXHREAD, FXPAR, WHERENAN
Common :
None.
Restrictions
Groups are not supported.
The optional parameters I1, I2, and STEP only work with one or
two-dimensional arrays. J1 and J2 only work with two-dimensional
arrays.
Use of the AVERAGE keyword is not compatible with arrays with missing
pixels.
Side Effects
If the keywords BSCALE and BZERO are present in the FITS header, and
have non-trivial values, then the returned array DATA is formed by the
equation
DATA = BSCALE*original + BZERO
However, this behavior can overridden by using the /NOSCALE keyword.
If the data is scaled, then the optional HEADER array is changed so
that BSCALE=1 and BZERO=0. This is so that these scaling parameters
are not applied to the data a second time by another routine. Also,
history records are added storing the original values of these
constants. Note that only the returned array is modified--the header
in the FITS file itself is untouched.
If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO
keywords are not changed. It is then the user's responsibility to
ensure that these parameters are not reapplied to the data. In
particular, these keywords should not be present in any header when
writing another FITS file, unless the user wants their values to be
applied when the file is read back in. Otherwise, FITS readers will
read in the wrong values for the data array.
Category
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
W. Thompson, May 1992, based in part on READFITS by W. Landsman, and
STSUB by M. Greason and K. Venkatakrishna.
W. Thompson, Jun 1992, added code to interpret BSCALE and BZERO
records, and added NOSCALE and NOUPDATE
keywords.
W. Thompson, Aug 1992, changed to call FXHREAD, and to add history
records for BZERO, BSCALE.
Minimium IDL Version:
V5.3 (uses COMPRESS keyword to OPEN)
Written :
William Thompson, GSFC, May 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 17 November 1993.
Corrected bug with AVERAGE keyword on non-IEEE compatible
machines.
Corrected bug with subsampling on VAX machines.
Version 3, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 4, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 5, Zarro (SAC/GSFC), 14 Feb 1997
Added I/O error checking
Version 6, 20-May-1998, David Schlegel/W. Thompson
Allow a single pixel to be read in.
Change the signal to read in the entire array to be -1
Version 7 C. Markwardt 22 Sep 2003
If the image is empty (NAXIS EQ 0), or NODATA is set, then
return only the header.
Version 8 W. Landsman 29 June 2004
Added COMPRESS keyword, check for .gz extension
Version 9, William Thompson, 19-Aug-2004
Make sure COMPRESS is treated as a scalar
Version 10, Craig Markwardt, 01 Mar 2004
Add EXTENSION keyword and ability to read different
extensions than the primary one.
Version 11, W. Landsamn September 2006
Assume since V5.5, remove VMS support
Version 11.1, W. Landsamn November 2007
Allow for possibility number of bytes requires 64 bit integer
Version 12, William Thompson, 18-Jun-2010, update BLANK value.