MODFITS
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','2001-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,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.)
(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
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