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.

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")
>>> probe.probe_center_frequency
np.float32(6250000.0)
>>> probe.n_el
128

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

Built-in probes

• Verasonics_l11_4v – Verasonics L11-4V linear array

• Verasonics_l11_5v – Verasonics L11-5V linear array

• Esaote_sll1543 – Esaote SLL1543 linear array

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,
... }
>>> f = File.create(
...     "probe_example.hdf5",
...     data={"raw_data": raw},
...     scan=scan,
...     probe=probe, # dictionary or zea.Probe object
...     overwrite=True,
... )
>>> f.probe.name
'verasonics_l11_4v'
>>> f.close()

Functions

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, ...])
Verasonics_l11_4v()	Verasonics L11-4V linear ultrasound transducer.
Verasonics_l11_5v()	Verasonics L11-5V linear ultrasound transducer.

class zea.probes.Esaote_sll1543

Bases: Probe

Esaote SLL1543 linear ultrasound transducer.

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

Set probe parameters

class zea.probes.Probe(name=None, type=None, probe_center_frequency=None, probe_bandwidth_percent=None, probe_geometry=None, element_width=None, element_height=None, lens_sound_speed=None, lens_thickness=None)

Bases: ProbeSpec

classmethod from_name(probe_name, **kwargs)

Create a probe from its name.

Parameters:

probe_name (str) – Name of the probe.

Returns:

Probe object.

Return type:

Probe

get_parameters()

Return a dict of the probe parameters.

static get_pitch(probe_geometry)

Compute the pitch (centre-to-centre element spacing) in metres from the probe geometry.

Returns None when the pitch is not defined for the geometry (fewer than 2 elements, or not a 1-D / linear array). Raises ValueError when the array looks like a ULA but the element positions are not uniformly spaced, to surface likely data errors rather than silently returning None.

Return type:

float | None

property kerf: float | None

Gap between elements in metres, derived from element_width and pitch.

property pitch: float | None

Centre-to-centre element spacing in metres, derived from probe_geometry.

Raises ValueError when:

• probe_geometry is not set,

• the probe has fewer than 2 elements, or

• the elements are not arranged along a single axis (not a 1-D / linear array).

• the spacing is non-uniform (elements are present but clearly not a ULA),

  to surface likely data errors rather than silently returning None.

to_tensor(keep_as_is=None)

Convert the attributes in the object to tensors.

class zea.probes.Verasonics_l11_4v

Bases: Probe

Verasonics L11-4V linear ultrasound transducer.

Verasonics L11-4V linear ultrasound transducer.

class zea.probes.Verasonics_l11_5v

Bases: Probe

Verasonics L11-5V linear ultrasound transducer.

Verasonics L11-5V linear ultrasound transducer.

zea.probes.create_probe_geometry(n_el, pitch)

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