zea.beamform.beamformer

Main beamforming functions for ultrasound imaging.

Functions

apply_delays(data, delays[, clip_min, clip_max])	Applies time delays for a single transmit using linear interpolation.
calculate_delays(grid, t0_delays, ...[, ...])	Calculates the delays in samples to every pixel in the grid.
complex_rotate(iq, theta)	Performs a simple phase rotation of I and Q component.
distance_Rx(grid, probe_geometry)	Computes distance to user-defined pixels from elements.
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, ...)	Apodization mask for the receive beamformer.
tof_correction(data, flatgrid, t0_delays, ...)	Time-of-flight correction for a flat grid.
transmit_delays(grid, t0_delays, ...[, ...])	Computes the transmit delay from transmission to each pixel in the grid.

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

Applies time delays for a single transmit using linear interpolation.

Most delays in d will not be by an integer number of samples, which means we have no measurement for that time instant. This function solves this by finding the sample before and after and interpolating the data to the desired delays in d using linear interpolation.

Parameters:

• data (ops.Tensor) – The RF or IQ data of shape (n_ax, n_el, n_ch). This is the data we are drawing samples from to for each element for each pixel.

• delays (ops.Tensor) – The delays in samples of shape (n_pix, n_el). Contains one delay value for every pixel in the image for every transducer element.

• clip_min (int, optional) – The minimum delay value to use. If set to -1 no clipping is applied. Defaults to -1.

• clip_max (int, optional) – The maximum delay value to use. If set to -1 no clipping is applied. Defaults to -1.

Returns:

The samples received by each transducer element corresponding to the

reflections of each pixel in the image of shape (n_pix, n_el, n_ch).

Return type:

ops.Tensor

zea.beamform.beamformer.calculate_delays(grid, t0_delays, tx_apodizations, probe_geometry, initial_times, sampling_frequency, sound_speed, n_tx, n_el, 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)

Calculates the delays in samples to every pixel in the grid.

The delay consists of two components: The transmit delay and the receive delay.

The transmit delay is the delay between transmission and the wavefront reaching the pixel.

The receive delay is the delay between the wavefront reaching a pixel and the reflections returning to a specific element.

Parameters:

• grid (Tensor) – The pixel coordinates to beamform to of shape (n_pix, 3).

• t0_delays (Tensor) – The transmit delays in seconds of shape (n_tx, n_el), shifted such that the smallest delay is 0. Defaults to None.

• tx_apodizations (Tensor) – The transmit apodizations of shape (n_tx, n_el).

• probe_geometry (Tensor) – The positions of the transducer elements of shape (n_el, 3).

• initial_times (Tensor) – The probe transmit time offsets of shape (n_tx,).

• sampling_frequency (float) – The sampling frequency of the probe in Hz.

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

• focus_distances (Tensor) – The focus distances of shape (n_tx,). If the focus distance is set to infinity, the beamformer will assume plane wave transmission.

• polar_angles (Tensor) – The polar angles of the plane waves in radians of shape (n_tx,).

• t_peak (Tensor) – Time of the peak of the pulse in seconds of shape (n_waveforms,).

• tx_waveform_indices (Tensor) – The indices of the waveform used for each transmit of shape (n_tx,).

• transmit_origins (Tensor) – Transmit origins of shape (n_tx, 3).

• apply_lens_correction (bool, optional) – Whether to apply lens correction to time-of-flights. This makes it slower, but more accurate in the near-field. Defaults to False.

• lens_thickness (float, optional) – Thickness of the lens in meters. Used for lens correction.

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

• n_iter (int, optional) – Number of iterations for the Newton-Raphson method used in lens correction. Defaults to 2.

Returns:

The tensor of transmit delays to every pixel

in samples (not in seconds), of shape (n_pix, n_tx).

receive_delays (Tensor): The tensor of receive delays from every pixel

back to the transducer element in samples (not in seconds), of shape (n_pix, n_el).

Return type:

transmit_delays (Tensor)

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

Performs a simple phase rotation of I and Q component.

Parameters:

• iq (ops.Tensor) – The iq data of shape (…, 2).

• theta (float) – The complex angle to rotate by.

Returns:

The rotated tensor of shape (…, 2).

Return type:

Tensor

Explanation

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)

Computes distance to user-defined pixels from elements.

