itd

hrtfpykit.hrtf.itd(hrtf, method='threshold', output='time', thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10, absolute=False)

Estimate interaural time difference for an HRTF.

itd is an HRTF-level metric. It reads the time-domain HRIR data and sample rate from hrtf.IR and expects the final two IR axes to be (ear, samples). The first two ear channels are treated as left and right, respectively; any leading source axes are preserved in the returned ITD array.

The default output is signed: positive values mean that the left-ear response is delayed relative to the right-ear response. Set absolute=True when only cue magnitude is needed.

Before estimation, both ear signals are low-pass filtered with a Butterworth IIR filter. The threshold method returns the first left/right onset difference whose level exceeds the per-ear peak level plus thresh_level dB. The maxiacce method estimates delay from the peak of the cross-correlation between Hilbert envelopes.

Parameters:

  • hrtf (HRTF) – HRTF object that provides an IR domain with values laid out as (..., ear, samples) and a finite positive sample_rate.

  • method ({threshold, maxiacce}, default=``threshold``) – Estimator used to resolve the left/right delay. threshold is an onset detector, while maxiacce uses envelope cross-correlation.

  • output ({time, samples}, default=``time``) – Unit used for the returned ITD values. time returns microseconds.

  • thresh_level (float, default=-10.0) – Threshold offset in decibels used by method=``threshold``. The effective threshold is computed independently for each ear as peak_level + thresh_level.

  • upper_cut_freq (float, default=3000.0) – Low-pass cutoff frequency in hertz applied before ITD estimation. The value must be between zero and the Nyquist frequency.

  • filter_order (int, default=10) – Positive Butterworth filter order used in the preprocessing stage.

  • absolute (bool, default=False) – If False, return signed ITD. If True, return abs(ITD) in the selected output unit.

Returns:

ITD values with shape hrtf.IR.values.shape[:-2]. Positive signed values mean the left-ear response is delayed relative to the right-ear response.

Return type:

np.ndarray

Raises:

ValueError – If the input is not an HRTF-like object, IR data are missing, empty, not array-like, do not contain ear and sample axes, have fewer than two ear channels or fewer than two samples, if sample rate is missing or invalid, if method or output is unsupported, if absolute is not a boolean, if the filter configuration is invalid, or if threshold mode cannot find a valid onset in either ear.

Examples

Estimate one signed ITD value in microseconds per source position:

>>> from hrtfpykit.hrtf import load_hrtf, itd
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> itd_time = itd(hrtf)
>>> itd_time.shape
(793,)

Request ITD values in samples:

>>> itd_samples = itd(hrtf, output="samples")
>>> itd_samples.shape
(793,)

Return ITD magnitude in microseconds:

>>> abs_itd_time = itd(hrtf, absolute=True)
>>> abs_itd_time.shape
(793,)