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