plot_etc_plane

hrtfpykit.plots.plot_etc_plane(hrtf, plane='horizontal', plane_angle=0.0, azimuth_range_mode='0-360', ear='both', x_axis='time', reference='max', colormap='jet', show=True, show_titles=True, show_labels=True, show_legends=True)

Plot energy time curves across a measured spatial plane.

plot_etc_plane selects the nearest measured horizontal or median plane from hrtf.Sources. It reads the selected samples from hrtf.IR.values, converts abs(IR) to dB, and draws a direction by time 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.

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

  • x_axis ({time, samples}, default=``time``) – Horizontal axis used for the ETC heatmap.

  • reference (float | {max}, default=``max``) – Reference used for decibel conversion. max normalizes the plotted plane to its maximum absolute IR value over the selected plane and ear channels.

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

  • 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 energy time heatmap.

Return type:

matplotlib.figure.Figure

Raises:

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

  • ValueError – If IR data is missing, time axis plotting lacks a sample rate, the azimuth range is invalid, the selected plane has no positions, the IR array has no samples, the reference is invalid, or the requested ear channel is unavailable.

Notes

This is the plane view counterpart of plot_etc(). It keeps the same dB reference behavior and shows all measured source positions in the selected plane at once.

Examples

Plot a horizontal plane ETC heatmap for both ears using sample indices:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import plot_etc_plane
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> plot_etc_plane(
...     hrtf,
...     plane="horizontal",
...     plane_angle=0.0,
...     ear="both",
...     x_axis="samples",
...     reference="max",
... )