plot_plane_grid

hrtfpykit.plots.plot_plane_grid(hrtf, plane='horizontal', show=True, show_titles=True, show_labels=True, show_legends=True)

Plot the source grid and highlight canonical planes.

plot_plane_grid reads Cartesian source positions from hrtf.Sources and overlays selected plane memberships. Horizontal, median, and frontal planes are resolved with the same plane definitions used by hrtfpykit plot and metric workflows.

The highlighted points therefore match the same plane definitions used by the metric and plane plotting functions.

Parameters:

  • plane (str | list[str] | tuple[str, ...], default=``horizontal``) – Plane or planes to highlight. Accepted values are horizontal, median, and frontal. A single string highlights one plane, while a list or tuple highlights multiple planes in the same figure.

  • show (bool, default=True) – If True, display the figure before returning.

  • show_titles (bool, default=True) – If False, suppress generated default figure titles.

  • show_labels (bool, default=True) – If False, suppress generated axis labels and colorbar labels.

  • show_legends (bool, default=True) – If False, suppress generated legends.

  • hrtf (HRTF)

Returns:

Figure containing the 3D source grid with highlighted planes.

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If plane is empty, contains an unsupported plane name, source positions cannot be resolved as Cartesian coordinates, or axis geometry cannot be computed from the current source grid.

Notes

Duplicate plane names are ignored after the first occurrence. A legend identifies the full source grid and each highlighted plane.

Examples

Plot the source grid and highlight the canonical horizontal plane:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import plot_plane_grid
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> plot_plane_grid(hrtf, plane="horizontal")