TWEAKBACK: Propagating The Solution

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:: License

drizzlepac.tweakback.apply_tweak(drz_file, orig_wcs_name, output_wcs_name=None, input_files=None, default_extname='SCI', **kwargs)[source]

Apply WCS solution recorded in drizzled file to distorted input images (_flt.fits files) used to create the drizzled file.

It is assumed that if input images given by input_files are drizzled together, they would produce the drizzled image given by drz_file image and with the “original” primary WCS. It is also assumed that drizzled image was aligned using tweakreg either to another image or to an external reference catalog. We will refer to the primary WCS in the drizzled image before tweakreg was run as the “original” WCS and the WCS after tweakreg was run as “tweaked” WCS.

By comparing both “original” and “tweaked” WCS, apply_wcs computes the correction that was applied by tweakreg to the “original” WCS and converts this correction in the drizzled image frame into a correction in the input image’s (input_files) frame that will be applied to the primary WCS of input images. If updated input images are now resampled again, they would produce an image very close to drz_file but with a primary WCS very similar to the “tweaked” WCS instead of the “original” WCS.

Parameters:

drz_filestr

File name of the drizzled image that contains both the “original” and “tweaked” WCS. Even though wildcards are allowed in the file name, their expansion must resolve to a single image file. By default, apply_tweak looks for the first image-like HDU in the drizzled image. To specify a particular extension from which to load WCS, append extension specification after the file name, for example:

'image_drz.fits[sci,1]' for first “sci” extension

'image_drz.fits[1]' for the first extension

'image_drz.fits[0]' for the primary HDU

orig_wcs_namestr

Name (provided by the WCSNAME? header keyword where ? respesents a letter A-Z) of the “original” WCS. This is the WCS of the resampled image (obtained by drizzling all input images) before this resampled image was aligned (“tweaked”) to another image/catalog.

If orig_wcs_name is None, the the original WCS must be specified using orig_wcs_key. When orig_wcs_key is provided, orig_wcs_name is ignored altogether.

output_wcs_namestr, None

Value of WCSNAME to be used to label the updated solution in the input (e.g., _flt.fits) files. If left blank or None, it will default to using either the current (primary) WCSNAME value from the drz_file or from the alternate WCS given by the tweaked_wcs_name or tweaked_wcs_key parameters.

input_filesstr, None

Filenames of distorted images whose primary WCS is to be updated with the same transformation as used in the “tweaked” drizzled image. Default value of None indicates that input image filenames will be derived from the D*DATA keywords written out by the AstroDrizzle. If they can not be found, the task will quit.

input_files string can contain one of the following:

a comma-separated list of valid science image file names (see note below) and (optionally) extension specifications, e.g.: 'j1234567q_flt.fits[1], j1234568q_flt.fits[sci,2]';

an @-file name, e.g., '@files_to_match.txt'.

Note

Valid science image file names are:

file names of existing FITS, GEIS, or WAIVER FITS files;
partial file names containing wildcard characters, e.g., '*_flt.fits';
Association (ASN) tables (must have _asn, or _asc suffix), e.g., 'j12345670_asn.fits'.

Warning

@-file names MAY NOT be followed by an extension specification.

Warning

If an association table or a partial file name with wildcard characters is followed by an extension specification, it will be considered that this extension specification applies to each file name in the association table or each file name obtained after wildcard expansion of the partial file name.

default_extnamestr

Extension name of extensions in input images whose primary WCS should be updated. This value is used only when file names provided in input_files do not contain extension specifications.

Other Parameters:

tweaked_wcs_namestr

Name of the “tweaked” WCS. This is the WCS of the resampled image (obtained by drizzling all input images) _after_ this resampled image was aligned (“tweaked”) to another image/catalog.

When neither tweaked_wcs_name nor ``tweaked_wcs_key are not provided, apply_tweak will take the current primary WCS in the drizzled image as a “tweaked” WCS. tweaked_wcs_name is ignored when tweaked_wcs_key is provided.

tweaked_wcs_key{’ ‘, ‘A’-‘Z’}

Same as tweaked_wcs_name except it specifies a WCS by key instead of name. When provided, tweaked_wcs_name is ignored.

orig_wcs_key{’ ‘, ‘A’-‘Z’}

Same as orig_wcs_name except it specifies a WCS by key instead of name. When provided, orig_wcs_name is ignored.

See also

stwcs.wcsutil.altwcs

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.

Warning

Parameters orig_wcs_name and tweaked_wcs_name (or their “key” equivalents) allow computation of transformation between any two WCS in the drizzled image and application of this transformation to the primary WCS of the input images. This will produce an expected result only if the WCS pointed to by orig_wcs_name was obtained by drizzling input images with their current primary WCS.

Examples

A drizzled image named acswfc_mos2_drz.fits was created from 4 images using AstroDrizzle. The primary WCS of this drizzled image was named 'INITIAL_GUESS'. This drizzled image was then aligned to some other image using TweakReg and the updated (“tweaked”) primary WCS was named 'BEST_WCS' while the previous primary WCS - the WCS named 'INITIAL_GUESS' - was archived by TweakReg under WCS key 'C'. We will refer to this archived WCS as the “original” WCS. apply_tweak can now be used to compute the transformation between the original and the tweaked WCS and apply this transformation to the WCS of each of the input images that were drizzle-combined to produce the resampled image acswfc_mos2_drz.fits.

The simplest way to accomplish this would be to run apply_tweak() using default parameters:

>>> from drizzlepac import tweakback
>>> tweakback.apply_tweak('acswfc_mos2_drz.fits', orig_wcs_name='INITIAL_GUESS')

or

