zea.beamform.geometry¶

Geometry helpers for beamforming.

Lightweight, backend-agnostic utilities derived purely from probe geometry. This is a leaf module (only depends on keras / numpy) so it can be imported from zea.beamform.beamformer, zea.simulator and zea.beamform.pfield without introducing an import cycle.

Functions

compute_element_normals(probe_geometry[, eps])

Estimate per-element unit surface normals from element positions.
zea.beamform.geometry.compute_element_normals(probe_geometry, eps=1e-12)[source]¶

Estimate per-element unit surface normals from element positions.

zea’s built-in receive f-number apodization (zea.beamform.beamformer.fnumber_mask()) measures the acceptance cone relative to each element’s surface normal. For a flat linear array every element faces +z and the normal is trivial, but for a curved/convex array the peripheral elements are physically tilted outward, so their true look-direction is not +z. Assuming +z for those elements needlessly clips the receive aperture at the lateral edges of the sector. This function derives each element’s outward normal directly from probe_geometry so no extra probe metadata (radius of curvature, per element angles, …) is required.

The array is treated as a 1-D curve of elements ordered along the aperture lying in the x-z imaging plane (zea’s convention; the medium is at +z). For each element the local tangent d is estimated by central finite differences of neighbouring element positions (one-sided at the two ends). The outward normal is the depth axis +z with its component along the tangent removed:

n = normalize(z_hat - (z_hat.d) / (d.d) * d)

This yields exactly (0, 0, 1) for a flat array (any spacing, ordered or not — the z column is identically zero, so the rejection leaves z_hat untouched), so existing linear-array reconstructions are unchanged bit-for-bit. For a convex arc it recovers the exact radial outward normal at the interior elements.

Parameters:

  • probe_geometry (Tensor) – Element positions (x, y, z) of shape (n_el, 3) in metres, ordered along the array.

  • eps (float) – Small value guarding the tangent-length division.

Returns:

Unit outward normals of shape (n_el, 3).

Return type:

Tensor

Notes

  • Intended for 1-D arrays (linear / phased / curved) in the x-z plane. For a genuine 3-D matrix array (elements spread in y) a single index-ordered tangent is not meaningful, so the function falls back to +z for every element when the geometry has a non-negligible y extent — reproducing today’s behaviour.

  • A single-element array falls back to +z.