wcsimage

This module provides support for working with image footprints on the sky, source catalogs, and setting and manipulating tangent-plane corrections of image WCS.

Authors:Mihai Cara (contact: help@stsci.edu)

jwst.tweakreg.wcsimage.convex_hull(x, y, wcs=None)

Computes the convex hull of a set of 2D points.

Implements Andrew’s monotone chain algorithm. The algorithm has O(n log n) complexity.

Credit: http://en.wikibooks.org/wiki/Algorithm_Implementation/Geometry/Convex_hull/Monotone_chain

Parameters:points (list of tuples) – An iterable sequence of (x, y) pairs representing the points. Returns:Output – A list of vertices of the convex hull in counter-clockwise order, starting from the vertex with the lexicographically smallest coordinates. Return type:list

class jwst.tweakreg.wcsimage.ImageWCS(wcs, v2_ref, v3_ref, roll_ref, ra_ref, dec_ref)

A class for holding JWST GWCS information and for managing tangent-plane corrections.

Parameters:

• wcs (GWCS) – A GWCS object.
• v2ref (float) – V2 position of the reference point in degrees.
• v3ref (float) – V3 position of the reference point in degrees.
• roll (float) – Roll angle in degrees.
• ra_ref (float) – RA of the reference point in degrees.
• dec_ref (float) – DEC of the reference point in degrees.

copy()

Returns a deep copy of this ImageWCS object.

det_to_tanp(x, y)

Convert detector (pixel) coordinates to tangent plane coordinates.

det_to_world(x, y)

Convert pixel coordinates to sky coordinates using full (i.e., including distortions) transformations.

original_wcs

Get original GWCS object.

ref_angles

Return a wcsinfo-like dictionary of main WCS parameters.

set_correction(matrix=[[1, 0], [0, 1]], shift=[0, 0])

Sets a tangent-plane correction of the GWCS object according to the provided liniar parameters.

Parameters:

• matrix (list, numpy.ndarray) – A 2x2 array or list of lists coefficients representing scale, rotation, and/or skew transformations.
• shift (list, numpy.ndarray) – A list of two coordinate shifts to be applied to coordinates before matrix transformations are applied.

tanp_to_det(x, y)

Convert tangent plane coordinates to detector (pixel) coordinates.

tanp_to_world(x, y)

Convert tangent plane coordinates to world coordinates.

wcs

Get current GWCS object.

world_to_det(ra, dec)

Convert sky coordinates to image’s pixel coordinates using full (i.e., including distortions) transformations.

world_to_tanp(ra, dec)

Convert tangent plane coordinates to detector (pixel) coordinates.

class jwst.tweakreg.wcsimage.RefCatalog(catalog, name=None)

An object that holds a reference catalog and provides tools for coordinate convertions using reference WCS as well as catalog manipulation and expansion.

Parameters:

• catalog (astropy.table.Table) –

  Reference catalog.

  ..note::

  Reference catalogs (Table) must contain both 'RA' and 'DEC' columns.

• name (str, None, optional) – Name of the reference catalog.

calc_bounding_polygon()

Calculate bounding polygon of the sources in the catalog.

calc_tanp_xy(tanplane_wcs)

Compute x- and y-positions of the sources from the reference catalog in the tangent plane provided by the tanplane_wcs. This creates the following columns in the catalog’s table: 'xtanp' and 'ytanp'.

Parameters:tanplane_wcs (ImageWCS) – A ImageWCS object that will provide transformations to the tangent plane to which sources of this catalog a should be “projected”.

catalog

Get/set image’s catalog.

expand_catalog(catalog)

Expand current reference catalog with sources from another catalog.

Parameters:catalog (astropy.table.Table) – A catalog of new sources to be added to the existing reference catalog. catalog must contain both 'RA' and 'DEC' columns.

intersection(wcsim)

Compute intersection of this WCSImageCatalog object and another WCSImageCatalog, WCSGroupCatalog, RefCatalog, or SphericalPolygon object.

Parameters:wcsim (WCSImageCatalog, WCSGroupCatalog, RefCatalog, SphericalPolygon) – Another object that should be intersected with this WCSImageCatalog. Returns:polygon – A SphericalPolygon that is the intersection of this WCSImageCatalog and wcsim. Return type:SphericalPolygon

intersection_area(wcsim)

Calculate the area of the intersection polygon.

name

Get/set WCSImageCatalog object’s name.

poly_area

Area of the bounding polygon (in srad).

polygon

Get image’s (or catalog’s) bounding spherical polygon.

class jwst.tweakreg.wcsimage.WCSImageCatalog(shape, wcs, ref_angles, catalog, name=None, meta={})

A class that holds information pertinent to an image WCS and a source catalog of the sources found in that image.

Parameters:

• shape (tuple) – A tuple of two integer values indicating the size of the image along each axis. Must follow the same convention as the shape of a numpy.ndarray objects. Specifically, first size should be indicate the number of rows in the image and second size should indicate the number of columns in the image.
• wcs (gwcs.WCS) – WCS associated with the image and the catalog.
• ref_angles (dict) – A Python dictionary providing essential WCS reference angles. This parameter must contain at least the following keys: ra_ref, dec_ref, v2_ref, v3_ref, and roll_ref.
• catalog (astropy.table.Table) – Source catalog associated with an image. Must contain ‘x’ and ‘y’ columns which indicate source coordinates (in pixels) in the associated image.
• name (str, None, optional) – Image catalog’s name.
• meta (dict, optional) – Additional information about image, catalog, and/or WCS to be stored (for convenience) within WCSImageCatalog object.

bb_radec

Get a 2xN numpy.ndarray of RA and DEC of the vertices of the bounding polygon.

