READFITS

       Read a FITS file into IDL data and header variables.

       READFITS() can also read gzip or Unix compressed FITS files.
       See http://idlastro.gsfc.nasa.gov/fitsio.html for other ways of
       reading FITS files with IDL.

       Result = READFITS( Filename/Fileunit,[ Header, heap, /NOSCALE, EXTEN_NO=,
                     NSLICE=, /SILENT , STARTROW =, NUMROW = , HBUFFER=,
                     /CHECKSUM, /COMPRESS, /No_Unsigned, NaNVALUE = ]

       Filename = Scalar string containing the name of the FITS file
                 (including extension) to be read.   If the filename has
                  a *.gz extension, it will be treated as a gzip compressed
                  file.   If it has a .Z extension, it will be treated as a
                  Unix compressed file.
                                   OR
       Fileunit - A scalar integer specifying the unit of an already opened
                  FITS file.  The unit will remain open after exiting
                  READFITS().  There are two possible reasons for choosing
                  to specify a unit number rather than a file name:
          (1) For a FITS file with many extensions, one can move to the
              desired extensions with FXPOSIT() and then use READFITS().  This
              is more efficient than repeatedly starting at the beginning of
              the file.
          (2) For reading a FITS file across a Web http: address after opening
              the unit with the SOCKET procedure (IDL V5.4 or later,
              Unix and Windows only)

       Result = FITS data array constructed from designated record.
                If the specified file was not found, then Result = -1

       Header = String array containing the header from the FITS file.
              If you don't need the header, then the speed may be improved by
              not supplying this parameter.    Note however, that omitting
              the header can imply /NOSCALE, i.e. BSCALE and BZERO values
              may not be applied.
       heap = For extensions, the optional heap area following the main
              data array (e.g. for variable length binary extensions).

       /CHECKSUM - If set, then READFITS() will call FITS_TEST_CHECKSUM to
                verify the data integrity if CHECKSUM keywords are present
                in the FITS header.   Cannot be used with the NSLICE, NUMROW
                or STARTROW keywords, since verifying the checksum requires
               that all the data be read.  See FITS_TEST_CHECKSUM() for more
               information.
       /COMPRESS - Signal that the file is gzip compressed.  By default,
               READFITS will assume that if the file name extension ends in
               '.gz' then the file is gzip compressed.   The /COMPRESS keyword
               is required only if the the gzip compressed file name does not
               end in '.gz' or .ftz
       EXTEN_NO - non-negative scalar integer specifying the FITS extension to
               read.  For example, specify EXTEN = 1 or /EXTEN to read the
               first FITS extension.
        HBUFFER - Number of lines in the header, set this to slightly larger
                than the expected number of lines in the FITS header, to
               improve performance when reading very large FITS headers.
               Should be a multiple of 36 -- otherwise it will be modified
               to the next higher multiple of 36.   Default is 180
       /NOSCALE - If present and non-zero, then the ouput data will not be
                scaled using the optional BSCALE and BZERO keywords in the
                FITS header.   Default is to scale.
       /NO_UNSIGNED - By default, if the header indicates an unsigned integer
               (BITPIX = 16, BZERO=2^15, BSCALE=1) then FITS_READ will output
               an IDL unsigned integer data type (UINT).   But if /NO_UNSIGNED
               is set, then the data is converted to type LONG.
       NSLICE - An integer scalar specifying which N-1 dimensional slice of a
                N-dimensional array to read.   For example, if the primary
                image of a file 'wfpc.fits' contains a 800 x 800 x 4 array,
                then
                 IDL> im = readfits('wfpc.fits',h, nslice=2)
                           is equivalent to
                 IDL> im = readfits('wfpc.fits',h)
                 IDL> im = im[*,*,2]
                 but the use of the NSLICE keyword is much more efficient.
       NUMROW -  Scalar non-negative integer specifying the number of rows
                 of the image or table extension to read.   Useful when one
                 does not want to read the entire image or table.   This
                 keyword is only for extensions and is ignored for primary
                 arrays.
       POINT_LUN  -  Position (in bytes) in the FITS file at which to start
                 reading.   Useful if READFITS is called by another procedure
                 which needs to directly read a FITS extension.    Should
                 always be a multiple of 2880, and not be used with EXTEN_NO
                 keyword.
       /SILENT - Normally, READFITS will display the size the array at the
                 terminal.  The SILENT keyword will suppress this
        STARTROW - Non-negative integer scalar specifying the row
               of the image or extension table at which to begin reading.
               Useful when one does not want to read the entire table.  This
               keyword is ignored when reading a primary data array.
       NaNVALUE - This keyword is included only for backwards compatibility
                  with routines that require IEEE "not a number" values to be
                  converted to a regular value.

       Read a FITS file test.fits into an IDL image array, IM and FITS
       header array, H.   Do not scale the data with BSCALE and BZERO.
              IDL> im = READFITS( 'test.fits', h, /NOSCALE)
       If the file contains a FITS extension, it could be read with
              IDL> tab = READFITS( 'test.fits', htab, /EXTEN )
       The function TBGET() can be used for further processing of a binary
       table, and FTGET() for an ASCII table.
       To read only rows 100-149 of the FITS extension,
              IDL> tab = READFITS( 'test.fits', htab, /EXTEN,
                                   STARTR=100, NUMR = 50 )
       To read in a file that has been compressed:
              IDL> tab = READFITS('test.fits.gz',h)

       If an error is encountered reading the FITS file, then
               (1) the system variable !ERROR_STATE.CODE is set negative
                   (via the MESSAGE facility)
               (2) the error message is displayed (unless /SILENT is set),
                   and the message is also stored in !!ERROR_STATE.MSG
               (3) READFITS returns with a value of -1

       (1) Cannot handle random group FITS

       (1) If data is stored as integer (BITPIX = 16 or 32), and BSCALE
       and/or BZERO keywords are present, then the output array is scaled to
       floating point (unless /NOSCALE is present) using the values of BSCALE
       and BZERO.   In the header, the values of BSCALE and BZERO are then
       reset to 1. and 0., while the original values are written into the
       new keywords O_BSCALE and O_BZERO.     If the BLANK keyword was
       present, then any input integer values equal to BLANK in the input
       integer image are unchanged by BSCALE or BZERO
       (2) The use of the NSLICE keyword is incompatible with the NUMROW
       or STARTROW keywords.
       (3) READFITS() underwent a substantial rewrite in February 2000 to
       take advantage of new features in IDL V5.3
            1. The /swap_if_little_endian keyword is now used to OPENR rather
                than calling IEEE_TO_HOST for improved performance
            2. The /compress keyword is now used with OPENR to allow gzip files
                to be read on any machine architecture.
            3. Removed NANvalue keyword, since in V5.3, NaN is recognized on
                all machine architectures
            4. Assume unsigned integers are always allowed
            5. Use STRJOIN to display image size
            6. Use !ERROR_STATE.MSG rather than !ERR_STRING
       (4) On some Unix shells, one may get a "Broken pipe" message if reading
        a Unix compressed (.Z) file, and not reading to the end of the file
       (i.e. the decompression has not gone to completion).     This is an
        informative message only, and should not affect the output of READFITS.

       Functions:   SXPAR()
       Procedures:  SXADDPAR, SXDELPAR

       V5.3 (Uses STRJOIN, /COMPRESS keyword to OPENR)

       Original Version written in 1988, W.B. Landsman   Raytheon STX
       Revision History prior to October 1998 removed
       Major rewrite to eliminate recursive calls when reading extensions
                  W.B. Landsman  Raytheon STX                    October 1998
       Add /binary modifier needed for Windows  W. Landsman    April 1999
       Read unsigned datatypes, added /no_unsigned   W. Landsman December 1999
       Output BZERO = 0 for unsigned data types   W. Landsman   January 2000
       Update to V5.3 (see notes)  W. Landsman                  February 2000
       Fixed logic error in use of NSLICE keyword  W. Landsman  March 2000
       Fixed byte swapping for Unix compress files on little endian machines
                                    W. Landsman    April 2000
       Added COMPRESS keyword, catch IO errors W. Landsman September 2000
       Option to read a unit number rather than file name W.L    October 2001
       Fix undefined variable problem if unit number supplied W.L. August 2002
       Don't read entire header unless needed   W. Landsman  Jan. 2003
       Added HBUFFER keyword    W. Landsman   Feb. 2003
       Added CHECKSUM keyword   W. Landsman   May 2003
       Restored NaNVALUE keyword for backwards compatibility,
               William Thompson, 16-Aug-2004, GSFC
       Recognize .ftz extension as compressed  W. Landsman   September 2004
       Fix unsigned integer problem introduced Sep 2004 W. Landsman Feb 2005

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