bluepebble.sigproc

Signal-processing primitives including beamforming and steering utilities.

Signal processing package public API.

class bluepebble.sigproc.Beamformer[source]

Abstract interface for beamforming algorithms.

abstractmethod beamform(sensor_signals, steering_delays_s)[source]

Form directional beams from multi-sensor input data.

Parameters:

  • sensor_signals (ArrayLike) – Sensor signal matrix with shape (num_sensors, num_samples).

  • steering_delays_s (ArrayLike) – Steering-delay matrix (seconds) with shape (num_directions, num_sensors).

Returns:

Beamformer output matrix. Concrete implementations define whether this contains complex beamformed time-series or real-valued beam power.

Return type:

BeamformerOutput

class bluepebble.sigproc.DelayAndSumBeamformer(sampling_rate_hz, shading=None, domain='time', nfft=500, overlap=250, f0=0.0, fmin=None, fmax=None)[source]

A Delay-and-Sum (DAS) beamformer.

Supports three processing modes:

  • 'time': time-domain delay-and-sum.

  • 'frequency': frequency-domain delay-and-sum.

  • 'broadband_power': STFT-based incoherent broadband power integration.

In all modes, steering is controlled via per-direction per-sensor delay values.

Parameters:

  • sampling_rate_hz (float)

  • shading (ndarray[tuple[Any, ...], dtype[float64]] | None)

  • domain (Literal['time', 'frequency', 'broadband_power'])

  • nfft (int)

  • overlap (int)

  • f0 (float)

  • fmin (float | None)

  • fmax (float | None)

sampling_rate_hz: float

The sampling frequency of the sensor signals, in Hz

domain: Literal['time', 'frequency', 'broadband_power']

Beamforming domain: ‘time’, ‘frequency’, or ‘broadband_power’.

nfft: int

STFT window size (samples)

overlap: int

STFT overlap (samples)

f0: float

Carrier frequency for baseband data (Hz)

fmin: float | None

Minimum frequency to integrate (Hz)

fmax: float | None

Maximum frequency to integrate (Hz)

shading: ndarray[tuple[Any, ...], dtype[float64]] | None

An array of shading weights applied to each sensor. If None, uniform weights are used.

beamform(sensor_signals, steering_delays_s)[source]

Beamform sensor data using the configured DAS processing domain.

Parameters:

  • sensor_signals (ArrayLike) – Sensor data matrix with shape (num_sensors, num_samples).

  • steering_delays_s (ArrayLike) – Steering-delay matrix with shape (num_directions, num_sensors).

Returns:

  • domain='time' or 'frequency': complex signals with shape (num_directions, num_samples_or_cropped_samples).

  • domain='broadband_power': real-valued power map with shape (num_directions, num_frames).

Return type:

BeamformerOutput

Raises:

  • ValueError – If the number of sensors in sensor_signals does not match steering_delays_s.

  • ValueError – If explicit shading length does not match the sensor count.

das_broadband_power(x, fs, nfft, sd, shading_weights, f0=0.0, fmin=None, fmax=None, overlap=0)[source]

Compute STFT-based broadband DAS power over steering directions.

The input sensor array data are transformed using STFT, steered at each frequency bin using phase shifts derived from sd, and then integrated incoherently (power sum across selected frequencies) to produce a direction-time power map.

Parameters:

  • x (ComplexArray) – Sensor data matrix with shape (num_sensors, num_samples).

  • fs (float) – Sampling frequency in Hz.

  • nfft (int) – STFT window length (number of FFT points).

  • sd (FloatArray) – Steering delays in seconds with shape (num_directions, num_sensors).

  • shading_weights (FloatArray) – Per-sensor beamforming weights with shape (num_sensors,).

  • f0 (float, optional) – Carrier frequency offset in Hz for baseband data. Defaults to 0.0.

  • fmin (float | None, optional) – Minimum frequency (Hz) included in the power integration. If None, the minimum available STFT bin frequency is used.

  • fmax (float | None, optional) – Maximum frequency (Hz) included in the power integration. If None, the maximum available STFT bin frequency is used.

  • overlap (int, optional) – Number of overlapping samples between adjacent STFT frames. Defaults to 0.

Returns:

Broadband beam power map with shape (num_directions, num_frames). Each entry contains integrated beam power over the active frequency bins for one steering direction and one STFT frame.

Return type:

FloatArray

class bluepebble.sigproc.MinimumVarianceDistortionlessResponseBeamformer(sampling_rate_hz, nfft=500, overlap=250, f0=0.0, fmin=None, fmax=None)[source]

A Minimum Variance Distortionless Response (MVDR) beamformer.

MVDR is an adaptive beamformer that computes optimal weights from the data covariance matrix. Unlike DAS beamformers, shading/tapering is not applied as it would interfere with the adaptive optimisation.

This implementation uses an STFT-based broadband approach: the sensor time-series are transformed into short-time frequency bins, a frequency-domain Capon (MVDR) beamformer is applied in each bin, and the narrowband outputs are integrated over frequency to produce power as a function of steering direction and time frame.

Parameters:

  • sampling_rate_hz (float)

  • nfft (int)

  • overlap (int)

  • f0 (float)

  • fmin (float | None)

  • fmax (float | None)

sampling_rate_hz: float

The sampling frequency of the sensor signals, in Hz

nfft: int

STFT window size (samples)

overlap: int

STFT overlap (samples)

f0: float

Carrier frequency for baseband data (Hz)

fmin: float | None

Minimum frequency to integrate (Hz)

fmax: float | None

Maximum frequency to integrate (Hz)

beamform(sensor_signals, steering_delays_s)[source]

Perform broadband MVDR beamforming and return power time-series.

Parameters:

  • sensor_signals (ArrayLike) – Sensor data matrix with shape (num_sensors, num_samples).

  • steering_delays_s (ArrayLike) – Steering-delay matrix with shape (num_directions, num_sensors).

Raises:

ValueError – If the number of sensors in sensor_signals does not match steering_delays_s.

Returns:

Real-valued beamformed power with shape (num_directions, num_time_frames).

Return type:

FloatArray

class bluepebble.sigproc.SteeringCalculator(ssp, steering_azimuths_rad)[source]

Compute steering delays for a horizontal sensor array.

Parameters:

  • ssp (SoundSpeedProfile)

  • steering_azimuths_rad (ndarray[tuple[Any, ...], dtype[float64]])

ssp: SoundSpeedProfile

Sound speed profile for calculating delays

steering_azimuths_rad: ndarray[tuple[Any, ...], dtype[float64]]

Azimuth angles for steering, in radians

calculate(platform)[source]

Calculate per-direction per-sensor steering delays.

This method assumes the platform has an array attribute which is an object with state_vector and ref_state_vector attributes, such as the one configured by TowedArrayPlatform.

Parameters:

platform (Platform) – The platform containing the sensor array.

Returns:

Steering-delay matrix in seconds with shape (num_directions, num_sensors).

Return type:

FloatArray