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 angle phi [rad] of each transmit, of shape (n_tx,).

The spherical azimuth angle (physics convention): the rotation of the transmit direction around the z axis, from +x. Zero for 2D imaging. This is not the ultrasound “azimuth” (lateral, along the array) direction; the transmit’s angle in the y-z plane is its elevation angle (see elevation_limits).

property bandwidth

Width of the RF band kept by processing [Hz], centered on the demodulation_frequency. Used by BandPassFilter and by check_for_aliasing().

center_frequency: float | ndarray

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

check_for_aliasing(demodulated=True, bandwidth=None)

Warn when the beamforming grid under-samples the data it will carry.

Run by grid for cartesian grids. Whether a pixel pitch under-samples depends on whether the data reaching the grid is RF or baseband IQ, which the parameters alone do not tell. By default IQ is assumed: its axial limit is never stricter than the RF one, so a grid that fails it aliases either way, and the lateral limit is the same for both. See zea.beamform.pixelgrid.aliasing_limits() for the criteria. Only regular cartesian grids, 2D or 3D, are checked.

Parameters:

• demodulated – Whether the data reaching the grid is baseband IQ. Pass False to check against the stricter RF axial limit.

• bandwidth – The RF band in Hz. Overrides the bandwidth parameter; when neither is set, probe_bandwidth_percent of the center_frequency is assumed.

Returns:

The warnings emitted; empty when the grid is adequate.

Return type:

list

property coordinates

Get the coordinates for scan conversion.

property coordinates_2d

The coordinates for scan conversion.

These index the polar image, so they live in the frame of grid_apex; rlims already carries the offset. The output covers extent. When rlims is set explicitly, it describes a polar image of its own rather than this grid, so the output covers its bounding box instead.

property demodulation_frequency

The demodulation frequency in Hz.

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

property elevation_limits

Elevation angle atan(y / z) [rad] of the first and last sample in elevation, shape (2,). Sets the default ylims, and with rlims and polar_limits spans a 3D frustum (see zea.display.scan_convert_3d()).

