idlastro / FITS Binary Table Extensions I/O: FXREAD

[Source code]

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, 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
V6.0 (uses V6.0 notation) 
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.
ersion 4, William Thompson, GSFC, 23 June 1994
       Modified so that ERRMSG is not touched if not defined.
ersion 5, Zarro (SAC/GSFC), 14 Feb 1997 
       Added I/O error checking
ersion 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
ersion 7 C. Markwardt 22 Sep 2003
       If the image is empty (NAXIS EQ 0), or NODATA is set, then
       return only the header.  
ersion 8 W. Landsman  29 June 2004
       Added COMPRESS keyword, check for .gz extension  
ersion 9, William Thompson, 19-Aug-2004
       Make sure COMPRESS is treated as a scalar
ersion 10, Craig Markwardt, 01 Mar 2004
       Add EXTENSION keyword and ability to read different
       extensions than the primary one.
ersion 11,  W. Landsman   September 2006 
       Assume since V5.5, remove VMS support
ersion 11.1,  W. Landsman   November 2007
       Allow for possibility number of bytes requires 64 bit integer
ersion 12, William Thompson, 18-Jun-2010, update BLANK value.
ersion 13, W. Landsman  Remove IEEE_TO_HOST, V6.0 notation
ersion 14, William Thompson, 25-Sep-2014, fix BSCALE bug in version 13
ersion 15, William Thompson, 24-Jul-2017, allow NAXISn=0 if n>NAXIS