sidescanpy.targets.waterfall#

Target boxes in waterfall plot coordinates.

A waterfall is drawn either in pixel space (x_axis="sample", y_axis="ping": port samples negative, starboard positive, the global ping index up the y-axis) or in meters (x_axis="across_track", y_axis="along_track"). waterfall_boxes() places each target in whichever of the two is active and returns plain rectangles for a plotting layer to draw.

2026 rshomberg@uri.edu

Contents

`BOX_AXES`	`(x_axis, y_axis)` pairs `waterfall_boxes()` can place targets on.
`WaterfallBox`	A labeled rectangle in waterfall axis units (lower-left corner + size).
`mean_sample_spacing_m`	Mean across-track meters per sample over one ping's finite samples.
`median_ping_spacing_m`	Median along-track meters per ping (robust to turns); `1.0` if undefined.
`target_waterfall_position`	Where `target` lands on a waterfall's axes, and the axis scale.
`waterfall_boxes`	Rectangles for every `(target, global_ping_idx)` placeable on these axes.
`targets_by_global_ping`	Targets on `freq_key`, keyed by their ping in a concatenated survey.

sidescanpy.targets.waterfall.BOX_AXES = (('sample', 'ping'), ('across_track', 'along_track'))#: (x_axis, y_axis) pairs waterfall_boxes() can place targets on.

class sidescanpy.targets.waterfall.WaterfallBox(label, x0, y0, width, height)#

Bases: NamedTuple

A labeled rectangle in waterfall axis units (lower-left corner + size).

label#: Alias for field number 0

x0#: Alias for field number 1

y0#: Alias for field number 2

width#: Alias for field number 3

height#: Alias for field number 4

sidescanpy.targets.waterfall.mean_sample_spacing_m(ds, local_ping, channel_idx)#

Mean across-track meters per sample over one ping’s finite samples.

Averaged over the whole ping rather than a local difference, so it is stable near the water-column boundary. 1.0 with fewer than two finite samples.

sidescanpy.targets.waterfall.median_ping_spacing_m(along_track)#: Median along-track meters per ping (robust to turns); 1.0 if undefined.

sidescanpy.targets.waterfall.target_waterfall_position(target, ds, ping_idx, ping_offset, x_axis, y_axis, along_track=None)#

Where target lands on a waterfall’s axes, and the axis scale.

Parameters:

targetTarget: Needs sample; channel defaults to port.
dsxr.Dataset or None: The plotted window (only read for the meters axes).
ping_idxint: The target’s global ping index (the pixel y-axis value).
ping_offsetint: Global ping index of ds’s first ping.
x_axis, y_axisstr: One of BOX_AXES.
along_tracknp.ndarray, optional: Along-track meters per ds ping (meters axes; None falls back to the local ping index).

Returns:

(x, y, x_scale, y_scale) or None: x_scale/y_scale convert one pixel (sample, ping) into axis units: 1.0 on the pixel axes; meters per sample (mean_sample_spacing_m()) and per ping (median_ping_spacing_m()) on the meters axes. None when the target has no sample, lies outside ds, has no finite across-track position, or the axes are unsupported.

sidescanpy.targets.waterfall.waterfall_boxes(ds, boxes, ping_offset, x_axis, y_axis, box_size)#

Rectangles for every (target, global_ping_idx) placeable on these axes.

box_size is in pixels (samples x pings) and is scaled into axis units per target (see target_waterfall_position()).

sidescanpy.targets.waterfall.targets_by_global_ping(placements, freq_key, file_start_ping)#

Targets on freq_key, keyed by their ping in a concatenated survey.

Parameters:

placementssequence of CatalogPlacement: From correlate_catalog().
freq_keystr
file_start_pingdict: {path: first global ping} of each concatenated file (files without freq_key are absent).