zea.beamform.beamformer

Main beamforming functions for ultrasound imaging.

This module implements the core time-of-flight (TOF) correction pipeline used by the TOFCorrection operation. It also exposes the lower-level building blocks (delay computation, f-number masking, phase rotation, etc.) so that they can be used independently.

Functions

apply_delays(data, delays[, clip_min, clip_max])	Interpolate RF/IQ data at fractional sample positions.
calculate_delays(grid, t0_delays, ...[, ...])	Compute transmit and receive delays in samples to every pixel.
calculate_delays_heterogeneous_medium(grid, ...)	Compute delays using a spatially-varying speed-of-sound map.
complex_rotate(iq, theta)	Phase-rotate IQ data by angle theta.
distance_Rx(grid, probe_geometry)	Euclidean distance from every pixel to every transducer element.
fnum_window_fn_hann(normalized_angle)	Hann window function for f-number masking.
fnum_window_fn_rect(normalized_angle)	Rectangular window function for f-number masking.
fnum_window_fn_tukey(normalized_angle[, alpha])	Tukey window function for f-number masking.
fnumber_mask(flatgrid, probe_geometry, ...)	Receive-aperture apodization mask based on the f-number.
tof_correction(data, flatgrid, t0_delays, ...)	Time-of-flight (TOF) correction for ultrasound data on a flat pixel grid.
transmit_delays(grid, t0_delays, ...[, ...])	Compute the transmit delay from transmission to each pixel.

zea.beamform.beamformer.apply_delays(data, delays, clip_min=-1, clip_max=-1)

Interpolate RF/IQ data at fractional sample positions.

Because the exact delay to a pixel will almost never fall on an integer sample index, this function performs linear interpolation between the two nearest samples (floor and ceil of each delay value).

Parameters:

• data (Tensor) – RF or IQ data of shape (n_ax, n_el, n_ch).

• delays (Tensor) – Delays in samples of shape (n_pix, n_el).

• clip_min (int) – Minimum allowed sample index. -1 means no clipping. Defaults to -1.

• clip_max (int) – Maximum allowed sample index. -1 means no clipping. Defaults to -1.

Returns:

Interpolated samples of shape (n_pix, n_el, n_ch).

Return type:

Tensor

zea.beamform.beamformer.calculate_delays(grid, t0_delays, tx_apodizations, probe_geometry, initial_times, sampling_frequency, sound_speed, focus_distances, polar_angles, t_peak, tx_waveform_indices, transmit_origins, apply_lens_correction=False, lens_thickness=None, lens_sound_speed=None, n_iter=2)

Compute transmit and receive delays in samples to every pixel.

The total round-trip delay for a pixel is the sum of two components:

• Transmit delay — time from transmission until the wavefront reaches the pixel.

• Receive delay — time from the pixel back to each transducer element.

Both are returned in sample units (i.e. already multiplied by sampling_frequency).

Parameters:

• grid (Tensor) – Pixel coordinates of shape (n_pix, 3).

• t0_delays (Tensor) – Per-element transmit delays in seconds of shape (n_tx, n_el), shifted so that the smallest delay is 0.

• tx_apodizations (Tensor) – Transmit apodization weights of shape (n_tx, n_el).

• probe_geometry (Tensor) – Element positions of shape (n_el, 3).

• initial_times (Tensor) – Per-transmit time offsets of shape (n_tx,).

• sampling_frequency (float) – Sampling frequency in Hz.

• sound_speed (float) – Assumed speed of sound in m/s.

• focus_distances (Tensor) – Focus distances of shape (n_tx,). Use 0 or np.inf for plane-wave transmission.

• polar_angles (Tensor) – Polar steering angles in radians of shape (n_tx,).

• t_peak (Tensor) – Waveform peak times in seconds of shape (n_waveforms,).

• tx_waveform_indices (Tensor) – Index into t_peak for each transmit of shape (n_tx,).

• transmit_origins (Tensor) – Origin of each transmit beam of shape (n_tx, 3).

• apply_lens_correction (bool, optional) – Apply acoustic-lens correction (slower but more accurate in the near-field). Defaults to False.

