sidescanpy.export.windows.levels#

Export styles, render levels, and the backscatter variables each level reads.

A style is the window shape (chip: a tight single-channel crop; single-swath: one full channel; dual-swath: both channels side by side). A render level is the processing state and coordinate system the window is rendered in: uncorrected/db/radiometric crop native sample/ping pixels; geometric/georef resample onto a real-meters grid.

Neither uncorrected nor backscatter_db is stored on disk: they are derived per loaded neighborhood by with_uncorrected_var() and with_db_var().

2026 rshomberg@uri.edu

Contents

`CHIP_STYLES`	Export window styles.
`RENDER_LEVELS`	Render levels, in correction order.
`PIXEL_LEVELS`	Render levels cropped in native sample/ping pixels (no `resolution_m`).
`LEVEL_VARS`	Value name (pixel render level, or geometric/georef `value_var`) -> backscatter variable.
`mask_nadir_gap_with_uncorrected`	`mask_nadir_gap()`, plus `uncorrected`.
`mask_dropouts`	Set dropout samples (recorded amplitude exactly zero) to NaN.
`with_db_var`	Add `backscatter_db` (`20*log10` of the uncorrected signal, no TVG gain).
`nominal_sample_interval_m`	Slant-range meters per sample at `ds`'s first ping.
`WindowSpec`	How one export style is rendered.

sidescanpy.export.windows.levels.CHIP_STYLES = ('chip', 'single-swath', 'dual-swath')#: Export window styles.

sidescanpy.export.windows.levels.RENDER_LEVELS = ('uncorrected', 'db', 'radiometric', 'geometric', 'georef')#: Render levels, in correction order.

sidescanpy.export.windows.levels.PIXEL_LEVELS = ('uncorrected', 'db', 'radiometric')#: Render levels cropped in native sample/ping pixels (no resolution_m).

sidescanpy.export.windows.levels.LEVEL_VARS#: Value name (pixel render level, or geometric/georef value_var) -> backscatter variable.

sidescanpy.export.windows.levels.mask_nadir_gap_with_uncorrected(ds)#

mask_nadir_gap(), plus uncorrected.

uncorrected is derived from the masked intensity, so both carry the same NaN nadir gap.

sidescanpy.export.windows.levels.mask_dropouts(ds)#

Set dropout samples (recorded amplitude exactly zero) to NaN.

A sample recorded as zero carries no measurement. It is found on uncorrected (every radiometric step undone; at or below MIN_LINEAR), which works whatever the correction state, including files corrected before TVG kept such samples at the dB floor, and masked in backscatter_intensity and uncorrected. Resampling then interpolates over it instead of spreading it into a dark spot.

Parameters:

dsxr.Dataset: Loaded channel with uncorrected (mask_nadir_gap_with_uncorrected()).

Returns:

xr.Dataset: ds itself when nothing is masked, otherwise a copy.

sidescanpy.export.windows.levels.with_db_var(ds)#

Add backscatter_db (20*log10 of the uncorrected signal, no TVG gain).

The same raw-to-dB step apply_tvg_to_amplitude() takes before adding gain.

sidescanpy.export.windows.levels.nominal_sample_interval_m(ds)#

Slant-range meters per sample at ds’s first ping.

Uses sample_rate_hz from ds.attrs (block-averaged neighborhoods divide it by their sample factor, so this reports the averaged cell size). Invalid sound velocity falls back to 1500 m/s as in sample_interval_m(), without its per-call warning (this is called once per exported window).

class sidescanpy.export.windows.levels.WindowSpec(style, level, size_px, jitter_px=0, resolution_m=None, value_var='radiometric', resample_method='griddata', across_axis='ground', swath_fill=False)#

Bases: object

How one export style is rendered.

Attributes:

stylestr: One of CHIP_STYLES.
levelstr: One of RENDER_LEVELS.
size_pxint: Output size (both axes).
jitter_pxint, default 0: Uniform center jitter, in output pixels.
resolution_mfloat, optional: Geometric/georef meters per output pixel; None chooses it per window (see extract_geo_style_window()).
value_varstr, default “radiometric”: Geometric/georef value (a key of LEVEL_VARS). Pixel levels read the level’s own variable.
resample_methodstr, default “griddata”: Geometric resampler.
across_axisstr, default “ground”: Geometric across-track axis ("ground" or "slant").
swath_fillbool, default False: Geometric swath styles: frame the across-track extent the data fills.

property is_pixel#: Whether the level crops native sample/ping pixels.

property backscatter_var#: Variable a geometric/georef window resamples.

property needs_db#: Whether backscatter_db must be derived for this spec.