sidescanpy.io.sdf.split#

Split one Klein SDF file’s pages into runs of constant sample interval.

The range setting can change mid-file. Klein keeps the metres per sample of a frequency only when the sample count scales with the range; on some recorders it does not (for example 2500 samples at 60 m, then 3334 at 40 m), so the sample interval changes. The survey model has one sample_rate_hz per frequency (computed by the converter from the first page), so such a file cannot become one survey without mapping some pings to the wrong range. split_by_sample_rate() cuts the pages into consecutive runs (in file order) within which every frequency keeps its sample rate, each run converted on its own by sidescanpy.io.sdf.convert().

Cut rule (same as the XTF split): a frequency’s rate is num_samples / range_m (proportional to the sample rate at constant sound speed). A run’s reference rate for a frequency is the first one it records; a page whose rate differs from that reference by more than rtol (relative) starts a new run, for every frequency. Pages without a positive range do not take part. Runs with fewer than min_pings pages of their most-recorded frequency are dropped (a range change often leaves a few pings at an intermediate setting); a file without a cut is kept whole.

2026 rshomberg@uri.edu

Contents

`SPLIT_RTOL`	Default relative change in sample rate that starts a new run.
`SPLIT_MIN_PINGS`	Default minimum run length (pings of the most-recorded frequency).
`sample_rate_runs`	Consecutive runs of constant sample rate, as `(start, stop)` page ranges.
`split_by_sample_rate`	Split one file's pages at sample-rate (range-setting) changes.

sidescanpy.io.sdf.split.SPLIT_RTOL = 0.01#: Default relative change in sample rate that starts a new run.

sidescanpy.io.sdf.split.SPLIT_MIN_PINGS = 50#: Default minimum run length (pings of the most-recorded frequency).

sidescanpy.io.sdf.split.sample_rate_runs(pages, *, rtol=0.01)#

Consecutive runs of constant sample rate, as (start, stop) page ranges.

Parameters:

pagessequence: Pages of one file in file order (non-sonar pages are allowed and never cause a cut).
rtolfloat, default 0.01: Relative change in a frequency’s rate that starts a new run.

Returns:

list[tuple[int, int]]: Half-open ranges over pages covering all of it; empty when pages is empty.

sidescanpy.io.sdf.split.split_by_sample_rate(pages, *, min_pings=50, rtol=0.01, source='')#

Split one file’s pages at sample-rate (range-setting) changes.

Parameters:

pagessequence: Pages of one file in file order (read_sdf()).
min_pingsint, default 50: Runs with fewer pings (of their most-recorded frequency) are dropped. Ignored when the file has a single run.
rtolfloat, default 0.01: Relative change in a frequency’s rate that starts a new run.
sourcestr, optional: File name for log messages.

Returns:

list[list]: The kept runs in file order. One run (the whole file) when the rate never changes; empty when every run is shorter than min_pings (logged at WARNING).