SkyLine (chip outline on the sky) management for image mosaic

This module provides support for working with footprints on the sky. Primary use case would use the following generalized steps:

  1. Initialize SkyLine objects for each input image. This object would be the union of all the input image’s individual chips WCS footprints.

  2. Determine overlap between all images. The determination would employ a recursive operation to return the extended list of all overlap values computed as [img1 vs [img2,img3,…,imgN],img2 vs [img3,…,imgN],…]

  3. Select the pair with the largest overlap, or the pair which produces the largest overlap with the first input image. This defines the initial reference SkyLine object.

  4. Perform some operation on the 2 images: for example, match sky in intersecting regions, or aligning second image with the first (reference) image.

  5. Update the second image, either apply the sky value or correct the WCS, then generate a new SkyLine object for that image.

  6. Create a new reference SkyLine object as the union of the initial reference object and the newly updated SkyLine object.

  7. Repeat Steps 2-6 for all remaining input images.

This process will work reasonably fast as most operations are performed using the SkyLine objects and WCS information solely, not image data itself.

Authors:

Mihai Cara, Warren Hack, Pey-Lian Lim

License:

LICENSE

class stsci.skypac.skyline.SkyLine(mlist)[source]

Manage outlines on the sky.

Skylines are designed to capture and manipulate HST WCS image information as spherical polygons. They are represented by the SkyLine class, which is an extension of SphericalPolygon class.

Each skyline has a list of members, members, and a composite spherical polygon, polygon, members. The polygon has all the functionalities of SphericalPolygon.

Each SkyLine has a list of members and a composite polygon with all the functionalities of SphericalPolygon.

Each member in members belongs to the SkyLineMember class, which contains image name (with path if given), science extension(s), and composite WCS and polygon of the extension(s). All skylines start out with a single member from a single image. When operations are used to find composite or intersecting skylines, the resulting skyline can have multiple members.

For example, a skyline from an ACS/WFC full-frame image would give 1 member, which is a composite of extensions 1 and 4. A skyline from the union of 2 such images would have 2 members, and so forth.

Parameters:
fname: str

FITS image. None to create empty SkyLine.

ext: a list of tuples (‘extname’,extver).
add_image(other)[source]

Return a new SkyLine that is the union of self and other.

Warning

SkyLine.union only returns polygon without members.

Parameters:
other: `SkyLine` object

Examples

>>> s1 = SkyLine('image1.fits')
>>> s2 = SkyLine('image2.fits')
>>> s3 = s1.add_image(s2)
find_intersection(other)[source]

Return a new SkyLine that is the intersection of self and other.

Warning

SkyLine.intersection only returns polygon without members.

Parameters:
other: `SkyLine` object

Examples

>>> s1 = SkyLine('image1.fits')
>>> s2 = SkyLine('image2.fits')
>>> s3 = s1.find_intersection(s2)
find_max_overlap(skylines)[source]

Find SkyLine from a list of skylines that overlaps the most with self.

Parameters:
skylines: list

A list of SkyLine instances.

Returns:
max_skyline: SkyLine instance or None

SkyLine that overlaps the most or None if no overlap found. This is not a copy.

max_overlap_area: float

Area of intersection.

property is_mf_mosaic

returns True if SkyLine members are from distinct image files (multi-file mosaic) and False otherwise.

static max_overlap_pair(skylines)[source]

Find a pair of skylines with maximum overlap.

Parameters:
skylines: list

A list of SkyLine instances.

Returns:
max_pair: tuple

Pair of SkyLine objects with max overlap among given skylines. If no overlap found, return None. These are not copies.

property members

List of SkyLineMember objects that belong to self. Duplicate members are discarded. Members are kept in the order of their additions to self.

property polygon

SphericalPolygon portion of SkyLine that contains the composite skyline from members belonging to self.

to_wcs()[source]

Combine HSTWCS objects from all members and return a new HSTWCS object. If no members, return None.

Warning

This cannot return WCS of intersection.

class stsci.skypac.skyline.SkyLineMember(image, ext, dq_bits=0, dqimage=None, dqext=None, usermask=None, usermask_ext=None)[source]

Container for SkyLine members that holds information about properties of a single extension (chip) in a FITS image such as:

  • WCS of the chip image;

  • bounding spherical polygon;

  • file name and extension from which the chip’s image has originated;

  • information required for unit conversions (EXPTIME, PHOTFLAM, BUNIT, etc.);

  • user mask and DQ array associated with chip’s image data.

Parameters:
image: ImageRef

An ImageRef object that refers to an open FITS file

ext: tuple, int, str

Extension specification in the image the SkyLineMember object will be associated with.

An int ext specifies extension number. A tuple in the form (str, int) specifies extension name and number. A string ext specifies extension name and the extension version is assumed to be 1. See documentation for astropy.io.fits.getData for examples.

dq_bits: int, None (Default = 0)

Integer sum of all the DQ bit values from the input image’s DQ array that should be considered “good” when building masks for sky computations. For example, if pixels in the DQ array can be combinations of 1, 2, 4, and 8 flags and one wants to consider DQ “defects” having flags 2 and 4 as being acceptable for sky computations, then dq_bits should be set to 2+4=6. Then a DQ pixel having values 2,4, or 6 will be considered a good pixel, while a DQ pixel with a value, e.g., 1+2=3, 4+8=12, etc. will be flagged as a “bad” pixel.

Default value (0) will make all non-zero pixels in the DQ mask to be considered “bad” pixels, and the corresponding image pixels will not be used for sky computations.
Set dq_bits to None to turn off the use of image’s DQ array for sky computations.

Note

DQ masks (if used), will be combined with user masks specified by the usermask parameter.

dqimage: ImageRef

An ImageRef object that refers to an open FITS file that has DQ data of the input image.

Note

When DQ data are located in the same FITS file as the science image data (e.g., HST/ACS, HST/WFC3, etc.), dqimage may point to the same ImageRef object. In this case the reference count of the ImageRef object must be increased adequately.

dqext: tuple, int, str

Extension specification of the dqimage that contains image’s DQ information. See help for ext for more details on acceptable formats for this parameter.

usermask: ImageRef

An ImageRef object that refers to an open FITS file that has user mask data that indicate what pixels in the input image should be used for sky computations (1) and which pixels should not be used for sky computations (0).

usermask_ext: tuple, int, str

Extension specification of the usermask mask file that contains user’s mask data that should be associated with the input image and ext. See help for ext for more details on acceptable formats for this parameter.