zea.scan

Structure containing the parameters defining an ultrasound acquisition.

This module provides the Parameters class, a flexible structure for managing all parameters related to an ultrasound acquisition (merged probe and scan parameters).

Features

• Flexible initialization: The Parameters 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.Parameters: 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, File, Probe, Parameters

>>> # The usual entry point: load the merged probe + scan parameters from a file
>>> path = (
...     "hf://zeahub/picmus/database/experiments/contrast_speckle/"
...     "contrast_speckle_expe_dataset_iq/contrast_speckle_expe_dataset_iq.hdf5"
... )
>>> with File(path) as f:
...     parameters = f.load_parameters()
>>> type(parameters).__name__
'Parameters'

>>> # You can also build one from a Probe's parameters ...
>>> probe = Probe.from_name("verasonics_l11_4v")
>>> parameters = Parameters(
...     probe_geometry=probe.probe_geometry,
...     center_frequency=probe.probe_center_frequency,
...     element_width=probe.element_width,
...     grid_size_z=256,
...     n_tx=11,
... )

>>> # ... from a Config's parameters ...
>>> config = Config.from_path("hf://zeahub/configs/config_picmus_rf.yaml")
>>> parameters = Parameters(n_tx=11, **config.parameters)

>>> # ... or fully manually
>>> parameters = Parameters(
...     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 = parameters.grid  # shape: (grid_size_z, grid_size_x, 3)

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

Classes

Parameters(**kwargs)	Represents a full ultrasound acquisition configuration with computed properties.
Scan(*args, **kwargs)	Deprecated alias for Parameters.

class zea.scan.Parameters(**kwargs)

Bases: BaseParameters

Represents a full ultrasound acquisition configuration with computed properties.

A Parameters object holds all parameters relevant to an acquisition — merged probe and scan parameters — and computes derived quantities (grid, wavelength, pfield, scan-conversion coordinates, …) lazily with dependency tracking and caching. Obtain one from a file via zea.data.file.File.load_parameters().

The set of valid file-backed parameters is derived from ScanSpec and ProbeSpec (single source of truth), extended with recon/beamforming parameters that are not stored in the file. Arbitrary custom parameters may also be set; they are stored as-is and are not used to compute any derived parameters (e.g. the beamforming grid). They are simply passed through — for example to a pipeline call (see BaseParameters).

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

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

• t_peak (np.ndarray, optional) – The time of the peak of the pulse of every transmit waveform of shape (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.

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

• 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, 'dtype': <class 'bool'>}, 'attenuation_coef': {'default': 0.0, 'dtype': <class 'numpy.float32'>}, 'azimuth_angles': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx',)}, 'center_frequency': {'dtype': <class 'numpy.float32'>, 'shape': ((), ('n_tx',))}, 'demodulation_frequency': {'dtype': <class 'numpy.float32'>, 'shape': ((), ('n_tx',))}, 'distance_to_apex': {'default': 0.0, 'dtype': <class 'numpy.float32'>}, 'dynamic_range': {'dtype': <class 'numpy.float32'>, 'shape': (2,)}, 'element_height': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'element_width': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'f_number': {'default': 1.0, 'dtype': <class 'float'>}, 'fill_value': {'dtype': <class 'float'>}, 'focus_distances': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx',)}, 'grid_size_x': {'dtype': <class 'numpy.int32'>}, 'grid_size_y': {'dtype': <class 'numpy.int32'>}, 'grid_size_z': {'dtype': <class 'numpy.int32'>}, 'grid_type': {'default': 'cartesian', 'dtype': <class 'str'>}, 'initial_times': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx',)}, 'lens_sound_speed': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'lens_thickness': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'n_ax': {'dtype': <class 'int'>}, 'n_ch': {'dtype': <class 'numpy.int32'>}, 'n_el': {'dtype': <class 'numpy.int32'>}, 'n_frames': {'dtype': <class 'numpy.int32'>}, 'n_tx': {'dtype': <class 'numpy.int32'>}, 'pfield_kwargs': {'default': {}, 'dtype': <class 'dict'>}, 'phi_range': {'dtype': <class 'numpy.float32'>, 'shape': (2,)}, 'pixels_per_wavelength': {'default': 4, 'dtype': <class 'numpy.int32'>}, 'polar_angles': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx',)}, 'polar_limits': {'dtype': <class 'numpy.float32'>, 'shape': (2,)}, 'probe_bandwidth_percent': {'default': 200.0, 'dtype': <class 'numpy.float32'>, 'shape': ()}, 'probe_center_frequency': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'probe_geometry': {'dtype': <class 'numpy.float32'>, 'shape': ('n_el', 3)}, 'resolution': {'default': None, 'dtype': (<class 'numpy.float32'>, <class 'NoneType'>)}, 'rho_range': {'dtype': <class 'numpy.float32'>, 'shape': (2,)}, 'sampling_frequency': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'selected_transmits': {'default': None, 'dtype': (<class 'NoneType'>, <class 'str'>, <class 'int'>, <class 'list'>, <class 'slice'>, <class 'numpy.ndarray'>)}, 'sound_speed': {'default': 1540.0, 'dtype': <class 'numpy.float32'>, 'shape': ()}, 't0_delays': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_el')}, 't_peak': {'dtype': <class 'numpy.float32'>}, 'tgc_gain_curve': {'dtype': <class 'numpy.float32'>, 'shape': ('n_ax',)}, 'theta_range': {'dtype': <class 'numpy.float32'>, 'shape': (2,)}, 'time_to_next_transmit': {'dtype': <class 'numpy.float32'>, 'shape': ('n_frames', 'n_tx')}, 'transmit_origins': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 3)}, 'tx_apodizations': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_el')}, 'waveforms_one_way': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_samples_one_way')}, 'waveforms_two_way': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_samples_two_way')}, 'xlims': {'dtype': <class 'numpy.float32'>, 'shape': (2,)}, 'ylims': {'dtype': <class 'numpy.float32'>, 'shape': (2,)}, 'zlims': {'dtype': <class 'numpy.float32'>, 'shape': (2,)}}

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.

