Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Libraries  >  ASTROLIB  >  FXREAD

FXREAD

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, 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.
      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. Landsman September 2006
              Assume since V5.5, remove VMS support
      Version 11.1, W. Landsman November 2007
              Allow for possibility number of bytes requires 64 bit integer
      Version 12, William Thompson, 18-Jun-2010, update BLANK value.
      Version 13, W. Landsman Remove IEEE_TO_HOST, V6.0 notation
      Version 14, William Thompson, 25-Sep-2014, fix BSCALE bug in version 13



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us