mach.geometry.ultrasound_angles_to_cartesian

mach.geometry.ultrasound_angles_to_cartesian#

mach.geometry.ultrasound_angles_to_cartesian(
azimuth_rad: Real[Array, '*angles'] | float | int,
elevation_rad: Real[Array, '*angles'] | float | int,
radius_m: Real[Array, '*angles'] | float | int = 1,
) → Real[Array, '*angles xyz=3'] | tuple[float, float, float]#

Convert ultrasound angles (azimuth, elevation, radius) to Cartesian coordinates.

The resulting vectors can be used directly with mach.wavefront.plane().

We define the “ultrasound convention” as: 1. Rotate azimuth (counter-clockwise) around fixed y-axis 2. Then rotate elevation (clockwise) around fixed x-axis

This convention is more intuitive for elevation multi-slice imaging where you first create a scan in azimuth, then rotate that plane in elevation.

Following the corrected mapping from magnusdk/vbeam#50

x = r * sin(azimuth) y = r * sin(elevation) * cos(azimuth) z = r * cos(elevation) * cos(azimuth)

Parameters:

  • azimuth_rad – Azimuth angle in radians - angle in xz-plane (around y-axis), applied first.

  • elevation_rad – Elevation angle in radians - angle from xz-plane (after azimuth rotation).

  • radius_m – Radius/distance from origin in meters (defaults to 1 for unit vectors).

Returns:

Cartesian coordinates in xyz-order. For array inputs: returns array with shape (*coords, 3). For scalar inputs: returns tuple[float, float, float].

Examples

>>> # Convert 15° azimuth to Cartesian
>>> import numpy as np
>>> x, y, z = ultrasound_angles_to_cartesian(np.radians(15), 0, 1)
>>> print(f"15° azimuth: ({x:.3f}, {y:.3f}, {z:.3f})")

>>> # Multiple angles
>>> azimuths = np.radians([-10, 0, 10])
>>> coords = ultrasound_angles_to_cartesian(azimuths, 0, 1)
>>> print(coords.shape)  # (3, 3)
Contents