FITS_READ
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:
<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.
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.
Input Keyword 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: By default, FITS_READ will add the primary data unit header
keywords to the output header, *if* the header includes
INHERIT = T. Set /NO_PDU to never append the primary 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, then the data is converted to type LONG.
/PDU - If set, then always add the primary data unit header keywords
to the output header, even if the INHERIT=T keyword is not found
This was the default behavior of FITS_READ prior to April 2007
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)
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