itd_difference

hrtfpykit.hrtf.itd_difference(hrtf_a, hrtf_b, method='threshold', output='seconds', thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10)

Compute absolute per-position ITD differences between two HRTFs.

The metric estimates interaural time difference for each input HRTF, validates that both HRTFs expose the same source positions, and returns abs(itd_a - itd_b). Here, itd_a and itd_b are the per-position ITD arrays estimated from hrtf_a and hrtf_b. The result is an unsigned timing-change magnitude for each source position in the current HRTF view.

Source positions are compared through get_positions() in degrees. If either input already represents a selected spatial subset, both HRTFs must expose the same selected source grid in the same order.

Parameters:

  • hrtf_a (HRTF) – First HRTF object used in the comparison. It must provide IR data, an IR sample rate, and a Sources grid matching hrtf_b.

  • hrtf_b (HRTF) – Second HRTF object used in the comparison. It must provide IR data, an IR sample rate, and a Sources grid matching hrtf_a.

  • method ({threshold, maxiacce}, default=``threshold``) – ITD estimator used for both HRTFs.

  • output ({seconds, samples}, default=``seconds``) – Unit of returned absolute ITD differences. samples requires equal sample rates in both HRTFs. seconds converts each ITD with that HRTF’s own sample rate before subtraction.

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

  • upper_cut_freq (float, default=3000.0) – Low-pass cutoff frequency in hertz used by filtered ITD estimation.

  • filter_order (int, default=10) – Positive Butterworth low-pass order used by filtered ITD estimation.

Returns:

Absolute ITD differences per source position. For standard HRTF data with shape (positions, ears, samples), the result has shape (positions,).

Return type:

np.ndarray

Raises:

ValueError – If either input is not an HRTF-like object with IR and Sources, if IR values or sample rates are missing, if output or ITD estimator options are invalid, if sample-domain output is requested for unequal sample rates, if source grids differ in shape or values, or if the calculated ITD arrays do not have matching shapes.

Notes

This function intentionally returns absolute differences, so the sign of the timing change is not retained.

Examples

Compare two HRTFs measured on the same source grid and return one absolute timing-difference value per source position:

>>> from hrtfpykit.hrtf import load_hrtf, itd_difference
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> itd_diff = itd_difference(hrtf_a, hrtf_b, output="seconds")
>>> itd_diff.shape
(793,)