idlastro / FITS I/O: FITS_READ

[Source code]

NAME
FITS_READ
PURPOSE
To read a FITS file.
CALLING SEQUENCE
FITS_READ, filename_or_fcb, data [,header, group_par]
INPUTS
FILENAME_OR_FCB - this parameter can be the FITS Control Block (FCB)
        returned by FITS_OPEN or the file name of the FITS file.  If
        a file name is supplied, FITS_READ will open the file with
        FITS_OPEN and close the file with FITS_CLOSE before exiting.
        When multiple extensions are to be read from the file, it is
        more efficient for the user to call FITS_OPEN and leave the
        file open until all extensions are read. FPACK 
        ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) compressed FITS 
        files can be read provided that the FPACK software is installed.
        Both Gzip compressed (.gz) and Unix compressed (*.Z) files can
        be read, although there is a performance penalty..
OUTPUTS
DATA - data array.  If /NOSCALE is specified, BSCALE and BZERO
        (if present in the header) will not be used to scale the data.
        If Keywords FIRST and LAST are used to read a portion of the
        data or the heap portion of an extension, no scaling is done
        and data is returned as a 1-D vector. The user can use the IDL
        function REFORM to convert the data to the correct dimensions
        if desired.  If /DATA_ONLY is specified, no scaling is done.
HEADER - FITS Header.  The STScI inheritance convention is recognized
        http://fits.gsfc.nasa.gov/registry/inherit/fits_inheritance.txt
        If an extension is read, and the INHERIT keyword exists with a 
        value of T, and the /NO_PDU keyword keyword is not supplied, 
        then the primary data unit header and the extension header will
         be combined.  The header will have the form:
                
                BEGIN MAIN HEADER --------------------------------
                
                BEGIN EXTENSION HEADER ---------------------------
                
INPUT KEYWORD PARAMETERS
/NOSCALE: Set to return the FITS data without applying the scale
        factors BZERO and BSCALE.
/HEADER_ONLY: set to read the header only.
/DATA_ONLY: set to read the data only.  If set, if any scale factors
        are present (BSCALE or BZERO), they will not be applied.
/NO_PDU: By default, FITS_READ will add the primary data unit header 
        keywords to the output header, *if* the header includes 
        INHERIT = T.   Set /NO_PDU to never append the primary header.
/NO_ABORT: Set to return to calling program instead of a RETALL
        when an I/O error is encountered.  If set, the routine will
        return  a non-null string (containing the error message) in the
        keyword MESSAGE.    (For backward compatibility, the obsolete 
        system variable !ERR is also set to -1 in case of an error.)   
        If /NO_ABORT not set, then FITS_READ will print the message and
        issue a RETALL
/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.  
/PDU - If set, then always add the primary data unit header keywords
       to the output header, even if the INHERIT=T keyword is not found
       This was the default behavior of FITS_READ prior to April 2007
EXTEN_NO - extension number to read.  If not set, the next extension
        in the file is read.  Set to 0 to read the primary data unit.
XTENSION - string name of the xtension to read
EXTNAME - string name of the extname to read
EXTVER - integer version number to read
EXTLEVEL - integer extension level to read
FIRST - set this keyword to only read a portion of the data.  It gives
        the first word of the data to read
LAST - set this keyword to only read a portion of the data.  It gives
        the last word number of the data to read
GROUP - group number to read for GCOUNT>1.  (Default=0, the first group)
OUTPUT KEYWORD PARAMETERS
ENUM - Output extension number that was read.  
MESSAGE = value: Output error message
NOTES
Determination or which extension to read.
        case 1: EXTEN_NO specified. EXTEN_NO will give the number of the
                extension to read.  The primary data unit is refered
                to as extension 0. If EXTEN_NO is specified, XTENSION,
                EXTNAME, EXTVER, and EXTLEVEL parameters are ignored.
        case 2: if EXTEN_NO is not specified, the first extension
                with the specified XTENSION, EXTNAME, EXTVER, and
                EXTLEVEL will be read.  If any of the 4 parameters
                are not specified, they will not be used in the search.
                Setting EXTLEVEL=0, EXTVER=0, EXTNAME='', or
                XTENSION='' is the same as not supplying them.
        case 3: if none of the keyword parameters, EXTEN_NO, XTENSION,
                EXTNAME, EXTVER, or EXTLEVEL are supplied.  FITS_READ
                will read the next extension in the file.  If the
                primary data unit (PDU), extension 0, is null, the
                first call to FITS_READ will read the first extension
                of the file.
        The only way to read a null PDU is to use EXTEN_NO = 0.
