sidescanpy.export.windows.geo

Real-meters export windows: the geometric and georef render levels.

extract_geo_style_window() resamples a loaded neighborhood (see sidescanpy.export.windows.neighborhood) into a size_px square grid at one resolution_m on both axes, for any style, and places the window’s targets in it. geometric grids are along/across-track meters; georef grids are UTM northing/easting.

2026 rshomberg@uri.edu

Contents

SWATH_FILL_PCT	Percentile of per-ping reach that sets a swath_fill frame's edges.
RESAMPLE_METHODS	Geometric-level resamplers (see extract_geo_style_window()).
swath_fill_extent	Across-track (lo, hi) meters the recorded data fills, for a swath frame.
geo_targets_within_window	Candidates whose real position falls inside a geometric window.
georef_targets_within_window	Candidates whose per-sample lat/lon falls inside a georef window.
extract_geo_style_window	geometric or georef window for one style, with its targets.

sidescanpy.export.windows.geo.SWATH_FILL_PCT = 10.0

Percentile of per-ping reach that sets a swath_fill frame’s edges.

The far edge is where at least 100 - SWATH_FILL_PCT % of pings still have data; the near (nadir-side, single swath only) edge is where at least that share already do. Longer-reaching pings are cropped slightly instead of every row carrying an empty margin.

sidescanpy.export.windows.geo.RESAMPLE_METHODS = ('kdtree', 'binned', 'griddata')

Geometric-level resamplers (see extract_geo_style_window()).

sidescanpy.export.windows.geo.swath_fill_extent(across, values, *, combine, channel_idx)

Across-track (lo, hi) meters the recorded data fills, for a swath frame.

A sample counts only where both its coordinate and its backscatter are finite (in slant mode the coordinate is finite everywhere, including the masked nadir gap).

Parameters:

across, valuesnp.ndarray

(ping, channel, sample) signed across-track meters and backscatter.

combinebool

True (dual swath): port’s far edge to starboard’s far edge, not centered on nadir; a side with no data mirrors the other so nadir stays centered. False (single swath): channel_idx’s near edge to its far edge.

channel_idxint or None

Channel for combine=False.

Returns:

tuple of float or None

None when there is no usable data.

sidescanpy.export.windows.geo.geo_targets_within_window(candidates, masked, lo, along_dist, size_px, meta, locate_fn, along_size_px=None, *, margin_px=0.0)

Candidates whose real position falls inside a geometric window.

The real-world counterpart of targets_within_window(): each candidate’s along-track distance (at its ping) and across-track meters (at its own channel and sample) are located in the window with locate_fn and kept if inside the grid. Candidates outside masked’s pings or sample axis, or with no finite across-track value, are skipped.

Parameters:

candidateslist of (Target, int)

Targets and their pings, where ping - lo indexes masked.

maskedxr.Dataset

The neighborhood the window was resampled from.

loint

Ping offset of masked.

along_distnp.ndarray

Along-track distance per masked ping, as used for the window.

size_pxint

Grid column count (and row count unless along_size_px).

metadict

The window extractor’s meta.

locate_fncallable

(along_m, across_m, meta) -> (row, col), e.g. locate_point().

along_size_pxint, optional

Grid row count when it differs from size_px.

margin_pxfloat, default 0.0

Also keep candidates up to this many pixels outside the grid (for background-window exclusion).

Returns:

list of Target

Copies with window-local sample (column) and extra_attributes["window_row"], before orientation (see flip_geo_vertical()).

sidescanpy.export.windows.geo.georef_targets_within_window(candidates, masked, lo, meta, size_px, *, margin_px=0.0)

Candidates whose per-sample lat/lon falls inside a georef window.

Like geo_targets_within_window(), but each candidate is located by latitude_per_sample/longitude_per_sample at its ping, channel and sample with locate_point(). Candidates without a finite position are skipped.

Returns:

list of Target

Copies with window-local sample/extra_attributes["window_row"].

sidescanpy.export.windows.geo.extract_geo_style_window(masked, *, center_sample, channel_idx, local_ping, style, level, size_px, jitter_px, rng, mps, items_by_channel, lo, primary=None, resolution_m_override=None, backscatter_var='backscatter_intensity', resample_method='griddata', swath_fill=False)

geometric or georef window for one style, with its targets.

Resolution (unless resolution_m_override): chip – the native max(meters_per_sample, ping_spacing); swath styles – the swath width over size_px, floored at the ping spacing. With swath_fill (swath styles, no override) the frame instead spans the across-track extent the data fills (swath_fill_extent()) at square pixels, with no ping-spacing floor and not pinned to nadir.

geometric windows include every co-located candidate from items_by_channel (both channels for dual swath) and are oriented with orient_geo_window(). georef windows carry only the primary target and are not reoriented (rows follow northing).

resample_method selects the geometric resampler: "kdtree" (average of measurements within a search radius; no fabricated values, some directional blur), "binned" (per-cell mean of the samples inside it; empty cells stay NaN) or "griddata" (scipy interpolation; no gaps inside coverage, but at a resolution finer than the ping spacing most cells are interpolated). georef windows use extract_georef_window(): with "griddata", scipy interpolation in the map frame (cells farther than the largest typical ping gap from every sample are NaN); with "kdtree" or "binned", the mean within that radius.

Parameters:

maskedxr.Dataset

Loaded neighborhood (see GeoNeighborhood).

center_sampleint

Window center on channel_idx’s sample axis (masked units).

channel_idxint

Channel of the center sample (and of a single-channel window).

local_pingint

Center ping, indexed into masked.

style, levelstr

See sidescanpy.export.windows.levels.

size_px, jitter_pxint

Output size and center jitter (pixels at resolution_m).

rngnp.random.Generator

mpsfloat

masked’s meters per sample.

items_by_channeldict

{channel: [(target, ping), ...]}, ping - lo indexing masked.

loint

primaryTarget, optional

The window’s own target (positioned at center_sample). None for a background window: every candidate is searched and the result lists only candidates found inside.

resolution_m_overridefloat, optional

backscatter_varstr, default “backscatter_intensity”

Variable resampled into the grid.

resample_methodstr, default “griddata”

swath_fillbool, default False

Returns:

RenderedWindow or None

None when the window can’t be built: center sample outside masked, geometry/georef variables missing, no finite geometry around the center, or (georef, or a background chip) a center sample with no position.