sidescanpy.processing#

Processing functions for SideScan sonar surveys.

Each function takes a validated input dataset, applies a transform, and returns a new dataset with updated values, processing_level, and processing_history. Functions are pure (no in-place mutation by default) unless explicitly marked otherwise.

Public entry points#

interpolate_aux_onto_pings() — replace per-ping nav, attitude, and heave fields with values interpolated from the survey’s auxiliary records onto each ping’s timestamp.
held_value_fixes() — reduce a sample-and-hold aux record (the latest fix repeated at every ping or packet) to its real fixes; the interpolate_aux step does this by default.
aux_update_events() — change and update-event statistics of a sample-and-hold record, for choosing groups and merge_window_s.
interpolate_onto_channel() — lower-level: interpolate any xr.Dataset (e.g. an external GPS log) onto one channel’s ping times.
along_track_distance_m(), fill_nav_stalls() — cumulative along-track distance from ping lat/lon, and nav-stall repair.
apply_tvg() — apply time-varying gain (spreading + absorption) to backscatter. Converts raw linear amplitude to dB.
apply_tvg_to_amplitude() — same TVG correction as apply_tvg(), but on a plain (..., n_samples) array rather than a full xr.Dataset — for data that isn’t a survey channel (e.g. a target catalog’s own decoded crop window).
francois_garrison_absorption_db_per_m() / absorption_for_frequency() — seawater absorption (Francois-Garrison) defaults for typical coastal seawater.
correct(), correct_survey(), correct_file() — the one correction API: an ordered list of built-in or caller-supplied steps, each skippable, idempotent and recorded in processing_history (see sidescanpy.processing.correct).
invert(), uncorrected_backscatter() — undo recorded steps from their history records.
processing_level() — derived from processing_history.
Bottom / nadir handling (bottom): detect_first_bottom_return(), altitude_from_bottom_track() (the "bottom_track" step), detect_nadir_noise_extent(), blank_nadir_noise(), mask_nadir_gap(), uniform_exclusion_boundary() and helpers.
apply_layback() — move ship positions astern to the towfish (the "layback" step, layback).
reject_range_outliers() — per-range-bin MAD outlier rejection.
mask_bright_ping_rows() — mask whole outlier-bright ping rows.
Segments (segments): find_segments(), split_by_segments(), Segment and the individual detectors.
backscatter_vs_range() / backscatter_vs_sample() — binned backscatter profiles; median_level_profile() — median level per range bin in dB, for the TVG model fit.
build_survey_track() / SurveyTrack — nadir track plus strided swath-edge positions across a multi-file survey.

Conventions#

Corrections are applied in place to backscatter_intensity; no raw copy is kept (a legacy backscatter_raw is dropped on rewrite).
Every correction step appends one processing_history record with the parameters it used; a step already recorded is not re-applied.

See docs/processing.md for full reference.

2026 rshomberg@uri.edu

Modules