property coordinates_2d

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 extent

(xmin, xmax, ymin, ymax, zmin, zmax).

Type:

The extent of the beamforming grid in the format

property extent_imshow

(xmin, xmax, ymin, ymax, zmin, zmax).

Returns:

The extent of the beamforming grid in the format (xmin, xmax, zmax, zmin).

This format can be used directly in matplotlib’s plt.imshow.

Return type:

np.ndarray

Type:

The extent of the beamforming grid in the format

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, [grid_size_y], 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

Whether the scan grid is 3D (True) or 2D (False).

key = 'type'

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 of shape (n_tx, grid_size_z, grid_size_x).

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.

probe_schema = {'element_height': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'element_width': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'lens_sound_speed': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'lens_thickness': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'probe_bandwidth_percent': {'default': 200.0, 'dtype': <class 'numpy.float32'>, 'shape': ()}, 'probe_center_frequency': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'probe_geometry': {'dtype': <class 'numpy.float32'>, 'shape': ('n_el', 3)}}

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.

scan_schema = {'azimuth_angles': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx',)}, 'center_frequency': {'dtype': <class 'numpy.float32'>, 'shape': ((), ('n_tx',))}, 'demodulation_frequency': {'dtype': <class 'numpy.float32'>, 'shape': ((), ('n_tx',))}, 'focus_distances': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx',)}, 'initial_times': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx',)}, 'polar_angles': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx',)}, 'sampling_frequency': {'dtype': <class 'numpy.float32'>, 'shape': ()}, 'sound_speed': {'default': 1540.0, 'dtype': <class 'numpy.float32'>, 'shape': ()}, 't0_delays': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_el')}, 'tgc_gain_curve': {'dtype': <class 'numpy.float32'>, 'shape': ('n_ax',)}, 'time_to_next_transmit': {'dtype': <class 'numpy.float32'>, 'shape': ('n_frames', 'n_tx')}, 'transmit_origins': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 3)}, 'tx_apodizations': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_el')}, 'waveforms_one_way': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_samples_one_way')}, 'waveforms_two_way': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_samples_two_way')}}

set_transmits(selection)

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

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

to_probe_dict()

Return file-backed probe parameters as a plain dict.

Suitable for passing directly to create() as the probe argument, or to save_file() alongside to_scan_dict().

Only fields defined in ProbeSpec that are currently stored on this object are included (None values are omitted).

Returns:

Probe parameter dict keyed by ProbeSpec

field names.

Return type:

dict

to_scan_dict()

Return scan parameters as a plain dict.

Suitable for passing directly to create() as the scan argument, or to save_file() alongside to_probe_dict().

Only fields defined in ScanSpec that are currently stored on this object are included (None values are omitted). Values are read through property access so that any active selected_transmits filtering is applied (e.g. after calling set_transmits()).

Returns:

Scan parameter dict keyed by ScanSpec

field names.

Return type:

dict

property transmit_origins

Transmit origins of shape (n_tx, 3).

property tx_apodizations

Transmit apodizations of shape (n_tx, n_el).

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

class zea.scan.Scan(*args, **kwargs)

Bases: Parameters

Deprecated alias for Parameters.

Scan was renamed to zea.Parameters (which now holds the merged probe and scan parameters). This subclass is kept temporarily to ease the transition: instantiating it emits a DeprecationWarning pointing to zea.Parameters. It will be removed in a future release.