This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Dec 20 10:37:44 2023.
NAME:
CHECK_FITS
PURPOSE:
Check that keywords in a FITS header array match the associated data
EXPLANATION:
Given a FITS array IM, and a associated FITS header HDR, this
procedure will check that
(1) HDR is a string array, and IM is defined and numeric
(2) The NAXISi values in HDR are appropriate to the dimensions
of IM
(3) The BITPIX value in HDR is appropriate to the datatype of IM
If the /UPDATE keyword is present, then the FITS header will be
modified, if necessary, to force agreement with the image array
CALLING SEQUENCE:
check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SILENT
ERRMSG = ]'
INPUT PARAMETERS:
IM - FITS array, e.g. as read by READFITS
HDR - FITS header (string array) associated with IM
OPTIONAL OUTPUTS:
dimen - vector containing actual array dimensions
idltype- data type of the FITS array as specified in the IDL SIZE
function (1 for BYTE, 2 for 16 bit integer, 3 for 32 bit integer etc.)
OPTIONAL KEYWORD INPUTS:
/NOTYPE - If this keyword is set, then only agreement of the array
dimensions with the FITS header are checked, and not the
data type.
/UPDATE - If this keyword is set then the BITPIX, NAXIS and NAXISi
FITS keywords will be updated to agree with the array
/FITS, /SDAS - these are obsolete keywords that now do nothing
/SILENT - If keyword is set and nonzero, the informational messages
will not be printed
/ALLOW_DEGEN - Don't check for degenerate axes.
OPTIONAL KEYWORD OUTPUT:
ERRMSG = If this keyword is present, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned.
PROCEDURE:
Program checks the NAXIS and NAXISi keywords in the header to
see if they match the image array dimensions, and checks whether
the BITPIX keyword agrees with the array type.
PROCEDURE CALLS:
FXADDPAR, FXPAR(), SXDELPAR
MODIFICATION HISTORY:
Written, December 1991 W. Landsman Hughes/STX to replace CHKIMHD
No error returned if NAXIS=0 and IM is a scalar W. Landsman Feb 93
Fixed bug for REAL*8 STSDAS data W. Landsman July 93
Make sure NAXIS agrees with NAXISi W. Landsman October 93
Converted to IDL V5.0 W. Landsman September 1997
Allow unsigned data types W. Landsman December 1999
Allow BZERO = 0 for unsigned data types W. Landsman January 2000
Added ERRMSG keyword, W. Landsman February 2000
Use FXADDPAR to put NAXISi in proper order W. Landsman August 2000
Improper FXADDPAR call for DATATYPE keyword W. Landsman December 2000
Remove explicit setting of obsolete !err W. Landsman February 2004
Remove SDAS support W. Landsman November 2006
Fix dimension errors introduced Nov 2006
Work again for null arrays W. Landsman/E. Hivon May 2007
Use V6.0 notation W.L. Feb. 2011
Add /ALLOW_DEGEN, William Thompson, 26-Jun-2019
(See external/astron/fits/check_fits.pro)
NAME:
FITSDIR
PURPOSE:
Display selected FITS keywords from the headers of FITS files.
EXPLANATION:
The values of either user-specified or default FITS keywords are
displayed in either the primary header and/or the first extension header.
Unless the /NOSIZE keyword is set, the data size is also displayed.
The default keywords are as follows (with keywords in 2nd row used if
those in the first row not found, and the 3rd row if neither the keywords
in the first or second rows found:)
DATE-OBS TELESCOP OBJECT EXPTIME
TDATEOBS TELNAME TARGNAME INTEG ;First Alternative
DATE OBSERVAT EXPOSURE ;Second Alternative
INSTRUME EXPTIM ;Third Alternative
FITSDIR will also recognize gzip compressed files (must have a .gz
or FTZ extension).
CALLING SEQUENCE:
FITSDIR , [ directory, TEXTOUT =, EXTEN=, KEYWORDS=, /NOSIZE, /NoTELESCOPE
ALT1_KEYWORDS= ,ALT2_KEYWORDS = ,ALT3_KEYWORDS =
OPTIONAL INPUT PARAMETERS:
DIRECTORY - Scalar string giving file name, disk or directory to be
searched. Wildcard file names are allowed. Examples of
valid names include 'iraf/*.fits' (Unix) or 'd:\myfiles\f*.fits',
(Windows).
OPTIONAL KEYWORD INPUT PARAMETER
KEYWORDS - FITS keywords to display, as either a vector of strings or as
a comma delimited scalar string, e.g.'testname,dewar,filter'
If not supplied, then the default keywords are 'DATE-OBS',
'TELESCOP','OBJECT','EXPTIME'
ALT1_KEYWORDS - A list (either a vector of strings or a comma delimited
strings of alternative keywords to use if the default
KEYWORDS cannot be found. By default, 'TDATEOBS', is the
alternative to DATE-OBS, 'TELNAME' for 'TELESCOP','TARGNAME'
for 'OBJECT', and 'INTEG' for EXPTIME
ALT2_KEYWORDS - A list (either a vector of strings or a comma delimited
strings of alternative keywords to use if neither KEYWORDS
nor ALT1_KEYWORDS can be found.
ALT3_KEYWORDS - A list (either a vector of strings or a comma delimited
strings of alternative keywords to use if neither KEYWORDS
nor ALT1_KEYWORDS nor ALT2_KEYWORDS can be found.
/NOSIZE - if set then information about the image size is not displayed
TEXTOUT - Controls output device as described in TEXTOPEN procedure
textout=1 TERMINAL using /more option
textout=2 TERMINAL without /more option
textout=3 <program>.prt
textout=4 laser.tmp
textout=5 user must open file
textout=7 Append to existing <program>.prt file
textout = filename (default extension of .prt)
EXTEN - Specifies an extension number (/EXTEN works for first extension)
which is checked for the desired keywords. FITSDIR searches
both the extension header and the primary header when an extension
number is specified.
/NOTELESCOPE - If set, then if the default keywords are used, then the
TELESCOPE (or TELNAME, OBSERVAT, INSTRUME) keywords are omitted
to give more room for display other keywords. The /NOTELESCOP
keyword has no effect if the default keywords are not used.
OUTPUT PARAMETERS:
None.
EXAMPLES:
(1) Print info on all'*.fits' files in the current directory using default
keywords. Include information from the first extension
IDL> fitsdir,/exten
(2) Write a driver program to display selected keywords in HST/ACS drizzled
(*drz) images
pro acsdir
keywords = 'date-obs,targname,detector,filter1,filter2,exptime'
fitsdir,'*drz.fits',key=keywords,/exten
return & end
(3) Write info on all *.fits files in the Unix directory /usr2/smith, to a
file 'smith.txt' using the default keywords, but don't display the value
of the TELESCOPE keyword
IDL> fitsdir ,'/usr2/smith/*.fits',t='smith.txt', /NoTel
PROCEDURE:
FILE_SEARCH() is used to find the specified FITS files. The
header of each file is read, and the selected keywords are extracted.
The formatting is adjusted so that no value is truncated on display.
SYSTEM VARIABLES:
TEXTOPEN (called by FITSDIR) will automatically define the following
non-standard system variables if they are not previously defined:
DEFSYSV,'!TEXTOUT',1
DEFSYSV,'!TEXTUNIT',0
PROCEDURES USED:
FDECOMP, FXMOVE(), MRD_HREAD, REMCHAR, SPEC_DIR(), TEXTOPEN, TEXTCLOSE
MODIFICATION HISTORY:
Written, W. Landsman, HSTX February, 1993
Search alternate keyword names W.Landsman October 1998
Avoid integer truncation for NAXISi >32767 W. Landsman July 2000
Don't leave open unit W. Landsman July 2000
Added EXTEN keyword, work with compressed files, additional alternate
keywords W. Landsman December 2000
Don't assume floating pt. exposure time W. Landsman September 2001
Major rewrite, KEYWORD & ALT*_KEYWORDS keywords, no truncation,
/NOSIZE keyword W. Landsman, SSAI August 2002
Assume V5.3 or later W. Landsman November 2002
Fix case where no keywords supplied W. Landsman January 2003
NAXIS* values must be integers W. Landsman SSAI June 2003
Trim spaces off of input KEYWORD values W. Landsman March 2004
Treat .FTZ extension as gzip compressed W. Landsman September 2004
Assume since V5.5, file_search() available W. Landsman Aug 2006
Don't assume all images compressed or uncompressed W. L. Apr 2010
Use V6.0 notation W.L. Feb 2011
Don't let a corrupted file cause an abort W.L. Feb 2014
Let textopen.pro define !TEXTUNIT W.L. Sep 2016
(See external/astron/fits/fitsdir.pro)
NAME:
FITSRGB_to_TIFF
PURPOSE:
Combine separate red, green, and blue FITS images into TIFF format
EXPLANATION:
The output TIFF (class R) file can have colors interleaved either
by pixel or image. The colour mix is also adjustable.
CALLING SEQUENCE:
FITSRGB_to_TIFF, path, rgb_files, tiff_name [,/BY_PIXEL, /PREVIEW,
RED= , GREEN =, BLUE =]
INPUTS:
path = file system directory path to the RGB files required.
rgb_files = string array with three components - the red FITS file
filename, the blue FITS file filename and the green FITS
file filename
OUTPUTS:
tiff_name = string containing name of tiff file to be produced
OPTIONAL OUTPUT:
Header = String array containing the header from the FITS file.
OPTIONAL INPUT KEYWORDS:
BY_PIXEL = This causes TIFF file RGB to be interleaved by pixel
rather than the default of by image.
PREVIEW = Allows a 24 bit image to be displayed on the screen
to check the colour mix.
RED = Real number containing the fractional mix of red
GREEN = Real number containing the fractional mix of green
BLUE = Real number containing the fractional mix of blue
EXAMPLE:
Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from
the directory '/data/images/space' and output a TIFF file named
'colour.tiff'
IDL> FITSRGB_to_TIFF, '/data/images/space', ['red.fits', $
'blue.fits', 'green.fits'], 'colour.tiff'
Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from
the current directory and output a TIFF file named '/images/out.tiff'
In this case, the red image is twice as strong as the green and the
blue is a third more intense. A preview on screen is also wanted.
IDL> FITSRGB_to_TIFF, '.', ['red.fits', $
'blue.fits', 'green.fits'], '/images/out.tiff', $
/PREVIEW, RED=0.5, GREEN=1.0, BLUE=0.666
RESTRICTIONS:
(1) Limited to the ability of the routine READFITS
NOTES:
None
PROCEDURES USED:
Functions: READFITS, CONCAT_DIR
Procedures: WRITE_TIFF
MODIFICATION HISTORY:
16th January 1995 - Written by Carl Shaw, Queen's University Belfast
27 Jan 1995 - W. Landsman, Add CONCAT_DIR for VMS, Windows compatibility
Converted to IDL V5.0 W. Landsman September 1997
Use WRITE_TIFF instead of obsolete TIFF_WRITE W. Landsman December 1998
Cosmetic changes W. Landsman February 2000
(See external/astron/fits/fitsrgb_to_tiff.pro)
NAME:
FITS_ADD_CHECKSUM
PURPOSE:
Add or update the CHECKSUM and DATASUM keywords in a FITS header
EXPLANATION:
Follows the May 2002 version of the FITS checksum proposal at
http://fits.gsfc.nasa.gov/registry/checksum.html
CALLING SEQUENCE:
FITS_ADD_CHECKSUM, Hdr, [ Data, /No_TIMESTAMP, /FROM_IEEE ]
INPUT-OUTPUT:
Hdr - FITS header (string array), it will be updated with new
(or modified) CHECKSUM and DATASUM keywords
OPTIONAL INPUT:
Data - data array associated with the FITS header. If not supplied, or
set to a scalar, then the program checks whether there is a
DATASUM keyword already in the FITS header containing the 32bit
checksum for the data. If there is no such keyword then there
assumed to be no data array associated with the FITS header.
OPTIONAL INPUT KEYWORDS:
/FROM_IEEE - If this keyword is set, then the input is assumed to be in
big endian format (e.g. an untranslated FITS array). This
keyword only has an effect on little endian machines (e.g.
a Linux box).
/No_TIMESTAMP - If set, then a time stamp is not included in the comment
field of the CHECKSUM and DATASUM keywords. Unless the
/No_TIMESTAMP keyword is set, repeated calls to FITS_ADD_CHECKSUM
with the same header and data will yield different values of
CHECKSUM (as the date stamp always changes). However, use of the
date stamp is recommended in the checksum proposal.
PROCEDURES USED:
CHECKSUM32, FITS_ASCII_ENCODE(), GET_DATE, SXADDPAR, SXPAR()
REVISION HISTORY:
W. Landsman SSAI December 2002
Fix problem with images with a multiple of 2880 bytes. W.L. May 2008
Avoid conversion error when DATASUM is an empty string W.L. June 2008
Don't update DATASUM if not already present and no data array supplied
W.L. July 2008
Make sure input header array has 80 chars/line W.L. Aug 2009
Make sure CHECKSUM is placed right after an already present DATASUM
keyword. Mats Löfdahl October 2019
(See external/astron/fits/fits_add_checksum.pro)
NAME:
FITS_ASCII_ENCODE()
PURPOSE:
Encode an unsigned longword as an ASCII string to insert in a FITS header
EXPLANATION:
Follows the July 2007 version of the FITS checksum proposal at
http://fits.gsfc.nasa.gov/registry/checksum.html
CALLING SEQUENCE:
result = FITS_ASCII_ENCODE( sum32)
INPUTS:
sum32 - 32bit *unsigned longword* (e.g. as returned by CHECKSUM32)
RESULT:
A 16 character scalar string suitable for the CHECKSUM keyword
EXAMPLE:
A FITS header/data unit has a checksum of 868229149. Encode the
complement of this value (3426738146) into an ASCII string
IDL> print,FITS_ASCII_ENCODE(3426738146U)
===> "hcHjjc9ghcEghc9g"
METHOD:
The 32bit value is interpreted as a sequence of 4 unsigned 8 bit
integers, and divided by 4. Add an offset of 48b (ASCII '0').
Remove non-alphanumeric ASCII characters (byte values 58-64 and 91-96)
by simultaneously incrementing and decrementing the values in pairs.
Cyclicly shift the string one place to the right.
REVISION HISTORY:
Written W. Landsman SSAI December 2002
Use V6.0 notation W.L. August 2013
(See external/astron/fits/fits_ascii_encode.pro)
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 external/astron/fits/fits_close.pro)
NAME:
FITS_HELP
PURPOSE:
To print a summary of the primary data units and extensions in a
FITS file.
;
CALLING SEQUENCE:
FITS_HELP,filename_or_fcb
INPUTS:
FILENAME_OR_FCB - name of the fits file or the FITS Control Block (FCB)
structure returned by FITS_OPEN. The file name is allowed
to be gzip compressed (with a .gz extension)
OUTPUTS:
A summary of the FITS file is printed. For each extension, the values
of the XTENSION, EXTNAME EXTVER EXTLEVEL BITPIX GCOUNT, PCOUNT NAXIS
and NAXIS* keywords are displayed.
EXAMPLES:
FITS_HELP,'myfile.fits'
FITS_OPEN,'anotherfile.fits',fcb
FITS_HELP,fcb
PROCEDURES USED:
FITS_OPEN, FITS_CLOSE
HISTORY:
Written by: D. Lindler August, 1995
Converted to IDL V5.0 W. Landsman September 1997
Don't truncate EXTNAME values at 10 chars W. Landsman Feb. 2005
Use V6.0 notation W. Landsman Jan 2012
(See external/astron/fits/fits_help.pro)
NAME:
FITS_INFO
PURPOSE:
Provide information about the contents of a FITS file
EXPLANATION:
Information includes number of header records and size of data array.
Applies to primary header and all extensions. Information can be
printed at the terminal and/or stored in a common block
This routine is mostly obsolete, and better results can be usually be
performed with FITS_HELP (for display) or FITS_OPEN (to read FITS
information into a structure)
CALLING SEQUENCE:
FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext =, EXTNAME= ]
INPUT:
Filename - Scalar string giving the name of the FITS file(s)
Can include wildcards such as '*.fits', or regular
expressions
allowed by the FILE_SEARCH() function. One can also search
gzip compressed FITS files, but their extension must
end in .gz or .ftz.
OPTIONAL INPUT KEYWORDS:
/SILENT - If set, then the display of the file description on the
terminal will be suppressed
TEXTOUT - specifies output device.
textout=1 TERMINAL using /more option
textout=2 TERMINAL without /more option
textout=3 <program>.prt
textout=4 laser.tmp
textout=5 user must open file, see TEXTOPEN
textout=7 append to existing <program.prt> file
textout = filename (default extension of .prt)
If TEXTOUT is not supplied, then !TEXTOUT is used
OPTIONAL OUTPUT KEYWORDS:
The following keyowrds are for use when only one file is processed
N_ext - Returns an integer scalar giving the number of extensions in
the FITS file
extname - returns a list containing the EXTNAME keywords for each
extension.
COMMON BLOCKS
DESCRIPTOR = File descriptor string of the form N_hdrrec Naxis IDL_type
Naxis1 Naxis2 ... Naxisn [N_hdrrec table_type Naxis
IDL_type Naxis1 ... Naxisn] (repeated for each extension)
For example, the following descriptor
167 2 4 3839 4 55 BINTABLE 2 1 89 5
indicates that the primary header containing 167 lines, and
the primary (2D) floating point image (IDL type 4)
is of size 3839 x 4. The first extension header contains
55 lines, and the byte (IDL type 1) table array is of
size
89 x 5.
The DESCRIPTOR is *only* computed if /SILENT is set.
EXAMPLE:
Display info about all FITS files of the form '*.fit' in the current
directory
IDL> fits_info, '*.fit'
Any time a *.fit file is found which is *not* in FITS format, an error
message is displayed at the terminal and the program continues
PROCEDURES USED:
GETTOK(), MRD_SKIP, STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE
SYSTEM VARIABLES:
The non-standard system variables !TEXTOUT and !TEXTUNIT will be
created by FITS_INFO if they are not previously defined.
DEFSYSV,'!TEXTOUT',1
DEFSYSV,'!TEXTUNIT',0
See TEXTOPEN.PRO for more info
MODIFICATION HISTORY:
Written, K. Venkatakrishna, Hughes STX, May 1992
Added N_ext keyword, and table_name info, G. Reichert
Work on *very* large FITS files October 92
More checks to recognize corrupted FITS files February, 1993
Proper check for END keyword December
Correctly size variable length binary tables WBL December 1994
EXTNAME keyword can be anywhere in extension header WBL January 1998
Correctly skip past extensions with no data WBL April 1998
Converted to IDL V5.0, W. Landsman, April 1998
No need for !TEXTOUT if /SILENT D.Finkbeiner February 2002
Define !TEXTOUT if needed. R. Sterner, 2002 Aug 27
Work on gzip compressed files for V5.3 or later W. Landsman 2003 Jan
Improve speed by only reading first 36 lines of header
Count headers with more than 32767 lines W. Landsman Feb. 2003
Assume since V5.3 (OPENR,/COMPRESS) W. Landsman Feb 2004
EXTNAME keyword can be anywhere in extension header again
WBL/S. Bansal Dec 2004
Read more than 200 extensions WBL March 2005
Work for FITS files with SIMPLE=F WBL July 2005
Assume since V5.4, fstat.compress available WBL April 2006
Added EXTNAME as an IDL keyword to return values. M. Perrin Dec 2007
make Ndata a long64 to deal with large files. E. Hivon Mar 2008
For GDL compatibility, first check if file is compressed before using
OPENR,/COMPRESS B. Roukema/WL Apr 2010
Increased nmax (max number of extensions) from 400 to 2000 Sept 2012
Correctly fills EXTNAME when SILENT is set EH Jan 2013
Turned ptr to long64 for very large files EH Dec 2013
Replace 2880L with 2880LL for very large files EH Mar 2015
Let TEXTOPEN test for !TEXTOUT WL Sep 2016
Replace || with OR to work on multiple files L.Haffner/WL Apr 30 2022
(See external/astron/fits/fits_info.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) files or Unix
compressed files *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
Handle axis sizes requiring 64 integer W.L. April 2014
Support for .Z compressed files M. Zechmeister/W.L. April 2014
Wrap filenames in "" when spawning subprocesses, to handle paths
with spaces or other atypical characters. M. Perrin Nov 2014
(See external/astron/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.
Both Gzip compressed (.gz) and Unix compressed (*.Z) files can
be read, although there is a performance penalty..
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, fcb
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
Assume 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
Make sure opened pipes are closed if fcb not left open W.L. April 2012
Fix bug with /data_only introduced Dec 2010 W. L. April 2014
(See external/astron/fits/fits_read.pro)
NAME:
FITS_TEST_CHECKSUM()
PURPOSE:
Verify the values of the CHECKSUM and DATASUM keywords in a FITS header
EXPLANATION:
Follows the 2007 version of the FITS checksum proposal at
http://fits.gsfc.nasa.gov/registry/checksum.html
CALLING SEQUENCE:
result = FITS_TEST_CHECKSUM(HDR, [ DATA, ERRMSG=, /FROM_IEEE ])
INPUTS:
HDR - FITS header (vector string)
OPTIONAL DATA:
DATA - data array associated with the FITS header. An IDL structure is
not allowed. If not supplied, or
set to a scalar, then there is assumed to be no data array
associated with the FITS header.
RESULT:
An integer -1, 0 or 1 indicating the following conditions:
1 - CHECKSUM (and DATASUM) keywords are present with correct values
0 - CHECKSUM keyword is not present
-1 - CHECKSUM or DATASUM keyword does not have the correct value
indicating possible data corruption.
OPTIONAL INPUT KEYWORD:
/FROM_IEEE - If this keyword is set, then the input is assumed to be in
big endian format (e.g. an untranslated FITS array). This
keyword only has an effect on little endian machines (e.g.
a Linux box).
/TRUST_DATASUM - If this keyword is set, then the DATA input
parameter is ignored and the DATASUM keyword in the HDR
is assumed to be correct. (If there is no DATASUM
keyword, /TRUST_DATASUM has no effect.) Useful if data is too
large to store entirely in memory at one time.
OPTIONAL OUTPUT KEYWORD:
ERRMSG - will contain a scalar string giving the error condition. If
RESULT = 1 then ERRMSG will be an empty string. If this
output keyword is not supplied, then the error message will be
printed at the terminal.
NOTES:
The header and data must be *exactly* as originally written in the FITS
file. By default, some FITS readers may alter keyword values (e.g.
BSCALE) or append information (e.g. HISTORY or an inherited primary
header) and this will alter the checksum value.
PROCEDURES USED:
CHECKSUM32, FITS_ASCII_ENCODE(), SXPAR()
EXAMPLE:
Verify the CHECKSUM keywords in the primary header/data unit of a FITS
file 'test.fits'
FITS_READ,'test.fits',data,hdr,/no_PDU,/NoSCALE
print,FITS_TEST_CHECKSUM(hdr,data)
Note the use of the /No_PDU and /NoSCALE keywords to avoid any alteration
of the FITS header
REVISION HISTORY:
W. Landsman SSAI December 2002
Return quietly if CHECKSUM keywords not found W. Landsman May 2003
Add /NOSAVE to CHECKSUM32 calls when possible W. Landsman Sep 2004
New option /TRUST_DATASUM. Mats Löfdahl July 2020
(See external/astron/fits/fits_test_checksum.pro)
NAME:
FITS_WRITE
PURPOSE:
To write a FITS primary data unit or extension.
EXPLANATION:
***NOTE** This version of FITS_READ must be used with a post Sep 2006
version of FITS_OPEN.
CALLING SEQUENCE:
FITS_WRITE, filename_or_fcb, data, [header_in]
INPUTS:
FILENAME_OR_FCB: name of the output data file or the FITS control
block returned by FITS_OPEN (called with the /WRITE or
/APPEND) parameters.
OPTIONAL INPUTS:
DATA: data array to write. If not supplied or set to a scalar, a
null image is written.
HEADER_IN: FITS header keyword. If not supplied, a minimal basic
header will be created. Required FITS keywords, SIMPLE,
BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and
do not need to be supplied with the header. If supplied,
their values will be updated as necessary to reflect DATA.
INPUT KEYWORD PARAMETERS:
XTENSION: type of extension to write (Default="IMAGE"). If not
supplied, it will be taken from HEADER_IN. If not in either
place, the default is "IMAGE". This parameter is ignored
when writing the primary data unit. Note that binary and
and ASCII table extensions already have a properly formatted
header (e.g. with TTYPE* keywords) and byte array data.
EXTNAME: EXTNAME for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTNAME will be written into the output extension.
EXTVER: EXTVER for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTVER will be written into the output extension.
EXTLEVEL: EXTLEVEL for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTLEVEL will be written into the output extension.
/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_WRITE will
print the message and issue a RETALL
/NO_DATA: Set if you only want FITS_WRITE to write a header. The
header supplied will be written without modification and
the user is expected to write the data using WRITEU to unit
FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is
responsible for the validity of the header, and must write
the correct amount and format of the data. When FITS_WRITE
is used in this fashion, it will pad the data from a previously
written extension to 2880 blocks before writting the header.
OUTPUT KEYWORD PARAMETERS:
MESSAGE: value of the error message for use with /NO_ABORT
HEADER: actual output header written to the FITS file.
NOTES:
If the first call to FITS_WRITE is an extension, FITS_WRITE will
automatically write a null image as the primary data unit.
Keywords and history in the input header will be properly separated
into the primary data unit and extension portions when constructing
the output header (See FITS_READ for information on the internal
Header format which separates the extension and PDU header portions).
EXAMPLES:
Write an IDL variable to a FITS file with the minimal required header.
FITS_WRITE,'newfile.fits',ARRAY
Write the same array as an image extension, with a null Primary data
unit.
FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE'
Write 4 additional image extensions to the same file.
FITS_OPEN,'newfile.fits',fcb
FITS_WRITE,fcb,data1,extname='FLUX',extver=1
FITS_WRITE,fcb,err1,extname'ERR',extver=1
FITS_WRITE,fcb,data2,extname='FLUX',extver=2
FITS_WRITE,fcb,err2,extname='ERR',extver=2
FITS_CLOSE,FCB
WARNING:
FITS_WRITE currently does not completely update the file control block.
When mixing FITS_READ and FITS_WRITE commands it is safer to use
file names, rather than passing the file control block.
PROCEDURES USED:
FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR()
HISTORY:
Written by: D. Lindler August, 1995
Work for variable length extensions W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
PCOUNT and GCOUNT added for IMAGE extensions J. Graham October 1999
Write unsigned data types W. Landsman December 1999
Pad data area with zeros not blanks W. McCann/W. Landsman October 2000
Return Message='' to signal normal operation W. Landsman Nov. 2000
Ensure that required extension table keywords are in proper order
W.V. Dixon/W. Landsman March 2001
Assume since V5.1, remove NaNValue keyword W. Landsman Nov. 2002
Removed obsolete !ERR system variable W. Landsman Feb 2004
Check that byte array supplied with table extension W. Landsman Mar 2004
Make number of bytes 64bit to avoid possible overflow W.L Apr 2006
Assume FITS_OPEN has opened the file with /SWAP_IF_LITTLE_ENDIAN
W. Landsman September 2006
Removes BZERO and BSCALE for floating point output, D. Lindler, Sep 2008
(See external/astron/fits/fits_write.pro)
NAME:
FXMOVE
PURPOSE:
Skip to a specified extension number or name in a FITS file
CALLING SEQUENCE:
STATUS=FXMOVE(UNIT, EXT, /Silent)
STATUS=FXMOVE(UNIT, EXTNAME, /Silent, EXT_NO=, ERRMSG= )
INPUT PARAMETERS:
UNIT = An open unit descriptor for a FITS data stream.
EXTEN = Number of extensions to skip.
or
Scalar string giving extension name (in the EXTNAME keyword)
OPTIONAL INPUT PARAMETER:
/SILENT - If set, then any messages about invalid characters in the
FITS file are suppressed.
OPTIONAL OUTPUT PARAMETER:
ERRMSG = If this keyword is present, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned.
EXT_NO - Extension number, scalar integer, useful if the user supplied
an extension name in the EXTEN parameter
RETURNS:
0 if successful.
-1 if an error is encountered.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Repositions the file pointer.
PROCEDURE:
Each FITS header is read in and parsed, and the file pointer is moved
to where the next FITS extension header until the desired
extension is reached.
PROCEDURE CALLS:
FXPAR(), MRD_HREAD, MRD_SKIP
MODIFICATION HISTORY:
Extracted from FXPOSIT 8-March-2000 by T. McGlynn
Added /SILENT keyword 14-Dec-2000 by W. Landsman
Save time by not reading the full header W. Landsman Feb. 2003
Allow extension name to be specified, added EXT_NO, ERRMSG keywords
W. Landsman December 2006
Make search for EXTNAME case-independent W.Landsman March 2007
Avoid round-off error for very large extensions N. Piskunov Dec 2007
Assume since V6.1 (/INTEGER keyword available to PRODUCT() ) Dec 2007
Capture error message from MRD_HREAD (must be used with post-June 2009
version of MRD-HREAD) W. Landsman July 2009
(See external/astron/fits/fxmove.pro)
NAME:
FXPOSIT
PURPOSE:
Return the unit number of a FITS file positioned at specified extension
EXPLANATION:
The FITS file will be ready to be read at the beginning of the
specified extension. Either an extension number or extension name
can be specified. Called by headfits.pro, mrdfits.pro
Modified in March 2009 to set the /SWAP_IF_LITTLE_ENDIAN keyword
when opening a file, and **may not be compatible with earlier versions**
CALLING SEQUENCE:
unit=FXPOSIT(FILE, EXT_NO_OR_NAME, /READONLY, COMPRESS=program,
UNIXPIPE=, ERRMSG= , EXTNUM= , UNIT=, /SILENT
/FPACK, /NO_FPACK
INPUT PARAMETERS:
FILE = FITS file name, scalar string. If an empty string is supplied
then the user will be prompted for the file name. The user
will also be prompted if a wild card is supplied, and more than
one file matches the wildcard.
EXT_NO_OR_NAME = Either the extension to be moved to (scalar
nonnegative integer) or the name of the extension to read
(scalar string)
RETURNS:
Unit number of file or -1 if an error is detected.
OPTIONAL INPUT KEYWORD PARAMETER:
COMPRESS - If this keyword is set and non-zero, then then treat
the file as compressed. If 1 assume a gzipped file.
and use IDLs internal decompression facility. For Unix
compressed or bzip2 compressed files spawn off a process to
decompress and use its output as the FITS stream. If the
keyword is not 1, then use its value as a string giving the
command needed for decompression.
/FPACK - Signal that the file is compressed with the FPACK software.
http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default,
(FXPOSIT 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
/NO_FPACK - The unit will only be used to read the FITS header. In
that case FPACK compressed files need not be uncompressed.
LUNIT - Integer giving the file unit number. Use this keyword if
you want to override the default use of GET_LUN to obtain
a unit number.
/READONLY - If this keyword is set and non-zero, then OPENR rather
than OPENU will be used to open the FITS file. Note that
compressed files are always set to /READONLY
/SILENT If set, then suppress any messages about invalid characters
in the FITS file.
OPTIONAL OUTPUT KEYWORDS:
EXTNUM - Nonnegative integer give the extension number actually read
Useful only if the extension was specified by name.
ERRMSG = If this keyword is present, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned.
UNIXPIPE - If set to 1, then the FITS file was opened with a UNIX pipe
rather than with the OPENR command. This is only required
when reading a FPACK, bzip or Unix compressed file. Note
that automatic byteswapping cannnot be set for a Unix pipe,
since the SWAP_IF_LITTLE_ENDIAN keyword is only available for the
OPEN command, and it is the responsibility of the calling
routine to perform the byteswapping.
SIDE EFFECTS:
Opens and returns a file unit.
PROCEDURE:
Open the appropriate file, or spawn a command and intercept
the output.
Call FXMOVE to get to the appropriate extension.
PROCEDURE CALLS:
FXMOVE()
MODIFICATION HISTORY:
Derived from William Thompson's FXFINDEND routine.
Modified by T.McGlynn, 5-October-1994.
Modified by T.McGlynn, 25-Feb-1995 to handle compressed
files. Pipes cannot be accessed using FXHREAD so
MRD_HREAD was written.
W. Landsman 23-Apr-1997 Force the /bin/sh shell when uncompressing
T. McGlynn 03-June-1999 Use /noshell option to get rid of processes left by spawn.
Use findfile to retain ability to use wildcards
W. Landsman 03-Aug-1999 Use EXPAND_TILDE under Unix to find file
T. McGlynn 04-Apr-2000 Put reading code into FXMOVE,
additional support for compression from D.Palmer.
W. Landsman/D.Zarro 04-Jul-2000 Added test for !VERSION.OS EQ 'Win32' (WinNT)
W. Landsman 12-Dec-2000 Added /SILENT keyword
W. Landsman April 2002 Use FILE_SEARCH for V5.5 or later
W. Landsman Feb 2004 Assume since V5.3 (OPENR,/COMPRESS available)
W. Landsman,W. Thompson, 2-Mar-2004, Add support for BZIP2
W. Landsman Don't leave open file if an error occurs
W. Landsman Sep 2004 Treat FTZ extension as gzip compressed
W. Landsman Feb 2006 Removed leading spaces (prior to V5.5)
W. Landsman Nov 2006 Allow specification of extension name
Added EXTNUM, ERRMSG keywords
W. Landsman/N.Piskunov Dec 2007 Added LUNIT keyword
W. Landsman Mar 2009 OPEN with /SWAP_IF_LITTLE_ENDIAN
Added UNIXPIPE output keyword
N. Rich May 2009 Check if filename is an empty string
W. Landsman May 2009 Support FPACK compressed files
Added /FPACK, /HEADERONLY keywords
W.Landsman July 2009 Deprecated /HEADERONLY add /NO_FPACK
W.Landsman July 2011 Check for SIMPLE in first 8 chars
Use gunzip to decompress Unix. Z file since compress utility
often not installed anymore)
W. Landsman October 2012 Add .fz extension if /FPACK set
W. Landsman July 2013 More diagnostics if file not found
(See external/astron/fits/fxposit.pro)
NAME:
HEADFITS
PURPOSE:
Read a FITS (primary or extension) header into a string array.
EXPLANATION:
HEADFITS() supports several types of compressed files including
gzip (.gz), Unix compressed (.Z), Bzip2 (.bz2) or FPACK (.fz
http://heasarc.gsfc.nasa.gov/fitsio/fpack/ )
CALLING SEQUENCE:
Result = HEADFITS(Filename/Fileunit ,[ ERRMSG =, EXTEN= , COMPRESS=,
/SILENT ])
INPUTS:
Filename = String containing the name of the FITS file to be read.
If set to an empty string, then user will be prompted for name.
File names ending in '.gz' are assumed to be gzip'ed compressed
and under Unix file names ending in '.Z' are assumed to be
Unix compressed, and file names ending in .bz2 are assumed to
be bzip2 compressed. If this default behaviour is not
sufficient then use the COMPRESS keyword.
or
Fileunit - A scalar integer specifying the unit of an already opened
FITS file. The unit will remain open after exiting
HEADFITS(). 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 HEADFITS(). This
is more efficient that 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.
OPTIONAL INPUT KEYWORDS:
EXTEN = Either an integer scalar, specifying which FITS extension to
read, or a scalar string specifying the extension name (stored
in the EXTNAME keyword). For example, to read the header of
the first extension set EXTEN = 1. Default is to read the
primary FITS header (EXTEN = 0). The EXTEN keyword cannot
be used when a unit number is supplied instead of a file name.
COMPRESS - If this keyword is set and non-zero, then treat the file
as compressed. If 1 assume a gzipped file. Use IDL's
internal decompression facilities for gzip files, while for
Unix or bzip2 compression spawn off a process to decompress and
use its output as the FITS stream. If the keyword is not 1,
then use its value as a string giving the command needed for
decompression. See FXPOSIT for more info.
/SILENT - If set, then suppress any warning messages about invalid
characters in the FITS file.
OPTIONAL KEYWORD OUTPUT:
ERRMSG = If this keyword is present, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned.
OUTPUTS:
Result of function = FITS header, string array
EXAMPLE:
Print the main FITS header of a file 'test.fits' into a string
variable, h
IDL> print, headfits( 'test.fits')
Print the second extension header of a gzip compressed FITS file
'test.fits.gz'. Use HPRINT for pretty format
IDL> hprint, headfits( 'test.fits.gz', ext=2)
Read the extension named CALSPEC
IDL> hprint,headfits('test.fits.gz',ext='CALSPEC')
PROCEDURES CALLED
FXPOSIT(), MRD_HREAD
MODIFICATION HISTORY:
Adapted by Frank Varosi from READFITS by Jim Wofford, January, 24 1989
Option to read a unit number rather than file name W.L October 2001
Test output status of MRD_HREAD call October 2003 W. Landsman
Allow extension to be specified by name Dec 2006 W. Landsman
No need to uncompress FPACK compressed files May 2009 W. Landsman
Use V6.0 notation W.L. Feb. 2011
Do not check for EOF() since MRD_HREAD does this Nov 2014 W. Landsman
(See external/astron/fits/headfits.pro)
NAME:
MKHDR
PURPOSE:
Make a minimal primary (or IMAGE extension) FITS header
EXPLANATION:
If an array is supplied, then the created FITS header will be
appropriate to the supplied array. Otherwise, the user can specify
the dimensions and datatype.
To update an *existing* FITS header with a new image array, instead
use check_FITS, /Update
CALLING SEQUENCE:
MKHDR, header ;Prompt for image size and type
or
MKHDR, header, im, [ /IMAGE, /EXTEND ]
or
MKHDR, header, type, naxisx, [/IMAGE, /EXTEND ]
OPTIONAL INPUTS:
IM - If IM is a vector or array then the header will be made
appropriate to the size and type of IM. IM does not have
to be the actual data; it can be a dummy array of the same
type and size as the data. Set IM = '' to create a dummy
header with NAXIS = 0.
TYPE - If 2 parameters are supplied, then the second parameter
is interpreted as an integer giving the IDL datatype e.g.
1 - Byte, 2 - 16 bit integer, 4 - float, 3 - Long
NAXISX - Vector giving the size of each dimension (NAXIS1, NAXIS2,
etc.).
OUTPUT:
HEADER - image header, (string array) with required keywords
BITPIX, NAXIS, NAXIS1, ... Further keywords can be added
to the header with SXADDPAR.
OPTIONAL INPUT KEYWORDS:
/IMAGE = If set, then a minimal header for a FITS IMAGE extension
is created. An IMAGE extension header is identical to
a primary FITS header except the first keyword is
'XTENSION' = 'IMAGE' instead of 'SIMPLE ' = 'T'
/EXTEND = If set, then the keyword EXTEND is inserted into the file,
with the value of "T" (true). The EXTEND keyword can
optionally be included in a primary header, if the FITS file
contains extensions.
RESTRICTIONS:
(1) MKHDR should not be used to make an STSDAS header or a FITS
ASCII or Binary Table extension header. Instead use
SXHMAKE - to create a minimal STSDAS header
FXBHMAKE - to create a minimal FITS binary table header
FTCREATE - to create a minimal FITS ASCII table header
(2) Any data already in the header before calling MKHDR
will be destroyed.
EXAMPLE:
Create a minimal FITS header, Hdr, for a 30 x 40 x 50 INTEGER*2 array
IDL> mkhdr, Hdr, 2, [30,40,50]
Alternatively, if the array already exists as an IDL variable, Array,
IDL> mkhdr, Hdr, Array
PROCEDURES CALLED:
SXADDPAR, GET_DATE
REVISION HISTORY:
Written November, 1988 W. Landsman
May, 1990, Adapted for IDL Version 2.0, J. Isensee
Aug, 1997, Use SYSTIME(), new DATE format W. Landsman
Allow unsigned data types W. Landsman December 1999
Set BZERO = 0 for unsigned integer data W. Landsman January 2000
EXTEND keyword must immediately follow last NAXISi W. Landsman Sep 2000
Add FITS definition COMMENT to primary headers W. Landsman Oct. 2001
Allow (nonstandard) 64 bit integers W. Landsman Feb. 2003
Add V6.0 notation W. Landsman July 2012
Support unsigned 64 bit integers W. Landsman January 2018
(See external/astron/fits/mkhdr.pro)
NAME:
MODFITS
PURPOSE:
Modify a FITS file by updating the header and/or data array.
EXPLANATION:
Update the data and/or header in a specified FITS extension or primary
HDU.
The size of the supplied FITS header or data array does not
need to match the size of the existing header or data array.
CALLING SEQUENCE:
MODFITS, Filename_or_fcb, Data, [ Header, EXTEN_NO =, EXTNAME= , ERRMSG=]
INPUTS:
FILENAME/FCB = Scalar string containing either the name of the FITS file
to be modified, or the IO file control block returned after
opening the file with FITS_OPEN,/UPDATE. The explicit
use of FITS_OPEN can save time if many extensions in a
single file will be updated.
DATA - data array to be inserted into the FITS file. Set DATA = 0
to leave the data portion of the FITS file unmodified. Data
can also be an IDL structure (e.g. as returned by MRDFITS).
provided that it does not include IDL pointers.
HEADER - FITS header (string array) to be updated in the FITS file.
OPTIONAL INPUT KEYWORDS:
A specific extension can be specified with either the EXTNAME or
EXTEN_NO keyword
EXTEN_NO - scalar integer specifying the FITS extension to modified. For
example, specify EXTEN = 1 or /EXTEN to modify the first
FITS extension.
EXTNAME - string name of the extension to modify.
OPTIONAL OUTPUT KEYWORD:
ERRMSG - If this keyword is supplied, then any error mesasges will be
returned to the user in this parameter rather than depending on
on the MESSAGE routine in IDL. If no errors are encountered
then a null string is returned.
EXAMPLES:
(1) Modify the value of the DATE keyword in the primary header of a
file TEST.FITS.
IDL> h = headfits('test.fits') ;Read primary header
IDL> sxaddpar,h,'DATE','2015-03-23' ;Modify value of DATE
IDL> modfits,'test.fits',0,h ;Update header only
(2) Replace the values of the primary image array in 'test.fits' with
their absolute values
IDL> im = readfits('test.fits') ;Read image array
IDL> im = abs(im) ;Take absolute values
IDL> modfits,'test.fits',im ;Update image array
(3) Add some HISTORY records to the FITS header in the first extension
of a file 'test.fits'
IDL> h = headfits('test.fits',/ext) ;Read first extension hdr
IDL> sxaddhist,['Comment 1','Comment 2'],h
IDL> modfits,'test.fits',0,h,/ext ;Update extension hdr
(4) Change 'OBSDATE' keyword to 'OBS-DATE' in every extension in a
FITS file. Explicitly open with FITS_OPEN to save compute time.
fits_open,'test.fits',io,/update ;Faster to explicity open
for i = 1,io.nextend do begin ;Loop over extensions
fits_read,io,0,h,/header_only,exten_no=i,/No_PDU ;Get header
date= sxpar(h,'OBSDATE') ;Save keyword value
sxaddpar,h,'OBS-DATE',date,after='OBSDATE'
sxdelpar,h,'OBSDATE' ;Delete bad keyword
modfits,io,0,h,exten_no=i ;Update header
endfor
Note the use of the /No_PDU keyword in the FITS_READ call -- one
does *not* want to append the primary header, if the STScI
inheritance convention is adopted.
NOTES:
Uses the BLKSHIFT procedure to shift the contents of the FITS file if
the new data or header differs in size by more than 2880 bytes from the
old data or header. If a file control block (FCB) structure is
supplied, then the values of START_HEADER, START_DATA and NBYTES may
be modified if the file size changes.
Also see the procedures FXHMODIFY to add a single FITS keyword to a
header in a FITS files, and FXBGROW to enlarge the size of a binary
table.
RESTRICTIONS:
(1) Cannot be used to modify the data in FITS files with random
groups or variable length binary tables. (The headers in such
files *can* be modified.) Cannot be used to modify individual
columns in binary or ASCII tables.
(2) If a data array but no FITS header is supplied, then MODFITS does
not check to make sure that the existing header is consistent with
the new data.
(3) Does not work with compressed files
(4) The Checksum keywords will not be updated if the array to be
updated is supplied as a structure (e.g. from MRDFITS).
PROCEDURES USED:
Functions: N_BYTES(), SXPAR()
Procedures: BLKSHIFT, CHECK_FITS, FITS_OPEN, FITS_READ. SETDEFAULTVALUE
MODIFICATION HISTORY:
Written, Wayne Landsman December, 1994
Fixed possible problem when using WRITEU after READU October 1997
New and old sizes need only be the same within multiple of 2880 bytes
Added call to IS_IEEE_BIG() W. Landsman May 1999
Added ERRMSG output keyword W. Landsman May 2000
Update tests for incompatible sizes W. Landsman December 2000
Major rewrite to use FITS_OPEN procedures W. Landsman November 2001
Add /No_PDU call to FITS_READ call W. Landsman June 2002
Update CHECKSUM keywords if already present in header, add padding
if new data size is smaller than old W.Landsman December 2002
Only check XTENSION value if EXTEN_NO > 1 W. Landsman Feb. 2003
Correct for unsigned data on little endian machines W. Landsman Apr 2003
Major rewrite to allow changing size of data or header W.L. Aug 2003
Fixed case where updated header exactly fills boundary W.L. Feb 2004
More robust error reporting W.L. Dec 2004
Make sure input header ends with a END W.L. March 2006
Assume since V5.5, remove VMS support, assume FITS_OPEN will
perform byte swapping W.L. Sep 2006
Update FCB structure if file size changes W.L. March 2007
Fix problem when data size must be extended W.L. August 2007
Don't assume supplied FITS header is 80 bytes W. L. Dec 2007
Check for new END position after adding CHECKSUM W.L. July 2008
Added EXTNAME input keyword W.L. July 2008
Allow data to be an IDL structure A. Conley/W.L. June 2009
Use V6.0 notation, add /NOZERO to BLKSHIFT W.L. Feb 2011
Don't try to update Checksums when structure supplied W.L. April 2011
Allow structure with only 1 element W.L. Feb 2012
Don't require that a FITS header is supplied W.L. Feb 2016
Use CATCH rather than ON_IOError, 2 W. L July 2018
Fix when no header supplied W.L. June 2022
(See external/astron/fits/modfits.pro)
NAME:
MRDFITS
PURPOSE:
Read all standard FITS data types into arrays or structures.
EXPLANATION:
Further information on MRDFITS is available at
http://idlastro.gsfc.nasa.gov/mrdfits.html
CALLING SEQUENCE:
Result = MRDFITS( Filename/FileUnit,[Exten_no/Exten_name, Header],
/FPACK, /NO_FPACK, /FSCALE , /DSCALE , /UNSIGNED,
ALIAS=strarr[2,n], /USE_COLNUM,
/NO_TDIM, ROWS = [a,b,...], $
/POINTER_VAR, /FIXED_VAR, EXTNUM=
RANGE=[a,b], COLUMNS=[a,b,...]), ERROR_ACTION=x,
COMPRESS=comp_prog, STATUS=status, /VERSION,
/EMPTYSTRING )
INPUTS:
Filename = String containing the name of the file to be read or
file number of an open unit. If an empty string is supplied,
then user will be prompted for the file name. The user
will also be prompted if a wild card is given in the file
name, and there is more than one file name match.
If the file name ends in .gz or .fz (or .Z on Unix systems)
the file will be dynamically decompressed.
or
FiluUnit = An integer file unit which has already been
opened for input. Data will be read from this
unit and the unit will be left pointing immediately
after the HDU that is read. Thus to read a compressed
file with many HDU's a user might do something like:
lun=fxposit(filename, 3) ; Skip the first three HDU's
repeat begin
thisHDU = mrdfits(lun, 0, hdr, status=status)
... process the HDU ...
endrep until status lt 0
Exten_no= Extension number to be read, 0 for primary array.
Assumed 0 if not specified.
If a unit rather than a filename
is specified in the first argument, this is
the number of HDU's to skip from the current position.
Exten_name - Name of the extension to read (as stored in the EXTNAME
keyword). This is a slightly slower method then specifying
the extension number.
OUTPUTS:
Result = FITS data array or structure constructed from
the designated extension. The format of result depends
upon the type of FITS data read.
Non-group primary array or IMAGE extension:
A simple multidimensional array is returned with the
dimensions given in the NAXISn keywords.
Grouped image data with PCOUNT=0.
As above but with GCOUNT treated as NAXIS(n+1).
Grouped image data with PCOUNT>0.
The data is returned as an array of structures. Each
structure has two elements. The first is a one-dimensional
array of the group parameters, the second is a multidimensional
array as given by the NAXIS2-n keywords.
ASCII and BINARY tables.
The data is returned as a structure with one column for
each field in the table. The names of the columns are
normally taken from the TTYPE keywords (but see USE_COLNUM).
Bit field columns
are stored in byte arrays of the minimum necessary
length. Spaces and invalid characters are replaced by
underscores, and other invalid tag names are converted using
the IDL_VALIDNAME(/CONVERT_ALL) function.
Columns specified as variable length columns are stored
with a dimension equal to the largest actual dimension
used. Extra values in rows are filled with 0's or blanks.
If the size of the variable length column is not
a constant, then an additional column is created giving the
size used in the current row. This additional column will
have a tag name of the form L#_"colname" where # is the column
number and colname is the column name of the variable length
column. If the length of each element of a variable length
column is 0 then the column is deleted.
OPTIONAL OUTPUT:
Header = String array containing the header from the FITS extension.
OPTIONAL INPUT KEYWORDS:
ALIAS The keyword allows the user to specify the column names
to be created when reading FITS data. The value of
this keyword should be a 2xn string array. The first
value of each pair of strings should be the desired
tag name for the IDL column. The second should be
the FITS TTYPE value. Note that there are restrictions
on valid tag names. The order of the ALIAS keyword
is compatible with MWRFITS.
COLUMNS - This keyword allows the user to specify that only a
subset of columns is to be returned. The columns
may be specified either as number 1,... n or by
name or some combination of these two.
If /USE_COLNUM is specified names should be C1,...Cn.
The use of this keyword will not save time or internal
memory since the extraction of specified columns
is done after all columns have been retrieved from the
FITS file. Structure columns are returned in the order
supplied in this keyword.
COMPRESS - This keyword allows the user to specify a
decompression program to use to decompress a file that
will not be automatically recognized based upon
the file name.
/DSCALE - As with FSCALE except that the resulting data is
stored in doubles.
/EMPTYSTRING - There was a bug in memory management for IDL versions
prior to V8.0, causing a memory leak when reading
empty strings in a FITS table. Setting /EMPTYSTRING will
avoid this problem by first reading strings into bytes and
then converting. However, there is a performance penalty.
ERROR_ACTION - Set the on_error action to this value (defaults
to 2).
/FIXED_VAR- Translate variable length columns into fixed length columns
and provide a length column for truly varying columns.
This was the only behavior prior to V2.5 for MRDFITS and remains
the default (see /POINTER_VAR)
/FPACK - If set, then assume the FITS file uses FPACK compression
(http://heasarc.gsfc.nasa.gov/fitsio/fpack/). To read
an FPACK compressed file, either this must be set or the
file name must end in ".fz"
/NO_FPACK - If present, then MRDFITS will not uncompress an extension
compressed with FPACK (i.e with a .fz extension), but will
just read the compressed binary stream.
/FSCALE - If present and non-zero then scale data to float
numbers for arrays and columns which have either
non-zero offset or non-unity scale.
If scaling parameters are applied, then the corresponding
FITS scaling keywords will be modified.
NO_TDIM - Disable processing of TDIM keywords. If NO_TDIM
is specified MRDFITS will ignore TDIM keywords in
binary tables.
/POINTER_VAR- Use pointer arrays for variable length columns.
The pointer tag must be dereferenced in the output structure
to access the variable length column. Prior to IDL V8.0, the user
was responsible for memory management when deleting or reassigning
the structure (e.g. using HEAP_FREE), but memory management of pointer
arrays is now automatic.
RANGE - A scalar or two element vector giving the start
and end rows to be retrieved. For ASCII and BINARY
tables this specifies the row number. For GROUPed data
this will specify the groups. For array images, this
refers to the last non-unity index in the array. E.g.,
for a 3 D image with NAXIS* values = [100,100,1], the
range may be specified as 0:99, since the last axis
is suppressed. Note that the range uses IDL indexing
So that the first row is row 0.
If only a single value, x, is given in the range,
the range is assumed to be [0,x-1].
ROWS - A scalar or vector specifying a specific row or rows to read
(first row is 0). For example to read rows 0,
12 and 23 only, set ROWS=[0,12,23]. Valid for images, ASCII
and binary tables, but not GROUPed data. For images
the row numbers refer to the last non-unity index in the array.
Note that the use of the ROWS will not improve the speed of
MRDFITS since the entire table will be read in, and then subset
to the specified rows. Cannot be used at the same time as
the RANGE keyword
/SILENT - Suppress informative messages.
STRUCTYP - The structyp keyword specifies the name to be used
for the structure defined when reading ASCII or binary
tables. Generally users will not be able to conveniently
combine data from multiple files unless the STRUCTYP
parameter is specified. An error will occur if the
user specifies the same value for the STRUCTYP keyword
in calls to MRDFITS in the same IDL session for extensions
which have different structures.
/UNSIGNED - For integer image data with appropriate zero points and scales,
read the data into unsigned integer arrays. This is the
default for binary tables.
/USE_COLNUM - When creating column names for binary and ASCII tables
MRDFITS attempts to use the appropriate TTYPE keyword
values. If USE_COLNUM is specified and non-zero then
column names will be generated as 'C1, C2, ... 'Cn'
for the number of columns in the table.
/VERSION Print the current version number
OPTIONAL OUTPUT KEYWORDS:
EXTNUM - the number of the extension actually read. Useful if the
user specified the extension by name.
OUTALIAS - This is a 2xn string array where the first column gives the
actual structure tagname, and the second gives the
corresponding FITS keyword name (e.g. in the TTYPE keyword).
This array can be passed directly to
the alias keyword of MWRFITS to recreate the file originally
read by MRDFITS.
STATUS - A integer status indicating success or failure of
the request. A status of >=0 indicates a successful read.
Currently
0 -> successful completion
-1 -> error
-2 -> end of file
EXAMPLES:
(1) Read a FITS primary array:
a = mrdfits('TEST.FITS') or
a = mrdfits('TEST.FITS', 0, header)
The second example also retrieves header information.
(2) Read rows 10-100 of the second extension of a FITS file.
a = mrdfits('TEST.FITS', 2, header, range=[10,100])
(3) Read a table and ask that any scalings be applied and the
scaled data be converted to doubles. Use simple column names,
suppress outputs.
a = mrdfits('TEST.FITS', 1, /dscale, /use_colnum, /silent)
(4) Read rows 3, 34 and 52 of a binary table and request that
variable length columns be stored as a pointer variable in the
output structure
a = mrdfits('TEST.FITS',1,rows=[3,34,52],/POINTER)
RESTRICTIONS:
(1) Cannot handle data in non-standard FITS formats.
(2) Doesn't do anything with BLANK or NULL values or
NaN's. They are just read in. They may be scaled
if scaling is applied.
(3) Does not automatically detect a FPACK compressed file. Either
the file name must end in .fz, or the /FPACK keyword must
be set
NOTES:
This multiple format FITS reader is designed to provide a
single, simple interface to reading all common types of FITS data.
MRDFITS DOES NOT scale data by default. The FSCALE or DSCALE
parameters must be used.
Null values in an FITS ASCII table are converted to NaN (floating data),
or -2147483647L (longwords) or '...' (strings).
PROCEDURES USED:
The following procedures are contained in the main MRDFITS program.
MRD_IMAGE -- Generate array/structure for images.
MRD_READ_IMAGE -- Read image data.
MRD_ASCII -- Generate structure for ASCII tables.
MRD_READ_ASCII -- Read an ASCII table.
MRD_TABLE -- Generate structure for Binary tables.
MRD_READ_TABLE -- Read binary table info.
MRD_READ_HEAP -- Read variable length record info.
MRD_SCALE -- Apply scaling to data.
MRD_COLUMNS -- Extract columns.
Other ASTRON Library routines used
FXPAR(), FXADDPAR, FXPOSIT, FXMOVE(), MATCH, MRD_STRUCT(), MRD_SKIP
MODIfICATION HISTORY:
V1.0 November 9, 1994 ---- Initial release.
Creator: Thomas A. McGlynn
V1.1 January 20, 1995 T.A. McGlynn
Fixed bug in variable length records.
Added TDIM support -- new routine mrd_tdim in MRD_TABLE.
V1.2
Added support for dynamic decompression of files.
Fixed further bugs in variable length record handling.
V1.2a
Added NO_TDIM keyword to turn off TDIM processing for
those who don't want it.
Bug fixes: Handle one row tables correctly, use BZERO rather than
BOFFSET. Fix error in scaling of images.
V1.2b
Changed MRD_HREAD to handle null characters in headers.
V2.0 April 1, 1996
-Handles FITS tables with an arbitrary number of columns.
-Substantial changes to MRD_STRUCT to allow the use of
substructures when more than 127 columns are desired.
-All references to table columns are now made through the
functions MRD_GETC and MRD_PUTC. See description above.
-Use of SILENT will now eliminate compilation messages for
temporary functions.
-Bugs in handling of variable length columns with either
a single row in the table or a maximum of a single element
in the column fixed.
-Added support for DCOMPLEX numbers in binary tables (M formats) for
IDL versions above 4.0.
-Created regression test procedure to check in new versions.
-Added error_action parameter to allow user to specify
on_error action. This should allow better interaction with
new CHECK facility. ON_ERROR statements deleted from
most called routines.
- Modified MRDFITS to read in headers containing null characters
with a warning message printed.
V2.0a April 16, 1996
- Added IS_IEEE_BIG() checks (and routine) so that we don't
worry about IEEE to host conversions if the machine's native
format is IEEE Big-endian.
V2.1 August 24, 1996
- Use resolve_routine for dynamically defined functions
for versions > 4.0
- Fix some processing in random groups format.
- Handle cases where the data segment is--legally--null.
In this case MRDFITS returns a scalar 0.
- Fix bugs with the values for BSCALE and BZERO (and PSCAL and
PZERO) parameters set by MRDFITS.
V2.1a April 24, 1997 Handle binary tables with zero length columns
V2.1b May 13,1997 Remove whitespace from replicate structure definition
V2.1c May 28,1997 Less strict parsing of XTENSION keyword
V2.1d June 16, 1997 Fixed problem for >32767 entries introduced 24-Apr
V2.1e Aug 12, 1997 Fixed problem handling double complex arrays
V2.1f Oct 22, 1997 IDL reserved words can't be structure tag names
V2.1g Nov 24, 1997 Handle XTENSION keywords with extra blanks.
V2.1h Jul 26, 1998 More flexible parsing of TFORM characters
V2.2 Dec 14, 1998 Allow fields with longer names for
later versions of IDL.
Fix handling of arrays in scaling routines.
Allow >128 fields in structures for IDL >4.0
Use more efficient structure copying for
IDL>5.0
V2.2b June 17, 1999 Fix bug in handling case where
all variable length columns are deleted
because they are empty.
V2.3 March 7, 2000 Allow user to supply file handle rather
than file name.
Added status field.
Now needs FXMOVE routine
V2.3b April 4, 2000
Added compress option (from D. Palmer)
V2.4 July 4, 2000 Added STATUS=-1 for "File access error" (Zarro/GSFC)
V2.4a May 2, 2001 Trim binary format string (W. Landsman)
V2.5 December 5, 2001 Add unsigned, alias, 64 bit integers. version, $
/pointer_val, /fixed_var.
V2.5a Fix problem when both the first and the last character
in a TTYPEnn value are invalid structure tag characters
V2.6 February 15, 2002 Fix error in handling unsigned numbers, $
and 64 bit unsigneds. (Thanks to Stephane Beland)
V2.6a September 2, 2002 Fix possible conflicting data structure for
variable length arrays (W. Landsman)
V2.7 July, 2003 Added Rows keyword (W. Landsman)
V2.7a September 2003 Convert dimensions to long64 to handle huge files
V2.8 October 2003 Use IDL_VALIDNAME() function to ensure valid tag names
Removed OLD_STRUCT and TEMPDIR keywords W. Landsman
V2.9 February 2004 Added internal MRD_FXPAR procedure for faster
processing of binary table headers E. Sheldon
V2.9a March 2004 Restore ability to read empty binary table W. Landsman
Swallow binary tables with more columns than given in TFIELDS
V2.9b Fix to ensure order of TFORMn doesn't matter
V2.9c Check if extra degenerate NAXISn keyword are present W.L. Oct 2004
V2.9d Propagate /SILENT to MRD_HREAD, more LONG64 casting W. L. Dec 2004
V2.9e Add typarr[good] to fix a problem reading zero-length columns
A.Csillaghy, csillag@ssl.berkeley.edu (RHESSI)
V2.9f Fix problem with string variable binary tables, possible math
overflow on non-IEEE machines WL Feb. 2005
V2.9g Fix problem when setting /USE_COLNUM WL Feb. 2005
V2.10 Use faster keywords to BYTEORDER WL May 2006
V2.11 Add ON_IOERROR, CATCH, and STATUS keyword to MRD_READ_IMAGE to
trap EOF in compressed files DZ Also fix handling of unsigned
images when BSCALE not present K Chu/WL June 2006
V2.12 Allow extension to be specified by name, added EXTNUM keyword
WL December 2006
V2.12a Convert ASCII table column to DOUBLE if single precision is
insufficient
V2.12b Fixed problem when both /fscale and /unsigned are set
C. Markwardt Aug 2007
V2.13 Use SWAP_ENDIAN_INPLACE instead of IEEE_TO_HOST and IS_IEEE_BIG
W. Landsman Nov 2007
V2.13a One element vector allowed for file name W.L. Dec 2007
V2.13b More informative error message when EOF found W.L. Jun 2008
V2.14 Use vector form of VALID_NUM(), added OUTALIAS keyword
W.L. Aug 2008
V2.15 Use new FXPOSIT which uses on-the-fly byteswapping W.L. Mar 2009
V2.15a Small efficiency updates to MRD_SCALE W.L. Apr 2009
V2.15b Fixed typo introduced Apr 2009
V2.15c Fix bug introduced Mar 2009 when file unit used W.L. July 2009
V2.16 Handle FPACK compressed files W. L. July 2009
V2.17 Use compile_opt hidden on all routines except mrdfits.pro W.L. July 2009
V2.18 Added /EMPTYSTRING keyword W. Landsman August 2009
V2.18a Fix Columns keyword output, A. Kimball/ W. Landsman Feb 2010
V2.18b Fix bug with /EMPTYSTRING and multidimensional strings
S. Baldridge/W.L. August 2010
V2.18c Fix unsigned bug caused by compile_opt idl2 WL Nov 2010
V2.19 Use V6.0 operators WL Nov 2010
V2.19a Fix complex data conversion in variable length tables WL Dec 2010
V2.19b Fix bug with /FSCALE introduced Nov 2010 WL Jan 2011
V2.19c Fix bug with ROWS keyword introduced Nov 2010 WL Mar 2011
V2.20 Convert Nulls in ASCII tables, better check of duplicate keywords
WL May 2011
V2.20a Better error checking for FPACK files WL October 2012
V2.20b Fix bug in MRD_SCALE introduced Nov 2010 (Sigh) WL Feb 2013
V2.21 Create unique structure tags when FITS column names differ
only in having a different case R. McMahon/WL March 2013
V2.22 Handle 64 bit variable length binary tables WL April 2014
V2.23 Use 64 bit for very large files WL April 2014
V2.24 Binary table is allowed to have zero columns WL September 2018
V2.25 Use long64 for ASCII table integers longer than I12 WL October 2020
V2.26 Use '8000000000000000'xll long64 offset for GDL/FL compatibility WL Aug 2021
V2.27 Allow different columns to have different datatypes for TSCALn and TZEROn
Use ULONG64() when necessary WL Sep 2021
(See external/astron/fits/mrdfits.pro)
NAME:
MRD_HREAD
PURPOSE:
Reads a FITS header from an opened disk file or Unix pipe
EXPLANATION:
Like FXHREAD but also works with compressed Unix files
CALLING SEQUENCE:
MRD_HREAD, UNIT, HEADER [, STATUS, /SILENT, ERRMSG =, /FIRSTBLOCK ]
INPUTS:
UNIT = Logical unit number of an open FITS file
OUTPUTS:
HEADER = String array containing the FITS header.
OPT. OUTPUTS:
STATUS = Condition code giving the status of the read. Normally, this
is zero, but is set to -1 if an error occurs, or if the
first byte of the header is zero (ASCII null).
OPTIONAL KEYWORD INPUT:
/FIRSTBLOCK - If set, then only the first block (36 lines or less) of
the FITS header are read into the output variable. If only
size information (e.g. BITPIX, NAXIS) is needed from the
header, then the use of this keyword can save time. The
file pointer is still positioned at the end of the header,
even if the /FIRSTBLOCK keyword is supplied.
/SILENT - If set, then warning messages about any invalid characters in
the header are suppressed.
/SKIPDATA - If set, then the file point is positioned at the end of the
HDU after the header is read, i.e. the following data block
is skipped. Useful, when one wants to the read the headers
of multiple extensions.
/NO_BADHEADER - if set, returns if FITS header has illegal characters
By default, MRD_HREAD replaces bad characters with blanks,
issues a warning, and continues.
OPTIONAL OUTPUT PARAMETER:
ERRMSG = If this keyword is present, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned.
RESTRICTIONS:
The file must already be positioned at the start of the header. It
must be a proper FITS file.
SIDE EFFECTS:
The file ends by being positioned at the end of the FITS header, unless
an error occurs.
REVISION HISTORY:
Written, Thomas McGlynn August 1995
Modified, Thomas McGlynn January 1996
Changed MRD_HREAD to handle Headers which have null characters
A warning message is printed out but the program continues.
Previously MRD_HREAD would fail if the null characters were
not in the last 2880 byte block of the header. Note that
such characters are illegal in the header but frequently
are produced by poor FITS writers.
Added /SILENT keyword W. Landsman December 2000
Added /FIRSTBLOCK keyword W. Landsman February 2003
Added ERRMSG, SKIPDATA keyword W. Landsman April 2009
Close file unit even after error message W.L. October 2010
Added /NO_BADHEADER Zarro (ADNET), January 2012
(See external/astron/fits/mrd_hread.pro)
NAME:
MWRFITS
PURPOSE:
Write all standard FITS data types from input arrays or structures.
EXPLANATION:
Must be used with a post-September 2009 version of FXADDPAR.
CALLING SEQUENCE:
MWRFITS, Input, Filename, [Header],
/LSCALE , /ISCALE, /BSCALE,
/USE_COLNUM, /Silent, /Create, /No_comment, /Version, $
Alias=, /ASCII, Separator=, Terminator=, Null=,
/Logical_cols, /Bit_cols, /Nbit_cols,
Group=, Pscale=, Pzero=, Status=
INPUTS:
Input = Array or structure to be written to FITS file.
-When writing FITS primary data or image extensions
input should be an array.
--If data is to be grouped
the Group keyword should be specified to point to
a two dimensional array. The first dimension of the
Group array will be PCOUNT while the second dimension
should be the same as the last dimension of Input.
--If Input is undefined, then a dummy primary dataset
or Image extension is created [This might be done, e.g.,
to put appropriate keywords in a dummy primary
HDU].
-When writing an ASCII table extension, Input should
be a structure array where no element of the structure
is a structure or array (except see below).
--A byte array will *not* be written as A field. This
limitation is because the byte array to string conversion
will not work with a FORMAT statement. Please convert
byte arrays to strings before calling MWRFITS
--Complex numbers are written to two columns with '_R' and
'_I' appended to the TTYPE fields (if present). The
complex number is enclosed in square brackets in the output.
--Strings are written to fields with the length adjusted
to accommodate the largest string. Shorter strings are
blank padded to the right.
-When writing a binary table extension, the input should
be a structure array with no element of the structure
being a substructure.
If a structure is specified on input and the output
file does not exist or the /CREATE keyword is specified
a dummy primary HDU is created.
Filename = String containing the name of the file to be written.
By default MWRFITS appends a new extension to existing
files which are assumed to be valid FITS. The /CREATE
keyword can be used to ensure that a new FITS file
is created even if the file already exists.
OUTPUTS:
OPTIONAL INPUTS:
Header = Header should be a string array. Each element of the
array is added as a row in the FITS header. No
parsing is done of this data. MWRFITS will prepend
required structural (and, if specified, scaling)
keywords before the rows specified in Header.
Rows describing columns in the table will be appended
to the contents of Header.
Header lines will be extended or truncated to
80 characters as necessary.
If Header is specified then on return Header will have
the header generated for the specified extension.
OPTIONAL INPUT KEYWORDS:
ALias= Set up aliases to convert from the IDL structure
to the FITS column name. The value should be
a STRARR(2,*) value where the first element of
each pair of values corresponds to a column
in the structure and the second is the name
to be used in the FITS file.
The order of the alias keyword is compatible with
use in MRDFITS.
ASCII - Creates an ASCII table rather than a binary table.
This keyword may be specified as:
/ASCII - Use default formats for columns.
ASCII='format_string' allows the user to specify
the format of various data types such using the following
syntax 'column_type:format, column_type:format'. E.g.,
ASCII='A:A1,I:I6,L:I10,B:I4,F:G15.9,D:G23.17,C:G15.9,M:G23.17'
gives the default formats used for each type. The TFORM
fields for the real and complex types indicate will use corresponding
E and D formats when a G format is specified.
Note that the length of the field for ASCII strings and
byte arrays is automatically determined for each column.
BIT_COLS= An array of indices of the bit columns. The data should
comprise a byte array with the appropriate dimensions.
If the number of bits per row (see NBIT_COLS)
is greater than 8, then the first dimension of the array
should match the number of input bytes per row.
BSCALE Scale floats, longs, or shorts to unsigned bytes (see LSCALE)
/CREATE If this keyword is non-zero, then a new FITS file will
be created regardless of whether the file currently
exists. Otherwise when the file already exists,
a FITS extension will be appended to the existing file
which is assumed to be a valid FITS file.
GROUP= This keyword indicates that GROUPed FITS data is to
be generated.
Group should be a 2-D array of the appropriate output type.
The first dimension will set the number of group parameters.
The second dimension must agree with the last dimension
of the Input array.
ISCALE Scale floats or longs to short integer (see LSCALE)
LOGICAL_COLS= An array of indices of the logical column numbers.
These should start with the first column having index *1*.
The structure element should either be an array of characters
with the values 'T' or 'F', or an array of bytes having the
values byte('T')=84b, byte('F')=70b or 0b. The use of bytes
allows the specification of undefined values (0b).
LSCALE Scale floating point numbers to long integers.
This keyword may be specified in three ways.
/LSCALE (or LSCALE=1) asks for scaling to be automatically
determined. LSCALE=value divides the input by value.
I.e., BSCALE=value, BZERO=0. Numbers out of range are
given the value of NULL if specified, otherwise they are given
the appropriate extremum value. LSCALE=(value,value)
uses the first value as BSCALE and the second as BZERO
(or TSCALE and TZERO for tables).
NBIT_COLS= The number of bits actually used in the bit array.
This argument must point to an array of the same dimension
as BIT_COLS.
/NO_COPY = By default, MWRFITS makes a copy of the input variable
before any modifications necessary to write it to a FITS
file. If you have a large array/structure, and don't
require it for subsequent processing, then /NO_COPY will
save memory.
NO_TYPES If the NO_TYPES keyword is specified, then no TTYPE
keywords will be created for ASCII and BINARY tables.
No_comment Do not write comment keywords in the header
NULL= Value to be written for integers/strings which are
undefined or unwritable.
PSCALE= An array giving scaling parameters for the group keywords.
It should have the same dimension as the first dimension
of Group.
PZERO= An array giving offset parameters for the group keywords.
It should have the same dimension as the first dimension
of Group.
Separator= This keyword can be specified as a string which will
be used to separate fields in ASCII tables. By default
fields are separated by a blank.
/SILENT Suppress informative messages. Errors will still
be reported.
Terminator= This keyword can be specified to provide a string which
will be placed at the end of each row of an ASCII table.
No terminator is used when not specified.
If a non-string terminator is specified (including
when the /terminator form is used), a new line terminator
is appended.
USE_COLNUM When creating column names for binary and ASCII tables
MWRFITS attempts to use structure field name
values. If USE_COLNUM is specified and non-zero then
column names will be generated as 'C1, C2, ... 'Cn'
for the number of columns in the table.
Version Print the version number of MWRFITS.
OPTIONAL OUTPUT KEYWORD:
Status - 0 if FITS file is successfully written, -1 if there is a
a problem (e.g. nonexistent directory, or no write permission)
EXAMPLE:
Write a simple array:
a=fltarr(20,20)
mwrfits,a,'test.fits'
Append a 3 column, 2 row, binary table extension to file just created.
a={name:'M31', coords:(30., 20.), distance:2}
a=replicate(a, 2);
mwrfits,a,'test.fits'
Now append an image extension:
a=lonarr(10,10,10)
mkhdr,hdr,a,/image ;Create minimal image extension FITS header
sxaddhist,["This is a comment line to put in the header", $
"And another comment"],hdr,/comment
mwrfits,a,'test.fits',hdr
RESTRICTIONS:
(1) Variable length columns are not supported for anything
other than simple types (byte, int, long, float, double).
(2) Empty strings are converted to 1 element blank strings (because
IDL refuses to write an empty string (0b) from a structure)
NOTES:
This multiple format FITS writer is designed to provide a
single, simple interface to writing all common types of FITS data.
Given the number of options within the program and the
variety of IDL systems available it is likely that a number
of bugs are yet to be uncovered.
PROCEDURES USED:
FXPAR(), FXADDPAR
MODIfICATION HISTORY:
Version 0.9: By T. McGlynn 1997-07-23
Initial beta release.
Dec 1, 1997, Lindler, Modified to work under VMS.
Version 0.91: T. McGlynn 1998-03-09
Fixed problem in handling null primary arrays.
Version 0.92: T. McGlynn 1998-09-09
Add no_comment flag and keep user comments on fields.
Fix handling of bit fields.
Version 0.93: T. McGlynn 1999-03-10
Fix table appends on VMS.
Version 0.93a W. Landsman/D. Schlegel
Update keyword values in chk_and_upd if data type has changed
Version 0.94: T. McGlynn 2000-02-02
Efficient processing of ASCII tables.
Use G rather than E formats as defaults for ASCII tables
and make the default precision long enough that transformations
binary to/from ASCII are invertible.
Some loop indices made long.
Fixed some ends to match block beginnings.
Version 0.95: T. McGlynn 2000-11-06
Several fixes to scaling. Thanks to David Sahnow for
documenting the problems.
Added PCOUNT,GCOUNT keywords to Image extensions.
Version numbers shown in SIMPLE/XTENSION comments
Version 0.96: T. McGlynn 2001-04-06
Changed how files are opened to handle ~ consistently
Version 1.0: T. McGlynn 2001-12-04
Unsigned integers,
64 bit integers.
Aliases
Variable length arrays
Some code cleanup
Version 1.1: T. McGlynn 2002-2-18
Fixed major bug in processing of unsigned integers.
(Thanks to Stephane Beland)
Version 1.2: Stephane Beland 2003-03-17
Fixed problem in creating dummy dataset when passing undefined
data, caused by an update to FXADDPAR routine.
Version 1.2.1 Stephane Beland 2003-09-10
Exit gracefully if write privileges unavailable
Version 1.3 Wayne Landsman 2003-10-24
Don't use EXECUTE() statement if on a virtual machine
Version 1.3a Wayne Landsman 2004-5-21
Fix for variable type arrays
Version 1.4 Wayne Landsman 2004-07-16
Use STRUCT_ASSIGN when modifying structure with pointer tags
Version 1.4a Wayne Landsman 2005-01-03
Fix writing of empty strings in binary tables
Version 1.4b Wayne Landsman 2006-02-23
Propagate /SILENT keyword to mwr_tablehdr
Version 1.5 Wayne Landsman 2006-05-24
Open file using /SWAP_IF_LITTLE_ENDIAN keyword
Convert empty strings to 1 element blank strings before writing
Version 1.5a Wayne Landsman 2006-06-29
Fix problem introduced 2006-05-24 with multidimensional strings
Version 1.5b K. Tolbert 2006-06-29
Make V1.5a fix work pre-V6.0
Version 1.5c I.Evans/W.Landsman 2006-08-08
Allow logical columns to be specified as bytes
Version 1,5d K. Tolbert 2006-08-11
Make V1.5a fix work for scalar empty string
Version 1.6 W. Landsman 2006-09-22
Assume since V5.5, remove VMS support
Version 1.6a W. Landsman 2006-09-22
Don't right-justify strings
Version 1.7 W. Landsman 2009-01-12
Added STATUS output keyword
Version 1.7a W. Landsman 2009-04-10
Since V6.4 strings are no longer limited to 1024
elements
Version 1.8 Pierre Chanial 2009-06-23
trim alias, implement logical TFORM 'L', don't
add space after tform key.
Version 1.9 W. Landsman 2009-07-20
Suppress compilation messages of supporting routines
Version 1.10 W. Landsman 2009-09-30
Allow TTYPE values of 'T' and 'F', fix USE_COLNUM for bin tables
Version 1.11 W. Landsman 2010-11-18
Allow LONG64 number of bytes, use V6.0 notation
Version 1.11a W. Landsman 2012-08-12
Better documentation, error checking for logical columns
Version 1.11b M. Haffner/W.L. 2012-10-12
Added /No_COPY keyword, fix problem with 32 bit overflow
Version 1.12 W. Landsman 2014-04-23
Version 1.12a W.Landsman/M. Fossati 2014-10-14
Fix LONG overflow for very large files
Version 1.12b I. Evans 2015-07-27
Fix value check for byte('T'), byte('F'), or 0b for logical
columns with null values
Version 1.13 W. Landsman 2016-02-24
Abort if a structure supplied with more than 999 tags
Version 1.13a W.Landsman 2019-06-03
Don't pad ASCII tables with 2880 byte blocks, instead set to zero
Version 1.14 W. Landsman 2019-7-24
Document that MWRFITS can't handle byte arrays in ASCII tables correctly
(See external/astron/fits/mwrfits.pro)
NAME:
RDFITS_STRUCT
PURPOSE:
Read an entire FITS file (all extensions) into a single IDL structure.
EXPLANATION:
Each header, image or table array is placed in a separate structure
tag.
CALLING SEQUENCE:
RDFITS_STRUCT, filename, struct, /SILENT, /HEADER_ONLY, EXTEN= ]
INPUT:
FILENAME = Scalar string giving the name of the FITS file.
One can also specify a gzip (.gz) compressed file
OPTIONAL KEYWORD:
/HEADER_ONLY - If set, then only the FITS headers (and not the data)
are read into the structure.
/SILENT - Set this keyword to suppress informational displays at the
terminal.
OUTPUT:
struct = structure into which FITS data is read. The primary header
and image are placed into tag names HDR0 and IM0. The ith
extension is placed into the tag names HDRi, and either TABi
(if it is a binary or ASCII table) or IMi (if it is an image
extension)
If /HEADER_ONLY is set, then struct will contain tags HDR0, HDR1
....HDRn containing all the headers of a FITS file with n
extensions
OPTIONAL INPUT KEYWORD:
EXTEN - positive integer array specifying which extensions to read.
Default is to read all extensions.
PROCEDURES USED:
FITS_OPEN, FITS_READ, FITS_CLOSE
METHOD:
The file is opened with FITS_OPEN which return information on the
number and type of each extension. The CREATE_STRUCT() function
is used iteratively, with FITS_READ calls to build the final structure.
EXAMPLE:
Read the FITS file 'm33.fits' into an IDL structure, st
IDL> rdfits_struct, 'm33.fits', st
IDL> help, /str, st ;Display info about the structure
To just read the second and fourth extensions
IDL> rdfits_struct, 'm33.fits', st, exten=[2,4]
RESTRICTIONS:
Does not handle random groups or variable length binary tables
MODIFICATION HISTORY:
Written K. Venkatakrishna, STX April 1992
Code cleaned up a bit W. Landsman STX October 92
Modified for MacOS I. Freedman HSTX April 1994
Work under Windows 95 W. Landsman HSTX January 1996
Use anonymous structures, skip extensions without data WBL April 1998
Converted to IDL V5.0, W. Landsman, April 1998
OS-independent deletion of temporary file W. Landsman Jan 1999
Major rewrite to use FITS_OPEN and CREATE_STRUCT() W. Landsman Sep 2002
Added /HEADER_ONLY keyword W. Landsman October 2003
Do not copy primary header into extension headers W. Landsman Dec 2004
Do not modify NAXIS when using /HEADER_ONLY W. Landsman Jan 2005
Added EXTEN keyword W. Landsman July 2009
(See external/astron/fits/rdfits_struct.pro)
NAME:
READFITS
PURPOSE:
Read a FITS file into IDL data and header variables.
EXPLANATION:
READFITS() can read FITS files compressed with gzip (.gz), Unix (.Z)
or BZip (.bz2) 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 ]
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.
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. BZip compressed files must have a .bz2
extension.
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
Fix problem passing extensions with > 2GB WL, M. Carlson August 2013
Always read entire header, even if header variable not supplied W. Landsman May 2017
Support BZip compression W. Landsman Aug 2017
Support unsigned long64 data W. Landsman Jan 2018
(See external/astron/fits/readfits.pro)
NAME:
SXADDHIST
PURPOSE:
Procedure to add HISTORY (or COMMENT) line(s) to a FITS header
EXPLANATION:
The advantage of using SXADDHIST instead of SXADDPAR is that with
SXADDHIST many HISTORY or COMMENT records can be added in a single call.
CALLING SEQUENCE
sxaddhist, history, header, [ /PDU, /COMMENT ]
INPUTS:
history - string or string array containing history or comment line(s)
to add to the FITS header
INPUT/OUTPUT
header - FITS header (string array). Upon output, it will contain the
specified HISTORY records added to the end
OPTIONAL KEYWORD INPUTS:
/BLANK - If specified then blank (' ') keywords will be written
rather than 'HISTORY ' keywords.
/COMMENT - If specified, then 'COMMENT ' keyword will be written rather
than 'HISTORY ' keywords.
Note that according to the FITS definition, any number of
'COMMENT' and 'HISTORY' or blank keywords may appear in a header,
whereas all other keywords may appear only once.
LOCATION=key - If present, the history will be added before this
keyword. Otherwise put it at the end.
/PDU - if specified, the history will be added to the primary
data unit header, (before the line beginning BEGIN EXTENSION...)
Otherwise, it will be added to the end of the header.
This has meaning only for extension headers using the STScI
inheritance convention.
OUTPUTS:
header - updated FITS header
EXAMPLES:
sxaddhist, 'I DID THIS', header ;Add one history record
hist = strarr(3)
hist[0] = 'history line number 1'
hist[1[ = 'the next history line'
hist[2] = 'the last history line'
sxaddhist, hist, header ;Add three history records
SIDE EFFECTS:
Header array is truncated to the final END statement
LOCATION overrides PDU.
HISTORY:
D. Lindler Feb. 87
April 90 Converted to new idl D. Lindler
Put only a single space after HISTORY W. Landsman November 1992
Aug. 95 Added PDU keyword parameters
LOCATION added. M. Greason, 28 September 2004.
Missing minus sign (1 -> -1) in testing for WHERE output when
looking for location to insert a comment M. Haffner Oct 2012
(See external/astron/fits/sxaddhist.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
/SAVECOMMENT, Missing=, /Null
INPUTS:
Header = String array containing FITS 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.
/NULL = If set, then keywords with values which are undefined, or
which have non-finite values (such as NaN, Not-a-Number) are
stored in the header without a value, such as
MYKEYWD = /My comment
MISSING = A value which signals that data with this value should be
considered missing. For example, the statement
FXADDPAR, HEADER, 'MYKEYWD', -999, MISSING=-999
would result in the valueless line described above for the
/NULL keyword. Setting MISSING to a value implies /NULL.
Cannot be used with string or complex values.
/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
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 occurrence
of an existing keyword (the one SXPAR reads) instead of the
first occurrence.
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
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.
Aug 2013 Only use keyword_set for binary keywords W. L.
Sep 2015 Added NULL and MISSING keywords W.L.
Sep 2016 Allow writing of byte or Boolean variables W.L.
Nov 2016 Allow value to be a 1 element scalar W.L.
Jun 2018 W. Thompson, for backward compatibility, save non-finite
values (e.g. NaN) as strings if /NULL not set
(See external/astron/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 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 external/astron/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,
DUP=, /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.
The default string is 'FITS Header' if abort is a integer or
single character. If ABORT is not supplied, SXPAR will return
quietly with COUNT = 0 if a keyword is not found.
OPTIONAL INPUT KEYWORDS:
DUP = When the FITS keyword exists more than once in a header, set
DUP to a positive integer to specify which value is to be
read. For example, set DUP = 2 to read the value of the
second appearance of a keyword in the header. If DUP is not
supplied, then by default, SXPAR() reads the *last* appearance and
issues a warning.
MISSING = By default, this routine returns 0 when keyword values are
not found. This can be overridden by using the MISSING
keyword, e.g. MISSING=-1.
/NAN = If set, then return Not-a-Number (!values.f_nan) for missing
values. Ignored if keyword MISSING is present.
/NOCONTINUE = If set, then continuation lines will not be read, even
if present in the header
/NULL = If set, then return !NULL (undefined) for missing values.
Ignored if MISSING or /NAN is present, or if earlier than IDL
version 8.0. If multiple values would be returned, then
MISSING= or /NAN should be used instead of /NULL, making sure
that the datatype is consistent with the non-missing values,
e.g. MISSING='' for strings, MISSING=-1 for integers, or
MISSING=-1.0 or /NAN for floating point. /NAN should not be
used if the datatype would otherwise be integer.
/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
IFOUND - Array of found keyword indicies when Name is of the form keyword*
For example, one searches for 'TUNIT*' and the FITS header contains
TUNIT1, TUNIT2, TUNIT4, and TUNIT6 then IFOUND woud be returned as
[1,2,4,6]. Set to zero if Name is not of the form keyword*.
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 !ERR 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, and the DUP keyword is not supplied, then a warning is given,
and the *last* occurrence 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 has a decimal point, and contains more than 8 numerals, or
contains the character 'D', 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 LONG64.
If the value is too long for one line, it may be continued on to the
the next input card, using the 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.
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 functions, but
both are too widely used to drop either one.
PROCEDURES CALLED:
cgErrorMsg(), 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
W. Landsman Apr 2014 Don't convert Long64 numbers to double
W. Landsman Nov 2014 Use cgErrorMsg rather than On_error,2
W. Landsman Dec 2014 Return Logical as IDL Boolean in IDL 8.4 or later
W. Landsman May 2015 Added IFound output keyword
J. Slavin Aug 2015 Allow for 72 character par values (fixed from 71)
W. Landsman Sep 2015 Added Missing, /NULL and /NaN keywords
W. Landsman Oct 2017 Added DUP keyword, Needed to support distortion
table lookup parameters
W. Landsman Jan 2018 Return ULONG64 integer if LONG64 will overflow
W. Landsman/Y. Yang May 2018 MISSING keyword was always returning 0
W. Landsman/M. Knight Aug 2018 Clean up use of Abort parameter
(See external/astron/fits/sxpar.pro)
NAME:
WRITEFITS
PURPOSE:
Write IDL array and header variables to a disk FITS file.
EXPLANATION:
A minimal FITS header is created if not supplied.
WRITEFITS works for all types of FITS files except random groups
CALLING SEQUENCE:
WRITEFITS, filename, data [, header, /APPEND, /COMPRESS, /CHECKSUM]
INPUTS:
FILENAME = String containing the name of the file to be written.
DATA = Image array to be written to FITS file. If DATA is
undefined or a scalar, then only the FITS header (which
must have NAXIS = 0) will be written to disk
OPTIONAL INPUT:
HEADER = String array containing the header for the FITS file.
If variable HEADER is not given, the program will generate
a minimal FITS header.
HEAP - A byte array giving the heap area following, e.g. a variable
length binary table
OPTIONAL INPUT KEYWORD:
/APPEND - If this keyword is set then the supplied header and data
array are assumed to be an extension and are appended onto
the end of an existing FITS file. If the file does not
exist, then WRITEFITS will create one with a minimal primary
header (and /EXTEND keyword) and then append the supplied
extension header and array. Note that the primary
header in an existing file must already have an EXTEND
keyword to indicate the presence of an FITS extension.
/COMPRESS - If this keyword is set, then the FITS file is written as
a gzip compressed file. An extension '.gz' is appended to
to the file name if it does not already exist. The /COMPRESS
option is incompatible with the /APPEND option.
/Checksum - If set, then the CHECKSUM keywords to monitor data integrity
will be included in the FITS header. For more info, see
http://fits.gsfc.nasa.gov/registry/checksum.html
By default, checksum keywords will updated if they are already
in the FITS header.
NaNvalue - Value in the data array which represents missing pixels.
This keyword should only used when missing pixels are not
represented by NaN values in the input array.
OUTPUTS:
None
RESTRICTIONS:
(1) It recommended that BSCALE and BZERO not be used (or set equal
to 1. and 0) except with integer data
(2) WRITEFITS will remove any group parameters from the FITS header
(3) As of Feb 2008, WRITEFITS no longer requires the primary header of a
FITS file with extensions to contain the EXTEND keyword, consistent
with Section 4.4.2.1 of the FITS 3.0 standard. A warning is still
given. See http://fits.gsfc.nasa.gov/fits_standard.html
EXAMPLE:
Write a randomn 50 x 50 array as a FITS file creating a minimal header.
IDL> im = randomn(seed, 50, 50) ;Create array
IDL> writefits, 'test', im ;Write to a FITS file "test"
PROCEDURES USED:
CHECK_FITS, FITS_ADD_CHECKSUM, MKHDR, MRD_HREAD, SXDELPAR, SXADDPAR,
SXPAR()
MODIFICATION HISTORY:
WRITTEN, Jim Wofford, January, 29 1989
Added call to IS_IEEE_BIG() W. Landsman Apr 96
Make sure SIMPLE is written in first line of header W. Landsman Jun 97
Use SYSTIME() instead of !STIME W. Landsman July 97
Create a default image extension header if needed W. Landsman June 98
Write unsigned data types W. Landsman December 1999
Update for IDL V5.3, add /COMPRESS keyword W. Landsman February 2000
Correct BZERO value for unsigned data W. Landsman July 2000
Eliminate duplication of input array if possible W. Landsman April 2001
Use FILE_SEARCH for V5.5 or later W. Landsman April 2002
Create the file if not already present and /APPEND is set
W. Landsman September 2002
Proper call to MRD_HREAD if /APPEND is set W. Landsman December 2002
Added /CHECKSUM keyword W. Landsman December 2002
Restored NANvalue keyword, William Thompson, October 2003
Write BZERO in beginning of header for unsigned integers WL April 2004
Added ability to write heap array WL October 2004
Correct checksum if writing heap array WL November 2004
Assume since V5.5, no VMS support, use file_search() WL September 2006
Set nbytes variable to LONG64 for very large files WL May 2007
Update CHECKSUM keywords if already present WL Oct 2007
EXTEND keyword no longer required in FITS files with extensions WL Feb 2008
Bug fix when filename ends with '.gz' and COMPRESS is used,
the output file must be compressed S. Koposov June 2008
Introduce V6.0 notation W.L. Nov. 2010
Set /APPEND if XTENSION specifies a table W.L. July 2012
Bug fix when /CHECKSUM used with unsigned data W.L. June 2013
June 2013 bug fix introduced problem when NAXIS=0 W.L. July 2013
Added /Silent keyword W.L. April 2016
Support unsigned 64 bit data type W.L. January 2018
Fix case of header with no data and checksum W.L. August 2018
(See external/astron/fits/writefits.pro)