Institut für Astronomie und Astrophysik
Abteilung AstronomieSand 1, D-72076 Tübingen, Germany
To read a FITS file.
FITS_READ, filename_or_fcb, data [,header, group_par]
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.
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. If an extension is read, and the /NO_PDU keyword parameter is not supplied, 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. SXADDPAR and SXADDHIST will add new keywords and history to the extension portion of the header unless the parameter /PDU is supplied in the calling sequence. 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.
/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: Set to not add the primary data unit header keywords to the output 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, or the IDL, then the data is converted to type LONG. 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)
ENUM - Output extension number that was read. MESSAGE = value: Output error message
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)
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
FITS_CLOSE, FITS_OPEN, IEEE_TO_HOST, IS_IEEE_BIG() SXADDPAR, SXDELPAR, SXPAR()
Written by: D. Lindler, August 1995 Converted to IDL V5.0 W. Landsman September 1997 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
[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]