# TWEAKREG: Image Alignment¶

Combining images using AstroDrizzle requires that the WCS information in the headers of each input image align to within sub-pixel accuracy. The TweakReg task allows the user to align sets of images to each other and/or to and external astrometric reference frame or image.

TweakReg - A replacement for IRAF-based tweakshifts

Authors: Warren Hack, Mihai Cara LICENSE
drizzlepac.tweakreg.TweakReg(files=None, editpars=False, configobj=None, imagefindcfg=None, refimagefindcfg=None, **input_dict)[source]

Tweakreg provides an automated interface for computing residual shifts between input exposures being combined using AstroDrizzle. The offsets computed by Tweakreg correspond to pointing differences after applying the WCS information from the input image’s headers. Such errors would, for example, be due to errors in guide-star positions when combining observations from different observing visits or from slight offsets introduced upon re-acquiring the guide stars in a slightly different position.

astrodrizzle

Notes

Tweakreg supports the use of calibrated, distorted images (such as FLT images for ACS and WFC3, or _c0m.fits images for WFPC2) as input images. All coordinates for sources derived from these images (either by this task or as provided by the user directly) will be corrected for distortion using the distortion model information specified in each image’s header. This eliminates the need to run AstroDrizzle on the input images prior to running TweakReg.

Note

All calibrated input images must have been updated using updatewcs from the STWCS package, to include the full distortion model in the header. Alternatively, one can set updatewcs parameter to True when running either TweakReg or AstroDrizzle from command line (Python interpreter) the first time on such images.

This task will use catalogs, and catalog-matching, based on the xyxymatch algorithm to determine the offset between the input images. The primary mode of operation will be to extract a catalog of source positions from each input image using either a ‘DAOFIND-like’ algorithm or SExtractor (if the user has SExtractor installed). Alternatively, the user can provide their catalogs of source positions derived from each input chip.

Note

Catalog files must be text files containing “white space”-separated list of values (xcol, ycol, etc.)

The reference frame will be defined either by:

• the image with the largest overlap with another input image AND with the largest total overlap with the rest of the input images,
• a catalog derived from a reference image specified by the user, or
• a catalog of undistorted sky positions (RA/Dec) and fluxes provided by the user.

For a given observation, the distortion model is applied to all distorted input positions, and the sources from each chip are then combined into a single catalog of undistorted positions.

The undistorted positions for each observation then get passed to xyxymatch for matching to objects from the reference catalog.

The source lists from each image will generally include cosmic-rays as detected sources, which can at times significantly confuse object identification between images. Observations that include long exposures often have more cosmic-ray events than source objects. As such, isolating the cosmic-ray events in those cases would significantly improve the efficiency of common source identification between images. One such method for trimming potential false detections from each source list would be to set a flux limit to exclude detections below that limit. As the fluxes reported in the default source object lists are provided as magnitude values, setting the maxflux or minflux parameter value to a magnitude- based limit, and then setting the ascend parameter to True, will allow for the creations of catalogs trimmed of all sources fainter than the provided limit. The trimmed source list can then be used in matching sources between images and in establishing the final fitting for the shifts.

A fit can then be performed on the matched set of positions between the input and the reference to produce the ‘shiftfile’. If the user is confident that the solution will be correct, the header of each input image can be updated directly with the fit derived for that image. Otherwise, the ‘shiftfile’ can be passed to AstroDrizzle for aligning the images.

Note

Because of the nature of the used algorithm it may be necessary to run this task multiple time until new shifts, rotations, and/or scales are small enough for the required precision.

New sources (that are not in the reference catalog) from the matched images are added to the reference catalog in order to allow next image to be matched to a larger reference catalog. This allows alignment of images that do not overlap directly with the reference image and/or catalog and it is particularly useful in image registration of large mosaics. Addition of new sources to the reference catalog can be turned off by setting expand_refcat to False when using an external reference catalog. When an external catalog is not provided (refcat='') or when using an external reference catalog with expand_refcat set to True (assuming writecat = True and clean = False), the list of all sources in the expanded reference catalog is saved in a catalog file named cumulative_sky_refcat_###.coo where ### is the base file name derived from either the external catalog (if provided) or the name of the image used as the reference image.

