MRT-based Satellite Trails Detection

This module identifies satellite trails in ACS/WFC imaging with the Median Radon Transform (MRT).

It contains a class called TrailFinder that is used to identify satellite trails and/or other linear features in astronomical image data. To accomplish this goal, the MRT is calculated for an image. Point sources are then extracted from the MRT and filtered to yield a final catalog of trails, which can then be used to create a mask.

A second class called WfcWrapper is designed explicitly to make ACS/WFC data easy to process.

This algorithm is found to be roughly 10x more sensitive compared to the current satellite trail finding code included with acstools, Satellite Trails Detection. However, this approach can struggle with dense fields, while the performance of Satellite Trails Detection in these fields may be more reliable (but this has not yet been tested).

For further details on this algorithm and tests of its performance, see the ISR ACS 2022-8.

Examples

Example 1: Identification of trails in an ACS/WFC image, j97006j5q_flc.fits (the second science and DQ extensions).

To load the data:

>>> import numpy as np
>>> from astropy.io import fits
>>> from acstools.findsat_mrt import TrailFinder
>>> file = 'j97006j5q_flc.fits'
>>> with fits.open(file) as h:
>>>     image = h['SCI', 2].data
>>>     dq = h['DQ', 2].data

Mask some bad pixels, remove median background, and rebin the data to speed up MRT calculation:

>>> from astropy.nddata import bitmask, block_reduce
>>> mask = bitmask.bitfield_to_boolean_mask(
...     dq, ignore_flags=[4096, 8192, 16384])
>>> image[mask] = np.nan
>>> image = image - np.nanmedian(image)
>>> image = block_reduce(image, 4, func=np.nansum)

Initialize TrailFinder and run these steps:

>>> s = TrailFinder(image, processes=8)  # initialization
>>> s.run_mrt()                       # calculates MRT
>>> s.find_mrt_sources()              # finds point sources in MRT
>>> s.filter_sources()                # filters sources from MRT
>>> s.make_mask()                     # makes a mask from the identified trails
>>> s.save_output()        # saves the output

The input image, mask, and MRT (with sources overlaid) can be plotted during this process:

>>> s.plot_mrt(show_sources=True)      # plots MRT with sources overlaid
>>> s.plot_image(overlay_mask=True)    # plots input image with mask overlaid

Example 2: Quick run to find satellite trails.

After loading and preprocessing the image (see example above), run the following:

>>> s = TrailFinder(image, processes=8)  # initialization
>>> s.run_all()                              # runs everything else

Example 3: Run identification/masking using the WFC wrapper.

WfcWrapper can automatically do the binning, background subtraction, and bad pixel flagging:

>>> from acstools.findsat_mrt import WfcWrapper
>>> w = WfcWrapper('jc8m32j5q_flc.fits', preprocess=True, extension=4, binsize=2)

In all other respects, it behaves just like TrailFinder, so to continue the process:

>>> w.run_mrt()
>>> w.find_sources()
>>> w.filter_sources()
>>> w.make_mask()

Or the entire process can be run in a single line with

>>> w = WfcWrapper('jc8m32j5q_flc.fits', preprocess=True, extension=4, binsize=2,
...                execute=True)

Classes

`TrailFinder`(image[, header, image_header, ...])	Top-level class to handle trail identification and masking.
`WfcWrapper`(image_file[, extension, binsize, ...])	Wrapper for `TrailFinder` designed specifically for ACS/WFC data.

Helper Functions

Various helper functions for MRT-based Satellite Trails Detection.

Functions

`merge_tables`(tbls[, theta_sep, rho_sep])	Merge multiple trail tables together while removing duplicates.
`good_indices`(inds, shape)	Ensures indices are within bounds of array.
`fit_streak_profile`(yarr, p0[, ...])	Fits a Gaussian to a 1D cross-section of a trail in an image.
`rotate_image_to_trail`(image, endpoints)	Rotates an image so a given trail runs in the horizontal direction.
`filter_sources`(image, streak_positions[, ...])	Filter trail catalog of likely spurious sources.
`create_mask`(image, trail_id, endpoints, widths)	Creates an image mask given a set of trail endpoints and widths.
`rotate`(origin, point, angle)	Rotate a point counterclockwise by a given angle around a given origin.
`streak_endpoints`(rho, theta, sz[, plot])	Get endpoints of a trail using rho and theta coordinates and image size.
`streak_persistence`(cutout, dx, streak_y0, ...)	Measure streak persistence across image.
`add_streak`(image, width, value[, rho, ...])	Generates a (optionally) PSF-convolved model trail and add it to an image.
`rot_sum`(image, angle, return_length)	Rotates and image by a designated angle and sums the values in each column.
`rot_med`(image, angle, return_length)	Rotates and image by a designated angle and take a median in each column.
`radon`(image[, theta, circle, ...])	Calculates the (median) radon transform of an image.
`create_mrt_line_kernel`(width, sigma[, ...])	Creates a model signal MRT signal of a line of specified width.
`update_dq`(filename, ext, mask[, dqval, ...])	Update the given image and DQ extension with the given satellite trails mask and flag.