WRITEFITS
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://heasarc.gsfc.nasa.gov/docs/heasarc/fits/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 extension 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