When enforce_user_order is False, image catalogs are matched to the reference catalog in order of decreasing overlap area with the reference catalog, otherwise user order of files specified in the file parameter is used.

Format of Exclusion Catalog

The format for the exclusions catalog requires 1 line in the file for every input image, regardless of whether or not that image has any defined exclusion regions. A sample file would look like:

j99da1emq_flt.fits
j99da1f2q_flt.fits test_exclusion.reg

This file specifies no exclusion files for the first image, and only an regions file for SCI,1 of the second image. NOTE: The first file can be dropped completely from the exclusion catalog file.

In the above example, should an exclusion regions file only be needed for the second chip in the second image, the file would need to look like:

j99da1emq_flt.fits
j99da1f2q_flt.fits None test_sci2_exclusion.reg

The value None could also be replaced by INDEF if desired, but either string needs to be present to signify no regions file for that chip while the code continues parsing the line to find a file for the second chip.

Format of Region Files

The format of the exclusions catalogs referenced in the ‘exclusions’ file defaults to the format written out by DS9 using the ‘DS9/Funtools’ region file format. A sample file with circle() regions will look like:

# Region file format: DS9 version 4.1
# Filename: j99da1f2q_flt.fits[SCI]
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman"
select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
image
circle(3170,198,20)
ellipse(3269,428,30,10,45) # a rotated ellipse
box(3241.1146,219.78132,20,20,15) # a rotated box
circle(200,200,50)  # outer circle
-circle(200,200,30) # inner circle

This region file will be interpreted as “find all sources in the image that are inside the four regions above but not inside the region -circle(200,200,30)”. Effectively we will instruct TweakReg to find all the sources inside the following regions:

circle(3170,198,20)
ellipse(3269,428,30,10,45) # a rotated ellipse
box(3241.1146,219.78132,20,20,15) # a rotated box
annulus(200,200,30,50)  # outer circle(r=50) - inner circle(r=30)

Examples

The tweakreg task can be run from either the TEAL GUI or from the command-line using PyRAF or Python. These examples illustrate the various syntax options available.

Example 1: Align a set of calibrated (_flt.fits) images using IMAGEFIND, a built-in source finding algorithm based on DAOPHOT. Auto-detect the sky sigma value and select sources > 200 sigma. (Auto-sigma is computed from the first input exposure as: 1.5*imstat(image,nclip=3,fields='stddev'). ) Set the convolution kernel width to ~2x the value of the PSF FWHM. Save the residual offsets (dx, dy, rot, scale, xfit_rms, yfit_rms) to a text file.

1. Run the task from PyRAF using the TEAL GUI:

>>> import drizzlepac
>>> epar tweakreg

2. Run the task from PyRAF using the command line while individually specifying source finding parameters for the reference image and input images:

>>> import drizzlepac
>>> from drizzlepac import tweakreg
>>> tweakreg.TweakReg('*flt.fits',
...       imagefindcfg={'threshold' : 200, 'conv_width' : 3.5},
...       refimagefindcfg={'threshold' : 400, 'conv_width' : 2.5},
...       updatehdr=False, shiftfile=True, outshifts='shift.txt')

or, using dict constructor,

>>> import drizzlepac
>>> from drizzlepac import tweakreg
>>> tweakreg.TweakReg('*flt.fits',
...       imagefindcfg=dict(threshold=200, conv_width=3.5),
...       refimagefindcfg=dict(threshold=400, conv_width=2.5),
...       updatehdr=False, shiftfile=True, outshifts='shift.txt')

Or, run the same task from the PyRAF command line, but specify all parameters in a config file named “myparam.cfg”:

>>> tweakreg.TweakReg('*flt.fits', configobj='myparam.cfg')

Alternately, edit the imagefind parameters in a TEAL GUI window prior to running the task:

>>> tweakreg.edit_imagefindpars()

3. Help can be accessed via the “Help” pulldown menu in the TEAL GUI. It can also be accessed from the PyRAF command-line and saved to a text file:

>>> from drizzlepac import tweakreg
>>> tweakreg.help()

or

>>> tweakreg.help(file='help.txt')
>>> page help.txt

drizzlepac.tweakreg.help(file=None)[source]

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.