This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
NAME:
FITS_CLOSE
*PURPOSE:
Close a FITS data file
*CATEGORY:
INPUT/OUTPUT
*CALLING SEQUENCE:
FITS_CLOSE,fcb
*INPUTS:
FCB: FITS control block returned by FITS_OPEN.
*KEYWORD PARAMETERS:
/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. If /NO_ABORT not set, then FITS_CLOSE will
print the message and issue a RETALL
MESSAGE = value: Output error message
*EXAMPLES:
Open a FITS file, read some data, and close it with FITS_CLOSE
FITS_OPEN,'infile',fcb
FITS_READ,fcb,data
FITS_READ,fcb,moredata
FITS_CLOSE,fcb
*HISTORY:
Written by: D. Lindler August, 1995
Converted to IDL V5.0 W. Landsman September 1997
Do nothing if fcb an invalid structure D. Schlegel/W. Landsman Oct. 2000
Return Message='' for to signal normal operation W. Landsman Nov. 2000
(See general/misc/SSW/fits/fits_close.pro)
NAME:
FITS_OPEN
PURPOSE:
Opens a FITS (Flexible Image Transport System) data file.
EXPLANATION:
Used by FITS_READ and FITS_WRITE
CALLING SEQUENCE:
FITS_OPEN, filename, fcb
INPUTS:
filename : name of the FITS file to open, scalar string
FITS_OPEN can also open gzip compressed (.gz) file *for
reading only*, although there is a performance penalty
FPACK ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ )
compressed FITS files can be read provided that the FPACK
software is installed.
*OUTPUTS:
fcb : (FITS Control Block) a IDL structure containing information
concerning the file. It is an input to FITS_READ, FITS_WRITE
FITS_CLOSE and MODFITS.
INPUT KEYWORD PARAMETERS:
/APPEND: Set to append to an existing file.
/FPACK - Signal that the file is compressed with the FPACK software.
http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default,
FITS_OPEN assumes that if the file name extension ends in
.fz that it is fpack compressed. The FPACK software must
be installed on the system
/HPRINT - print headers with routine HPRINT as they are read.
(useful for debugging a strange file)
/NO_ABORT: Set to quietly return to calling program when an I/O error
is encountered, and return a non-null string
(containing the error message) in the keyword MESSAGE.
If /NO_ABORT not set, then FITS_OPEN will display the error
message and return to the calling program.
/UPDATE Set this keyword to open an existing file for update
/WRITE: Set this keyword to open a new file for writing.
OUTPUT KEYWORD PARAMETERS:
MESSAGE = value: Output error message. If the FITS file was opened
successfully, then message = ''.
NOTES:
The output FCB should be passed to the other FITS routines (FITS_OPEN,
FITS_READ, FITS_HELP, and FITS_WRITE). It has the following structure
when FITS_OPEN is called without /WRITE or /APPEND keywords set.
FCB.FILENAME - name of the input file
.UNIT - unit number the file is opened to
.FCOMPRESS - 1 if unit is a FPACK compressed file opened with
a pipe to SPAWN
.NEXTEND - number of extensions in the file.
.XTENSION - string array giving the extension type for each
extension.
.EXTNAME - string array giving the extension name for each
extension. (null string if not defined the extension)
.EXTVER - vector of extension version numbers (0 if not
defined)
.EXTLEVEL - vector of extension levels (0 if not defined)
.GCOUNT - vector with the number of groups in each extension.
.PCOUNT - vector with parameter count for each group
.BITPIX - BITPIX for each extension with values
8 byte data
16 short word integers
32 long word integers
-32 IEEE floating point
-64 IEEE double precision floating point
.NAXIS - number of axes for each extension. (0 for null data
units)
.AXIS - 2-D array where axis(*,N) gives the size of each axes
for extension N
.START_HEADER - vector giving the starting byte in the file
where each extension header begins
.START_DATA - vector giving the starting byte in the file
where the data for each extension begins
.HMAIN - keyword parameters (less standard required FITS
keywords) for the primary data unit.
.OPEN_FOR_WRITE - flag (0= open for read, 1=open for write,
2=open for update)
.LAST_EXTENSION - last extension number read.
.RANDOM_GROUPS - 1 if the PDU is random groups format,
0 otherwise
.NBYTES - total number of (uncompressed) bytes in the FITS file
When FITS open is called with the /WRITE or /APPEND option, FCB
contains:
FCB.FILENAME - name of the input file
.UNIT - unit number the file is opened to
.NEXTEND - number of extensions in the file.
.OPEN_FOR_WRITE - flag (1=open for write, 2=open for append
3=open for update)
EXAMPLES:
Open a FITS file for reading:
FITS_OPEN,'myfile.fits',fcb
Open a new FITS file for output:
FITS_OPEN,'newfile.fits',fcb,/write
PROCEDURES USED:
GET_PIPE_FILESIZE (for Fcompress'ed files) HPRINT, SXDELPAR, SXPAR()
HISTORY:
Written by: D. Lindler August, 1995
July, 1996 NICMOS Modified to allow open for overwrite
to allow primary header to be modified
DJL Oct. 15, 1996 corrected to properly extend AXIS when more
than 100 extensions present
Converted to IDL V5.0 W. Landsman September 1997
Use Message = '' rather than !ERR =1 as preferred signal of normal
operation W. Landsman November 2000
Lindler, Dec, 2001, Modified to use 64 bit words for storing byte
positions within the file to allow support for very large
files
Work with gzip compressed files W. Landsman January 2003
Fix gzip compress for V5.4 and earlier W.Landsman/M.Fitzgerald Dec 2003
Assume since V5.3 (STRSPLIT, OPENR,/COMPRESS) W. Landsman Feb 2004
Treat FTZ extension as gzip compressed W. Landsman Sep 2004
Assume since V5.4 fstat.compress available W. Landsman Apr 2006
FCB.Filename now expands any wildcards W. Landsman July 2006
Make ndata 64bit for very large files B. Garwood/W. Landsman Sep 2006
Open with /SWAP_IF_LITTLE_ENDIAN, remove obsolete keywords to OPEN
W. Landsman Sep 2006
Warn that one cannot open a compressed file for update W.L. April 2007
Use post-V6.0 notation W.L. October 2010
Support FPACK compressed files, new .FCOMPRESS tag to FCB structure
W.L. December 2010
Read gzip'ed files even if gzip is not installed W.L. October 2012
(See general/misc/SSW/fits/fits_open.pro)
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
Don't assume FCB has a FCOMPRESS tag W.L./Satori UeNO September 2012
(See general/misc/SSW/fits/fits_read.pro)
NAME:
GETTOK
PURPOSE:
Retrieve the first part of a (vector) string up to a specified character
EXPLANATION:
GET TOKen - Retrieve first part of string until the character char
is encountered.
CALLING SEQUENCE:
token = gettok( st, char, [ /EXACT, /NOTRIM ] )
INPUT:
char - character separating tokens, scalar string
INPUT-OUTPUT:
st - string to get token from (on output token is removed unless
/NOTRIM is set), scalar or vector
OUTPUT:
token - extracted string value is returned, same dimensions as st
OPTIONAL INPUT KEYWORD:
/EXACT - The default behaviour of GETTOK is to remove any leading
blanks and (if the token is a blank) convert tabs to blanks.
Set the /EXACT keyword to skip these steps and leave the
input string unchanged before searching for the character
tokens.
/NOTRIM - if set, then the input string is left unaltered
EXAMPLE:
If ST is ['abc=999','x=3.4234'] then gettok(ST,'=') would return
['abc','x'] and ST would be left as ['999','3.4234']
PROCEDURE CALLS:
REPCHR()
HISTORY
version 1 by D. Lindler APR,86
Remove leading blanks W. Landsman (from JKF) Aug. 1991
V5.3 version, accept vector input W. Landsman February 2000
Slightly faster implementation W. Landsman February 2001
Added EXACT keyword W. Landsman March 2004
Assume since V5.4, Use COMPLEMENT keyword to WHERE W. Landsman Apr 2006
Added NOTRIM keyword W. L. March 2011
(See general/misc/SSW/fits/gettok.pro)
NAME:
HPRINT
PURPOSE:
Display a FITS header (or other string array)
EXPLANATION:
On a GUI terminal, the string array is displayed using XDISPSTR.
If printing at a non-GUI terminal, the string array is printed 1 line
at a time, to make sure that each element of the string array is
displayed on a separate line.
CALLING SEQUENCE:
HPRINT, h, [ firstline ]
INPUTS:
H - FITS header (or any other string array).
OPTIONAL INPUT:
FIRSTLINE - scalar integer specifying the first line to begin
displaying. The default is FIRSTLINE = 1, i.e. display
all the lines. If Firstline is negative, then the first
line to be printed is counted backward from the last line.
NOTES:
When displaying at the terminal, HPRINT has the following differences
from the intrinsic PRINT procedure
(1) Arrays are printed one line at a time to avoid a space between 80
character lines
(2) Lines are trimmed with STRTRIM before being printed to speed up
display
(3) The /more option is used for output.
EXAMPLE:
Read the header from a FITS file named 'test.fits' and display it at the
terminal beginning with line 50
IDL> h = headfits( 'test.fits') ;Read FITS header
IDL> hprint, h, 50 ;Display starting at line 50
To print the last 25 lines of the header
IDL> hprint, h, -25
REVISION HISTORY:
Written W. Landsman July, 1990
Added test for user quit July, 1991
Added optional FIRSTLINE parameter November, 1992
Modified for when STDOUT is not a TTY W. Landsman September 1995
Converted to IDL V5.0 W. Landsman September 1997
Fixed printing in IDLDE, C. Gehman August, 1998
Skip PRINTF if IDL in demo mode W. Landsman October 2004
Fixed bug on non-terminals, William Thompson, 18-Oct-2004
Assume since V5.4 Use BREAK instead of GOTO W. Landsman Apr 2006
Call XDISPSTR on a GUI terminal W. Landsman Jun 2006
(See general/misc/SSW/fits/hprint.pro)
NAME:
MRD_SKIP
PURPOSE:
Skip a number of bytes from the current location in a file or a pipe
EXPLANATION:
First tries using POINT_LUN and if this doesn't work, perhaps because
the unit is a pipe or a socket, MRD_SKIP will just read in the
requisite number of bytes.
CALLING SEQUENCE:
MRD_SKIP, Unit, Nskip
INPUTS:
Unit - File unit for the file or pipe in question, integer scalar
Nskip - Number of bytes to be skipped, positive integer
NOTES:
This routine should be used in place of POINT_LUN wherever a pipe
or socket may be the input unit (see the procedure FXPOSIT for an
example). Note that it assumes that it can only work with nskip >= 0
so it doesn't even try for negative values.
For reading a pipe, MRD_SKIP currently uses a maximum buffer size
of 8 MB. This chunk value can be increased for improved efficiency
(or decreased if you really have little memory.)
REVISION HISTORY:
Written, Thomas A. McGlynn July 1995
Don't even try to skip bytes on a pipe with POINT_LUN, since this
might reset the current pointer W. Landsman April 1996
Increase buffer size, check fstat.compress W. Landsman Jan 2001
Only a warning if trying read past EOF W. Landsman Sep 2001
Use 64bit longword for skipping in very large files W. Landsman Sep 2003
Assume since V5.4, fstat.compress available W. Landsman April 2006
POINT_LUN for compressed files is as fast as any W. Landsman Oct 2006
Don't try to use POINT_LUN on compressed files W. Landsman Dec. 2006
(See general/misc/SSW/fits/mrd_skip.pro)
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
(See general/misc/SSW/fits/readfits.pro)
NAME:
REPCHR
PURPOSE:
Replace all occurrences of one character with another in a text string.
CATEGORY:
CALLING SEQUENCE:
new = repchr(old, c1, [c2])
INPUTS:
old = original text string. in
c1 = character to replace. in
c2 = character to replace it with. in
default is space.
KEYWORD PARAMETERS:
OUTPUTS:
new = edited string. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 28 Oct, 1986.
Johns Hopkins Applied Physics Lab.
RES 1 Sep, 1989 --- converted to SUN.
R. Sterner, 27 Jan, 1993 --- dropped reference to array.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
Converted to IDL V5.0 W. Landsman September 1997
(See general/misc/SSW/fits/repchr.pro)
NAME:
SXADDPAR
PURPOSE:
Add or modify a parameter in a FITS header array.
CALLING SEQUENCE:
SXADDPAR, Header, Name, Value, [ Comment, Location, /SaveComment,
BEFORE =, AFTER = , FORMAT= , /PDU]
INPUTS:
Header = String array containing FITS or STSDAS header. The
length of each element must be 80 characters. If not
defined, then SXADDPAR will create an empty FITS header array.
Name = Name of parameter. If Name is already in the header the value
and possibly comment fields are modified. Otherwise a new
record is added to the header. If name is equal to 'COMMENT'
or 'HISTORY' or a blank string then the value will be added to
the record without replacement. For these cases, the comment
parameter is ignored.
Value = Value for parameter. The value expression must be of the
correct type, e.g. integer, floating or string. String values
of 'T' or 'F' are considered logical values.
OPTIONAL INPUT PARAMETERS:
Comment = String field. The '/' is added by this routine. Added
starting in position 31. If not supplied, or set equal to
'', or /SAVECOMMENT is set, then the previous comment field is
retained (when found)
Location = Keyword string name. The parameter will be placed before the
location of this keyword. This parameter is identical to
the BEFORE keyword and is kept only for consistency with
earlier versions of SXADDPAR.
OPTIONAL INPUT KEYWORD PARAMETERS:
BEFORE = Keyword string name. The parameter will be placed before the
location of this keyword. For example, if BEFORE='HISTORY'
then the parameter will be placed before the first history
location. This applies only when adding a new keyword;
keywords already in the header are kept in the same position.
AFTER = Same as BEFORE, but the parameter will be placed after the
location of this keyword. This keyword takes precedence over
BEFORE.
FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A
scalar string should be used. For complex numbers the format
should be defined so that it can be applied separately to the
real and imaginary parts. If not supplied then the default is
'G19.12' for double precision, and 'G14.7' for floating point.
/PDU = specifies keyword is to be added to the primary data unit
header. If it already exists, it's current value is updated in
the current position and it is not moved.
/SAVECOMMENT = if set, then any existing comment is retained, i.e. the
COMMENT parameter only has effect if the keyword did not
previously exist in the header.
OUTPUTS:
Header = updated FITS header array.
EXAMPLE:
Add a keyword 'TELESCOP' with the value 'KPNO-4m' and comment 'Name
of Telescope' to an existing FITS header h.
IDL> sxaddpar, h, 'TELESCOPE','KPNO-4m','Name of Telescope'
NOTES:
The functions SXADDPAR() and FXADDPAR() are nearly identical, with the
major difference being that FXADDPAR forces required FITS keywords
BITPIX, NAXISi, EXTEND, PCOUNT, GCOUNT to appear in the required order
in the header, and FXADDPAR supports the OGIP LongString convention.
There is no particular reason for having two nearly identical
procedures, but both are too widely used to drop either one.
All HISTORY records are inserted in order at the end of the header.
All COMMENT records are also inserted in order at the end of the header
header, but before the HISTORY records. The BEFORE and AFTER keywords
can override this.
All records with no keyword (blank) are inserted in order at the end of
the header, but before the COMMENT and HISTORY records. The BEFORE and
AFTER keywords can override this.
RESTRICTIONS:
Warning -- Parameters and names are not checked
against valid FITS parameter names, values and types.
MODIFICATION HISTORY:
DMS, RSI, July, 1983.
D. Lindler Oct. 86 Added longer string value capability
Converted to NEWIDL D. Lindler April 90
Added Format keyword, J. Isensee, July, 1990
Added keywords BEFORE and AFTER. K. Venkatakrishna, May '92
Pad string values to at least 8 characters W. Landsman April 94
Aug 95: added /PDU option and changed routine to update last occurence
of an existing keyword (the one SXPAR reads) instead of the
first occurence.
Comment for string data can start after column 32 W. Landsman June 97
Make sure closing quote supplied with string value W. Landsman June 98
Converted to IDL V5.0 W. Landsman June 98
Increase precision of default formatting of double precision floating
point values. C. Gehman, JPL September 1998
Mar 2000, D. Lindler, Modified to use capital E instead of lower case
e for exponential formats.
Apr 2000, Make user-supplied format upper-case W. Landsman
Oct 2001, Treat COMMENT or blank string like HISTORY keyword W. Landsman
Jan 2002, Allow BEFORE, AFTER to apply to COMMENT keywords W. Landsman
June 2003, Added SAVECOMMENT keyword W. Landsman
Jan 2004, If END is missing, then add it at the end W. Landsman
May 2005 Fix SAVECOMMENT error with non-string values W. Landsman
Oct 2005 Jan 2004 change made SXADDPAR fail for empty strings W.L.
May 2011 Fix problem with slashes in string values W.L.
(See general/misc/SSW/fits/sxaddpar.pro)
NAME:
SXDELPAR
PURPOSE:
Procedure to delete a keyword parameter(s) from a FITS header
CALLING SEQUENCE:
sxdelpar, h, parname
INPUTS:
h - FITS or STSDAS header, string array
parname - string or string array of keyword name(s) to delete
OUTPUTS:
h - updated FITS header, If all lines are deleted from
the header, then h is returned with a value of 0
EXAMPLE:
Delete the astrometry keywords CDn_n from a FITS header, h
IDL> sxdelpar, h, ['CD1_1','CD1_2','CD2_1','CD2_2']
NOTES:
(1) No message is returned if the keyword to be deleted is not found
(2) All appearances of a keyword in the header will be deleted
HISTORY:
version 1 D. Lindler Feb. 1987
Test for case where all keywords are deleted W. Landsman Aug 1995
Allow for headers with more than 32767 lines W. Landsman Jan. 2003
Use ARRAY_EQUAL, cleaner syntax W. L. July 2009
(See general/misc/SSW/fits/sxdelpar.pro)
NAME:
SXPAR
PURPOSE:
Obtain the value of a parameter in a FITS header
CALLING SEQUENCE:
result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT =, /NoCONTINUE,
/SILENT ])
INPUTS:
Hdr = FITS header array, (e.g. as returned by READFITS)
string array, each element should have a length of 80 characters
Name = String name of the parameter to return. If Name is of the
form 'keyword*' then an array is returned containing values of
keywordN where N is a positive (non-zero) integer. The value of
keywordN will be placed in RESULT[N-1]. The data type of RESULT
will be the type of the first valid match of keywordN found.
OPTIONAL INPUTS:
ABORT - string specifying that SXPAR should do a RETALL
if a parameter is not found. ABORT should contain
a string to be printed if the keyword parameter is not found.
If not supplied, SXPAR will return quietly with COUNT = 0
(and !ERR = -1) if a keyword is not found.
OPTIONAL INPUT KEYWORDS:
/NOCONTINUE = If set, then continuation lines will not be read, even
if present in the header
/SILENT - Set this keyword to suppress warning messages about duplicate
keywords in the FITS header.
OPTIONAL OUTPUT KEYWORDS:
COUNT - Optional keyword to return a value equal to the number of
parameters found by SXPAR, integer scalar
COMMENT - Array of comments associated with the returned values
OUTPUTS:
Function value = value of parameter in header.
If parameter is double precision, floating, long or string,
the result is of that type. Apostrophes are stripped
from strings. If the parameter is logical, 1b is
returned for T, and 0b is returned for F.
If Name was of form 'keyword*' then a vector of values
are returned.
SIDE EFFECTS:
!ERR is set to -1 if parameter not found, 0 for a scalar
value returned. If a vector is returned it is set to the
number of keyword matches found. The use of !ERR is deprecated, and
instead the COUNT keyword is preferred
If a keyword (except HISTORY or COMMENT) occurs more than once in a
header, a warning is given, and the *last* occurence is used.
EXAMPLES:
Given a FITS header, h, return the values of all the NAXISi values
into a vector. Then place the history records into a string vector.
IDL> naxisi = sxpar( h ,'NAXIS*') ; Extract NAXISi value
IDL> history = sxpar( h, 'HISTORY' ) ; Extract HISTORY records
PROCEDURE:
The first 8 chacters of each element of Hdr are searched for a
match to Name. The value from the last 20 characters is returned.
An error occurs if there is no parameter with the given name.
If a numeric value has no decimal point it is returned as type
LONG. If it contains more than 8 numerals, or contains the
characters 'D' or 'E', then it is returned as type DOUBLE. Otherwise
it is returned as type FLOAT. Very large integer values, outside
the range of valid LONG, are returned as DOUBLE.
If the value is too long for one line, it may be continued on to the
the next input card, using the OGIP CONTINUE convention. For more info,
see http://fits.gsfc.nasa.gov/registry/continue_keyword.html
Complex numbers are recognized as two numbers separated by one or more
space characters.
If a numeric value has no decimal point (or E or D) it is returned as
type LONG. If it contains more than 8 numerals, or contains the
character 'D', then it is returned as type DOUBLE. Otherwise it is
returned as type FLOAT. If an integer is too large to be stored as
type LONG, then it is returned as DOUBLE.
NOTES:
The functions SXPAR() and FXPAR() are nearly identical, although
FXPAR() has slightly more sophisticated parsing, and additional keywords
to specify positions in the header to search (for speed), and to force
the output to a specified data type.. There is no
particular reason for having two nearly identical procedures, but
both are too widely used to drop either one.
PROCEDURES CALLED:
GETTOK(), VALID_NUM()
MODIFICATION HISTORY:
DMS, May, 1983, STPAR Written.
D. Lindler Jan 90 added ABORT input parameter
J. Isensee Jul,90 added COUNT keyword
W. Thompson, Feb. 1992, added support for FITS complex values.
W. Thompson, May 1992, corrected problem with HISTORY/COMMENT/blank
keywords, and complex value error correction.
W. Landsman, November 1994, fix case where NAME is an empty string
W. Landsman, March 1995, Added COMMENT keyword, ability to read
values longer than 20 character
W. Landsman, July 1995, Removed /NOZERO from MAKE_ARRAY call
T. Beck May 1998, Return logical as type BYTE
W. Landsman May 1998, Make sure integer values are within range of LONG
W. Landsman Feb 1998, Recognize CONTINUE convention
W. Landsman Oct 1999, Recognize numbers such as 1E-10 as floating point
W. Landsman Jan 2000, Only accept integer N values when name = keywordN
W. Landsman Dec 2001, Optional /SILENT keyword to suppress warnings
W. Landsman/D. Finkbeiner Mar 2002 Make sure extracted vectors
of mixed data type are returned with the highest type.
W.Landsman Aug 2008 Use vector form of VALID_NUM()
W. Landsman Jul 2009 Eliminate internal recursive call
W. Landsman Apr 2012 Require vector numbers be greater than 0
(See general/misc/SSW/fits/sxpar.pro)
NAME:
VALID_NUM()
PURPOSE:
Check if a string is a valid number representation.
EXPLANATION:
The input string is parsed for characters that may possibly
form a valid number. It is more robust than simply checking
for an IDL conversion error because that allows strings such
as '22.3qwert' to be returned as the valid number 22.3
This function had a major rewrite in August 2008 to use STREGEX
and allow vector input. It should be backwards compatible.
CALLING SEQUENCE:
IDL> status = valid_num(string [,value] [,/integer])
INPUTS:
string - the string to be tested, scalar or array
RETURNS
status - byte scalar or array, same size as the input string
set to 1 where the string is a valid number, 0 for invalid
OPTIONAL OUTPUT:
value - The value the string decodes to, same size as input string.
This will be returned as a double precision number unless
/INTEGER is present, in which case a long integer is returned.
OPTIONAL INPUT KEYWORD:
/INTEGER - if present code checks specifically for an integer.
EXAMPLES:
(1) IDL> print,valid_num(3.2,/integer)
--> 0 ;Since 3.2 is not an integer
(2) IDL> str =['-0.03','2.3g', '3.2e12']
IDL> test = valid_num(str,val)
test = [1,0,1] & val = [-0.030000000 ,NaN ,3.2000000e+12]
REVISION HISTORY:
Version 1, C D Pike, RAL, 24-May-93
Version 2, William Thompson, GSFC, 14 October 1994
Added optional output parameter VALUE to allow
VALID_NUM to replace STRNUMBER in FITS routines.
Version 3 Wayne Landsman rewrite to use STREGEX, vectorize
Version 4 W.L. (fix from C. Markwardt) Better Stregex expression,
was missing numbers like '134.' before Jan 1 2010
(See general/misc/SSW/fits/valid_num.pro)