compare_ild_difference

hrtfpykit.plots.compare_ild_difference(hrtf_a, hrtf_b, mode='broad-band', output='db', fft_length=None, epsilon=1e-12, azimuth_range_mode='-180-180', colormap='jet', show=True, titles=True)

Plot absolute ILD differences between two HRTFs across source positions.

The function computes per-position ILD differences using ild_difference() and displays them as a color-coded scatter map over azimuth and elevation. Marker color encodes the absolute ILD difference in the requested output representation.

The underlying metric validates that the two HRTFs share the same source grid. Broad-band mode produces one value per source position. Frequency- dependent mode delegates to the metric and is only plottable here when the reduced output still aligns one value with each source position.

Parameters:

  • hrtf_a (HRTF) – First HRTF used for ILD comparison. Must contain IR data and a source grid compatible with hrtf_b.

  • hrtf_b (HRTF) – Second HRTF used for ILD comparison. Must contain IR data and a source grid compatible with hrtf_a.

  • mode ({broad-band, frequency-dependent}, default=``broad-band``) – ILD mode passed to ild_difference().

  • output ({db, linear}, default=``db``) – ILD output representation and colorbar label style.

  • fft_length (int | None, default=None) – Optional FFT length used when mode is frequency-dependent.

  • epsilon (float, default=1e-12) – Positive floor passed to ild_difference().

  • azimuth_range_mode ({0-360, -180-180}, default=``-180-180``) – Azimuth convention applied on the x-axis.

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

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

  • titles (bool, default=True) – If True, applies the figure title.

Return type:

None

Raises:

ValueError – If delegated ILD-difference calculation fails, source positions are invalid, or the returned ILD-difference values cannot be aligned with the number of source positions.

Notes

This function visualizes absolute ILD differences returned by ild_difference(). Use lower-level metric functions directly when signed left/right level changes are required.

Examples

Plot broad-band ILD differences between two HRTFs across the shared source grid:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_ild_difference
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> compare_ild_difference(
...     hrtf_a,
...     hrtf_b,
...     mode="broad-band",
...     output="db",
...     colormap="plasma",
... )