compare_itd_difference

hrtfpykit.plots.compare_itd_difference(hrtf_a, hrtf_b, method='threshold', output='seconds', thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10, azimuth_range_mode='0-360', colormap='jet', show=True, titles=True)

Plot signed ITD differences between two HRTFs across source positions.

The function computes per-position ITD for both inputs and plots the signed difference itd_a - itd_b as a color-coded spatial scatter map. Azimuth is shown on the x-axis, elevation is shown on the y-axis, and marker color encodes the timing difference in the requested output unit.

This plot requires both HRTFs to expose the same source grid in the same order. It is useful for inspecting where a transformation, model, or measurement changes ITD and whether that change is localized to specific source directions.

Parameters:

  • hrtf_a (HRTF) – First HRTF used in the signed subtraction. Must contain IR data, an IR sample rate, and a source grid matching hrtf_b.

  • hrtf_b (HRTF) – Second HRTF used in the signed subtraction. Must contain IR data, an IR sample rate, and a source grid matching hrtf_a.

  • method ({threshold, maxiacce}, default=``threshold``) – ITD estimator passed to itd().

  • output ({seconds, samples}, default=``seconds``) – Unit of ITD values and colorbar label.

  • thresh_level (float, default=-10.0) – Threshold offset in dB when method is threshold.

  • upper_cut_freq (float, default=3000.0) – Low-pass cutoff in Hz used before ITD estimation.

  • filter_order (int, default=10) – Butterworth low-pass filter order used in ITD estimation.

  • azimuth_range_mode ({0-360, -180-180}, default=``0-360``) – 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 either input is not HRTF-like, IR data or sample rates are missing, output is unsupported, sample output is requested with unequal sample rates, source grids differ, calculated ITD arrays have different shapes, source positions are invalid, or the ITD differences cannot be aligned with source positions.

Notes

This plotting function computes a signed difference directly. That differs from itd_difference(), which returns absolute per-position differences. Positive and negative colors therefore retain the direction of hrtf_a - hrtf_b.

Examples

Plot the signed ITD difference between two HRTFs that share the same source grid:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_itd_difference
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> compare_itd_difference(
...     hrtf_a,
...     hrtf_b,
...     method="threshold",
...     output="seconds",
...     azimuth_range_mode="-180-180",
...     colormap="viridis",
... )