sidescanpy.analysis.beam#

Beam geometry from measured boundaries.

estimate_beam_geometry() triangulates the sidescan beam’s near and far edges from data already measured elsewhere:

  • near edge, per (ping, channel): arccos(altitude / slant_range) at the first bottom return (analyze_nadir());

  • far edge, survey-wide: arctan(usable_range / altitude) with the usable range from estimate_usable_range().

A wrong altitude_m shifts both edges together, so this can’t by itself separate a tilted beam from bad altitude.

Contents

BeamGeometryResult

Near/far beam-edge angles (degrees from vertical).

estimate_beam_geometry

Estimate the beam's near-edge, far-edge, centre angle and width.
class sidescanpy.analysis.beam.BeamGeometryResult(confidence=None, ping_idx=None, altitude_m=None, near_ray=<factory>, far_ray=<factory>, near_angle_deg_median=None, near_angle_deg_std=None, near_angle_valid_fraction=None, far_angle_deg=None, beam_center_angle_deg=None, beam_width_deg=None, usable_range_m=None, notes=<factory>)#

Bases:

Near/far beam-edge angles (degrees from vertical).

confidence reflects the cross-ping near-edge measurement: "determined", "ambiguous" (too much ping-to-ping spread), "undetermined" (too few valid pings), or None when the reference ping’s altitude is unusable. near_ray / far_ray hold the single ping_idx geometry per side ("port", "starboard") for plotting. Far-edge values are None without a usable range.

sidescanpy.analysis.beam.estimate_beam_geometry(ds, first_bottom_return_sample, usable_range_m, range_var='across_track_m', slant_range_var='slant_range_m', *, ping_idx=None, near_angle_max_std_deg=15.0, min_valid_fraction=0.2)#

Estimate the beam’s near-edge, far-edge, centre angle and width.

Run nadir-noise blanking first on hardware that doesn’t blank it itself, or the near edge measures the noise burst rather than the beam (reported as "undetermined").

Parameters:
dsxr.Dataset

Needs range_var, slant_range_var and altitude_m.

first_bottom_return_samplenp.ndarray or None

(ping, channel) first-bottom-return sample indices (NadirResult.first_bottom_return_sample).

usable_range_mfloat or None

Survey-aggregate usable range for the far edge.

range_varstr, default “across_track_m”

Signed cross-track distance (port negative), for the diagram.

slant_range_varstr, default “slant_range_m”

Range used for the near-angle back-calculation.

ping_idxint, optional

Ping for the near_ray / far_ray diagram geometry (default: middle ping). Doesn’t affect the cross-ping statistics.

near_angle_max_std_degfloat, default 15.0

Cross-ping near-angle std above this → "ambiguous".

min_valid_fractionfloat, default 0.2

Minimum fraction of (ping, channel) pairs with a valid near angle (finite altitude, slant_range >= altitude, detected boundary); below it → "undetermined".