# Tweakback

`tweakback` - propagate the “tweaked” solutions back to the original input files.

Version 0.4.0 - replaced previous algorithm that used fitting of WCS footprints to reconstruct the transformation that was applied to the old drizzled image (to align it with another image) to obtain the new drizzled image WCS with an algorithm that is based on linearization of the exact compound operator that transforms current image coordinates to the “aligned” (to the new drizzled WCS) image coordinates.

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

`drizzlepac.tweakback.``determine_extnum`(drzfile, extname='SCI')

`drizzlepac.tweakback.``determine_orig_wcsname`(header, wnames, wkeys)

  Determine the name of the original, unmodified WCS solution

`drizzlepac.tweakback.``extract_input_filenames`(drzfile)

  Generate a list of filenames from a drizzled image’s header

`drizzlepac.tweakback.``getHelpAsString`(docstring=False, show_ver=True)

  return useful help from a file in the script directory called __taskname__.help

`drizzlepac.tweakback.``help`(file=None)

  Print out syntax help for running astrodrizzle

  Parameters:

  file : str (Default = None)

  > If given, write out help to the filename specified by this parameter Any previously existing file with this name will be deleted before writing out the help.

`drizzlepac.tweakback.``linearize`(wcsim, wcsima, wcs_olddrz, wcs_newdrz, imcrpix, hx=1.0, hy=1.0)

`drizzlepac.tweakback.``run`(configobj)

`drizzlepac.tweakback.``tweakback`(drzfile, input=None, origwcs=None, newname=None, wcsname=None, extname='SCI', force=False, verbose=False)

  Apply WCS solution recorded in drizzled file to distorted input images (`_flt.fits` files) used to create the drizzled file. This task relies on the original WCS and updated WCS to be recorded in the drizzled image’s header as the last 2 alternate WCSs.

  Parameters:

  drzfile : str (Default = ‘’)

  > filename of undistorted image which contains the new WCS and WCS prior to being updated

  newname : str (Default = None)

  > Value of `WCSNAME` to be used to label the updated solution in the output (eq., `_flt.fits`) files. If left blank or None, it will default to using the current `WCSNAME` value from the input drzfile.

  input : str (Default = ‘’)

  > filenames of distorted images to be updated using new WCS from ‘drzfile’. These can be provided either as an `@-file`, a comma-separated list of filenames or using wildcards.

  > Note

  > A blank value will indicate that the task should derive the filenames from the ‘drzfile’ itself, if possible. The filenames will be derived from the `D*DATA` keywords written out by astrodrizzle (or MultiDrizzle or drizzle). If they can not be found, the task will quit.

  origwcs : str (Default = None)

  > Value of `WCSNAME` keyword prior to the drzfile image being updated by tweakreg. If left blank or None, it will default to using the second to last `WCSNAME*` keyword value found in the header.

  wcsname : str (Default = None)

  > Value of WCSNAME for updated solution written out by `tweakreg` as specified by the `wcsname` parameter from `tweakreg`. If this is left blank or `None`, it will default to the current `WCSNAME` value from the input drzfile.

  extname : str (Default = ‘SCI’)

  > Name of extension in `input` files to be updated with new WCS

  force : bool (Default = False)

  > This parameters specified whether or not to force an update of the WCS even though WCS already exists with this solution or `wcsname`?

  verbose : bool (Default = False)

  > This parameter specifies whether or not to print out additional messages during processing.

  See also

  `stwcs.wcsutil.altwcs`
    Alternate WCS implementation

  Notes

  The algorithm used by this function is based on linearization of the exact compound operator that converts input image coordinates to the coordinates (in the input image) that would result in alignment with the new drizzled image WCS.

  If no input distorted files are specified as input, this task will attempt to generate the list of filenames from the drizzled input file’s own header.

  Examples

  An image named `acswfc_mos2_drz.fits` was created from 4 images using astrodrizzle. This drizzled image was then aligned to another image using tweakreg and the header was updated using the `WCSNAME` = `TWEAK_DRZ`. The new WCS can then be used to update each of the 4 images that were combined to make up this drizzled image using:

      >>> from drizzlepac import tweakback
      >>> tweakback.tweakback('acswfc_mos2_drz.fits')

  If the same WCS should be applied to a specific set of images, those images can be updated using:

      >>> tweakback.tweakback('acswfc_mos2_drz.fits',
      ...                     input='img_mos2a_flt.fits,img_mos2e_flt.fits')

`drizzlepac.tweakback.``update_chip_wcs`(chip_wcs, drz_old_wcs, drz_new_wcs, xrms=None, yrms=None)

`drizzlepac.tweakback.``tweakback`(drzfile, input=None, origwcs=None, newname=None, wcsname=None, extname='SCI', force=False, verbose=False)

  Apply WCS solution recorded in drizzled file to distorted input images (`_flt.fits` files) used to create the drizzled file. This task relies on the original WCS and updated WCS to be recorded in the drizzled image’s header as the last 2 alternate WCSs.

  Parameters:

  drzfile : str (Default = ‘’)

  > filename of undistorted image which contains the new WCS and WCS prior to being updated

  newname : str (Default = None)

  > Value of `WCSNAME` to be used to label the updated solution in the output (eq., `_flt.fits`) files. If left blank or None, it will default to using the current `WCSNAME` value from the input drzfile.

  input : str (Default = ‘’)

  > filenames of distorted images to be updated using new WCS from ‘drzfile’. These can be provided either as an `@-file`, a comma-separated list of filenames or using wildcards.

  > Note

  > A blank value will indicate that the task should derive the filenames from the ‘drzfile’ itself, if possible. The filenames will be derived from the `D*DATA` keywords written out by astrodrizzle (or MultiDrizzle or drizzle). If they can not be found, the task will quit.

  origwcs : str (Default = None)

  > Value of `WCSNAME` keyword prior to the drzfile image being updated by tweakreg. If left blank or None, it will default to using the second to last `WCSNAME*` keyword value found in the header.

  wcsname : str (Default = None)

  > Value of WCSNAME for updated solution written out by `tweakreg` as specified by the `wcsname` parameter from `tweakreg`. If this is left blank or `None`, it will default to the current `WCSNAME` value from the input drzfile.

  extname : str (Default = ‘SCI’)

  > Name of extension in `input` files to be updated with new WCS

  force : bool (Default = False)

  > This parameters specified whether or not to force an update of the WCS even though WCS already exists with this solution or `wcsname`?

  verbose : bool (Default = False)

  > This parameter specifies whether or not to print out additional messages during processing.

  See also

  `stwcs.wcsutil.altwcs`
    Alternate WCS implementation

  Notes

  The algorithm used by this function is based on linearization of the exact compound operator that converts input image coordinates to the coordinates (in the input image) that would result in alignment with the new drizzled image WCS.

  If no input distorted files are specified as input, this task will attempt to generate the list of filenames from the drizzled input file’s own header.

  Examples

  An image named `acswfc_mos2_drz.fits` was created from 4 images using astrodrizzle. This drizzled image was then aligned to another image using tweakreg and the header was updated using the `WCSNAME` = `TWEAK_DRZ`. The new WCS can then be used to update each of the 4 images that were combined to make up this drizzled image using:

      >>> from drizzlepac import tweakback
      >>> tweakback.tweakback('acswfc_mos2_drz.fits')

  If the same WCS should be applied to a specific set of images, those images can be updated using:

      >>> tweakback.tweakback('acswfc_mos2_drz.fits',
      ...                     input='img_mos2a_flt.fits,img_mos2e_flt.fits')