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.
distance_Rx(grid, probe_geometry)	Computes distance to user-defined pixels from elements.
distance_Tx_generic(grid, t0_delays, ...[, ...])	Generic transmit distance calculation.
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.

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_el, n_pix, 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, **kwargs)

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

Returns:

The tensor of transmit delays to every pixel,

shape (n_pix, n_tx).

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

back to the transducer element, shape (n_pix, n_el).

Return type:

transmit_delays (Tensor)

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

Computes distance to user-defined pixels from elements.

Expects all inputs to be numpy 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.distance_Tx_generic(grid, t0_delays, tx_apodization, probe_geometry, focus_distance, polar_angle, sound_speed=1540)

Generic transmit distance calculation.

Computes distance to user-defined pixels for generic transmits based on the t0_delays.

Parameters:

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

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

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

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

• sound_speed (float) – The speed of sound in m/s. Defaults to 1540.

Returns:

Distance from each pixel to each element in meters of shape (n_pix,)

Return type:

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, fnum, angles, focus_distances, apply_phase_rotation=False, 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

• (num_samples

• 3)

• initial_times (ops.Tensor) – Time-ofsampling_frequencyet per transmission of shape (n_tx,).

• sampling_frequency (float) – Sampling frequency.

• demodulation_frequency (float) – Demodulation frequency.

• fnum (int, optional) – Focus number. Defaults to 1.

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

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

• apply_phase_rotation (bool, optional) – Whether to apply phase rotation to time-of-flights. Defaults to False.

• 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, num_rf_iq_channels).

Return type:

(ops.Tensor)