• lens_thickness (float, optional) – Lens thickness in meters.

• lens_sound_speed (float, optional) – Speed of sound in the lens in m/s.

• n_iter (int, optional) – Newton-Raphson iterations for lens correction. Defaults to 2.

Returns:

• transmit_delays — of shape (n_pix, n_tx).

• receive_delays — of shape (n_pix, n_el).

Return type:

tuple[Tensor, Tensor]

zea.beamform.beamformer.calculate_delays_heterogeneous_medium(grid, sos_map, sos_grid_x, sos_grid_z, t0_delays, probe_geometry, initial_times, sampling_frequency, t_peak, tx_waveform_indices, n_ray_points=100)

Compute delays using a spatially-varying speed-of-sound map.

Integrates the slowness (1 / speed-of-sound) along straight rays between each element and each pixel to approximate heterogeneous travel times.

For the homogeneous (constant speed-of-sound) variant see calculate_delays(). If you do not have a SOS map, it is recommended to use calculate_delays().

Important

Only valid for multistatic acquisitions (n_tx == n_el).

Note

Currently only supports 2D grids, not yet compatible with 3D. Assumes the grid is in the x-z plane and the y dimension is zero. Please use calculate_delays() for 3D data.

Note

This function is not compatible with the torch backend.

Parameters:

• grid (Tensor) – Pixel coordinates of shape (n_pix, 3).

• sos_map (Tensor) – Speed-of-sound map of shape (Nz, Nx) in m/s.

• sos_grid_x (Tensor) – x-coordinates of sos_map columns.

• sos_grid_z (Tensor) – z-coordinates of sos_map rows.

• t0_delays (Tensor) – Transmit delays of shape (n_tx, n_el), shifted so that the smallest delay is 0.

• probe_geometry (Tensor) – Element positions of shape (n_el, 3).

• initial_times (Tensor) – Per-transmit time offsets of shape (n_tx,).

• sampling_frequency (float) – Sampling frequency in Hz.

• t_peak (Tensor) – Waveform peak times of shape (n_waveforms,).

• tx_waveform_indices (Tensor) – Index into t_peak for each transmit of shape (n_tx,).

• n_ray_points (int, optional) – Number of integration points along each element-to-pixel ray. Higher values improve accuracy at the cost of computation time. Defaults to 100.

Returns:

• tx_delays — Transmit delays in samples (n_tx, n_pix).

• rx_delays — Receive delays in samples (n_el, n_pix).

Return type:

tuple[Tensor, Tensor]

zea.beamform.beamformer.complex_rotate(iq, theta)

Phase-rotate IQ data by angle theta.

When delaying IQ-demodulated data it is not sufficient to interpolate the I and Q channels independently — the carrier phase shift must be compensated as well. This function applies the rotation:

\[\begin{split}I_\Delta &= I' \cos\theta - Q' \sin\theta \\ Q_\Delta &= Q' \cos\theta + I' \sin\theta\end{split}\]

Parameters:

• iq (Tensor) – IQ data of shape (..., 2).

• theta (Tensor or float) – Rotation angle in radians (broadcastable to iq[..., 0]).

Returns:

Rotated IQ data of shape (..., 2).

Return type:

Tensor

Derivation

The IQ data is related to the RF data as follows:

\[\begin{split}x(t) &= I(t)\cos(\omega_c t) + Q(t)\cos(\omega_c t + \pi/2)\\ &= I(t)\cos(\omega_c t) - Q(t)\sin(\omega_c t)\end{split}\]

If we want to delay the RF data x(t) by Δt we can substitute in \(t=t+\Delta t\). We also define \(I'(t) = I(t + \Delta t)\), \(Q'(t) = Q(t + \Delta t)\), and \(\theta=\omega_c\Delta t\). This gives us:

\[\begin{split}x(t + \Delta t) &= I'(t) \cos(\omega_c (t + \Delta t)) - Q'(t) \sin(\omega_c (t + \Delta t))\\ &= \overbrace{(I'(t)\cos(\theta) - Q'(t)\sin(\theta) )}^{I_\Delta(t)} \cos(\omega_c t)\\ &- \overbrace{(Q'(t)\cos(\theta) + I'(t)\sin(\theta))}^{Q_\Delta(t)} \sin(\omega_c t)\end{split}\]

