transfer_wcs_correction

jwst.tweakreg.utils.transfer_wcs_correction(to_image, from_image, matrix=None, shift=None)[source]

Applies the same total WCS correction that was applied by tweakreg (!) to the WCS in the from_image data model to the WCS of the to_image data model. In some ways this function is analogous function to the tweakback function for HST available in the drizzlepac package.

One fundamental difference between this function and tweakback is that JWST data models do not keep a history of data’s WCS via alternative WCS as it is done in HST data and so it is impossible to select and apply only one particular WCS correction if there were multiple corrections previously applied to a WCS. The tangent-plane correction in JWST WCS is cumulative/total correction. If you would like to apply a specific/custom correction, you can do that via matrix and shift arguments which is defined in the reference tangent plane provided by the from_image’s WCS.

When providing your own corrections via matrix and shift arguments, this function is similar to the adjust_wcs() function but provides an alternative way of specifying corrections via affine transformations in a reference tangent plane.

Warning

Upon return, if the to_image argument is an ImageModel it will be modified with an updated ImageModel.meta.wcs WCS model. If to_image argument is a file name of an ImageModel, that model will be read in, its WCS will be updated, and the updated model will be written out to the same file. BACKUP the file in to_image argument before calling this function.

Warning

This function does not support input data models whose WCS were modified by adjust_wcs(). Only WCS corrections computed by either the tweakreg step or by tweakwcs package are supported.

Parameters:

  • to_image (str, ImageModel) –

    Image model to which the correction should be applied/transferred to.

    Warning

    If it is a string file name then, upon return, this file will be overwritten with a data model with an updated WCS.

  • from_image (str, ImageModel, gwcs.wcs.WCS) –

    A data model whose WCS was previously corrected. This data model plays two roles: 1) it is the reference WCS which provides a tangent plane in which corrections have been defined, and 2) it provides WCS corrections to be applied to to_image’s WCS.

    If the WCS of the from_image data model does not contain corrections, then both matrix and shift arguments must be supplied.

  • matrix (2D list, 2D numpy.ndarray, None, optional) –

    A 2D matrix part of an affine transformation defined in the tangent plane derived from the from_image’s WCS.

    Note

    When provided, shift argument must also be provided in which case matrix and shift arguments override the correction (if present) from the from_file’s WCS.

  • shift (list, numpy.ndarray, None, optional) –

    A list of length 2 representing the translational part of an affine transformation (in arcsec) defined in the tangent plane derived from the from_image’s WCS.

    Note

    When provided, matrix argument must also be provided in which case matrix and shift arguments override the correction (if present) from the from_file’s WCS.

Returns:

  • Upon return, if the to_image argument is an ImageModel it will be

  • modified with an updated ImageModel.meta.wcs WCS model.

  • If to_image argument is a file name of an ImageModel, that

  • model will be read in, its WCS will be updated, and the updated model

  • will be written to the same file. BACKUP the file in to_image

  • argument before calling this function.