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)

# Or initialize from a Config object
config = Config.from_hf("zeahub/configs", "config_picmus_rf.yaml", repo_type="dataset")
scan = Scan(**config.scan, n_tx=11)

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

# 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) – Center frequency of the transducer 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) – Focus distances in meters for each event of shape (n_tx,).

  • 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.

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

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

  • 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. Defaults to None.

  • 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. Defaults to 0.0.

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

  • selected_transmits (None, str, int, list, 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.

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

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'>}, 'dynamic_range': {'default': (-60, 0), 'type': (<class 'tuple'>, <class 'list'>)}, 'element_width': {'type': <class 'float'>}, 'f_number': {'default': 1.0, 'type': <class 'float'>}, 'fill_value': {'default': 0.0, 'type': <class 'float'>}, 'focus_distances': {'type': <class 'numpy.ndarray'>}, 'grid_size_x': {'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'>, <class 'int'>)}, 'lens_thickness': {'type': <class 'float'>}, 'n_ax': {'type': <class 'int'>}, 'n_ch': {'type': <class 'int'>}, 'n_el': {'type': <class 'int'>}, 'n_tx': {'type': <class 'int'>}, 'pfield_kwargs': {'default': {}, 'type': <class 'dict'>}, 'phi_range': {'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'>}, 'sound_speed': {'default': 1540.0, 'type': (<class 'float'>, <class 'int'>)}, 't0_delays': {'type': <class 'numpy.ndarray'>}, 'theta_range': {'type': (<class 'tuple'>, <class 'list'>)}, 'time_to_next_transmit': {'type': <class 'numpy.ndarray'>}, 'tx_apodizations': {'type': <class 'numpy.ndarray'>}, 'xlims': {'type': (<class 'tuple'>, <class 'list'>)}, 'ylims': {'type': (<class 'tuple'>, <class 'list'>)}, 'zlims': {'type': (<class 'tuple'>, <class 'list'>)}}
property azimuth_angles

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

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.

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.

property flatgrid

The beamforming grid of shape (grid_size_z*grid_size_x, 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_z

Grid height 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 n_tx

The number of currently selected transmits.

property n_tx_total

The total number of transmits in the full dataset.

property pfield

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.

property rho_range

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

property selected_transmits

Get the currently selected transmit indices.

Returns:

The list of selected transmit indices. If none were explicitly selected and n_tx is available, all transmits are used.

Return type:

list

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 - int: Select this many evenly spaced transmits - list/array: Use these specific transmit indices

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

Transmit apodizations of shape (n_tx, n_el).

property wavelength

Calculate the wavelength based on sound speed and 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 zlims

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