This means that to correctly interpolate the IQ data to the new components \(I_\Delta(t)\) and \(Q_\Delta(t)\), it is not sufficient to just interpolate the I- and Q-channels independently. We also need to rotate the I- and Q-channels by the angle \(\theta\). This function performs this rotation.

zea.beamform.beamformer.distance_Rx(grid, probe_geometry)

Euclidean distance from every pixel to every transducer element.

Parameters:

• grid (Tensor) – Pixel positions (x, y, z) of shape (n_pix, 3).

• probe_geometry (Tensor) – Element positions (x, y, z) of shape (n_el, 3).

Returns:

Distances of shape (n_pix, n_el).

Return type:

Tensor

zea.beamform.beamformer.fnum_window_fn_hann(normalized_angle)

Hann window function for f-number masking.

Provides a smooth cosine roll-off from 1 at normalized_angle = 0 to 0 at normalized_angle = 1.

Parameters:

normalized_angle (Tensor) – Normalized angle values.

Returns:

Apodization weights with the same shape as normalized_angle.

Return type:

Tensor

zea.beamform.beamformer.fnum_window_fn_rect(normalized_angle)

Rectangular window function for f-number masking.

Returns 1 when normalized_angle <= 1 and 0 otherwise.

Parameters:

normalized_angle (Tensor) – Normalized angle values (0 = on-axis, 1 = edge of the f-number cone).

Returns:

Binary mask with the same shape as normalized_angle.

Return type:

Tensor

zea.beamform.beamformer.fnum_window_fn_tukey(normalized_angle, alpha=0.5)

Tukey window function for f-number masking.

A Tukey window is flat in the center and tapers with a cosine lobe near the edges. Setting alpha = 0 produces a rectangular window; alpha = 1 produces a Hann window.

Parameters:

• normalized_angle (Tensor) – Normalized angle values in [0, 1].

• alpha (float, optional) – Shape parameter controlling the fraction of the window inside the cosine taper. Defaults to 0.5.

Returns:

Apodization weights with the same shape as normalized_angle.

Return type:

Tensor

zea.beamform.beamformer.fnumber_mask(flatgrid, probe_geometry, f_number, fnum_window_fn)

Receive-aperture apodization mask based on the f-number.

Computes a per-pixel, per-element mask that suppresses contributions from elements whose angle to a pixel exceeds the acceptance cone defined by the f-number. The transition within the cone is controlled by fnum_window_fn (e.g. fnum_window_fn_rect(), fnum_window_fn_hann(), fnum_window_fn_tukey()).

Parameters:

• flatgrid (Tensor) – Flattened pixel grid of shape (n_pix, 3).

• probe_geometry (Tensor) – Element positions of shape (n_el, 3).

• f_number (float) – Receive f-number (depth / aperture). A value of 0 disables masking.

• fnum_window_fn (callable) – Window function mapping normalized angles in [0, 1] to weights. Must return 0 for inputs > 1.

Returns:

Mask of shape (n_pix, n_el, 1).

Return type:

Tensor

zea.beamform.beamformer.tof_correction(data, flatgrid, t0_delays, tx_apodizations, sound_speed, probe_geometry, initial_times, sampling_frequency, demodulation_frequency, f_number, polar_angles, focus_distances, t_peak, tx_waveform_indices, transmit_origins, apply_lens_correction=False, lens_thickness=0.001, lens_sound_speed=1000, fnum_window_fn=<function fnum_window_fn_rect>, sos_map=None, sos_grid_x=None, sos_grid_z=None)

Time-of-flight (TOF) correction for ultrasound data on a flat pixel grid.

Corrects raw RF or IQ data for differences in propagation time from the transmitter through each pixel and back to every receiving element. Two modes are supported:

• Homogeneous medium (default) — a constant sound_speed is used to compute delays analytically via calculate_delays().

• Heterogeneous medium — a spatially-varying speed-of-sound map (sos_map) is provided and delays are computed numerically via calculate_delays_heterogeneous_medium().

