zea.simulator

Frequency domain ultrasound simulator.

The simulator works in the frequency domain (RFFT domain) and simulates RF data as a superposition of scatterer responses. Every scatterer has a location and a magnitude.

To use it in your code, simply call the simulate_rf() function with the desired transmit scheme parameters and scatterers. To simulate a sequence of multiple frames, you can call simulate_rf() repeatedly with different scatterer positions and magnitudes and then stack the results.

Example usage

A simple example of simulating RF data with a single scatterer at the center of the probe. For a more in depth example see the notebook: Simulating ultrasound data with zea.

raw_data = simulate_rf(
    scatterer_positions=np.array([[0, 0, 20e-3]]),
    scatterer_magnitudes=np.array([1.0]),
    probe_geometry=np.stack(
        [np.linspace(-20e-3, 20e-3, 64), np.zeros(64), np.zeros(64)], axis=-1
    ),
    apply_lens_correction=True,
    lens_thickness=1e-3,
    lens_sound_speed=1000,
    sound_speed=1540,
    n_ax=1024,
    center_frequency=5e6,
    sampling_frequency=20e6,
    t0_delays=np.zeros((1, 64)),
    initial_times=np.zeros(1),
    element_width=0.2e-3,
    attenuation_coef=0.5,
    tx_apodizations=np.ones((1, 64)),
)

Functions

attenuate(f, attenuation_coef, dist)

Applies attenuation to the signal in the frequency domain.

delay2(f, tau, n_fft, sampling_frequency)

Applies a delay in the frequency domain without phase wrapping.

directivity(f, theta, element_width, sound_speed)

Computes the directivity of a single element.

get_pulse_spectrum_fn(center_frequency[, ...])

Computes the spectrum of a sine that is windowed with a Hann window.

get_transducer_bandwidth_fn(...)

Computes the spectrum of a probe with a center frequency and bandwidth.

hann_fd(f, width)

The fourier transform of a hann window in the time domain with given width.

hann_unnormalized(x, width)

Hann window function that is 1 at the peak.

simulate_rf(scatterer_positions, ...)

Simulates RF data for a given set of scatterers.

sinc(x)

The normalized sinc function with a small offset to prevent division by zero.

spread(dist[, mindist])

Function modeling geometric spreading of the wavefront.

zea.simulator.attenuate(f, attenuation_coef, dist)[source]

Applies attenuation to the signal in the frequency domain.

Parameters:
  • f (array-like) – The input frequencies.

  • attenuation_coef (float) – The attenuation coefficient in dB/cm/MHz.

  • dist (float) – The distance the signal has traveled.

Returns:

The spectrum of the attenuation.

Return type:

array-like

zea.simulator.delay2(f, tau, n_fft, sampling_frequency)[source]

Applies a delay in the frequency domain without phase wrapping.

Parameters:
  • f (array-like) – The input frequencies.

  • tau (float) – The delay to apply.

  • n_fft (int) – The number of samples in the FFT.

  • sampling_frequency (float) – The sampling frequency.

Returns:

The spectrum of the delay.

Return type:

array-like

zea.simulator.directivity(f, theta, element_width, sound_speed, rigid_baffle=True)[source]

Computes the directivity of a single element.

Parameters:
  • f (array-like) – The input frequencies [Hz].

  • theta (array-like) – The angles [rad].

  • element_width (float) – The width of the element [m].

  • sound_speed (float) – The speed of sound [m/s].

  • rigid_baffle (bool) – Whether the element is mounted on a rigid baffle, impacting the directivity.

Returns:

The directivity of the element.

Return type:

array-like

zea.simulator.get_pulse_spectrum_fn(center_frequency, n_period=3.0)[source]

Computes the spectrum of a sine that is windowed with a Hann window.

Parameters:
  • center_frequency (float) – The center frequency of the pulse.

  • n_period (float) – The number of periods to include in the pulse.

Returns:

A function that computes the spectrum of the pulse for the input frequencies in Hz.

Return type:

spectrum_fn (callable)

zea.simulator.get_transducer_bandwidth_fn(center_frequency, bandwidth)[source]

Computes the spectrum of a probe with a center frequency and bandwidth.

Parameters:
  • center_frequency (float) – The center frequency of the probe.

  • bandwidth (float) – The bandwidth of the probe.

Returns

spectrum_fn (callable): A function that computes the spectrum of the pulse for the input frequencies in Hz.

zea.simulator.hann_fd(f, width)[source]

The fourier transform of a hann window in the time domain with given width.

zea.simulator.hann_unnormalized(x, width)[source]

Hann window function that is 1 at the peak. This means that the integral of the window function is not necessarily 1.

Parameters:
  • x (array-like) – The input values.

  • width (float) – The width of the window. This is the total width from -x to x. The window will be nonzero in the range [-width/2, width/2].

Returns:

The values of the Hann window function.

Return type:

hann_vals (array-like)

zea.simulator.simulate_rf(scatterer_positions, scatterer_magnitudes, probe_geometry, apply_lens_correction, lens_thickness, lens_sound_speed, sound_speed, n_ax, center_frequency, sampling_frequency, t0_delays, initial_times, element_width, attenuation_coef, tx_apodizations)[source]

Simulates RF data for a given set of scatterers.

Parameters:
  • scatterer_positions (array-like) – The positions of the scatterers [m] of shape (n_scat, 3).

  • scatterer_magnitudes (array-like) – The magnitudes of the scatterers of shape (n_scat,).

  • probe_geometry (array-like) – The geometry of the probe [m] of shape (n_el, 3).

  • apply_lens_correction (bool) – Whether to apply lens correction.

  • lens_thickness (float) – The thickness of the lens [m].

  • lens_sound_speed (float) – The speed of sound in the lens [m/s].

  • sound_speed (float) – The speed of sound in the medium [m/s].

  • n_ax (int) – The number of samples in the RF data.

  • center_frequency (float) – The center frequency of the pulse [Hz].

  • sampling_frequency (float) – The sampling frequency of the RF data [Hz].

  • t0_delays (array-like) – The delays of the transmitting elements [s] of shape (n_tx, n_el).

  • initial_times (array-like) – The initial times of the transmitting elements [s] of shape (n_tx,).

  • element_width (float) – The width of the elements [m].

  • attenuation_coef (float) – The attenuation coefficient [dB/cm/MHz].

  • tx_apodizations (array-like) – The apodizations of the transmitting elements of shape (n_tx, n_el).

Returns:

The simulated RF data of shape (1, n_tx, n_ax, n_el, 1).

Return type:

rf_data (array-like)

zea.simulator.sinc(x)[source]

The normalized sinc function with a small offset to prevent division by zero.

zea.simulator.spread(dist, mindist=0.0001)[source]

Function modeling geometric spreading of the wavefront.

Parameters:
  • dist (array-like) – The distance the wave has traveled.

  • mindist (float) – The minimum distance to prevent division by zero.

Returns:

The geometric spreading factor of same shape as dist.

Return type:

array-like