If not explicitly provided, the range of the transmits’ elevation angles atan2(sin(theta) sin(phi), cos(theta)), from polar_angles and azimuth_angles, widened on each side by 15 % of that range, or by elevation_margin when set. None without azimuth_angles (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.

elevation_margin: float | None

Fixed angle [rad] to widen the default elevation_limits by on each side, replacing the automatic margin of 15 % of their range. Defaults to None (automatic).

enable_scanline: bool

one pixel column per transmit instead of a shared compounded grid_type grid, paired with flat_aligned_apodization (fed to AlignedApodization). Defaults to False.

Scanline imaging needs focused transmits (every focus distance > 0), and the grid type must match how the lines run:

• grid_type="polar" for steered lines whose axes meet in one point (sector / phased-array or curved-array geometry): the polar grid with one column per transmit angle, fanning out from grid_apex. polar_limits are the angles of the first and the last transmit.

• grid_type="cartesian" for unsteered, parallel lines (linear-scan geometry): a vertical column under each transmit (see scanline_pixel_grid()).

Both grids lie in the x-z plane, so the columns follow the transmit angles projected onto it, atan(x / z) (see Angle and radius names).

Any other combination raises a ValueError when the grid is built.

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

For a cartesian grid, the extent of the grid itself. For a polar grid, the window the scan-converted image fills, which ScanConvert takes from here:

• x spans xlims, which defaults to the width of the sector; an explicit value crops or pads the image.

• z spans the grid, except that on a flat array it starts at zlims[0], the depth the image was asked to start at. The rows of a polar grid are arcs around grid_apex, so at the sector edges the first rows reach above that depth (or, with a virtual apex, behind the array); those parts are cropped. A curved array needs no crop, since its rows already lie at a constant distance below the array surface, the first one at zlims[0].

Type:

The extent of the image 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 f_number

the acceptance cone of each element in the built-in receive mask (fnumber_mask()). 0 disables the mask.

If not explicitly provided, it follows from the probe: 1 / (2 tan(alpha)), with alpha the angle at which an element’s directivity drops to -6 dB (see element_acceptance_angle()), at the center frequency. The element width falls back to 90 % of the pitch. Elements narrower than about 0.6 wavelength receive over the whole half-space, which gives 0 (typical for phased arrays). Without a probe geometry or center frequency it is 1.0.

This sets which pixels each element contributes to; it does not change the grid.

Type:

Receive f-number

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

Can be set explicitly to any weighting, in which case it is stored over the full transmit axis and read back sliced by selected_transmits. This requires enable_scanline to be False: a scanline grid has one column per selected transmit, so its pixel axis is defined by the transmit selection and a mask stored over the full transmit axis cannot stay aligned with it. When left unset, it is the one-hot mask (see scanline_aligned_apodization()) that isolates each pixel’s owning transmit if enable_scanline is True, and 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_apex

The point (x, y, z) [m] a polar grid fans out from, of shape (3,).

It lies on the central axis, at or behind the array: (0, 0, -d) with d >= 0. Radii are measured from it, so rlims = zlims - grid_apex[2]. It is derived, not set: the grid fans out from where the transmits fan out from. In order of precedence:

1. Steered focused transmit axes that meet in one point: that point. This is the middle of the array for transmits launched from there, a virtual apex behind a flat array whose transmits are spread over it, and the centre of curvature for transmits along a curved array’s normals.

2. Unsteered diverging waves that share one virtual source: that source.

3. A curved array: its centre of curvature (see radius_of_curvature).

4. A flat array whose polar_limits are derived (not set, and not a scanline grid, whose limits are its transmit angles): the apex they are seen from, where the outermost edge ray, traced back from its array end, crosses the central axis. The middle of the array when the edge rays are all parallel to it.

5. A flat array with a sector (explicit or polar_margin-widened, non-zero polar_limits): the virtual apex whose sector edges pass through the ends of the array, d = (aperture / 2) / tan(max |polar_limits|).

6. Otherwise the middle of the array.

Missing transmit_origins count as zeros, as in the beamformer.

property grid_size_x

Grid width in pixels, set to prevent aliasing if not provided.

For a cartesian grid, the number of lateral (x) pixels across xlims. For a polar grid, the number of rays, sized by the outer arc length (zlims[1] - grid_apex[2]) * (polar_limits[1] - polar_limits[0]). When enable_scanline is True, this is fixed to n_tx (one column per transmit).

property grid_size_y

Grid size in elevation (y), across the array, in pixels. For a cartesian grid, set to prevent aliasing if not provided. For a polar grid, this can be thought of as the number of rays in the elevation 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. A polar grid fans out from grid_apex.

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_rx

Number of receive channels in the channel data.

Equal to n_el unless the acquisition used a receive sub-aperture, which rx_aperture_indices then maps onto the probe’s elements.

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 transmit waveforms, one per selected transmit.

property pfield: ndarray

Compute or return the pressure field (pfield) for weighting of shape (n_tx, grid_size_z, grid_size_x).

Uses attenuation_coef, unless overridden in pfield_kwargs.

pfield_kwargs: dict

Extra keyword arguments for the pressure-field computation.

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

pixels_per_wavelength: int

Number of grid pixels per wavelength. Defaults to 4.

property polar_angles

Polar angle theta [rad] of each transmit, of shape (n_tx,).

The spherical polar angle (physics convention): the angle between the transmit direction and +z. Together with azimuth_angles it gives the direction (sin(theta) cos(phi), sin(theta) sin(phi), cos(theta)). In 2D imaging phi = 0 and theta is signed, positive toward +x, so it equals the polar angle atan(x / z) of the grid (see polar_limits).

property polar_limits

The polar angle atan(x / z) [rad] of the first and last column of a polar grid, signed, positive toward +x. In 3D it is the angle of the projection onto the x-z plane, next to elevation_limits for the y-z plane.

If not explicitly provided, the range of the transmit angles (polar_angles, projected onto the x-z plane when azimuth_angles is given), widened on each side to cover the region each transmit insonifies down to zlims[1], as seen from grid_apex (see insonified_edge_rays()). Focused transmits add no margin. For plane or diverging waves on a flat array, neither of which defines an apex, the apex is where the outermost edge ray crosses the central axis. Set polar_margin to widen by a fixed angle instead.

With enable_scanline=True this is the angle of the first and the last transmit, projected onto the x-z plane like the default, since the columns are the transmits in order; an explicit value is ignored there.

polar_margin: float | None

Fixed angle [rad] to widen the default polar_limits by on each side, replacing the automatic margin derived from the transmits. Defaults to None (automatic).

probe_bandwidth_percent: float

Probe bandwidth as a percentage of the center frequency. Defaults to 100.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': 100.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 radius_of_curvature

The probe’s radius of curvature [m], fitted from probe_geometry.

inf for a flat array, or when there is no probe geometry. This is a property of the probe; for a curved array it is also the default distance from the array to grid_apex, the centre of curvature.

resolution: float | None

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

property rlims

Radius (rho_min, rho_max) [m] of the first and last row of a polar grid.

Rho is measured from grid_apex, so it is zlims - grid_apex[2] (zlims are depths below the transducer), matching the rows of polar_pixel_grid(). Used for scan conversion, together with polar_limits for the columns.

property rx_aperture_indices

Probe element index of each receive channel of shape (n_tx, n_rx).

None for the usual case where every element receives on every transmit, in which case the mapping is the identity and n_rx equals n_el. Only acquisitions with a receive sub-aperture (a sliding receive window, or a multiplexed front-end with fewer channels than elements) carry it, since the mapping is then not recoverable from the channel data alone. Sliced by selected_transmits, so it stays aligned with t0_delays and tx_apodizations.

The transmit counterpart needs no such field: the transmit aperture is recorded per element in tx_apodizations, whose zeros mark the elements that did not fire.

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',)}, 'rx_aperture_indices': {'dtype': (<class 'numpy.int16'>, <class 'numpy.int32'>, <class 'numpy.int64'>), 'shape': ('n_tx', 'n_rx')}, '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(). Otherwise it defaults to 1 / center_frequency.

property tgc_gain_curve

Time gain compensation (TGC) curve of shape (n_ax,).

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

update(params=None, *, force=False, **kwargs)

Update parameters from a mapping and/or keyword arguments.

See zea.internal.parameters.BaseParameters.update().

property waveforms_one_way

One-way transmit waveforms of shape (n_tx, n_samples_one_way), or None.

property waveforms_two_way

Two-way transmit waveforms of shape (n_tx, n_samples_two_way), or None.

property wavelength

Calculate the wavelength based on sound speed and transmit center frequency.

property xlims

The lateral (x) limits of the grid in meters.

If not explicitly provided, the limits describe the grid:

• Polar grid (including scanline): the width of the sector, from grid_apex, zlims and polar_limits. An explicit value sets the width of the scan-converted image instead (crop or pad, see extent); it does not change the sector.

• Cartesian scanline grid: the lateral extent of its columns.

• Cartesian grid: what the transmits insonify down to the deepest pixel, and at least the probe width. Each transmit’s region is bounded by the same edge rays that set the default polar_limits (see insonified_edge_rays()).

property ylims

The y-limits of the beamforming grid [m]. If not explicitly set, it is computed based on the elevation_limits and probe geometry.

property zlims

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