Expects all inputs to be arrays specified in SI units.

Parameters:

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

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

Returns:

Distance from each pixel to each element of shape

(n_pix, n_el).

Return type:

dist (ops.Tensor)

zea.beamform.beamformer.fnum_window_fn_hann(normalized_angle)

Hann window function for f-number masking.

zea.beamform.beamformer.fnum_window_fn_rect(normalized_angle)

Rectangular window function for f-number masking.

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

Tukey window function for f-number masking.

Parameters:

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

• alpha (float, optional) – The alpha parameter for the Tukey window. 0.0 corresponds to a rectangular window, 1.0 corresponds to a Hann window. Defaults to 0.5.

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

Apodization mask for the receive beamformer.

Computes a mask to disregard pixels outside of the vision cone of a transducer element. Transducer elements can only accurately measure signals within some range of incidence angles. Waves coming in from the side do not register correctly leading to a worse image.

Parameters:

• flatgrid (ops.Tensor) – The flattened image grid (n_pix, 3).

• probe_geometry (ops.Tensor) – The transducer element positions of shape (n_el, 3).

• f_number (int) – The receive f-number. Set to zero to not use masking and return 1. (The f-number is the ratio between distance from the transducer and the size of the aperture below which transducer elements contribute to the signal for a pixel.).

• fnum_window_fn (callable) – F-number function to define the transition from straight in front of the element (fn(0.0)) to the largest angle within the f-number cone (fn(1.0)). The function should be zero for fn(x>1.0).

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>)

Time-of-flight correction for a flat grid.

Parameters:

• data (ops.Tensor) – Input RF/IQ data of shape (n_tx, n_ax, n_el, n_ch).

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

• t0_delays (ops.Tensor) – Times at which the elements fire shifted such that the first element fires at t=0 of shape (n_tx, n_el)

• tx_apodizations (ops.Tensor) – Transmit apodizations of shape (n_tx, n_el)

• sound_speed (float) – Speed-of-sound.

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

• initial_times (Tensor) – The probe transmit time offsets of shape (n_tx,).

• sampling_frequency (float) – Sampling frequency.

• demodulation_frequency (float) – Demodulation frequency.

• f_number (float) – Focus number (ratio of focal depth to aperture size).

• polar_angles (ops.Tensor) – The angles of the waves in radians of shape (n_tx,)

• focus_distances (ops.Tensor) – The focus distance of shape (n_tx,)

• t_peak (ops.Tensor) – Time of the peak of the pulse in seconds. Shape (n_waveforms,).

• tx_waveform_indices (ops.Tensor) – The indices of the waveform used for each transmit of shape (n_tx,).

• transmit_origins (ops.Tensor) – Transmit origins of shape (n_tx, 3).

• apply_lens_correction (bool, optional) – Whether to apply lens correction to time-of-flights. This makes it slower, but more accurate in the near-field. Defaults to False.

• lens_thickness (float, optional) – Thickness of the lens in meters. Used for lens correction. Defaults to 1e-3.

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

• fnum_window_fn (callable, optional) – F-number function to define the transition from straight in front of the element (fn(0.0)) to the largest angle within the f-number cone (fn(1.0)). The function should be zero for fn(x>1.0).

Returns:

time-of-flight corrected data with shape: (n_tx, n_pix, n_el, n_ch).

Return type:

(ops.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)

Computes the transmit delay from transmission to each pixel in the grid.

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

The receive delays can be precomputed since they do not depend on the transmit parameters.

Parameters:

• grid (ops.Tensor) – Flattened tensor of pixel positions in x,y,z of shape (n_pix, 3)

• t0_delays (Tensor) – The transmit delays in seconds of shape (n_el,).

• tx_apodization (Tensor) – The transmit apodization of shape (n_el,).

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

• focus_distance (float) – The focus distance in meters.

• polar_angle (float) – The polar angle in radians.

• initial_time (float) – The initial time for this transmit in seconds.

• azimuth_angle (float, optional) – The azimuth angle in radians. Defaults to 0.0.

• transmit_origin (ops.Tensor, optional) – The origin of the transmit beam of shape (3,). If None, defaults to (0, 0, 0). Defaults to None.

Returns:

The transmit delays of shape (n_pix,).

Return type:

Tensor