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


  >  Docs Center  >  Libraries  >  ASTROLIB  >  READFITS

READFITS

READFITS

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
      Skip extra SPAWN with FPACK decompress J. Eastman, W.L. July 2010
      Fix possible problem when startrow=0 supplied J. Eastman/W.L. Aug 2010
      First header is not necessarily primary if unit supplied WL Jan 2011
      Fix test for 'SIMPLE' at beginning of header WL November 2012
      Fix problem passing extensions with > 2GB WL, M. Carlson August 2013



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