ild

hrtfpykit.hrtf.ild(hrtf, mode='broad-band', epsilon=1e-12, absolute=False)

Compute interaural level difference for an HRTF.

ild is an HRTF-level metric. It reads the active domain data from hrtf and returns interaural level differences in decibels between the first two ear channels, where ear index 0 is the left ear and ear index 1 is the right ear. Any leading source or batch axes are preserved in the output.

In mode="broad-band", ILD is calculated from the time-domain impulse responses in hrtf.IR.values by comparing the RMS level of the left and right ears over the final sample axis. In mode="frequency-dependent", ILD is calculated directly from hrtf.TF.values by comparing left and right magnitudes at each frequency bin.

By default, the result is signed. Positive values mean the left ear has a greater level than the right ear. Negative values mean the right ear has a greater level than the left ear. Use absolute=True to return abs(ILD_db).

Parameters:

  • hrtf (HRTF) – HRTF object that provides IR and TF domain views. Broad-band mode requires hrtf.IR.values with layout (..., ear, samples). Frequency-dependent mode requires hrtf.TF.values with layout (..., ear, frequency).

  • mode ({"broad-band", "frequency-dependent"}, default=``”broad-band”``) – ILD calculation mode. "broad-band" returns one ILD value per leading entry. "frequency-dependent" returns one ILD value per leading entry and frequency bin.

  • epsilon (float, default=1e-12) – Positive floor added to left and right levels before division to avoid division by zero.

  • absolute (bool, default=False) – If False, return signed ILD values in dB. If True, return abs(ILD_db).

Returns:

ILD values in dB. Broad-band mode returns shape hrtf.IR.values.shape[:-2]. Frequency-dependent mode returns shape hrtf.TF.values.shape[:-2] + (hrtf.TF.values.shape[-1],).

Return type:

numpy.ndarray

Raises:

ValueError – If hrtf is not an HRTF-like object with IR and TF domains, if the selected domain values are missing, empty, not NumPy arrays, do not contain ear and sample/frequency axes, or contain fewer than two ear channels; if mode is unsupported; if epsilon is not finite and positive; or if absolute is not a boolean.

Examples

Compute signed broad-band ILD for every source position in a loaded HRTF:

>>> from hrtfpykit.hrtf import ild, load_hrtf
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> broad_band = ild(hrtf, mode="broad-band")
>>> broad_band.shape
(793,)

Compute a frequency-dependent ILD matrix:

>>> frequency_dependent = ild(hrtf, mode="frequency-dependent")
>>> frequency_dependent.shape
(793, 129)

Return unsigned broad-band ILD when side is not needed:

>>> unsigned_ild = ild(hrtf, mode="broad-band", absolute=True)
>>> unsigned_ild.shape
(793,)