plot_spectrum_plane

hrtfpykit.plots.plot_spectrum_plane(hrtf, plane='horizontal', plane_angle=0.0, azimuth_range_mode='0-360', x_axis='linear', unit='db', ear='both', reference='max', colormap='jet', freq_min=None, freq_max=None, show=True, show_titles=True, show_labels=True, show_legends=True)

Plot HRTF magnitude across a measured spatial plane.

plot_spectrum_plane selects the nearest measured horizontal or median plane from hrtf.Sources. It reads hrtf.TF.magnitude and hrtf.TF.frequency_bins, optionally converts magnitude to dB to decibels, and draws a frequency by angle heatmap.

Horizontal planes use spherical azimuth on the y axis. Median planes use lateral polar angle on the y axis, where 0 degrees is front, 90 degrees is up, 180 degrees is back, and -90 degrees is down.

Parameters:

  • plane ({horizontal, median}, default=``horizontal``) – Plane to visualize. horizontal uses a horizontal plane selected by spherical elevation. median uses the nearest measured lateral polar lateral angle.

  • plane_angle (float, default=0.0) – Plane coordinate in degrees used to resolve the nearest measured plane. For plane="horizontal" this is spherical elevation. For plane="median" this is lateral polar lateral angle.

  • azimuth_range_mode ({0-360, -180-180}, default=``0-360``) – Azimuth convention used for horizontal plane azimuth values. 0-360 follows the SOFA anticlockwise convention: front is 0 degrees, listener left is 90 degrees, back is 180 degrees, and listener right is 270 degrees. -180-180 wraps listener right to -90 degrees. Because horizontal plane azimuth is drawn on the y axis in this plot, signed azimuth keeps normal Matplotlib numeric orientation.

  • x_axis ({linear, log}, default=``linear``) – Frequency scale used on the x axis.

  • unit ({db, linear}, default=``db``) – Magnitude representation used for the heatmap values.

  • ear ({left, right, both}, default=``both``) – Ear channel to display. When both is selected, a separate subplot is created for each ear.

  • reference (float | {max}, default=``max``) – Reference used when unit=``db``. max normalizes the plotted plane to its maximum value.

  • colormap (str, default=``jet``) – Colormap name used for the heatmap.

  • freq_min (float | None, default=None) – Minimum frequency in Hz included in the plot.

  • freq_max (float | None, default=None) – Maximum frequency in Hz included in the plot.

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

  • show_titles (bool, default=True) – If False, suppress generated default subplot and 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 selected plane magnitude heatmap.

Return type:

matplotlib.figure.Figure

Raises:

  • AttributeError – If plane, unit, x_axis, or ear is not one of the supported values, or if plane_angle is not finite.

  • ValueError – If TF data is missing, the azimuth range is invalid, the selected plane has no positions, frequency bins are invalid, the selected frequency range contains no bins, or the requested ear channel is not available.

Notes

Horizontal plane azimuth follows azimuth_range_mode on the y axis. In signed mode, +90 degrees remains above -90 degrees because hrtfpykit only reverses the visual axis when azimuth is plotted on the x axis.

Examples

Plot a horizontal plane spectrum heatmap around ear height:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import plot_spectrum_plane
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> plot_spectrum_plane(
...     hrtf,
...     plane="horizontal",
...     plane_angle=0.0,
...     x_axis="linear",
...     ear="left",
...     freq_max=16000.0,
... )