sidescanpy.export.windows.background#

Background (no-target) export windows.

A detector trained only on target-centered images never sees an empty frame. sample_background_windows() samples window centers across a set of converted surveys, renders each one through the same window extractors as target windows (extract_pixel_style_window(), extract_geo_style_window()), and keeps only windows that

contain no cataloged target within the window plus margin_m. Every catalog target (any confidence) is correlated to its ping with correlate_target(), projected onto every frequency of its file (place_catalog()), and located in the rendered window with the same lookup target windows use for co-located targets. A conservative geographic guard additionally rejects a window whose reach from nadir (plus margin) covers any target’s recorded lat/lon – this catches targets on another file, another line crossing the same ground, or targets that never correlated;
are mostly data: at most max_nan_frac of the rendered cells are NaN (outside coverage, nadir gap, cropped far range).

Background windows are only as clean as the target catalog: an object the catalog misses can appear in one and be learned as background.

2026 rshomberg@uri.edu

Contents

`BackgroundCandidate`	A sampled background window center.
`WindowFootprint`	Real-world extent of a rendered window.
`BackgroundWindow`	One accepted background window, rendered and ready to write.
`nan_fraction`	Fraction of non-finite cells in `image`.
`sample_background_candidates`	Draw `n` window centers, uniformly by ping over every allowed ping.
`sample_background_windows`	Sample, render and screen `n` background windows for one style.

class sidescanpy.export.windows.background.BackgroundCandidate(path, freq_key, ping, channel, sample)#

Bases: object

A sampled background window center.

Attributes:

pathPath: Source .ss.h5 file.
freq_keystr: Frequency channel.
pingint: File ping index of the center.
channelint: Side of the center sample (0 = port); the channel of a single-channel window.
sampleint: Center sample on channel.

class sidescanpy.export.windows.background.WindowFootprint(frame, rows, cols, reach_m)#

Bases: object

Real-world extent of a rendered window.

Attributes:

framestr: "pixel": rows are file pings, cols the style’s column space (samples, or combined columns for dual swath). "geometric": rows along-track and cols across-track meters, in the loaded neighborhood’s frame. "georef": rows northing and cols easting meters in the window’s UTM zone.
rows, colstuple of float: (min, max) bounds, before margin_m.
reach_mfloat: Upper bound on the distance from the center ping’s nadir to any point of the window (used by the geographic guard).

class sidescanpy.export.windows.background.BackgroundWindow(index, candidate, style, draw, across_center_m, footprint, window, nan_fraction)#

Bases: object

One accepted background window, rendered and ready to write.

Attributes:

indexint: Placement number within this style (0-based, in acceptance order).
candidateBackgroundCandidate
stylestr
drawint: Draw index for n_draws > 1 (independent jitter around the same center).
across_center_mfloat or None: Signed across-track meters of the center sample (across_track_m, else signed slant range).
footprintWindowFootprint
windowRenderedWindow: window.targets is empty.
nan_fractionfloat

sidescanpy.export.windows.background.nan_fraction(image)#: Fraction of non-finite cells in image.

sidescanpy.export.windows.background.sample_background_candidates(index, n, rng, *, freq_keys=None, ping_ranges=None)#

Draw n window centers, uniformly by ping over every allowed ping.

Parameters:

indexdict: From build_position_index().
nint: Number of candidates.
rngnp.random.Generator
freq_keyssequence of str, optional: Frequencies to sample (default: every frequency in index).
ping_rangesmapping, optional: {file_name: [(start, stop), ...]} allowed half-open ping ranges per file (keyed by Path.name). Files absent from the mapping contribute no pings; None allows every ping of every file.

Returns:

list of BackgroundCandidate: Empty if no ping is allowed. Channel and center sample are uniform.

sidescanpy.export.windows.background.sample_background_windows(index, catalog, spec, n, rng, *, freq_keys=None, ping_ranges=None, margin_m=0.0, max_nan_frac=0.3, max_match_dist_m=25.0, n_draws=1, max_attempts=None, candidates=None)#

Sample, render and screen n background windows for one style.

Candidates come from sample_background_candidates() (or from candidates), one at a time, until n are accepted or max_attempts are spent. A candidate is rendered n_draws times (independent jitter around the same center, as n_augment does for targets); it is accepted when its first draw passes, and each later draw is kept only if it passes too. A draw passes when it has no catalog target inside the window plus margin_m (the frame check and the geographic guard; see the module docstring) and at most max_nan_frac NaN cells.

Parameters:

indexdict: From build_position_index().
catalogsequence of Target: Every cataloged target, regardless of confidence.
specWindowSpec: Style and rendering settings – the same ones target windows use.
nint: Accepted windows wanted (each contributing up to n_draws draws).
rngnp.random.Generator: Drives candidate sampling and jitter.
freq_keys, ping_ranges: See sample_background_candidates().
margin_mfloat, default 0.0: Extra clearance around the window, meters.
max_nan_fracfloat, default 0.3
max_match_dist_mfloat, default 25.0: Catalog correlation distance (see place_catalog()).
n_drawsint, default 1
max_attemptsint, optional: Candidates to try before giving up (default 50 * n).
candidatesiterable of BackgroundCandidate, optional: Caller-chosen centers to screen, in order, instead of sampling; freq_keys/ping_ranges are then not applied.

Returns:

list of BackgroundWindow: In acceptance order; fewer than n placements (with a warning) if the attempts run out.