[wesselvannierop]

This PR fixes the various names we have been using for angles and coordinate systems, and sticks to one convention. Also adds an interactive beamforming grid viewer, which shows visually how all the variables relate.

Also derives the default pixel grid from the probe and transmit geometry, so polar sectors, their apex and the cartesian width follow what the transmits actually insonify, and settles the angle names.

Fixes #669 and #47 (angle naming); touches #547 (acquisition-dependent defaults).

Changes

• grid_apex (new, derived) replaces distance_to_apex: the point the polar grid fans out from, i.e. where steered focused axes meet, a diverging wave's virtual source, or a curved array's centre of curvature.
• Default polar_limits cover the region each transmit insonifies at zlims[1], replacing the fixed 15 % margin. New polar_margin sets a fixed margin instead.
• Default xlims, grid_size_x, extent follow the sector or insonified width (λ/4 along the outer arc), and scan conversion fills extent.
• Scanline grids follow the transmit angles (in the x-z plane) from grid_apex; unsupported transmit/grid combinations raise a ValueError.
• Default f_number is derived from the element's −6 dB directivity (0, no receive mask, for typical phased arrays). This changes pixel values, not the grid.
• Angle names are the same from the grid through scan conversion, in 2D and 3D: rlims (radius from grid_apex), polar_limits (atan(x/z)), and in 3D one more, elevation_limits (atan(y/z)). θ and φ only name the transmit angles as the file format stores them: spherical polar_angles and azimuth_angles, physics convention.
• Default elevation_limits (and so the default ylims) come from the transmits' elevation angle atan(tanθ·sinφ), instead of the range of φ. New elevation_margin sets a fixed margin, like polar_margin.
• Verasonics converter (fix): polar_angles and azimuth_angles are now the spherical transmit angles, converted from TX.Steer. azimuth_angles used to hold the elevation steering angle alpha, so Steer = (0, 10°) was read as θ = 0, φ = 10°, which points straight down; it is now θ = 10°, φ = 90°. Data with alpha = 0 converts as before; files already converted from elevation-steered acquisitions need to be reconverted (details).

Breaking / deprecated

• rho_range / theta_range / phi_range → rlims / polar_limits / elevation_limits. Deprecated aliases kept. The polar/cartesian helpers now measure angles toward +x, like the rest of zea (theta_range still gives the old images).
• frustum_convert_* → frustum_to_xyz / xyz_to_frustum / frustum_to_xz / xz_to_frustum, and plot_frustum_vertices' phi_ / theta_ / rho_ planes and styles → elevation_ / polar_ / radius_. Deprecated aliases kept.
• azimuth_limits → elevation_limits (deprecated alias). It already set ylims as an elevation angle, so explicit values keep their effect; the derived default changes (see above).
• ScanConvert outputs are renamed without aliases (rho_range / theta_range / phi_range / d_rho / d_theta / d_phi → rlims / polar_limits / elevation_limits / dr / d_polar / d_elevation), so code reading the old keys breaks.
• Default grids and the default f_number change, so beamformed images change.

Overlaps with #673: this branch copies its is_plane_wave / is_focused / is_diverging helpers.

Before / after grids

Curved, 1 plane wave

main gave polar_limits [0°, 0°], so a zero-width, empty image. An unsteered plane wave on a curved array spreads along the element normals, so the sector is now the array's own angular span.

Phased, scanline, virtual apex

main displayed lines fired at ±45° at ±58.5°, so every target was misplaced. Now each column follows its transmit axis and fans out from where the axes meet, 9.4 mm behind the array. The targets now land within about 0.8 mm, one pixel of the coarse 33-line image.

Phased, plane waves

Steered plane waves cover a trapezoid: as wide as the array at the top, with edges at the steepest steering angle. The sector now runs through the array's ends at ±20°, from a virtual apex 26 mm back, so the shallow region under the array's ends is no longer cut off.

Phased, diverging waves

The old ±39° was the steering range plus a fixed 15 %, which cut off about 18 mm per side at 100 mm depth. The limits now follow the rays from each virtual source through the array's ends. The extra targets only show with the new f_number, so both changes are needed.

Phased, focused lines from a virtual apex

The old 15 % margin added 13.5° per side that no beam reached. The grid now fans out from where the lines come from: a virtual apex 9.4 mm behind the array. On main, the 705 columns sampled the deepest row at only ~λ/2; the column count now follows the arc (λ/4). The grid change alone finds the same targets; the gain comes from the new f_number.

Curved, focused lines along normals

The sector now ends at the outermost lines (±30°). The 8 targets not shown lie at 31–37°, in the outer tail of the outermost beams, 8–17 dB below the interior. Set polar_margin to include that tail.

Linear, plane waves (cartesian)

The old width came from an f-number-1 receive cone, regardless of the transmits. It now follows where the ±10° plane waves reach. The two targets dropped were at −44 dB on main, at noise level.

Curved, docs figure (explicit sector)

The column count now comes from the arc length at the deepest row (λ/4) instead of an unrelated xlims. That removes about 20 % oversampling.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[codecov]

Codecov Report

❌ Patch coverage is 93.33333% with 39 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
zea/parameters.py	91.41%	13 Missing and 7 partials ⚠️
zea/display.py	89.38%	5 Missing and 7 partials ⚠️
docs/explorer/make_reference.py	96.87%	1 Missing and 1 partial ⚠️
zea/data/convert/verasonics.py	87.50%	2 Missing ⚠️
zea/visualize.py	92.00%	1 Missing and 1 partial ⚠️
zea/beamform/geometry.py	98.64%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[wesselvannierop]

Still working on fully fixing #47

[wesselvannierop]

Fixed in this PR (bb5da16): the Verasonics converter stored elevation steering as azimuth_angles.

This PR documents polar_angles / azimuth_angles as spherical θ / φ (physics convention). The Verasonics converter (zea/data/convert/verasonics.py) used to copy TX.Steer[:, 1] (alpha) straight into azimuth_angles. But alpha is Verasonics' elevation steering angle (tilt toward ±y), not a rotation around z.

The converter now converts (theta, alpha) to spherical (θ, φ) with steer_to_spherical. The direction convention comes from fitting the TX.Delay of a Matrix1024 acquisition steered in both angles.

• Changed: elevation-steered matrix-array acquisitions. For example, Steer = (0, 10°) (10° toward +y) used to be read as θ = 0, φ = 10°, which points straight down. It is now θ = 10°, φ = 90°.
• Unchanged: data with alpha = 0, which still converts to (theta, 0). That covers all linear, phased and curved array data, and the Open-H-RF 3D files I checked (azimuth_angles = 0 everywhere, steering in x only, confirmed by fitting the t0_delays). So existing data should be fine.
• Action needed: files already converted from elevation-steered acquisitions keep the wrong angles, so they need to be reconverted.

Open-H-RF is unaffected.