# UPDATEHDR: Functions for Updating WCS with New Solutions

The functions in this module support updating the WCS information in distorted images with the alignment solution determined by `tweakreg` or saved in a shiftfile.

Authors: | Warren Hack, Mihai Cara
License: | http://www.stsci.edu/resources/software_hardware/pyraf/LICENSE

`drizzlepac.updatehdr.``create_unique_wcsname`(fimg, extnum, wcsname)

  This function evaluates whether the specified wcsname value has already been used in this image. If so, it automatically modifies the name with a simple version ID using wcsname_NNN format.

  Parameters:

  fimg : obj

  > PyFITS object of image with WCS information to be updated

  extnum : int

  > Index of extension with WCS information to be updated

  wcsname : str

  > Value of WCSNAME specified by user for labelling the new WCS

  Returns:

  uniqname : str

  > Unique WCSNAME value

`drizzlepac.updatehdr.``update_from_shiftfile`(shiftfile, wcsname=None, force=False)

  Update headers of all images specified in shiftfile with shifts from shiftfile.

  Parameters:

  shiftfile : str

  > Filename of shiftfile.

  wcsname : str

  > Label to give to new WCS solution being created by this fit. If a value of None is given, it will automatically use ‘TWEAK’ as the label. [Default =None]

  force : bool

  > Update header even though WCS already exists with this solution or wcsname? [Default=False]

`drizzlepac.updatehdr.``update_wcs`(image, extnum, new_wcs, wcsname='', reusename=False, verbose=False)

  Updates the WCS of the specified extension number with the new WCS after archiving the original WCS.

  The value of ‘new_wcs’ needs to be the full HSTWCS object.

  Parameters:

  image : str

  > Filename of image with WCS that needs to be updated

  extnum : int

  > Extension number for extension with WCS to be updated/replaced

  new_wcs : object

  > Full HSTWCS object which will replace/update the existing WCS

  wcsname : str

  > Label to give newly updated WCS

  reusename : bool

  > User can choose whether to over-write WCS with same name or not. [Default: False]

  verbose : bool, int

  > Print extra messages during processing? [Default: False]

`drizzlepac.updatehdr.``updatewcs_with_shift`(image, reference, wcsname=None, reusename=False, fitgeom='rscale', rot=0.0, scale=1.0, xsh=0.0, ysh=0.0, fit=None, xrms=None, yrms=None, verbose=False, force=False, sciext='SCI')

  Update the SCI headers in ‘image’ based on the fit provided as determined in the WCS specified by ‘reference’. The fit should be a 2-D matrix as generated for use with ‘make_vector_plot()’.

  Parameters:

  image : str or PyFITS.HDUList object

  > Filename, or PyFITS object, of image with WCS to be updated. All extensions with EXTNAME matches the value of the ‘sciext’ parameter value (by default, all ‘SCI’ extensions) will be updated.

  reference : str

  > Filename of image/headerlet (FITS file) which contains the WCS used to define the tangent plane in which all the fit parameters (shift, rot, scale) were measured.

  wcsname : str

  > Label to give to new WCS solution being created by this fit. If a value of None is given, it will automatically use ‘TWEAK’ as the label. If a WCS has a name with this specific value, the code will automatically append a version ID using the format ‘_n’, such as ‘TWEAK_1’, ‘TWEAK_2’,or ‘TWEAK_update_1’. [Default =None]

  reusename : bool

  > User can specify whether or not to over-write WCS with same name. [Default: False]

  rot : float

  > Amount of rotation measured in fit to be applied. [Default=0.0]

  scale : float

  > Amount of scale change measured in fit to be applied. [Default=1.0]

  xsh : float

  > Offset in X pixels from defined tangent plane to be applied to image. [Default=0.0]

  ysh : float

  > Offset in Y pixels from defined tangent plane to be applied to image. [Default=0.0]

  fit : arr

  > Linear coefficients for fit [Default = None]

  xrms : float

  > RMS of fit in RA (in decimal degrees) that will be recorded as CRDER1 in WCS and header [Default = None]

  yrms : float

  > RMS of fit in Dec (in decimal degrees) that will be recorded as CRDER2 in WCS and header [Default = None]

  verbose : bool

  > Print extra messages during processing? [Default=False]

  force : bool

  > Update header even though WCS already exists with this solution or wcsname? [Default=False]

  sciext : string

  > Value of FITS EXTNAME keyword for extensions with WCS headers to be updated with the fit values. [Default=’SCI’]

  Notes

  The algorithm used to apply the provided fit solution to the image involves applying the following steps to the WCS of each of the input image’s chips:

  1. compute RA/Dec with full distortion correction for
       reference point as (Rc_i,Dc_i)
  2. find the Xc,Yc for each Rc_i,Dc_i and get the difference from the
       CRPIX position for the reference WCS as (dXc_i,dYc_i)
  3. apply fit (rot&scale) to (dXc_i,dYc_i) then apply shift, then add
       CRPIX back to get new (Xcs_i,Ycs_i) position
  4. compute (Rcs_i,Dcs_i) as the sky coordinates for (Xcs_i,Ycs_i)
  5. compute delta of (Rcs_i-Rc_i, Dcs_i-Dcs_i) as (dRcs_i,dDcs_i)
  6. apply the fit to the chip’s undistorted CD matrix, the apply linear
       distortion terms back in to create a new CD matrix
  7. add (dRcs_i,dDcs_i) to CRVAL of the reference chip’s WCS
  8. update header with new WCS values