imalign

A module that provides functions for “aligning” images: specifically, it provides functions for computing corrections to image WCS so that images catalogs “align” to the reference catalog on the sky.

Authors:Mihai Cara (contact: help@stsci.edu)
jwst.tweakreg.imalign.align(imcat, refcat=None, enforce_user_order=True, expand_refcat=False, minobj=None, searchrad=1.0, use2dhist=True, separation=0.5, tolerance=1.0, xoffset=0.0, yoffset=0.0, fitgeom='general', nclip=3, sigma=3.0)[source]

Align (groups of) images by adjusting the parameters of their WCS based on fits between matched sources in these images and a reference catalog which may be automatically created from one of the input images.

Parameters:
  • imcat (list of WCSImageCatalog or WCSGroupCatalog) –

    A list of WCSImageCatalog or WCSGroupCatalog objects whose WCS should be adjusted. The difference between WCSImageCatalog and WCSGroupCatalog is that the later is used to find a single fit to all sources in all component images simultaneously. This fit is later applied to each component image’s WCS.

    Warning

    This function modifies the WCS of the input images provided through the imcat parameter. On return, each input image WCS will be updated with an “aligned” version.

  • refcat (RefCatalog, optional) – A RefCatalog object that contains a catalog of reference sources as well as (optionally) a valid reference WCS. When refcat is None, a reference catalog will be created from one of the input (group of) images.
  • enforce_user_order (bool, optional) – Specifies whether images should be aligned in the order specified in the file input parameter or align should optimize the order of alignment by intersection area of the images. Default value (True) will align images in the user specified order, except when some images cannot be aligned in which case align will optimize the image alignment order. Alignment order optimization is available only when expand_refcat = True.
  • expand_refcat (bool, optional) – Specifies whether to add new sources from just matched images to the reference catalog to allow next image to be matched against an expanded reference catalog. By delault, the reference catalog is not being expanded.
  • minobj (int, None, optional) – Minimum number of identified objects from each input image to use in matching objects from other images. If the default None value is used then align will automatically deternmine the minimum number of sources from the value of the fitgeom parameter.
  • searchrad (float, optional) – The search radius for a match.
  • use2dhist (bool, optional) – Use 2D histogram to find initial offset?
  • separation (float, optional) – The minimum separation for sources in the input and reference catalogs in order to be considered to be disctinct sources. Objects closer together than ‘separation’ pixels are removed from the input and reference coordinate lists prior to matching. This parameter gets passed directly to xyxymatch() for use in matching the object lists from each image with the reference image’s object list.
  • tolerance (float, optional) – The matching tolerance in pixels after applying an initial solution derived from the ‘triangles’ algorithm. This parameter gets passed directly to xyxymatch() for use in matching the object lists from each image with the reference image’s object list.
  • xoffset (float, optional) – Initial estimate for the offset in X between the images and the reference frame. This offset will be used for all input images provided. This parameter is ignored when use2dhist is True.
  • yoffset (float (Default = 0.0)) – Initial estimate for the offset in Y between the images and the reference frame. This offset will be used for all input images provided. This parameter is ignored when use2dhist is True.
  • fitgeom ({'shift', 'rscale', 'general'}, optional) – The fitting geometry to be used in fitting the matched object lists. 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.
  • nclip (int, optional) – Number (a non-negative integer) of clipping iterations in fit.
  • sigma (float, optional) – Clipping limit in sigma units.
jwst.tweakreg.imalign.overlap_matrix(images)[source]

Compute overlap matrix: non-diagonal elements (i,j) of this matrix are absolute value of the area of overlap on the sky between i-th input image and j-th input image.

Note

The diagonal of the returned overlap matrix is set to 0.0, i.e., this function does not compute the area of the footprint of a single image on the sky.

Parameters:images (list of WCSImageCatalog, WCSGroupCatalog, or RefCatalog) – A list of catalogs that implement intersection_area() method.
Returns:m – A numpy.ndarray of shape NxN where N is equal to the number of input images. Each non-diagonal element (i,j) of this matrix is the absolute value of the area of overlap on the sky between i-th input image and j-th input image. Diagonal elements are set to 0.0.
Return type:numpy.ndarray
jwst.tweakreg.imalign.max_overlap_pair(images, enforce_user_order)[source]

Return a pair of images with the largest overlap.

Warning

Returned pair of images is “poped” from input images list and therefore on return images will contain a smaller number of elements.

Parameters:
  • images (list of WCSImageCatalog, WCSGroupCatalog, or RefCatalog) – A list of catalogs that implement intersection_area() method.
  • enforce_user_order (bool) – When enforce_user_order is True, a pair of images will be returned in the same order as they were arranged in the images input list. That is, image overlaps will be ignored.
Returns:

Returns a tuple of two images - elements of input images list. When enforce_user_order is True, images are returned in the order in which they appear in the input images list. When the number of input images is smaller than two, im1 and im2 may be None.
Return type:

(im1, im2)
jwst.tweakreg.imalign.max_overlap_image(refimage, images, enforce_user_order)[source]

Return the image from the input images list that has the largest overlap with the refimage image.

Warning

Returned image of images is “poped” from input images list and therefore on return images will contain a smaller number of elements.

Parameters:
  • images (list of WCSImageCatalog, or WCSGroupCatalog) – A list of catalogs that implement intersection_area() method.
  • enforce_user_order (bool) – When enforce_user_order is True, returned image is the first image from the images input list regardless ofimage overlaps.
Returns:

image – Returns an element of input images list. When input list is empty - None is returned.
Return type:

WCSImageCatalog, WCSGroupCatalog, or None