hierarchical_footprints

hierarchical_footprints#

scarlet2.detect.hierarchical_footprints(obs, scales=None, strict=True, K=3, split_peaks=True, image_type='ground', min_separation=0, min_area=9, thresh=0, catalog=None, flatten=True, return_detect=False)[source]#

Decompose an observed image into a list of HierarchicalFootprint objects.

Creates a detection image from the inverse-variance weighted sum of obs.data, then iterates from the largest starlet scale to the smallest. At each scale, every detected footprint is matched to the best-overlapping source already registered from larger scales (measured by IoU). If the registered source’s peak lies inside the new footprint, it is a primary match: the source peak is refined and its footprint is grown to the union. Otherwise, the new footprint becomes a child of the best-matching source. Footprints with no overlap with any registered source are promoted to new top-level sources.

When split_peaks is True (default), footprints that contain more than one peak are split into separate sources by using a watershed algorithm. Otherwise, additional peaks become children of the originating footprint.

If catalog is provided, the detected sources are matched to the catalog positions via a global bipartite assignment (Hungarian algorithm). The cost of assigning catalog entry i to source j is the squared distance from the catalog position to the nearest peak of source j, restricted to cases where the catalog position falls inside source j’s footprint mask. Catalog entries with no containing footprint are returned as None.

Each footprint’s bounding box is grown beyond the detection threshold to the noise level. Assuming an exponential profile I(r) = I0*exp(-r/h), the scale length h is estimated from the footprint size as h = r_foot / ln(S), where r_foot is the mean distance from the peak to the edge of the footprint bounding box and S = I0 / (K*sigma_j). The box is grown to the radius where the profile reaches the noise level (1*sigma_j): half_size = r_foot * ln(S*K) / ln(S).

Parameters:

  • obs (Observation) – The observation providing image data, per-pixel weights, and the coordinate frame used to convert centers to pixel positions.

  • scales (list of int, optional) – Starlet scales (indices into the coefficient array, default [1,2,3]) to use for detection.

  • strict (bool, optional) – If True, the coarse residual plane is pushed one scale higher so that the selected scales are cleanly separated without bleed from the largest-scale smooth background. Default False.

  • K (float, optional) – Detection threshold multiplier used when sigma_scales is given. Must match the value passed to get_detect_wavelets(). Default 3.

  • split_peaks (bool, optional) – If True (default), footprints with multiple peaks are split into separate sources using a watershed algorithm. Otherwise, additional peaks become children of the originating footprint, which retains the full footprint area, i.e. the children overlap. Splitting peaks allows to reduce the overlap of mostly independent sources.

  • image_type (str) – The type of image that is being used. This should be "ground" for ground based images with wide PSFs or "space" for images from space-based telescopes with a narrow PSF.

  • min_separation (float, optional) – Minimum pixel separation between peaks within a footprint.

  • min_area (int, optional) – Minimum number of pixels a footprint must contain to be kept. Also used as the minimum area for watershed sub-footprints when split_peaks is True.

  • thresh (float, optional) – Detection threshold; pixels must strictly exceed this value.

  • catalog (list of (y, x) tuples, optional) – If given, the output is catalog-indexed: one entry per catalog position, matched to the best overlapping detected source, or None if undetected. Matching is a global optimal assignment — each source is assigned to at most one catalog entry.

  • flatten (bool, optional) – Whether to flatten the source list so that children appear as independent entries. Default True.

  • return_detect (bool, optional) – Whether to return the detection image. Default False.

Returns:

sources – When catalog is None: top-level sources, each potentially carrying a tree of children. Sources detected only at finer scales appear as additional top-level entries with their scale set accordingly. When catalog is given: catalog-length list where each entry is the matched HierarchicalFootprint, or None if no source was detected at that catalog position.

Return type:

list of HierarchicalFootprint or None

Contents