compare_lsd_plane

hrtfpykit.plots.compare_lsd_plane(hrtf_a, hrtf_b, plane='horizontal', ear='left', elevation=0.0, epsilon=1e-12, x_axis='linear', freq_min=None, freq_max=None, colormap='jet', show=True, titles=True)

Plot plane-restricted LSD as a frequency-angle heatmap.

This function visualizes log-spectral distance values in decibels for a canonical spatial plane. It calls lsd() with reduction is none so the output keeps one value per selected plane position and selected frequency bin. Frequency is shown in kilohertz on the x-axis, direction is shown on the y-axis, and color encodes LSD.

Horizontal-plane plots use signed azimuth in the -180 .. 180 convention on the y-axis. Median-plane plots use lateral-polar polar angle on the y-axis. If multiple source positions map to the same displayed direction, their LSD rows are averaged before rendering the heatmap.

Parameters:

  • hrtf_a (HRTF) – First HRTF used in the comparison. Must contain TF frequency bins and a source grid compatible with hrtf_b.

  • hrtf_b (HRTF) – Second HRTF used in the comparison. Must contain comparable TF data and a source grid compatible with hrtf_a.

  • plane ({horizontal, median}, default=``horizontal``) – Canonical plane used to select source positions.

  • ear ({left, right}, default=``left``) – Ear channel used for LSD computation.

  • elevation (float, default=0.0) – Requested elevation in degrees when plane is horizontal. Ignored when plane is median.

  • epsilon (float, default=1e-12) – Positive floor passed to lsd() before dB conversion.

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

  • freq_min (float | None, default=None) – Minimum frequency in Hz included in the LSD heatmap. When omitted, defaults to 20 Hz.

  • freq_max (float | None, default=None) – Maximum frequency in Hz included in the LSD heatmap. When omitted, defaults to 20000 Hz.

  • colormap (str, default=``jet``) – Matplotlib colormap used for heatmap coloring.

  • show (bool, default=True) – If True, calls matplotlib.pyplot.show().

  • titles (bool, default=True) – If True, applies a figure title with plane context.

Return type:

None

Raises:

ValueError – If plane or x_axis is unsupported, required frequency bins are missing, the selected plane is empty, frequency limits are invalid, the selected frequency range contains too few bins, delegated LSD calculation does not return a 2D plane-frequency matrix, or no finite LSD values are available for heatmap rendering.

Notes

freq_min and freq_max are specified in hertz, while the displayed x-axis uses kilohertz. When omitted, the function uses the default LSD band of 20 Hz to 20 kHz before intersecting that range with hrtf_a frequency bins.

Examples

Plot a horizontal-plane LSD heatmap from 100 Hz to 16 kHz:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_lsd_plane
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> compare_lsd_plane(
...     hrtf_a,
...     hrtf_b,
...     plane="horizontal",
...     ear="right",
...     elevation=0.0,
...     x_axis="log",
...     freq_max=16000.0,
...     colormap="viridis",
... )