idlastro / FITS I/O: READFITS

[Source code]

NAME
READFITS
PURPOSE
Read a FITS file into IDL data and header variables. 
EXPLANATION
READFITS() can read FITS files compressed with gzip or Unix (.Z) 
compression.  FPACK ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ )
compressed FITS files can also be read provided that the FPACK software
is installed.
See http://idlastro.gsfc.nasa.gov/fitsio.html for other ways of
reading FITS files with IDL.   
CALLING SEQUENCE
Result = READFITS( Filename/Fileunit,[ Header, heap, /NOSCALE, EXTEN_NO=,
              NSLICE=, /SILENT , STARTROW =, NUMROW = , HBUFFER=,
              /CHECKSUM, /COMPRESS, /FPACK, /No_Unsigned, NaNVALUE = ]
INPUTS
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.     If Filename is an empty string then
           the user will be queried for the file name.
                            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 
OUTPUTS
Result = FITS data array constructed from designated record.
         If the specified file was not found, then Result = -1
OPTIONAL OUTPUT
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).
OPTIONAL INPUT KEYWORDS
/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.   
/FPACK - Signal that the file is compressed with the FPACK software. 
        http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default, 
        (READFITS will assume that if the file name extension ends in 
        .fz that it is fpack compressed.     The FPACK software must
        be installed on the system 
 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 READFITS() 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.
          Note that any degenerate dimensions are ignored, so that the
          above code would also work with a 800 x 800 x 4 x 1 array.
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.  
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.  
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.
/UNIXPIPE - When a FileUnit is supplied to READFITS(), then /UNIXPIPE
          indicates that the unit is to a Unix pipe, and that 
          no automatic byte swapping is performed.
EXAMPLE
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)
ERROR HANDLING
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
RESTRICTIONS
(1) Cannot handle random group FITS
NOTES
(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 (giving the value of undefined elements *prior* to the 
application of BZERO and BSCALE) then the *keyword* value will be
updated with the values of BZERO and BSCALE.
(2) The use of the NSLICE keyword is incompatible with the NUMROW
or STARTROW keywords.
(3) 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.   
PROCEDURES USED
Functions:   SXPAR()
Procedures:  MRD_SKIP, SXADDPAR, SXDELPAR
MODIFICATION HISTORY
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
Don't modify header for unsigned integers, preserve double precision
    BSCALE value  W. Landsman March 2006
Use gzip instead of compress for Unix compress files W.Landsman Sep 2006
Call MRD_SKIP to skip bytes on different file types W. Landsman Oct 2006
Make ndata 64bit for very large files E. Hivon/W. Landsman May 2007
Fixed bug introduced March 2006 in applying Bzero C. Magri/W.L. Aug 2007
Check possible 32bit overflow when using NSKIP W. Landsman Mar 2008
Always reset BSCALE, BZERO even for unsigned integers W. Landsman May 2008
Make ndata 64bit for very large extensions J. Schou/W. Landsman Jan 2009
Use PRODUCT() to compute # of data points  W. Landsman  May 2009
Read FPACK compressed file via UNIX pipe. W. Landsman May 2009
Fix error using NUMROW,STARTROW with non-byte data, allow these 
    keywords to be used with primary array  W. Landsman July 2009
Ignore degenerate trailing dimensions with NSLICE keyword W.L. Oct 2009
Add DIALOG_PICKFILE() if filename is an empty string  W.L. Apr 2010
Set BLANK values *before* applying BSCALE,BZERO, use short-circuit
    operators  W.L. May 2010
kip extra SPAWN with FPACK decompress J. Eastman, W.L. July 2010
ix possible problem when startrow=0 supplied J. Eastman/W.L. Aug 2010
irst header is not necessarily primary if unit supplied WL Jan 2011
ix test for 'SIMPLE' at beginning of header WL November 2012
ix problem passing extensions with > 2GB WL, M. Carlson August 2013