sidescanpy.viz.track

Survey track + scan-line plotting.

Full-survey overview: the vessel’s nadir track plus periodic “rungs” showing the port/starboard scan-line (swath edge) positions, in a projected coordinate system (UTM by default). Each rung is split at nadir and its two halves are colored by side (port red, starboard green by default, the navigation-light convention). Distinct from plot_waterfall (per-ping backscatter imagery) and plot_gridded_raster (resampled backscatter raster) — this shows geometry/coverage only, no backscatter values.

sidescanpy.processing.build_survey_track builds the lat/lon arrays this plot needs from a multi-file survey dict.

2026 rshomberg@uri.edu

Contents

plot_track_and_scanlines

Plot a survey's nadir track plus periodic port/starboard scan-line "rungs", in a projected coordinate system.

sidescanpy.viz.track.plot_track_and_scanlines(track_lat, track_lon, scan_port_lat, scan_port_lon, scan_stbd_lat, scan_stbd_lon, *, crs=None, fig=None, ax=None, title=None, show_land=False, show_locator=False, show_scale_bar=True, scan_nadir_lat=None, scan_nadir_lon=None, port_color='tab:red', starboard_color='tab:green')

Plot a survey’s nadir track plus periodic port/starboard scan-line “rungs”, in a projected coordinate system. Each rung is drawn as two halves, nadir to port edge and nadir to starboard edge, colored by side.

Parameters:

track_lat, track_lonarray

Per-ping nadir position (WGS84 degrees) — one point per ping, drawn as a continuous line.

scan_port_lat, scan_port_lon, scan_stbd_lat, scan_stbd_lonarray

Port/starboard swath-edge position (WGS84 degrees), same length, index-aligned — typically a strided subset of pings (drawing a rung per ping is unreadable/slow for a full survey). Each index draws one port-to-starboard line segment.

crspyproj.CRS, optional

Target CRS to project into. Defaults to an auto-selected UTM zone from the track’s centroid (see sidescanpy.grids.utm_crs_for_lonlat).

fig, axoptional

Existing figure/axes to draw into.

titlestr, optional

Plot title. Default includes point/rung counts and the CRS.

show_landbool, default False

Draw land/water context (vendored 1:50m Natural Earth data) behind the track — see sidescanpy.viz.basemap. Requires the optional maps extra (cartopy); raises ImportError with an install hint if it isn’t installed.

show_locatorbool, default False

Add a small inset (bottom-left) showing this survey’s location zoomed way out, with a marker box. Requires the optional maps extra.

show_scale_barbool, default True

Draw a scale bar (see sidescanpy.viz.scalebar). Only drawn for a projected crs (the default) – a caller-supplied geographic CRS is skipped, not drawn wrong, since meters-per- degree isn’t a single constant this function can infer.

scan_nadir_lat, scan_nadir_lonarray, optional

Nadir position at each rung (WGS84 degrees), index-aligned with the scan arrays (SurveyTrack.scan_nadir_*). Where the rung splits into its two halves. Defaults to the midpoint of each rung, which is right when both sides have the same range.

port_color, starboard_colorstr, default “tab:red”, “tab:green”

Matplotlib colors for the port and starboard halves.

Returns:

fig, ax