ild_difference

hrtfpykit.hrtf.ild_difference(hrtf_a, hrtf_b, mode='broad-band', output='db', fft_length=None, epsilon=1e-12)

Compute absolute per-position ILD differences between two HRTFs.

The metric estimates interaural level difference for each input HRTF, validates that both HRTFs expose the same source positions, and returns abs(ild_a - ild_b). Here, ild_a and ild_b are the ILD arrays estimated from hrtf_a and hrtf_b. The result is an unsigned level-ratio change magnitude for each source position, and optionally for each frequency bin.

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.

  • mode ({broad-band, frequency-dependent}, default=``broad-band``) – ILD mode used for both HRTFs. Broad-band mode compares RMS level ratios, while frequency-dependent mode compares per-bin magnitude ratios after IR-to-TF conversion.

  • output ({db, linear}, default=``db``) – Output representation used for both HRTFs. db compares dB ILD values; linear compares raw left/right ratios.

  • fft_length (int | None, default=None) – FFT length used by the internal IR-to-TF conversion when mode is frequency-dependent.

  • epsilon (float, default=1e-12) – Positive floor used before left/right division.

Returns:

Absolute ILD differences. For standard HRTF data, broad-band mode returns shape (positions,) and frequency-dependent mode returns shape (positions, frequency_bins).

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 mode or output is unsupported, if source grids differ in shape or values, if frequency-dependent mode is requested with unequal sample rates, if epsilon or FFT conversion settings are invalid, or if calculated ILD arrays do not have matching shapes.

Notes

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

Examples

Compare frequency-dependent ILD values for two HRTFs measured on the same source grid:

>>> from hrtfpykit.hrtf import load_hrtf, ild_difference
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> ild_diff = ild_difference(
...     hrtf_a,
...     hrtf_b,
...     mode="frequency-dependent",
...     output="db",
... )
>>> ild_diff.shape
(793, 129)