Skip to content

Aperture

Adaptive aperture mask construction. The functions live at the top-level noobase.aperture namespace (not under noobase.image), but are listed alongside the image-domain pages here because they consume 2-D image cutouts.

grow_mask(data, seed_pixels, *, detection=None, err=None, label_map=None, label_allowed=None, connectivity='eight', shape_weight=1.0, min_neighbor_support=2, min_pixels_before_shape_gate=8, fill_min_cardinal_support=3, snr_threshold=<object object at 0x7faa155006a0>, snr_hysteresis=3, gradient_ratio_threshold=1.0, gradient_hysteresis=3, gradient_lo_percentile=75.0, gradient_hi_percentile=99.0, min_pixels_before_stop_check=30, check_interval=5, annulus_thickness=2)

Grow a boolean source mask outward from one or more seed pixels.

Growth is a greedy region grow on a max-heap. Each candidate pixel's priority is its detection value plus a shape reward proportional to how many of its neighbours are already in the mask, so growth fills concavities before extending arms. A hard min_neighbor_support floor (after a warm-up) refuses pixels with too few in-mask neighbours, forbidding one-pixel-wide tendrils. Two annulus stop criteria (SNR and radial gradient) decide when to stop, measured on data.

Parameters:

Name Type Description Default
data ndarray

2-D image of dtype float64. Used for the stop statistics and returned to the caller for photometry. Also the default heap key when detection is not given.

 required
seed_pixels sequence of (int, int) or ndarray of shape (N, 2)

One or more (row, col) starting pixels. All must lie inside data; when a label is given, all must sit on an allowed label. Seeds are admitted unconditionally.

 required
detection ndarray

2-D image, same shape and dtype as data, driving the heap priority. Pass a smoothed / matched-filter image here to keep growth from chasing single-pixel noise ridges; defaults to data (plain brightest-pixel growth).

 None
err ndarray

2-D 1-sigma error image, same shape and dtype as data. Required if (and only if) the SNR stop is enabled.

 None
label_map ndarray

2-D int32 segmentation map, same shape as data. Must be paired with label_allowed (both or neither).

 None
label_allowed sequence of int

Whitelisted labels the mask may occupy. Include the background label explicitly if growth into background is desired.

 None
connectivity (four, eight)

Pixel adjacency used for heap-neighbour expansion, neighbour support, and annulus dilation. Default "eight".

 "four"
shape_weight float

Soft compactness bias, in units of the heap-key image noise level (see the module docstring). 0 disables the soft term. Default 1.0.

 1.0
min_neighbor_support int

Hard floor on a candidate's in-mask neighbour count, enforced once min_pixels_before_shape_gate pixels are admitted. 2 forbids one-pixel-wide tendrils under either connectivity; 1 (or 0) disables the floor. Must not exceed the connectivity's neighbour count (4 or 8). Default 2.

 2
min_pixels_before_shape_gate int

Admitted-pixel count before the min_neighbor_support floor activates, letting the seed core establish itself first. Default 8.

 8
fill_min_cardinal_support int or None

Unconditional concavity fill (the closing counterpart to min_neighbor_support). A pixel with at least this many of its four cardinal neighbours already in the mask is admitted at once, regardless of flux, closing deep notches and enclosed holes. Must be 3 (closes three-walled notches and holes) or 4 (holes only); None disables it. Default 3. Source separation is left to the label gate, never this fill; a closed-over bad pixel joins the footprint for photometry to exclude.

 3
snr_threshold float

Threshold for the cumulative inner-annulus signal-to-noise stop. If unspecified, defaults to 2.0 when err is provided and to None otherwise (auto-follows err). Pass None to force-disable the SNR stop.

 <object object at 0x7faa155006a0>
snr_hysteresis int

Consecutive checks with SNR below threshold required to fire. Default 3.

 3
gradient_ratio_threshold float

Threshold for the mean(outer) / mean(inner) radial-gradient stop. > 1 corresponds to "outer is brighter than inner", i.e. the radial profile has flipped. Default 1.0. Pass None to disable the gradient stop.

 1.0
gradient_hysteresis int

Consecutive checks with ratio above threshold required to fire. Default 3.

 3
gradient_lo_percentile float

Each annulus is summarised, in the gradient ratio, by the mean of its pixels within this percentile band rather than a plain mean. The lower bound (default 75) drops the sky pixels that otherwise dilute the ring and hide a rising neighbour; the upper bound (default 99) trims isolated hot pixels by count (a multi-pixel neighbour survives). Must satisfy 0 <= lo < hi <= 100; (0, 100) recovers the plain mean.

 75.0
gradient_hi_percentile float

Each annulus is summarised, in the gradient ratio, by the mean of its pixels within this percentile band rather than a plain mean. The lower bound (default 75) drops the sky pixels that otherwise dilute the ring and hide a rising neighbour; the upper bound (default 99) trims isolated hot pixels by count (a multi-pixel neighbour survives). Must satisfy 0 <= lo < hi <= 100; (0, 100) recovers the plain mean.

 75.0
min_pixels_before_stop_check int

Lower bound on the admitted-pixel count before stop checks may fire. Default 30.

 30
check_interval int

Evaluate stop criteria every check_interval admitted pixels. Must be >= 1. Default 5.

 5
annulus_thickness int

Per-ring dilation iteration count. Default 2.

 2

Returns:

Type Description
GrowthResult

.mask (bool ndarray), .stop_reason ("snr_below" / "gradient_flip" / "filled"), .n_iterations (int). "filled" is the failure outcome: the cutout was too small for the source.

Raises:

Type Description
ValueError

For any invalid input — see the parameter descriptions for the constraints; the message identifies the specific violation.

GrowthResult

Result of grow_mask: the boolean source mask plus the termination reason and the heap-loop iteration count.

mask property

The boolean source mask, shape (rows, cols) matching the input data.

n_iterations property

Number of pixels admitted by the heap loop after the seeds. The total number of True pixels in mask equals n_iterations plus the (de-duplicated) seed count.

stop_reason property

Why the growth terminated. One of "snr_below", "gradient_flip", or "filled" — the last is the failure outcome (mask reached the cutout edge before any stop fired).