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