mach.wavefront

mach.wavefront#

Convenience functions for determining the transmit-arrival distance of a wavefront.

Functions

earliest_arrival(element_positions_m, ...[, ...])

Earliest transmit arrival distance from per-element delays.

plane(origin_m, points_m, direction)

Plane-wave transmit distance.

spherical(origin_m, points_m, focus_m[, ...])

Spherical-wave transmit distance (also known as focused or diverging waves).
mach.wavefront.earliest_arrival(
element_positions_m: Real[Array, '*elements xyz=3'],
element_delays_s: Real[Array, '*elements'],
points_m: Real[Array, '*points xyz=3'],
*,
sound_speed_m_s: float | int,
element_chunk_size: int = 1024,
point_chunk_size: int = 32768,
) → Real[Array, '*points']#

Earliest transmit arrival distance from per-element delays.

Parameters:

  • element_positions_m – Positions of the active transmit elements, in meters. Leading element dimensions may be multidimensional, e.g. (rows, cols, 3) for a 2D matrix array.

  • element_delays_s – Per-element transmit delays, in seconds, with the same leading shape as element_positions_m. Delays must share the same time reference as the receive chain (for example, normalized so the earliest firing element has delay zero).

  • points_m – Positions of the points to compute the transmit-arrival time for, in meters.

  • sound_speed_m_s – Speed of sound, in meters per second.

  • element_chunk_size – Number of elements processed per reduction chunk. Tune for memory on large apertures.

  • point_chunk_size – Number of image points processed per chunk. Tune for memory on large grids.

Returns:

Minimum path length min_i (sound_speed_m_s * element_delays_s[i] + |P - e_i|) in meters. Divide by sound speed to obtain arrival time in seconds.

Raises:

  • ValueError – If sound speed or a chunk size is nonpositive, or no elements are provided.

  • jaxtyping.TypeCheckError – If the element positions and delays have incompatible shapes.

Notes

This is the earliest arrival, not necessarily the strongest pulse time The same minimum-over-elements method is used in delay-based DAS paths such as PyMUST dasmtx (creatis-ULTIM/PyMUST) and ultraspy transmit mode 0 (pecarlat/ultraspy/-/raw/26b0bc171b5344a2241897b7e63af92e845aa77c/src/ultraspy/cpu/kernels/numpy_cores/das.py).

mach.wavefront.plane(
origin_m: Real[Array, 'xyz=3'],
points_m: Real[Array, '*points xyz=3'],
direction: Real[Array, 'xyz=3'],
) → Real[Array, '*points']#

Plane-wave transmit distance.

Plane-wave transmit is described by its propagation direction and origin-position.

Parameters:

  • origin_m – The origin position of the plane-wave in meters.

  • points_m – The position of the points to compute the transmit-arrival time for, in meters.

  • direction – The direction of the plane-wave. Must be a unit vector. We use direction vector instead of angles because it is less ambiguous.

Returns:

The transmit-wavefront-arrival distance for each point in meters. To convert to time, divide by sound speed: distance_m / sound_speed_m_s

Notes

Does not check for negative distances.

mach.wavefront.spherical(
origin_m: Real[Array, 'xyz=3'],
points_m: Real[Array, '*points xyz=3'],
focus_m: Real[Array, 'xyz=3'],
aperture_bounds_m: Real[Array, 'corners=4 xyz=3'] | None = None,
) → Real[Array, '*points']#

Spherical-wave transmit distance (also known as focused or diverging waves).

Spherical waves propagate like a collapsing sphere focusing onto a point, or an expanding sphere diverging from a point.

Parameters:

  • origin_m – xyz-position of the transmitting element/sender in meters. distance=0 at the origin.

  • points_m – xyz-positions of the points to compute the transmit-arrival time for, in meters.

  • focus_m – xyz-position of the focal point where spherical waves converge, in meters. sometimes called the source or apex. for a focused wave, the focus is in front of the origin. for a diverging wave, the focus is behind the origin. Note: ‘focus’ refers to the convergence point, while ‘origin’ refers to the physical transducer element that transmits the wave.

  • aperture_bounds_m – Optional corners of the active transmit aperture as shape (4, 3) in meters. Corners must form a nondegenerate rectangle, be coplanar, and be ordered around its perimeter using the right-hand rule so their normal points into the imaging region (for example: lateral-min elevation-min, lateral-max elevation-min, lateral-max elevation-max, lateral-min elevation-max). When aperture_bounds_m is provided, spherical uses the ideal spherical equation inside the rectangular focus pyramids and linearly interpolates boundary spherical distances between them, following the unified pixel-based beamforming idea of Nguyen and Prager (https://doi.org/10.1109/TMI.2015.2456982). This removes the focal-plane discontinuity of the ideal spherical equation for off-axis pixels. Outside the insonified sector the result is a travel-time continuity approximation, not a full wave model.

Returns:

The transmit-wavefront-arrival distance for each point in meters. To convert to time, divide by sound speed: distance_m / sound_speed_m_s

Raises:

ValueError – If aperture bounds do not describe an ordered rectangle or if the focus lies in the aperture plane.

Notes

Without aperture_bounds_m, this matches Equation 5 / Figure 2 from Perrot et al., Ultrasonics 2021, https://www.biomecardio.com/publis/ultrasonics21.pdf with L=0, extended to 3D.

The sign convention accounts for the direction of wave propagation. For typical ultrasound imaging where z increases with depth, negative values indicate the wavefront arrives before the reference time, positive values after.