zea.scan

Structure containing parameters defining an ultrasound scan.

This module provides the Scan class, a flexible structure for managing all parameters related to an ultrasound scan acquisition.

Features

  • Flexible initialization: The Scan class supports lazy initialization, allowing you to specify any combination of supported parameters. You can pass only the parameters you have, and the rest will be computed or set to defaults as needed.

  • Automatic computation: Many scan properties (such as grid, number of pixels, wavelength, etc.) are computed automatically from the provided parameters. This enables you to work with minimal input and still obtain all necessary scan configuration details.

  • Dependency tracking and lazy evaluation: Derived properties are computed only when accessed, and are automatically invalidated and recomputed if their dependencies change. This ensures efficient memory usage and avoids unnecessary computations.

  • Parameter validation: All parameters are type-checked and validated against a predefined schema, reducing errors and improving robustness.

  • Selection of transmits: The scan supports flexible selection of transmit events, using the set_transmits() method. You can select all, a specific number, or specific transmit indices. The selection is stored and can be accessed via the selected_transmits property.

Comparison to zea.Config and zea.Probe

  • zea.config.Config: A general-purpose parameter dictionary for experiment and pipeline configuration. It is not specific to ultrasound acquisition and does not compute derived parameters.

  • zea.probes.Probe: Contains only probe-specific parameters (e.g., geometry, frequency).

  • zea.scan.Scan: Combines all parameters relevant to an ultrasound acquisition, including probe, acquisition, and scan region. It also provides automatic computation of derived properties and dependency management.

Example Usage

>>> from zea import Config, Probe, Scan

>>> # Initialize Scan from a Probe's parameters
>>> probe = Probe.from_name("verasonics_l11_4v")
>>> scan = Scan(**probe.get_parameters(), grid_size_z=256, n_tx=11)

>>> # Or initialize from a Config object
>>> config = Config.from_path("hf://zeahub/configs/config_picmus_rf.yaml")
>>> scan = Scan(n_tx=11, **config.scan)

>>> # Or manually specify parameters
>>> scan = Scan(
...     grid_size_x=128,
...     grid_size_z=256,
...     xlims=(-0.02, 0.02),
...     zlims=(0.0, 0.06),
...     ylims=(0.0, 0.0),
...     center_frequency=6.25e6,
...     sound_speed=1540.0,
...     sampling_frequency=25e6,
...     n_el=128,
...     n_tx=11,
...     probe_geometry=probe.probe_geometry,
... )

>>> # Access a derived property (computed lazily)
>>> grid = scan.grid  # shape: (grid_size_z, grid_size_x, 3)

>>> # Select a subset of transmit events
>>> _ = scan.set_transmits(3)  # Use 3 evenly spaced transmits
>>> _ = scan.set_transmits([0, 2, 4])  # Use specific transmit indices
>>> _ = scan.set_transmits("all")  # Use all transmits

Classes

Scan(**kwargs)

Represents an ultrasound scan configuration with computed properties.
class zea.scan.Scan(**kwargs)[source]

Bases: Parameters

Represents an ultrasound scan configuration with computed properties.