calc_bounding_polygon()

Calculate bounding polygon of the image or of the sources in the catalog (if catalog was set).

catalog

Get/set image’s catalog.

det_to_tanp(x, y)

Convert detector (pixel) coordinates to tangent plane coordinates.

det_to_world(x, y)

Convert pixel coordinates to sky coordinates using full (i.e., including distortions) transformations.

imshape

Get/set image’s shape. This must be a tuple of two dimensions following the same convention as the shape of numpy.ndarray.

imwcs

Get ImageWCS WCS.

intersection(wcsim)

Compute intersection of this WCSImageCatalog object and another WCSImageCatalog, WCSGroupCatalog, or SphericalPolygon object.

Parameters:wcsim (WCSImageCatalog, WCSGroupCatalog, SphericalPolygon) – Another object that should be intersected with this WCSImageCatalog. Returns:polygon – A SphericalPolygon that is the intersection of this WCSImageCatalog and wcsim. Return type:SphericalPolygon

intersection_area(wcsim)

Calculate the area of the intersection polygon.

name

Get/set WCSImageCatalog object’s name.

polygon

Get image’s (or catalog’s) bounding spherical polygon.

ref_angles

Get wcsinfo.

set_wcs(wcs, ref_angles)

Set gwcs.WCS and the associated wcsinfo`.

Note

Setting the WCS triggers automatic bounding polygon recalculation.

Parameters:

• wcs (gwcs.WCS) – WCS object.
• ref_angles (dict) – A Python dictionary providing essential WCS reference angles. This parameter must contain at least the following keys: ra_ref, dec_ref, v2_ref, v3_ref, and roll_ref.

tanp_to_det(x, y)

Convert tangent plane coordinates to detector (pixel) coordinates.

tanp_to_world(x, y)

Convert tangent plane coordinates to world coordinates.

wcs

Get gwcs.WCS.

world_to_det(ra, dec)

Convert sky coordinates to image’s pixel coordinates using full (i.e., including distortions) transformations.

world_to_tanp(ra, dec)

Convert tangent plane coordinates to detector (pixel) coordinates.

class jwst.tweakreg.wcsimage.WCSGroupCatalog(images, name=None)

A class that holds together WCSImageCatalog image catalog objects whose relative positions are fixed and whose source catalogs should be fitted together to a reference catalog.

Parameters:

• images (list of WCSImageCatalog) – A list of WCSImageCatalog image catalogs.
• name (str, None, optional) – Name of the group.

align_to_ref(refcat, minobj=15, searchrad=1.0, separation=0.5, use2dhist=True, xoffset=0.0, yoffset=0.0, tolerance=1.0, fitgeom='rscale', nclip=3, sigma=3.0)

Matches sources from the image catalog to the sources in the reference catalog, finds the affine transformation between matched sources, and adjusts images’ WCS according to this fit.

Parameters:

• refcat (RefCatalog) – A RefCatalog object that contains a catalog of reference sources as well as a valid reference WCS.
• 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.
• 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.
• use2dhist (bool, optional) – Use 2D histogram to find initial offset?
• 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.
• 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.
• 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.

apply_affine_to_wcs(tanplane_wcs, matrix, shift)

Applies a general affine transformation to the WCS.

calc_tanp_xy(tanplane_wcs)

Compute x- and y-positions of the sources from the image catalog in the tangent plane. This creates the following columns in the catalog’s table: 'xtanp' and 'ytanp'.

Parameters:tanplane_wcs (ImageWCS) – A ImageWCS object that will provide transformations to the tangent plane to which sources of this catalog a should be “projected”.

catalog

Get/set image’s catalog.

create_group_catalog()

Combine member’s image catalogs into a single group’s catalog.

Returns:group_catalog – Combined group catalog. Return type:astropy.table.Table

fit2ref(refcat, tanplane_wcs, fitgeom='general', nclip=3, sigma=3.0)

Perform linear fit of this group’s combined catalog to the reference catalog.

Parameters:

• refcat (RefCatalog) – A RefCatalog object that contains a catalog of reference sources.
• tanplane_wcs (ImageWCS) – A ImageWCS object that will provide transformations to the tangent plane to which sources of this catalog a should be “projected”.
• 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.

get_matched_cat()

Retrieve only those sources from the catalog that have been matched to the sources in the reference catalog.

get_unmatched_cat()

Retrieve only those sources from the catalog that have not been matched to the sources in the reference catalog.

intersection(wcsim)

Compute intersection of this WCSGroupCatalog object and another WCSImageCatalog, WCSGroupCatalog, or SphericalPolygon object.

Parameters:wcsim (WCSImageCatalog, WCSGroupCatalog, SphericalPolygon) – Another object that should be intersected with this WCSGroupCatalog. Returns:polygon – A SphericalPolygon that is the intersection of this WCSGroupCatalog and wcsim. Return type:SphericalPolygon

intersection_area(wcsim)

Calculate the area of the intersection polygon.

match2ref(refcat, minobj=15, searchrad=1.0, separation=0.5, use2dhist=True, xoffset=0.0, yoffset=0.0, tolerance=1.0)

Uses xyxymatch to cross-match sources between this catalog and

a reference catalog.

Parameters:

• refcat (RefCatalog) – A RefCatalog object that contains a catalog of reference sources as well as a valid reference WCS.
• 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.
• 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.
• use2dhist (bool, optional) – Use 2D histogram to find initial offset?
• 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.
• 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.

name

Get/set WCSImageCatalog object’s name.

polygon

Get image’s (or catalog’s) bounding spherical polygon.

recalc_catalog_radec()

Recalculate RA and DEC of the sources in the catalog.

update_bounding_polygon()

Recompute bounding polygons of the member images.