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