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


  >  Docs Center  >  Libraries  >  ASTROLIB  >  FITS_READ

FITS_READ

FITS_READ

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:
                      <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.
      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.

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)
      FPACK compressed files are always closed and reopened when exiting
      FITS_READ so that the pointer is set to the beginning of the file. (Since
      FPACK files are opened with a bidirectional pipe rather than OPEN, one
      cannot 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



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