plot_ild_fd

hrtfpykit.plots.plot_ild_fd(hrtf, plane='horizontal', plane_angle=0.0, azimuth_range_mode='0-360', colormap='jet', freq_min=None, freq_max=None, show=True, show_titles=True, show_labels=True, show_legends=True)

Plot frequency dependent ILD across a measured spatial plane.

plot_ild_fd calls ild() as ild(hrtf, mode="frequency-dependent", epsilon=1e-12, absolute=False) using the current hrtf.TF data. It then selects a horizontal plane with get_horizontal_plane() or a median plane with get_median_plane(), restricts the selected frequency bins, and draws ILD in dB as 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.

  • 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 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 frequency dependent ILD heatmap.

Return type:

matplotlib.figure.Figure

Raises:

  • AttributeError – If plane is not horizontal or median, or if plane_angle is not finite.

  • ValueError – If TF data or frequency bins are missing, the azimuth range is invalid, the selected plane has no positions, frequency bins are invalid, the selected frequency range is empty, or the frequency dependent ILD shape is invalid.

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 frequency dependent ILD over the horizontal plane:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import plot_ild_fd
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> plot_ild_fd(
...     hrtf,
...     plane="horizontal",
...     plane_angle=0.0,
...     freq_max=16000.0,
... )