Parameters

Note

For the HDF5 data format and file I/O see Data. For pipeline operations see Pipeline.

Parameters in the file

Every zea HDF5 file stores all parameters needed to process the acquisition alongside the raw data. They are split into two groups:

Probe (probe/)

Fixed for the whole acquisition — element geometry, center frequency, bandwidth, lens properties. Shared across all tracks. Defined by ProbeSpec.

Scan (scan/)

Per-track transmit sequence — delays, apodizations, angles, waveforms, sound speed. Each track has its own ScanSpec.

See the Group reference table for the complete field listing.

zea.Parameters

load_parameters() merges the probe and scan groups into a single Parameters object and adds derived quantities (wavelength, n_tx, grid, xlims/zlims, selected_transmits):

with zea.File("data.hdf5") as f:
    parameters = f.load_parameters()             # single-track
    parameters = f.tracks[0].load_parameters()   # multi-track

Config

A config is a YAML file (loaded as Config) that specifies where the data lives, the pipeline to run, the device to use, and any parameter overrides.

>>> from zea import Config
>>> from zea.config import check_config

>>> config = Config.from_path("../configs/config_picmus_rf.yaml")
>>> config = check_config(config)   # fills defaults, validates
>>> config.pipeline.operations
['demodulate',
 {'name': 'downsample', 'params': {'factor': 4}},
 {'name': 'beamform', 'params': {'beamformer': 'delay_and_sum', 'enable_pfield': False}},
 'envelope_detect',
 'normalize',
 'log_compress']

>>> config.to_yaml("my_config.yaml")

Supported keys

data — where to find the file

Key	Default	Description
path	null	Full path to the HDF5 file. Supports local absolute paths, paths relative to the user data root (set in users.yaml), and Hugging Face Hub paths (hf://org/repo/path/to/file.hdf5).
local	true	Whether to use local data (true) or data at a remote location (false). Use null when the users.yaml paths are single paths, shared by both.
indices	null	Which frames to load: null (default), 'all', a single int, or a list of positive ints.

parameters — override any field from the Group reference or pass custom keys straight through to the pipeline:

parameters:
  center_frequency: 5.0e6
  xlims: [-0.02, 0.02]
  grid_size_x: 512

pipeline — list of operations (see Pipeline):

Key	Default	Description
operations	[identity]	Ordered list of operations. Each entry is either an operation name (string) or a mapping with name and optional params.
jit_options	'ops'	JIT scope: 'ops' (compile each op), 'pipeline' (compile the whole pipeline), or null (disable JIT).
with_batch_dim	true	Whether operations expect a leading batch dimension.

Top-level keys

Key	Default	Description
device	'auto:1'	Target hardware: cpu, gpu, cuda, gpu:0, auto:1 (auto-select; -1 for last device).
hide_devices	null	Device indices to exclude from auto-selection (int or list of ints).
git	null	Git commit or branch recorded for reproducibility.

The top-level config is open: arbitrary extra sections (model:, etc.) are accepted and passed through unchanged.

Defining a beamforming grid

The extent of the final produced image is defined by xlims and zlims. For a cartesian beamforming grid (grid_type="cartesian") this is also the extent of the beamforming grid. For a polar grid (grid_type="polar") the rays fan out from an apex a distance distance_to_apex behind the transducer surface. The rlims (radii from the apex) are then derived from zlims and the distance_to_apex offset. The final image after scan conversion is then defined by xlims and zlims again.

The pixel grid of a polar zea.Parameters object on a curved probe.

API reference

zea.Config([dictionary, __parent__])

Config object for managing configuration settings.

zea.config.check_config(config, verbose=False)

Check a config given dictionary