FITS_READ

       To read a FITS file.

       FITS_READ, filename_or_fcb, data [,header, group_par]

       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.

       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.  If an extension is read, and the /NO_PDU keyword
               parameter is not supplied, the primary data unit header
               and the extension header will be combined.  The header will have
               the form:
                       <required keywords for the extension: XTENSION, BITPIX,
                               NAXIS, ...>
                       BEGIN MAIN HEADER --------------------------------
                       <PDU header keyword and history less required keywords:
                               SIMPLE, BITPIX, NAXIS, ...>
                       BEGIN EXTENSION HEADER ---------------------------
                       <extension header less required keywords that were
                               placed at the beginning of the header.
                       END
               The structure of the header is such that if a keyword is
               duplicated in both the PDU and extension headers, routine
               SXPAR will print a warning and return the extension value of
               the keyword. SXADDPAR and SXADDHIST will add new keywords and
               history to the extension portion of the header unless the
               parameter /PDU is supplied in the calling sequence.
       GROUP_PAR - Group parameter block for FITS random groups format files
               or the heap area for variable length binary tables.
               Any scale factors in the header (PSCALn and PZEROn) are not
               applied to the group 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: Set to not add the primary data unit header keywords to the
               output 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, or the IDL, then the data is converted to type LONG.
       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)

       ENUM - Output extension number that was read.
       MESSAGE = value: Output error message

       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)

       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

       FITS_CLOSE, FITS_OPEN, IEEE_TO_HOST, IS_IEEE_BIG()
       SXADDPAR, SXDELPAR, SXPAR()

       Written by:     D. Lindler, August 1995
       Converted to IDL V5.0   W. Landsman   September 1997
       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

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