sidescanpy.export.windows.neighborhood

Bounded, block-averaged ping neighborhoods for geometric/georef windows.

A geometric or georef window is resampled from the pings around its center. load_geo_neighborhood() loads only those pings, only the variables the resample reads, nadir-masks them at native resolution, and block-averages them down to about SWATH_OVERSAMPLE source cells per output pixel per axis – loading a full-swath neighborhood of every per-sample array at native resolution costs gigabytes per window on a real survey.

2026 rshomberg@uri.edu

Contents

SWATH_OVERSAMPLE	Source cells kept per output pixel, per axis, after block averaging.
SWATH_LOAD_BLOCK_PINGS	Pings loaded and masked per piece in load_swath_neighborhood().
SWATH_LOAD_VARS	Variables the geometric/georef resample and the nadir mask read.
neighborhood_ping_spacing_m	Mean along-track meters per ping over pings [lo, hi).
across_values	Signed across-track coordinate (port negative) for a geometric window.
geo_decimation	Neighborhood half-span and block-average factors for one style.
load_swath_neighborhood	Nadir- and dropout-masked pings [lo, hi), block-averaged by fp pings x fs samples.
decimate_target	target in a block-averaged neighborhood's (fp, fs) pixel units.
GeoNeighborhood	A loaded, block-averaged neighborhood for geometric/georef windows.
load_geo_neighborhood	Block-averaged neighborhood around ping_idx serving every style in styles.

sidescanpy.export.windows.neighborhood.SWATH_OVERSAMPLE = 2.0

Source cells kept per output pixel, per axis, after block averaging.

sidescanpy.export.windows.neighborhood.SWATH_LOAD_BLOCK_PINGS = 2048

Pings loaded and masked per piece in load_swath_neighborhood().

sidescanpy.export.windows.neighborhood.SWATH_LOAD_VARS

Variables the geometric/georef resample and the nadir mask read.

sidescanpy.export.windows.neighborhood.neighborhood_ping_spacing_m(ds_full, lo, hi)

Mean along-track meters per ping over pings [lo, hi).

Navigation stalls (repeated fixes) are filled before measuring. 0.0 for fewer than two pings.

sidescanpy.export.windows.neighborhood.across_values(ds, across_axis)

Signed across-track coordinate (port negative) for a geometric window.

"ground": across_track_m (ground-projected). "slant": slant_range_m with the same sign convention – still meters, so a window covers the same real extent on both axes, but the water column is kept (slant_range_m is finite everywhere; the nadir mask still blanks the backscatter there).

Raises:

ValueError

Unknown across_axis.

KeyError

"slant" without slant_range_m in ds.

sidescanpy.export.windows.neighborhood.geo_decimation(ds_full, ping_idx, style, *, size_px, jitter_px, resolution_m, across_axis='ground', swath_fill=False, margin_m=0.0)

Neighborhood half-span and block-average factors for one style.

The half-span (pings) covers the output window in meters – size_px * resolution_m along-track plus jitter and margin_m – with slack for turns and edge-shifting. The (ping, sample) factors keep about SWATH_OVERSAMPLE source cells per output pixel.

Parameters:

ds_fullxr.Dataset

The whole (lazy) frequency channel.

ping_idxint

Window center ping.

stylestr

"chip", "single-swath" or "dual-swath".

size_px, jitter_pxint

Output size and jitter of the window.

resolution_mfloat or None

Output meters per pixel; None estimates the value extract_geo_style_window() will choose (chip: max(meters_per_sample, ping_spacing); swath styles: swath width / size_px, floored at the ping spacing unless swath_fill).

across_axisstr, default “ground”

See across_values().

swath_fillbool, default False

Estimate resolution the way swath_fill windows choose it.

margin_mfloat, default 0.0

Extra along-track meters the neighborhood must cover beyond the window (background windows load enough to check nearby targets).

Returns:

(half_span_pings, fp, fs)

sidescanpy.export.windows.neighborhood.load_swath_neighborhood(ds_full, lo, hi, fp, fs, *, with_db, extra_vars=(), skip_vars=())

Nadir- and dropout-masked pings [lo, hi), block-averaged by fp pings x fs samples.

Loads only SWATH_LOAD_VARS (plus extra_vars, minus skip_vars) in SWATH_LOAD_BLOCK_PINGS-sized pieces, masking each piece at native resolution (nadir gap, and dropouts with mask_dropouts()) before averaging. sample_rate_hz is divided by fs so nominal_sample_interval_m() reports the averaged cell size.

Parameters:

ds_fullxr.Dataset

The whole (lazy) frequency channel.

lo, hiint

Ping range.

fp, fsint

Ping and sample block-average factors (partial edge blocks are trimmed).

with_dbbool

Also add backscatter_db.

extra_vars, skip_varstuple of str

Variables to add to / remove from SWATH_LOAD_VARS.

Returns:

xr.Dataset

sidescanpy.export.windows.neighborhood.decimate_target(target, fs, fp)

target in a block-averaged neighborhood’s (fp, fs) pixel units.

Moves sample (integer division) and scales bbox (x by fs, y by fp).

class sidescanpy.export.windows.neighborhood.GeoNeighborhood(ds, target, local_ping, mps, items, lo, fp=1, fs=1)

Bases: object

A loaded, block-averaged neighborhood for geometric/georef windows.

Attributes:

dsxr.Dataset

The averaged neighborhood (see load_swath_neighborhood()).

targetTarget or None

The window’s primary target in averaged units (None for a window with no primary target).

local_pingint

Center ping, indexed into ds.

mpsfloat

Averaged meters per sample.

itemsdict

{channel: [(target, ping), ...]} co-target candidates, in averaged units; ping maps file ping p to lo + (p - lo) // fp so that ping - lo indexes ds.

loint

File ping index of the neighborhood’s first ping.

fp, fsint

Ping and sample averaging factors.

to_averaged_sample(sample)

A native sample index in this neighborhood’s averaged sample units.

sidescanpy.export.windows.neighborhood.load_geo_neighborhood(ds_full, target, ping_idx, items_by_channel, styles, *, size_px, jitter_px, resolution_m, with_db, across_axis='ground', per_sample_latlon=True, swath_fill=False, margin_m=0.0)

Block-averaged neighborhood around ping_idx serving every style in styles.

Uses the widest half-span and finest averaging factors any of styles needs (see geo_decimation()), and translates target and items_by_channel into the averaged units.

Parameters:

ds_fullxr.Dataset

The whole (lazy) frequency channel.

targetTarget or None

Primary target (None for a background window).

ping_idxint

Center ping (file index).

items_by_channeldict

{channel: [(target, file_ping_idx), ...]} co-target candidates.

styleslist of str

size_px, jitter_px, resolution_m, across_axis, swath_fill, margin_m

See geo_decimation().

with_dbbool

Add backscatter_db.

per_sample_latlonbool, default True

Load latitude_per_sample/longitude_per_sample (only the georef level reads them).

Returns:

GeoNeighborhood

With across_axis="slant", ds["across_track_m"] is replaced by signed slant range (see across_values()), so every downstream geometric lookup works in slant meters.