zea.Parameters

class zea.Parameters(**kwargs)

Bases: BaseParameters

Contains and computes all parameters relevant to an ultrasound acquisition.

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

property aperture_size

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

apply_lens_correction: bool

Whether to apply lens correction to the transmit delays. Defaults to False.

attenuation_coef: float

Attenuation coefficient [dB/(MHz*cm)]. Defaults to 0.0.

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.

Returns None if azimuth angles were not provided (e.g. standard 2D imaging).

The presence check uses the raw parameter to avoid triggering the azimuth_angles “using zeros” fallback warning for 2D data.

center_frequency: float | ndarray

Transmit center frequency [Hz]. Scalar, or shape (n_tx,) per transmit.

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.

dynamic_range: ndarray

Dynamic range for image display in dB, shape (2,) as (min_dB, max_dB).

element_height: float

Height (elevation) of each transducer element [m].

element_width: float

Width of each transducer element [m].

enable_scanline: bool

one pixel column per transmit (see scanline_pixel_grid()) instead of a shared compounded grid_type grid, paired with flat_aligned_apodization (fed to AlignedApodization). Combine with grid_type="cartesian" for vertical focused columns (linear-scan geometry) or grid_type="polar" for steered rays from each transmit’s own origin (sector / phased-array geometry). Defaults to False.

Note

This only builds the scanline grid. For true classical scanline beamforming, also construct the beamformer with Beamform(enable_aligned_apodization=True) so that flat_aligned_apodization masks each pixel to its owning transmit; without it every transmit is still compounded onto the one-column-per-transmit grid.

Type:

Whether to beamform in scanline (line-by-line) mode

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

f_number: float

F-number of the transducer. Defaults to 1.0.

fill_value: float

Value used for out-of-bounds pixels during scan conversion.

find_transmits(selection)

Find transmit events based on a selection.

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 (positive finite focus_distances)

• "diverging" (-) – Use only diverging transmits (negative finite focus_distances)

• "plane" (-) – Use only plane wave transmits (np.inf, the preferred marker, or 0)

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

Return type:

list

Returns:

The selected transmit indices.

Raises:

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

property flat_aligned_apodization

Per-pixel, per-transmit compounding apodization weight of shape (n_pix, n_tx).

Only defined when enable_scanline is True, where it is the one-hot mask (see scanline_aligned_apodization()) that isolates each pixel’s owning transmit. None otherwise, which makes AlignedApodization a no-op.

This weights the transmit axis (compounding), not the receive channels; for custom receive-aperture apodization see flat_receive_apodization.

property flat_pfield

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

flat_receive_apodization: ndarray

Optional custom receive-aperture apodization of shape (n_pix, n_el).

Per-pixel, per-element (receive-channel) weights, fed to ReceiveApodization when the beamformer is built with Beamform(enable_receive_apodization=True). This is the user-supplied counterpart of the built-in f-number mask (fnumber_mask()) and is applied in addition to it (set f_number=0 to use a fully custom receive apodization alone). None (default) makes ReceiveApodization a no-op.

Distinct from flat_aligned_apodization, which weights the transmit axis (compounding), not the receive channels.

property flatgrid

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

focal_region_length: float

Full length in meters of the region around the focal plane of focused transmits.

In this region the first-arrival and last-arrival transmit delays are linearly blended, smoothing the focal-plane transition while preserving the same model outside the region. This targets the focal-depth artifact described by Rindal et al. (IUS 2018). Defaults to 0.0 (disabled, i.e. conventional first/last-arrival switching everywhere). A typical starting value is 2e-3 m (corresponding to +/-1e-3 m around the focal plane).

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. When enable_scanline is True, this is fixed to n_tx (one column per transmit).

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. When enable_scanline is True, this is the number of depth samples per transmit line.

grid_type: str

Beamforming grid type, "cartesian" or "polar". Defaults to "cartesian". Combine with enable_scanline=True for line-by-line (scanline) imaging instead of a shared compounded grid.

property is_3d

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

key = 'type'

lens_sound_speed: float

Speed of sound in the lens material [m/s].

lens_thickness: float

Thickness of the lens [m].

n_ax: int

Number of axial samples in the received signal.

n_ch: int

Number of channels (1 for RF, 2 for IQ data).

n_el: int

Number of elements in the transducer array.

n_frames: int

Number of frames in the dataset.

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

pfield_kwargs: dict

Extra keyword arguments for the pressure-field computation.

See zea.beamform.pfield.compute_pfield(). Defaults to {}.

phi_range: tuple | ndarray

Range of phi angles for 3D imaging [rad], shape (2,).

pixels_per_wavelength: int

Number of grid pixels per wavelength. Defaults to 4.

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_bandwidth_percent: float

Probe bandwidth as a percentage of the center frequency. Defaults to 200.0.

probe_center_frequency: float

Nominal center frequency of the probe [Hz].

probe_geometry: ndarray

Element positions [m], shape (n_el, 3).

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.

resolution: float | None

Resolution for scan conversion [mm/pixel]. If None, computed from the image.

property rho_range

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

sampling_frequency: float

Sampling frequency of the received signal [Hz].

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'), ('n_timing_intervals',))}, 'transmit_origins': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 3)}, 'tx_apodizations': {'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_el')}, 'waveforms_one_way': {'default': None, 'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_samples_one_way')}, 'waveforms_two_way': {'default': None, 'dtype': <class 'numpy.float32'>, 'shape': ('n_tx', 'n_samples_two_way')}}

selected_transmits: list[int] | None

Indices of the currently selected transmit events, or None when not yet resolved (e.g. image-only files where n_tx is unknown).

Assigning to this attribute (or calling set_transmits()) accepts any of the following, which are resolved to concrete indices via find_transmits():

• None or "all": use all transmits. If the total transmit count n_tx is not yet known (image-only files), set_transmits(None) leaves this as None until n_tx is set.

• "center": use only the center transmit.

• int: select this many evenly spaced transmits.

• list/np.ndarray: use these specific transmit indices.

• slice: use transmits given by the slice (e.g. slice(0, 10, 2)).

set_transmits(selection)

Set the selected transmits based on a selection.

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 (positive finite focus_distances)

• "diverging" (-) – Use only diverging transmits (negative finite focus_distances)

• "plane" (-) – Use only plane wave transmits (np.inf, the preferred marker, or 0)

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

sound_speed: float

Speed of sound in the medium [m/s]. Defaults to 1540.0.

property t_peak

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

If not set explicitly and waveforms_two_way (the two-way, pulse-echo transmit waveform) is available, this is estimated from it via compute_time_to_peak_stack(). Otherwise it defaults to 1 / center_frequency.

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

waveforms_one_way: ndarray | None

One-way transmit waveforms, shape (n_tx, n_samples_one_way). None if absent.

waveforms_two_way: ndarray | None

Two-way transmit waveforms, shape (n_tx, n_samples_two_way). None if absent.

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