FXREAD

       Read basic FITS files.

       Read an image array from a disk FITS file.  Optionally allows the
       user to read in only a subarray and/or every Nth pixel.

       FXREAD, FILENAME, DATA  [, HEADER  [, I1, I2  [, J1, J2 ]]  [, STEP]]

       FILENAME = String containing the name of the file to be read.

       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.

       DATA     = Data array to be read from the file.

       HEADER   = String array containing the header for the FITS file.

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

       GET_DATE, IEEE_TO_HOST, FXADDPAR, FXHREAD, FXPAR, WHERENAN

       None.

       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.

       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.

       Data Handling, I/O, FITS, Generic.

       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)

       William Thompson, GSFC, May 1992.

       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.

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]