Parameters:

  • grid_size_x (int) – Grid width in pixels. For a cartesian grid, this is the lateral (x) pixels in the grid, set to prevent aliasing if not provided. For a polar grid, this can be thought of as the number for rays in the polar direction.

  • grid_size_z (int) – Grid height in pixels. This is the number of axial (z) pixels in the grid, set to prevent aliasing if not provided.

  • sound_speed (float, optional) – Speed of sound in the medium in m/s. Defaults to 1540.0.

  • sampling_frequency (float) – Sampling frequency in Hz.

  • center_frequency (float) – Transmit center frequency in Hz.

  • demodulation_frequency (float, optional) – Demodulation frequency in Hz.

  • n_el (int) – Number of elements in the transducer array.

  • n_tx (int) – Number of transmit events in the dataset.

  • n_ax (int) – Number of axial samples in the received signal.

  • n_ch (int, optional) – Number of channels (1 for RF, 2 for IQ data).

  • xlims (tuple of float) – Lateral (x) limits of the imaging region in meters (min, max).

  • ylims (tuple of float, optional) – Elevation (y) limits of the imaging region in meters (min, max).

  • zlims (tuple of float) – Axial (z) limits of the imaging region in meters (min, max).

  • probe_geometry (np.ndarray) – Element positions as array of shape (n_el, 3).

  • polar_angles (np.ndarray) – Polar angles for each transmit event in radians of shape (n_tx,). These angles are often used in 2D imaging.

  • azimuth_angles (np.ndarray) – Azimuth angles for each transmit event in radians of shape (n_tx,). These angles are often used in 3D imaging.

  • t0_delays (np.ndarray) – Transmit delays in seconds of shape (n_tx, n_el), shifted such that the smallest delay is 0.

  • tx_apodizations (np.ndarray) – Transmit apodizations of shape (n_tx, n_el).

  • focus_distances (np.ndarray) – Distance from the origin point on the transducer to where the beam comes to focus for each transmit in meters of shape (n_tx,).

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

  • initial_times (np.ndarray) – Initial times in seconds for each event of shape (n_tx,).

  • bandwidth_percent (float, optional) – Bandwidth as percentage of center frequency. Defaults to 200.0.

  • time_to_next_transmit (np.ndarray) – The time between subsequent transmit events of shape (n_frames, n_tx).

  • tgc_gain_curve (np.ndarray) – Time gain compensation (TGC) curve of shape (n_ax,).

  • waveforms_one_way (np.ndarray) – The one-way transmit waveforms of shape (n_waveforms, n_samples).

  • waveforms_two_way (np.ndarray) – The two-way transmit waveforms of shape (n_waveforms, n_samples).

  • tx_waveform_indices (np.ndarray) – Indices of the waveform used for each transmit event of shape (n_tx,).

  • t_peak (np.ndarray, optional) – The time of the peak of the pulse of every transmit waveform of shape (n_waveforms,).

  • pixels_per_wavelength (int, optional) – Number of pixels per wavelength. Defaults to 4.

  • element_width (float, optional) – Width of each transducer element in meters.

  • resolution (float, optional) – Resolution for scan conversion in mm / pixel. If None, it is calculated based on the input image.

  • pfield_kwargs (dict, optional) – Additional parameters for pressure field computation. See zea.beamform.pfield.compute_pfield for details.

  • apply_lens_correction (bool, optional) – Whether to apply lens correction to delays. Defaults to False.

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

  • f_number (float, optional) – F-number of the transducer. Defaults to 1.0.

  • theta_range (tuple, optional) – Range of theta angles for 3D imaging.

  • phi_range (tuple, optional) – Range of phi angles for 3D imaging.

  • rho_range (tuple, optional) – Range of rho (radial) distances for 3D imaging.

  • fill_value (float, optional) – Value to use for out-of-bounds pixels.

  • attenuation_coef (float, optional) – Attenuation coefficient in dB/(MHz*cm). Defaults to 0.0.

  • selected_transmits (None, str, int, list, slice, or np.ndarray, optional) – Specifies which transmit events to select. - None or “all”: Use all transmits. - “center”: Use only the center transmit. - int: Select this many evenly spaced transmits. - list/array: Use these specific transmit indices. - slice: Use transmits specified by the slice (e.g., slice(0, 10, 2)).

  • grid_type (str, optional) – Type of grid to use for beamforming. Can be “cartesian” or “polar”. Defaults to “cartesian”.

  • dynamic_range (tuple, optional) – Dynamic range for image display. Defined in dB as (min_dB, max_dB). Defaults to (-60, 0).

  • distance_to_apex (float, optional) – Distance from the transducer to the apex of the pixel grid. This property is used for polar grids. Will be computed automatically if not provided.