Important

The heterogeneous mode currently requires multistatic acquisitions (n_tx == n_el).

After delay computation the data is interpolated to the requested pixel positions, masked with the receive f-number aperture, and — for IQ data — phase-rotated to compensate for the demodulation carrier (see complex_rotate()).

Parameters:

• data (Tensor) – Input RF or IQ data of shape (n_tx, n_ax, n_el, n_ch). Use n_ch=1 for RF data and n_ch=2 for IQ (in-phase / quadrature).

• flatgrid (Tensor) – Pixel locations (x, y, z) of shape (n_pix, 3).

• t0_delays (Tensor) – Per-element transmit fire times, shifted so that the first element fires at t = 0, of shape (n_tx, n_el).

• tx_apodizations (Tensor) – Transmit apodization weights of shape (n_tx, n_el).

• sound_speed (float) – Speed of sound in m/s.

• probe_geometry (Tensor) – Element positions (x, y, z) of shape (n_el, 3).

• initial_times (Tensor) – Per-transmit time offsets of shape (n_tx,).

• sampling_frequency (float) – Sampling frequency in Hz.

• demodulation_frequency (float) – Demodulation (carrier) frequency in Hz. Only used when n_ch=2 (IQ data).

• f_number (float) – Receive f-number. Set to 0 to disable f-number masking.

• polar_angles (Tensor) – Steering angles in radians of shape (n_tx,).

• focus_distances (Tensor) – Focus distances in meters of shape (n_tx,). Use 0 or np.inf for plane-wave transmission.

• t_peak (Tensor) – Time of each waveform peak in seconds of shape (n_waveforms,).

• tx_waveform_indices (Tensor) – Index into t_peak for each transmit of shape (n_tx,).

• transmit_origins (Tensor) – Origin of each transmit beam of shape (n_tx, 3).

• apply_lens_correction (bool, optional) – Apply acoustic-lens correction to the receive travel times (slower but more accurate in the near-field). Defaults to False.

• lens_thickness (float, optional) – Lens thickness in meters. Defaults to 1e-3.

• lens_sound_speed (float, optional) – Speed of sound inside the lens in m/s. Defaults to 1000.

• fnum_window_fn (callable, optional) – Window function applied to the normalized angle for f-number masking. Receives values in [0, 1] and should return 0 for values > 1. Defaults to fnum_window_fn_rect().

• sos_map (Tensor, optional) – 2-D speed-of-sound map of shape (Nz, Nx) in m/s. When provided, delays are computed numerically (heterogeneous mode, multistatic only). Defaults to None.

• sos_grid_x (Tensor, optional) – x-coordinates of sos_map columns.

• sos_grid_z (Tensor, optional) – z-coordinates of sos_map rows.

Returns:

Time-of-flight corrected data of shape (n_tx, n_pix, n_el, n_ch).

Return type:

Tensor

zea.beamform.beamformer.transmit_delays(grid, t0_delays, tx_apodization, rx_delays, focus_distance, polar_angle, initial_time, azimuth_angle=None, transmit_origin=None)

Compute the transmit delay from transmission to each pixel.

Uses the first-arrival time for pixels before the focus (or virtual source) and the last-arrival time for pixels beyond the focus.

Parameters:

• grid (Tensor) – Pixel positions (x, y, z) of shape (n_pix, 3).

• t0_delays (Tensor) – Per-element transmit delays in seconds of shape (n_el,).

• tx_apodization (Tensor) – Transmit apodization weights of shape (n_el,).

• rx_delays (Tensor) – Travel times in seconds from elements to pixels of shape (n_pix, n_el).

• focus_distance (float) – Focus distance in meters. Use 0 or np.inf for plane-wave transmission.

• polar_angle (float) – Polar steering angle in radians.

• initial_time (float) – Time offset for this transmit in seconds.

• azimuth_angle (float, optional) – Azimuth steering angle in radians. Defaults to None (treated as 0).

• transmit_origin (Tensor, optional) – Origin of the transmit beam of shape (3,). Defaults to (0, 0, 0).

Returns:

Transmit delays of shape (n_pix,).

Return type:

Tensor