Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Libraries  >  ASTROLIB  >  MODFITS

MODFITS

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



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us