Image Alignment¶

Main module that performs image alignment and WCS correction.

Author: Mihai Cara (for help, contact HST Help Desk)
License: LICENSE

subpixal.align.align_images(catalog, resample, wcslin=None, fitgeom='general', nclip=3, sigma=3.0, nmax=10, eps_shift=0.003, use_weights=True, cc_type='NCC', wcsname='SUBPIXAL', wcsupdate='batch', combine_seg_mask=True, iterative=False, history='last')[source]¶

Perform relative image alignment using sub-pixel cross-correlation. Image alignment is performed by adusting each image’s WCS so that images align on the sky (i.e., sources from the catalog overlap). Input image data (provided through the resample parameter) are not changed.

Parameters

catalogcatalogs.ImageCatalog

A catalog object of ImageCatalog-derived type. This object will hold source-finding and source filtering parameters and should be able to find sources in provided images on demand.

resampleresample.Resample

An object of resample.Resample-derived type that can resample its images onto a common output grid.

wcslinastropy.wcs.WCS, None, optional

A WCS object that does not have non-linear distortions. This WCS defines a tangen plane in which image alignemnt will be performed. When not provided or set to None, it is set to drz_cutouts[0].wcs.

fitgeom{‘shift’, ‘rscale’, ‘general’}, optional

The fitting geometry to be used in fitting cutout displacements. This parameter is used in fitting the offsets, rotations and/or scale changes from the matched object lists. The ‘general’ fit geometry allows for independent scale and rotation for each axis.

nclipint, optional

Number (a non-negative integer) of clipping iterations in fit.

sigmafloat, optional

Clipping limit in sigma units.

nmaxint, tuple of two int, optional

A positive integer number indicating the number of resample-alignment iterations to be performed. After detecting that resampled images do not change significantly, the algorithm will automatically switch to a faster resampling fast_add_image() and fast_drop_image() methods instead of performing “full” resample that includes sky re-computation, cosmic ray detection, etc.

When nmax is a tuple of integers, first number indicates the maximum number of iterations to be performed and the second number indicates the maximum number of iterations with “full” resample to be performed.

eps_shiftfloat, optional

The algorithm will stop iterations when found shifts are below eps_shift value for all images.

use_weightsbool, optional

Indicates whether to perform a weighted fit when catalog contains a 'weights' column.

cc_type{‘CC’, ‘NCC’, ‘ZNCC’}, optional

Cross-correlation algorithm to be used. 'CC' indicates the “standard” cross-correlation algorithm. 'NCC' refers to the normalized cross-correlation and 'ZNCC' refers to the zero-normalized cross-correlation, see, e.g., Terminology in image processing.

wcsnamestr, None, optional

Label to give newly updated WCS. The default value will set the WCS name to SUBPIXAL.

wcsupdate{‘otf’, ‘batch’}, optional

Indicates when to update the WCS of an image: on-the-fly ('otf') setting will update image WCS as soon as the image was aligned while the 'batch' mode will first compute WCS corrections for all images and then will update their WCS at once. With 'otf' setting, next image (within the same iteration) will be aligned to a drizzled image obtained using (at least some) already aligned (in this iteration) images.

combine_seg_mask: bool, optional

Indicates whether to combine segmanetation mask with cutout’s mask. When True, segmentation image is used to create a mask that indicates “good” pixels in the image. This mask is combined with cutout’s mask.

iterativebool, optional

If True, after each iteration user will be asked whether to continue or stop alignment process.

history{‘all’, ‘last’, None}

On return this function returns “fit history” containing information that can be used to analyze the goodness of fit. When history is 'all', then info from each iteration is saved. When history is 'last' only info for the last iteration is saved, and when history is None, no informationn is saved.

Returns

fit_historylist of dict: A list of Python dictionaries containing fit information as well as “image” information such as image cutouts, blots, cross-correlation image, etc.

subpixal.align.find_linear_fit(img_cutouts, drz_cutouts, wcslin=None, fitgeom='general', nclip=3, sigma=3.0, use_weights=True, cc_type='NCC')[source]¶

Perform linear fit to diplacements (found using cross-correlation) between img_cutouts and “blot” of drz_cutouts onto img_cutouts.

Parameters

img_cutoutsCutout: Cutouts whose WCS should be aligned.
drz_cutoutsCutout: Cutouts that serve as “reference” to which img_cutouts will be aligned.
wcslinastropy.wcs.WCS, None, optional: A WCS object that does not have non-linear distortions. This WCS defines a tangen plane in which image alignemnt will be performed. When not provided or set to None, internally wcslin will be set to drz_cutouts[0].wcs.
fitgeom{‘shift’, ‘rscale’, ‘general’}, optional: The fitting geometry to be used in fitting cutout displacements. This parameter is used in fitting the offsets, rotations and/or scale changes from the matched object lists. The ‘general’ fit geometry allows for independent scale and rotation for each axis.
nclipint, optional: Number (a non-negative integer) of clipping iterations in fit.
sigmafloat, optional: Clipping limit in sigma units.
use_weightsbool, optional: Indicates whether to perform a weighted fit when all input drz_cutouts.src_weight are not None.
cc_type{‘CC’, ‘NCC’, ‘ZNCC’}, optional: Cross-correlation algorithm to be used. 'CC' indicates the “standard” cross-correlation algorithm. 'NCC' refers to the normalized cross-correlation and 'ZNCC' refers to the zero-normalized cross-correlation, see, e.g., Terminology in image processing.

Returns

fitdict: A dictionary of various fit parameters computed during the fit. Use fit.keys() to find which parameters are being returned.
interlaced_ccnumpy.ndarray: Interlaced (super-sampled) cross-correlation image. This is provided as a diagnostic tool for debugging purposes.
nonshifted_bltsCutout: A list of cutouts of blotted drz_cutouts without applying any sub-pixel shifts. This is provided as a diagnostic tool for debugging purposes.

subpixal.align.correct_wcs(imwcs, wcslin, rotmat, shifts, fitgeom)[source]¶: Correct input WCS using supplied linear transformations defined in a linear WCS. This function modifies imwcs with the corrected WCS parameters.

subpixal.align.update_image_wcs(image, ext, wcs, wcsname=None)[source]¶

Updates the WCS of the specified extension with the new WCS after archiving the original WCS.

Parameters

imagestr, astropy.io.fits.HDUList

Filename of image with WCS that needs to be updated

extint, str or tuple of (string, int)

The key identifying the HDU. If ext is a tuple, it is of the form (name, ver) where ver is an EXTVER value that must match the HDU being searched for.

If the key is ambiguous (e.g. there are multiple ‘SCI’ extensions) the first match is returned. For a more precise match use the (name, ver) pair.

If even the (name, ver) pair is ambiguous (it shouldn’t be but it’s not impossible) the numeric index must be used to index the duplicate HDU.

wcsobject

Full HSTWCS object which will replace/update the existing WCS

wcsnamestr, None, optional

Label to give newly updated WCS. The default value will set the WCS name to SUBPIXAL.