sidescanpy.io.hdf5#

HDF5 IO for full SideScanSurvey objects.

This module reads and writes complete SideScanSurvey objects — multiple frequency channels plus optional navigation, attitude, DVL, and sensor auxiliary records — as a single .ss.h5 file with a grouped layout.

For single-frequency channels in standalone NetCDF, see sidescanpy.io.netcdf.

Public entry points#

read_survey() — read a .ss.h5 file back into a validated survey. Accepts chunks= for lazy/dask-backed loading of frequency channel data.
write_survey() — write a survey to disk with grouped layout and per-variable encoding.
read_survey_dir(), load_channel_dataset(), available_frequencies(), concat_survey_frequency() — multi-file directory reading (see survey_dir).
check_disk_space(), atomic_write_survey() — in-place rewrite support.

File layout#

/                           (root: survey_name, source_format,
│                            source_files_json)
/frequencies/
    hz_<freq>/              (per SideScanFrequencyChannel)
    ...
/aux_streams/
    navigation/             (always written, may be empty)
    attitude/
    dvl/
    sensors/
        <sensor_type>/      (only if any sensors present)

Conventions#

Engine: h5netcdf.
Aux records always written, even when empty (zero obs). The reader returns them as empty-but-valid datasets; has_navigation/has_attitude/has_dvl correctly report False in that case.
Compression: gzip level 4 on backscatter only. Aux records are tiny and stored uncompressed.
chunks= applies only to frequency channels. Aux records always load eagerly regardless.

See docs/format/ss_h5.md for full reference.

2026 rshomberg@uri.edu

Modules