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