zea.probes

Ultrasound probe definitions and the base Probe class.

A probe describes the physical transducer: element positions, centre frequency, bandwidth, and properties such as element dimensions and lens geometry. All probe objects are instances of Probe, which inherits validation from ProbeSpec.

Probe parameters

A probe is described by the fields below (all optional — record what you have; see ProbeSpec for exact dtypes and shapes):

  • name – probe model identifier, e.g. "verasonics_c5_2v".

  • type – geometry class: "linear", "phased", "curved", …

  • probe_geometry – element positions (x, y, z) in metres, shape (n_el, 3). The element count n_el and pitch are derived from it.

  • probe_center_frequency – the probe’s nominal centre frequency (Hz), a fixed property of the transducer. For the built-in probes it is defined as the midpoint of the -6 dB band named by the probe (e.g. “L11-4v” -> 4-11 MHz -> 7.5 MHz), so it derives consistently with probe_bandwidth_percent from the band edges. This is the defined band centre, not a measured peak-response frequency, and it is distinct from the centre frequency of the transmit pulse used in an acquisition, which lives in ScanSpec.center_frequency / center_frequency.

  • probe_bandwidth_percent – fractional bandwidth as a percentage, (f_high - f_low) / f_centre * 100, using the arithmetic band centre above (the standard fractional-bandwidth reference).

  • element_width – width of a single element (m), along the array (azimuthal) direction.

  • element_height – elevation aperture of a single element (m).

  • lens_sound_speed / lens_thickness – acoustic-lens speed of sound (m/s) and thickness (m), used to correct receive travel times for the lens.

There are three ways to obtain a probe:

Loading a built-in probe

A small set of probes is pre-defined and can be retrieved by name:

>>> from zea import Probe
>>> probe = Probe.from_name("verasonics_l11_4v")
>>> float(probe.probe_center_frequency)
7500000.0
>>> probe.n_el
128

See Probe.from_name() for the full list of registered names.

Built-in probes

Loading a probe from a data file

When you open a File, the probe stored in that file is accessible through the probe property:

>>> from zea import 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:
...     probe = f.probe
>>> probe.name
'verasonics_l11_4v'

Defining a custom probe

Pass any combination of fields from ProbeSpec directly to Probe. Only the fields you provide are validated; everything else is left as None:

>>> import numpy as np
>>> from zea import Probe
>>> from zea.probes import create_probe_geometry

>>> probe = Probe(
...     name="my_probe",
...     type="linear",
...     probe_center_frequency=np.float32(5e6),
...     probe_geometry=create_probe_geometry(n_el=64, pitch=0.3e-3),
... )
>>> probe.n_el
64

You can also register a custom probe class with the probe_registry decorator so it becomes retrievable by name — see the built-in classes below as examples.

Saving a probe to a data file

Pass a Probe object directly to create() via the probe argument, alternatively a simple dictionary of probe parameters will also work:

>>> import numpy as np
>>> from zea import File, Probe

>>> n_frames, n_tx, n_el, n_ax = 1, 4, 128, 64
>>> probe = Probe.from_name("verasonics_l11_4v")
>>> raw = np.zeros((n_frames, n_tx, n_ax, n_el, 1), dtype=np.float32)
>>> scan = {
...     "sampling_frequency": np.float32(40e6),
...     "center_frequency": np.float32(6.25e6),
...     "demodulation_frequency": np.float32(6.25e6),
...     "initial_times": np.zeros(n_tx, dtype=np.float32),
...     "t0_delays": np.zeros((n_tx, n_el), dtype=np.float32),
...     "tx_apodizations": np.ones((n_tx, n_el), dtype=np.float32),
...     "focus_distances": np.full(n_tx, np.inf, dtype=np.float32),
...     "transmit_origins": np.zeros((n_tx, 3), dtype=np.float32),
...     "polar_angles": np.zeros(n_tx, dtype=np.float32),
...     "time_to_next_transmit": np.ones((n_frames, n_tx), dtype=np.float32) * 1e-4,
... }
>>> File.create(
...     "probe_example.hdf5",
...     data={"raw_data": raw},
...     scan=scan,
...     probe=probe, # dictionary or zea.Probe object
...     overwrite=True,
... )

Functions

create_curved_probe_geometry(n_el, pitch, radius)

Create the geometry of a convex (curved) array.

create_probe_geometry(n_el, pitch)

Create probe geometry based on number of elements and pitch.

Classes

Esaote_sll1543()

Esaote SLL1543 linear ultrasound transducer.

Probe([name, type, probe_center_frequency, ...])

Probe class which is a container for ultrasound transducer parameters.

Verasonics_c5_2v()

Verasonics C5-2v convex (curved) array.

Verasonics_l11_4v()

Verasonics L11-4V linear array.

Verasonics_l11_5v()

Verasonics L11-5V linear array.

Verasonics_p4_2v()

Verasonics P4-2v phased array.
class zea.probes.Esaote_sll1543[source]

Bases: Probe

Esaote SLL1543 linear ultrasound transducer.

https://lysis.cc/products/esaote-sl1543

Set probe parameters

class zea.probes.Verasonics_c5_2v[source]

Bases: Probe

Verasonics C5-2v convex (curved) array.

Elevation focus ~60 mm, sensitivity -55.5 to -50.5 dB.

Verasonics C5-2v convex (curved) ultrasound transducer.

class zea.probes.Verasonics_l11_4v[source]

Bases: Probe

Verasonics L11-4V linear array.

Elevation focus ~20 mm, sensitivity -64.5 to -59.5 dB.

Verasonics L11-4V linear ultrasound transducer.

class zea.probes.Verasonics_l11_5v[source]

Bases: Probe

Verasonics L11-5V linear array.

Verasonics L11-5V linear ultrasound transducer.

class zea.probes.Verasonics_p4_2v[source]

Bases: Probe

Verasonics P4-2v phased array.

Elevation focus ~60 mm, sensitivity -69 to -65 dB.

Verasonics P4-2v phased-array ultrasound transducer.

zea.probes.create_curved_probe_geometry(n_el, pitch, radius)[source]

Create the geometry of a convex (curved) array.

Elements lie on an arc of the given radius of curvature in the x-z plane (y = 0), with the apex element at the origin facing +z and the peripheral elements curving back toward -z (zea’s convention: the medium is at +z). pitch is the arc spacing between adjacent elements, so the per-element angular step is pitch / radius.

Parameters:

  • n_el (int) – Number of elements in the probe.

  • pitch (float) – Arc distance between adjacent elements in metres.

  • radius (float) – Radius of curvature of the array in metres.

Returns:

Probe geometry with shape (n_el, 3).

Return type:

np.ndarray

zea.probes.create_probe_geometry(n_el, pitch)[source]

Create probe geometry based on number of elements and pitch.

Parameters:

  • n_el (int) – Number of elements in the probe.

  • pitch (float) – Pitch of the elements in the probe.

Returns:

Probe geometry with shape (n_el, 3).

Return type:

np.ndarray