>>> tweakback.apply_tweak('acswfc_mos2_drz.fits', orig_wcs_key='C')

If the same WCS should be applied to a specific set of images or extensions in those images, then we can explicitly specify input files:

>>> tweakback.apply_tweak(
...     'acswfc_mos2_drz.fits',
...     input='img_mos2a_flt.fits,img_mos2c_flt.fits[1],img_mos2d_flt.fits[sci,1]'
... )

In the examples above, current primary WCS of the input 'img_mos2?_flt.fits' files will be archived and the primary WCS will be replaced with a “tweaked” WCS obtained by applying relevant transformations to the current primary WCS. Because we did not specify output_wcs_name, the name of this tweaked primary WCS in the input images will be set to 'BEST_WCS'.

drizzlepac.tweakback.determine_extnum(drzfile, extname='SCI')[source]

drizzlepac.tweakback.determine_orig_wcsname(header, wnames, wkeys)[source]: Determine the name of the original, unmodified WCS solution

drizzlepac.tweakback.extract_input_filenames(drzfile)[source]: Generate a list of filenames from a drizzled image’s header

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

drizzlepac.tweakback.run(configobj)[source]

drizzlepac.tweakback.update_chip_wcs(chip_wcs, drz_old_wcs, drz_new_wcs, xrms=None, yrms=None)[source]

drizzlepac.tweakback.help(file=None)

Print out syntax help for running tweakback.

Parameters:

filestr (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.apply_tweak(drz_file, orig_wcs_name, output_wcs_name=None, input_files=None, default_extname='SCI', **kwargs)[source]

Apply WCS solution recorded in drizzled file to distorted input images (_flt.fits files) used to create the drizzled file.

It is assumed that if input images given by input_files are drizzled together, they would produce the drizzled image given by drz_file image and with the “original” primary WCS. It is also assumed that drizzled image was aligned using tweakreg either to another image or to an external reference catalog. We will refer to the primary WCS in the drizzled image before tweakreg was run as the “original” WCS and the WCS after tweakreg was run as “tweaked” WCS.

By comparing both “original” and “tweaked” WCS, apply_wcs computes the correction that was applied by tweakreg to the “original” WCS and converts this correction in the drizzled image frame into a correction in the input image’s (input_files) frame that will be applied to the primary WCS of input images. If updated input images are now resampled again, they would produce an image very close to drz_file but with a primary WCS very similar to the “tweaked” WCS instead of the “original” WCS.

Parameters:

drz_filestr

File name of the drizzled image that contains both the “original” and “tweaked” WCS. Even though wildcards are allowed in the file name, their expansion must resolve to a single image file. By default, apply_tweak looks for the first image-like HDU in the drizzled image. To specify a particular extension from which to load WCS, append extension specification after the file name, for example:

'image_drz.fits[sci,1]' for first “sci” extension

'image_drz.fits[1]' for the first extension

'image_drz.fits[0]' for the primary HDU

orig_wcs_namestr

Name (provided by the WCSNAME? header keyword where ? respesents a letter A-Z) of the “original” WCS. This is the WCS of the resampled image (obtained by drizzling all input images) before this resampled image was aligned (“tweaked”) to another image/catalog.

If orig_wcs_name is None, the the original WCS must be specified using orig_wcs_key. When orig_wcs_key is provided, orig_wcs_name is ignored altogether.

output_wcs_namestr, None

Value of WCSNAME to be used to label the updated solution in the input (e.g., _flt.fits) files. If left blank or None, it will default to using either the current (primary) WCSNAME value from the drz_file or from the alternate WCS given by the tweaked_wcs_name or tweaked_wcs_key parameters.

input_filesstr, None

Filenames of distorted images whose primary WCS is to be updated with the same transformation as used in the “tweaked” drizzled image. Default value of None indicates that input image filenames will be derived from the D*DATA keywords written out by the AstroDrizzle. If they can not be found, the task will quit.

input_files string can contain one of the following:

a comma-separated list of valid science image file names (see note below) and (optionally) extension specifications, e.g.: 'j1234567q_flt.fits[1], j1234568q_flt.fits[sci,2]';

an @-file name, e.g., '@files_to_match.txt'.

Note

Valid science image file names are:

file names of existing FITS, GEIS, or WAIVER FITS files;
partial file names containing wildcard characters, e.g., '*_flt.fits';
Association (ASN) tables (must have _asn, or _asc suffix), e.g., 'j12345670_asn.fits'.

Warning

@-file names MAY NOT be followed by an extension specification.

Warning

If an association table or a partial file name with wildcard characters is followed by an extension specification, it will be considered that this extension specification applies to each file name in the association table or each file name obtained after wildcard expansion of the partial file name.

default_extnamestr

Extension name of extensions in input images whose primary WCS should be updated. This value is used only when file names provided in input_files do not contain extension specifications.

Other Parameters:

tweaked_wcs_namestr

Name of the “tweaked” WCS. This is the WCS of the resampled image (obtained by drizzling all input images) _after_ this resampled image was aligned (“tweaked”) to another image/catalog.

When neither tweaked_wcs_name nor ``tweaked_wcs_key are not provided, apply_tweak will take the current primary WCS in the drizzled image as a “tweaked” WCS. tweaked_wcs_name is ignored when tweaked_wcs_key is provided.

tweaked_wcs_key{’ ‘, ‘A’-‘Z’}

Same as tweaked_wcs_name except it specifies a WCS by key instead of name. When provided, tweaked_wcs_name is ignored.

orig_wcs_key{’ ‘, ‘A’-‘Z’}

Same as orig_wcs_name except it specifies a WCS by key instead of name. When provided, orig_wcs_name is ignored.