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. 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: BEGIN MAIN HEADER -------------------------------- BEGIN EXTENSION HEADER --------------------------- 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 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 Asuume 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