sidescanpy.io.sdf.reader

Klein SDF file reader.

Iterates pages in a Klein SDF file. Each page has: - A 4-byte sync marker (always 0xFFFFFFFF) - A 512-byte typed header (described by SDFPageHeader) - Variable-length body (sonar samples for sonar pages, raw bytes otherwise)

The reader handles file-level concerns: marker validation, header parsing, page-version dispatch, and sample data extraction. The pages module defines what a page IS (typed structures); the reader handles WHERE pages are.

Three entry points: - read_sdf_header(f): low-level, reads marker + header at current position - read_sdf(path): eager, returns list of all pages (sonar + unknown) - read_sdf_iter(path): lazy, yields pages one at a time

On a bad marker, logs a warning and scans forward (up to 1 MB) looking for the next valid marker. This is robust to small corruption, mid-page truncation, or our own header parsing errors.

For sonar pages, the body is parsed into port and starboard sample arrays, with any remaining bytes preserved in extension_bytes for future decoding. For non-sonar pages, the entire body is preserved in body_bytes.

2026 rshomberg@uri.edu

Contents

MAX_MARKER_SCAN_BYTES	int([x]) -> integer int(x, base=10) -> integer
read_sdf_header	Read marker + header from the current file position.
read_sdf	Read all pages from a Klein SDF file (eager).
read_sdf_iter	Iterate pages from a Klein SDF file (lazy).

sidescanpy.io.sdf.reader.MAX_MARKER_SCAN_BYTES = 1048576

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.sdf.reader.read_sdf_header(f)

Read marker + header from the current file position.

Validates the marker, then parses the next 512 bytes as an SDFPageHeader. Advances the file pointer by 516 bytes total. Caller is responsible for handling sonar/non-sonar dispatch and for reading the page body.

Parameters:

fBinaryIO

Open file with pointer at the start of a page (marker position).

Returns:

SDFPageHeader

Raises:

ValueError

If the marker is invalid, the input is truncated, or header parsing fails.

sidescanpy.io.sdf.reader.read_sdf(path)

Read all pages from a Klein SDF file (eager).

Includes both sonar pages (SDFSonarPage) and non-sonar pages (SDFUnknownPage). Caller can filter by type if needed.

Parameters:

pathPath or str

Path to a Klein SDF file.

Returns:

list[SDFPage]

All pages in file order.

sidescanpy.io.sdf.reader.read_sdf_iter(path)

Iterate pages from a Klein SDF file (lazy).

Yields both sonar pages (SDFSonarPage with port/stbd data) and non-sonar pages (SDFUnknownPage with raw body bytes). On bad markers or parsing errors, logs a warning and scans forward to find the next valid marker.

Parameters:

pathPath or str

Path to a Klein SDF file.

Yields:

SDFPage

Either SDFSonarPage or SDFUnknownPage.

Raises:

FileNotFoundError

If the file does not exist.