VALID_PARAMS = {'apply_lens_correction': {'default': False, 'type': <class 'bool'>}, 'attenuation_coef': {'default': 0.0, 'type': <class 'float'>}, 'azimuth_angles': {'type': <class 'numpy.ndarray'>}, 'bandwidth_percent': {'default': 200.0, 'type': <class 'float'>}, 'center_frequency': {'type': <class 'float'>}, 'demodulation_frequency': {'type': <class 'float'>}, 'distance_to_apex': {'type': <class 'float'>}, 'dynamic_range': {'type': (<class 'tuple'>, <class 'list'>)}, 'element_width': {'type': <class 'float'>}, 'f_number': {'default': 1.0, 'type': <class 'float'>}, 'fill_value': {'type': <class 'float'>}, 'focus_distances': {'type': <class 'numpy.ndarray'>}, 'grid_size_x': {'type': <class 'int'>}, 'grid_size_y': {'type': <class 'int'>}, 'grid_size_z': {'type': <class 'int'>}, 'grid_type': {'default': 'cartesian', 'type': <class 'str'>}, 'initial_times': {'type': <class 'numpy.ndarray'>}, 'lens_sound_speed': {'type': <class 'float'>}, 'lens_thickness': {'type': <class 'float'>}, 'n_ax': {'type': <class 'int'>}, 'n_ch': {'type': <class 'int'>}, 'n_el': {'type': <class 'int'>}, 'n_frames': {'type': <class 'int'>}, 'n_tx': {'type': <class 'int'>}, 'pfield_kwargs': {'default': {}, 'type': <class 'dict'>}, 'phi_range': {'default': None, 'type': (<class 'tuple'>, <class 'list'>)}, 'pixels_per_wavelength': {'default': 4, 'type': <class 'int'>}, 'polar_angles': {'type': <class 'numpy.ndarray'>}, 'polar_limits': {'type': (<class 'tuple'>, <class 'list'>)}, 'probe_geometry': {'type': <class 'numpy.ndarray'>}, 'resolution': {'default': None, 'type': <class 'float'>}, 'rho_range': {'type': (<class 'tuple'>, <class 'list'>)}, 'sampling_frequency': {'type': <class 'float'>}, 'selected_transmits': {'default': None, 'type': (<class 'NoneType'>, <class 'str'>, <class 'int'>, <class 'list'>, <class 'slice'>, <class 'numpy.ndarray'>)}, 'sound_speed': {'default': 1540.0, 'type': <class 'float'>}, 't0_delays': {'type': <class 'numpy.ndarray'>}, 't_peak': {'type': <class 'numpy.ndarray'>}, 'tgc_gain_curve': {'type': <class 'numpy.ndarray'>}, 'theta_range': {'type': (<class 'tuple'>, <class 'list'>)}, 'time_to_next_transmit': {'type': <class 'numpy.ndarray'>}, 'transmit_origins': {'type': <class 'numpy.ndarray'>}, 'tx_apodizations': {'type': <class 'numpy.ndarray'>}, 'tx_waveform_indices': {'type': <class 'numpy.ndarray'>}, 'waveforms_one_way': {'default': None, 'type': <class 'numpy.ndarray'>}, 'waveforms_two_way': {'default': None, 'type': <class 'numpy.ndarray'>}, 'xlims': {'type': (<class 'tuple'>, <class 'list'>)}, 'ylims': {'type': (<class 'tuple'>, <class 'list'>)}, 'zlims': {'type': (<class 'tuple'>, <class 'list'>)}}
property aperture_size

Calculate the aperture size (x,y,z) based on the probe geometry.

property azimuth_angles

Azimuth angles for each transmit event in radians of shape (n_tx,). These angles are often used in 3D imaging.

property azimuth_limits

The limits of the azimuth angles.

property coordinates

Get the coordinates for scan conversion, will be 3D if phi_range is set, otherwise 2D.

property coordinates_2d

The coordinates for scan conversion.

property coordinates_3d

The coordinates for scan conversion.

property demodulation_frequency

The demodulation frequency in Hz.

property distance_to_apex

