sidescanpy.viz

Thin plotting helpers for SideScan sonar data.

Each function renders one result onto a matplotlib Axes (creating a figure when none is given) and returns the Axes or (Figure, Axes) so callers can compose or customize it. Nothing here saves files or runs corrections: saving, multi-panel layouts and workflow belong to the caller (see the examples in examples/). Requires the viz extra (matplotlib).

Public functions

• plot_waterfall() — port+starboard waterfall image with configurable x-axis (sample, ground_range, across_track, slant_range) and y-axis (ping, time, along_track) modes.

• resolve_waterfall_axes() — pick x/y axis mode for a correction’s step set (geometric corrections always render in real-world distance).

• plot_survey_overview() — compressed, whole-survey waterfall (strided ping axis) with optional break markers at caller-supplied ping indices, e.g. file boundaries in a multi-file concatenated survey.

• plot_gridded_raster() — 2D heatmap of one gridded raster.

• plot_grid_coverage() — the same raster, each cell’s opacity set by how many samples fell in it.

• plot_track_and_scanlines() — full-survey nadir track plus periodic port/starboard scan-line rungs, in a projected (UTM by default) coordinate system. Geometry/coverage only, no backscatter. The track comes from sidescanpy.processing.build_survey_track().

• plot_track_with_targets() — the same, with target catalog positions overlaid.

• plot_target_position_scatter() — plain lat/lon scatter of targets.

• contact_sheet() — grid of image thumbnails, one Figure.

• render_target_context() — one window image with a box at a target.

• sidescanpy.viz.analysis — one plot per analysis result (value histograms, outlier comparison, nadir zoom/waterfall, beam geometry, usable range, segments overview, navigation summary).

• sidescanpy.viz.tvg — TVG plots: plot_tvg_fit() (model fit and after-TVG check), mean vs. range, gain curve; the deprecated range-decay plots (candidate fits, decay fit and residuals, fit-window limits).

• resolve_cmap() — a colormap that renders NaN black, the convention every sidescanpy plot follows.

• sidescanpy.viz.scalebar, sidescanpy.viz.basemap (maps extra) — overlays used by the map-style plots.

2026 rshomberg@uri.edu

Contents

resolve_cmap

Return a Colormap with NaN cells set to render as NAN_COLOR.

Modules

• analysis
• basemap
• contact_sheet
• gridded
• scalebar
• targets
• track
• tvg
• waterfall

sidescanpy.viz.resolve_cmap(cmap)

Return a Colormap with NaN cells set to render as NAN_COLOR.

Accepts either a registered colormap name or an existing Colormap instance, matching every call site’s existing cmap: str | Colormap signature. Always returns a copy so the shared, registry-wide colormap object referenced by a bare name is never mutated in place.