bluepebble.plotter

Plotting helpers for bearings, world geometry, spectrograms, and detector metrics output.

Defines plotting utilities.

bluepebble.plotter.apply_shared_colourscale(fig, zmin=None, zmax=None, colorbar=None)[source]

Apply a shared colour scale across all heatmap traces in a figure.

Parameters:

  • fig (go.Figure) – Figure containing one or more heatmap traces.

  • zmin (float | None) – Lower bound of the shared colour scale. If None, computed as the minimum finite value across all heatmap traces.

  • zmax (float | None) – Upper bound of the shared colour scale. If None, computed as the maximum finite value across all heatmap traces.

  • colorbar (dict | None) – Plotly colorbar dict applied to the first heatmap trace. If None, the existing colorbar is left unchanged.

Returns:

The modified figure (mutated in-place and returned).

Return type:

go.Figure

bluepebble.plotter.deduplicate_legend(fig)[source]

Suppress duplicate legend entries, keeping the first occurrence of each name.

Parameters:

fig (go.Figure) – Figure whose legend entries should be deduplicated.

Returns:

The modified figure (mutated in-place and returned).

Return type:

go.Figure

bluepebble.plotter.launch_bathymetry_and_sound_speed_viewer(bathymetry, ssp, x_range=None, y_range=None, z_res_m=10.0, host='127.0.0.1', port=8050, debug=False, jupyter_mode=None)[source]

Launch an interactive bathymetry/profile dashboard for measured environments.

The dashboard provides: - A bathymetry map (Blue Pebble -z convention) used as a profile selector. - A selected-point sound-speed profile plot (depth shown as +z downward).

This viewer is designed for measured-data models where bathymetry and SSP vary in both horizontal and vertical dimensions. It expects model objects compatible with GEBCOBathymetry and LeroyCopernicusSoundSpeedProfile.

Parameters:

  • bathymetry (object) – Bathymetry model instance supporting get_grid(x_range, y_range) and exposing local x/y coverage arrays.

  • ssp (object) – Sound-speed model instance supporting Leroy/Copernicus cached fields and interpolation helpers.

  • x_range (tuple[float, float] | None) – Optional x-range in meters for the viewer. If None, the overlap between bathymetry and SSP coverage is used.

  • y_range (tuple[float, float] | None) – Optional y-range in meters for the viewer. If None, the overlap between bathymetry and SSP coverage is used.

  • z_res_m (float) – Vertical resolution in meters used to resample SSP profiles.

  • host (str) – Dash server host.

  • port (int) – Dash server port.

  • debug (bool) – Dash debug flag.

  • jupyter_mode (str | None) – Optional Dash notebook display mode. Supported values are {"inline", "tab", "external", "jupyterlab"}. If None (default), the app runs as a standard local web server.

Returns:

Runs the Dash application until the server is stopped.

Return type:

None

bluepebble.plotter.plot_world(truths, platform, bathymetry=None, figsize=(600, 500))[source]

Plot the world picture of the platform and target trajectories.

Parameters:

  • truths (Sequence[GroundTruthPath]) – Ground-truth paths representing target trajectories.

  • platform (Platform) – The platform whose trajectory is to be plotted.

  • bathymetry (object | None) – Optional bathymetry model implementing get_grid(x_range, y_range). If provided, bathymetry is rendered as a background heatmap.

  • figsize (tuple[float, float]) – Figure size. Values that look like inches (for example (12, 6)) are converted to pixels using 100 px/in; larger values are treated as pixels. Default is (600, 500).

Returns:

A Plotly figure object containing the world picture plot.

Return type:

go.Figure

bluepebble.plotter.plot_btr(timesteps, steering_azimuths, data=None, truths=None, detections=None, tracks=None, data_type='SNR (dB)', cmin=None, cmax=None, colorscale='Turbo', figsize=(800, 600), fig=None, row=None, col=None)[source]

Plot the bearing-time record (BTR) of the beamformed data.

Optionally overlays truth trajectories and detections on the BTR plot.

Parameters:

  • timesteps (ArrayLike) – Timesteps corresponding to the first dimension of data.

  • steering_azimuths (ArrayLike) – Steering azimuth angles corresponding to the second dimension of data.

  • data (ArrayLike | None) – Beamformed data to plot as a heatmap. If None, no heatmap is drawn and only overlays are rendered.

  • truths (Sequence[GroundTruthPath] | None) – Ground-truth paths representing target trajectories. Default is None.

  • detections (Sequence[Detection] | None) – Detection objects to overlay. Default is None.

  • tracks (Collection[Track] | None) – Track objects to overlay. Default is None.

  • data_type (str) – Label for the plotted heatmap quantity (for example "SNR (dB)"). Used as the colorbar title. Default is "SNR (dB)".

  • cmin (float | None) – Optional lower bound of the heatmap color scale. If None (default), Plotly automatically chooses the lower bound from the data.

  • cmax (float | None) – Optional upper bound of the heatmap color scale. If None (default), Plotly automatically chooses the upper bound from the data.

  • colorscale (str) – Name of the Plotly colorscale to use for the heatmap. Default is "Turbo".

  • figsize (tuple[float, float]) – Figure size for standalone plots. Values that look like inches (for example (12, 6)) are converted to pixels using 100 px/in; larger values are treated as pixels. Ignored when fig is provided.

  • fig (go.Figure | None) – Optional target figure. Provide a subplot figure from plotly.subplots.make_subplots() to draw directly into a cell. If None, a new standalone figure is created.

  • row (int | None) – Subplot row when fig is provided.

  • col (int | None) – Subplot column when fig is provided.

