sidescanpy.io.jsf.converter

Convert JSFMessage objects into a SideScanSurvey.

The converter takes a flat list of mixed JSFMessages, dispatches by type internally, groups sonar messages by frequency, and produces a fully populated SideScanSurvey with one frequency channel per (start, end) pair plus aux records (navigation, attitude, dvl, sensors).

This module performs no I/O. The reader is responsible for parsing JSF bytes into JSFMessage instances and for any cross-file message ordering.

Starting depth

The sonar data message’s “starting depth (window offset) in samples” (SonarDataMessage.starting_depth_samples) is applied to the sample axis: it is taken as the number of sample intervals before the first recorded sample, so recorded sample i gets the absolute sample coordinate starting_depth + i and the slant range (starting_depth + i) x interval. When pings (or sides) differ in offset, each trace is placed at its own offset on a common axis starting at the smallest one, NaN elsewhere. The offset is 0 in every file seen so far; a nonzero one logs one WARNING per frequency, because that reading of the field has not been checked against a real file, and is recorded in jsf_starting_depth_min / jsf_starting_depth_max.

2026 rshomberg@uri.edu

Contents

convert

Convert a list of JSFMessages into a SideScanSurvey.

sidescanpy.io.jsf.converter.convert(messages, *, source_files, survey_name=None, repair_mode='nan_pad')

Convert a list of JSFMessages into a SideScanSurvey.

Parameters:

messageslist of JSFMessage

Mixed list of all message types from one or more JSF files.

source_fileslist of Path

File(s) the messages were parsed from. Stored on the survey.

survey_namestr, optional

Survey name. Defaults to source_files[0].stem.

repair_mode{“drop”, “nan_pad”, “abort”}, default “nan_pad”

How to handle unmatched port/starboard pings within a frequency: - “drop” : silently drop orphans - “nan_pad” : keep ping, fill missing channel with NaN - “abort” : raise ValueError on first orphan

Returns:

SideScanSurvey

Populated survey with one frequency channel per distinct (transmit_freq_start, transmit_freq_end) pair, plus aux records.

Raises:

ValueError

If messages is empty. If file-level attrs (transmit_freq_start/end, sweep_length, sample_freq, sample_interval) are not constant within a frequency group. If port and starboard sample counts disagree for a paired ping. If repair_mode == "abort" and an orphan ping is found.