If FIRST and LAST are specified, the data is returned without applying
any scale factors (BSCALE and BZERO) and the data is returned in a
1-D vector.  This will allow you to read any portion of a multiple
dimension data set.  Once returned, the IDL function REFORM can be
used to place the correct dimensions on the data.
IMPLICIT IMAGES: FITS_READ will construct an implicit image
        for cases where NAXIS=0 and the NPIX1, NPIX2, and PIXVALUE
        keywords are present.  The output image will be:
                image = replicate(PIXVALUE,NPIX1,NPIX2)
PACK compressed files are always closed and reopened when exiting 
ITS_READ so that the pointer is set to the beginning of the file. (Since 
PACK files are opened with a bidirectional pipe rather than OPEN, one 
annot use POINT_LUN to move to a specified position in the file.)
EXAMPLES
Read the primary data unit of a FITS file, if it is null read the
first extension:
        FITS_READ, 'myfile.fits', data, header
Read the first two extensions of a FITS file and the extension with
EXTNAME = 'FLUX' and EXTVER = 4
        FITS_OPEN, 'myfile.fits', fcb
        FITS_READ, fcb,data1, header2, exten_no = 1
        FITS_READ, fcb,data1, header2, exten_no = 2
        FITS_READ, fcb,data3, header3, extname='flux', extver=4
        FITS_CLOSE, fcb
Read the sixth image in a data cube for the fourth extension.
        FITS_OPEN, 'myfile.fits', fcb
        image_number = 6
        ns = fcb.axis[0,4]
        nl = fcb.axis[1,4]
        i1 = (ns*nl)*(image_number-1)
        i2 = i2 + ns*nl-1
        FITS_READ,fcb,image,header,first=i1,last=i2
        image = reform(image,ns,nl,/overwrite)
        FITS_CLOSE, fcb
PROCEDURES USED
FITS_CLOSE, FITS_OPEN
SXADDPAR, SXDELPAR, SXPAR()
WARNINGS
In Sep 2006, FITS_OPEN was modified to open FITS files using the
/SWAP_IF_LITTLE_ENDIAN keyword to OPEN, so that subsequent routines 
(FITS_READ, FITS_WRITE) did not require any byte swapping.    An error
may result if an pre-Sep 2006 version of FITS_OPEN is used with a 
post Sep 2006 version of FITS_READ, FITS_WRITE or MODFITS.
HISTORY
Written by:     D. Lindler, August 1995
Avoid use of !ERR       W. Landsman   August 1999
Read unsigned datatypes, added /no_unsigned   W. Landsman December 1999
Don't call FITS_CLOSE unless fcb is defined   W. Landsman January 2000
Set BZERO = 0 for unsigned integer data   W. Landsman  January 2000
Only call IEEE_TO_HOST if needed          W. Landsman February 2000
Ensure EXTEND keyword in primary header   W. Landsman April 2001
Don't erase ERROR message when closing file  W. Landsman April 2002
Assume at least V5.1 remove NANValue keyword  W. Landsman November 2002
Work with compress files (read file size from fcb),
requires updated (Jan 2003) version of FITS_OPEN W. Landsman Jan 2003
Do not modify BSCALE/BZERO for  unsigned integers W. Landsman April 2006
Assume FITS_OPEN has opened the file with /SWAP_IF_LITTLE_ENDIAN
                  W. Landsman   September 2006
Fix problem with /DATA_ONLY keyword  M.Buie/W.Landsman  October 2006
Only append primary header if INHERIT=T  W. Landsman  April 2007
Make ndata 64bit for very large files E. Hivon/W. Landsman May 2007
Added /PDU keyword to always append primary header W. Landsman June 2007
Use PRODUCT to compute # of data points   W. Landsman  May 2009
Make sure FIRST is long64 when computing position W.L. October 2009
Read FPACK compressed files, W.L.  December 2010
Don't assume FCB has a FCOMPRESS tag  W.L./Satori UeNO   September 2012
Make sure opened pipes are closed if fcb not left open W.L. April 2012
Fix bug with /data_only introduced Dec 2010      W. L. April 2014