Returns:

A Plotly figure object containing the BTR plot.

Return type:

go.Figure

bluepebble.plotter.plot_spectrogram(signal, sr, n_fft=4096, hop_length=1024, y_lim=None, yaxis_format='kHz', figsize=(12, 6), fig=None, row=None, col=None, analysis_mode='stft', db_reference='peak', z_lim=None, z_percentiles=None, showscale=True, colorbar_title='Intensity (dB)', colorscale='Turbo', customdata=None, hovertemplate=None)[source]

Generate and display a formatted spectrogram with Plotly.

Parameters:

  • signal (ArrayLike) – 1D array-like audio signal.

  • sr (int) – Sampling rate in Hz.

  • n_fft (int) – FFT window size.

  • hop_length (int) – STFT hop length.

  • y_lim (tuple[float, float] | None) – Optional y-axis limits in Hz as (min, max).

  • yaxis_format (str) – "kHz" to label y-axis in kHz or "Hz" for Hz.

  • figsize (tuple[float, float]) – Figure size. Values that look like inches (for example (12, 6)) are converted to pixels using 100 px/in; larger values are treated as pixels. Ignored when fig is provided.

  • fig (go.Figure | None) – Optional target figure. Provide a subplot figure from plotly.subplots.make_subplots() to draw directly into a cell. If None, a new standalone figure is created.

  • row (int | None) – Subplot row when fig is provided.

  • col (int | None) – Subplot column when fig is provided.

  • analysis_mode (str) – Spectral analysis backend. Use "stft" for short-time Fourier transform magnitude or "psd" for power spectral density.

  • db_reference (str) – Decibel reference mode. "peak" computes values relative to each panel’s peak value. "absolute" leaves values in absolute dB units.

  • z_lim (tuple[float, float] | None) – Optional colour scale limits in dB as (min, max).

  • z_percentiles (tuple[float, float] | None) – Optional percentile-based colour scale limits as (low, high) in [0, 100]. Used only when z_lim is None.

  • showscale (bool) – Whether to show a colour bar for this trace.

  • colorbar_title (str) – Colour bar title text.

  • colorscale (str) – Plotly colour scale name.

  • customdata (ArrayLike | None) – Optional customdata to attach to the heatmap trace for use in hover templates.

  • hovertemplate (str | None) – Optional hover template for the heatmap trace. See Plotly documentation for details on hover templates and how to reference customdata.

Returns:

A Plotly figure containing the spectrogram.

Return type:

go.Figure

bluepebble.plotter.plot_roc(results, show_diagonal=True, figsize=(600, 500))[source]

Plot Receiver Operating Characteristic (ROC) curves for one or more sweep results.

Parameters:

  • results (Sequence[SweepResult]) – Sweep results produced by sweep_detection_parameter(). Each result is drawn as a separate trace using its label attribute.

  • show_diagonal (bool) – If True (default), overlay the random-classifier diagonal.

  • figsize (tuple[float, float]) – Figure dimensions in pixels. Default is (600, 500).

Returns:

Plotly figure containing the ROC curves.

Return type:

go.Figure

bluepebble.plotter.plot_pr(results, figsize=(600, 500))[source]

Plot Precision-Recall (PR) curves for one or more sweep results.

Parameters:

  • results (Sequence[SweepResult]) – Sweep results produced by sweep_detection_parameter(). Each result is drawn as a separate trace using its label attribute.

  • figsize (tuple[float, float]) – Figure dimensions in pixels. Default is (600, 500).

Returns:

Plotly figure containing the PR curves.

Return type:

go.Figure

bluepebble.plotter.plot_roc_pr(results, show_diagonal=True, figsize=(600, 900))[source]

Plot ROC and Precision-Recall curves stacked vertically for one or more sweep results.

Parameters:

  • results (Sequence[SweepResult]) – Sweep results produced by sweep_detection_parameter(). Each result is drawn as a separate trace pair (same colour in both subplots) using its label attribute.

  • show_diagonal (bool) – If True (default), overlay the random-classifier diagonal on the ROC subplot.

  • figsize (tuple[float, float]) – Figure dimensions in pixels. Default is (600, 900).

Returns:

Plotly figure with ROC (top) and PR (bottom) subplots.

Return type:

go.Figure