Calculate the distance from the transducer to the apex of the pixel grid.

property element_width

The width of each transducer element in meters.

property extent

The extent of the beamforming grid in the format (xmin, xmax, zmax, zmin). Can be directly used with plt.imshow(x, extent=scan.extent) for visualization.

property flat_pfield

Flattened pfield for weighting of shape (n_pix, n_tx).

property flatgrid

The beamforming grid of shape (grid_size_z*grid_size_x*grid_size_y, 3).

property focus_distances

Focus distances in meters for each event of shape (n_tx,).

property frames_per_second

The number of frames per second [Hz]. Assumes a constant frame rate.

Frames per second computed based on time between transmits within a frame. Ignores time between frames (e.g. due to processing).

Uses the time it took to do all transmits (per frame). So if you only use some portion of the transmits, the fps will still be calculated based on all.

property grid

The beamforming grid of shape (grid_size_z, grid_size_x, 3).

property grid_size_x

Grid width in pixels. For a cartesian grid, this is the lateral (x) pixels in the grid, set to prevent aliasing if not provided. For a polar grid, this can be thought of as the number for rays in the polar direction.

property grid_size_y

Grid height in pixels. For a cartesian grid, this is the vertical (y) pixels in the grid, set to prevent aliasing if not provided. For a polar grid, this can be thought of as the number for rays in the azimuthal direction.

property grid_size_z

Grid depth in pixels. This is the number of axial (z) pixels in the grid, set to prevent aliasing if not provided.

property initial_times

Initial times in seconds for each event of shape (n_tx,).

property is_3d
property n_tx

The number of currently selected transmits.

property n_tx_total

The total number of transmits in the full dataset.

property n_waveforms

The number of unique transmit waveforms.

property pfield: ndarray

Compute or return the pressure field (pfield) for weighting.

property polar_angles

Polar angles for each transmit event in radians of shape (n_tx,). These angles are often used in 2D imaging.

property polar_limits

The limits of the polar angles, used for polar grids.

property pulse_repetition_frequency

The pulse repetition frequency (PRF) [Hz]. Assumes a constant PRF.

property rho_range

A tuple specifying the range of rho values (min_rho, max_rho). Defined in mm. Used for scan conversion.

set_transmits(selection)[source]

Select which transmit events to use.

This method provides flexible ways to select transmit events:

Parameters:

selection – Specifies which transmits to select: - None: Use all transmits - “all”: Use all transmits - “center”: Use only the center transmit - “focused”: Use only focused transmits - “diverging”: Use only diverging transmits - “plane”: Use only plane wave transmits - int: Select this many evenly spaced transmits - list/array: Use these specific transmit indices - slice: Use transmits specified by the slice (e.g., slice(0, 10, 2))

Returns:

The current instance for method chaining.

Raises:

ValueError – If the selection is invalid or incompatible with the scan.

property t0_delays

Transmit delays in seconds of shape (n_tx, n_el), shifted such that the smallest delay is 0.

property t_peak

The time of the peak of the pulse in seconds of shape (n_waveforms,).

property tgc_gain_curve

Time gain compensation (TGC) curve of shape (n_ax,).

property theta_range

A tuple specifying the range of theta values (min_theta, max_theta). Defined in radians. Used for scan conversion.

property time_to_next_transmit

The time between subsequent transmit events of shape (n_frames, n_tx).

property transmit_origins

Transmit origins of shape (n_tx, 3).

property tx_apodizations

Transmit apodizations of shape (n_tx, n_el).

property tx_waveform_indices

Indices of the waveform used for each transmit event of shape (n_tx,).

property wavelength

Calculate the wavelength based on sound speed and transmit center frequency.

property xlims

The x-limits of the beamforming grid [m]. If not explicitly set, it is computed based on the polar limits and probe geometry.

property ylims

The y-limits of the beamforming grid [m]. If not explicitly set, it is computed based on the azimuth limits and probe geometry.

property zlims

The z-limits of the beamforming grid [m].