load_hrtf

hrtfpykit.hrtf.load_hrtf(path, mode='r', parallel=False, check_sofa_against_conventions=True, fft_length=None, mesh2hrtf_compatible=False, mesh2hrtf_n_shift=30)

Load a SOFA file as an HRTF object.

This function is the public loader for SOFA-based HRTF workflows in hrtfpykit. It reads the file through the package SOFA API, verifies that the declared SOFA convention is an HRTF convention, and populates the central HRTF abstraction with synchronized time- and frequency-domain data. Loaded objects keep the original SOFA handle in Sofa while exposing NumPy arrays through IR and TF for processing, plotting, selection, and export.

  • IR (time domain)

  • TF (frequency domain)

Supported conventions:

  • SimpleFreeFieldHRIR: loaded from Data.IR and converted to TF.

  • SimpleFreeFieldHRTF: loaded from Data.Real, Data.Imag, and N and converted to IR.

HRIR files derive TF.values and TF.frequency_bins with a real FFT. HRTF files rebuild IR.values with inverse real FFT from the one-sided positive-frequency representation. For SimpleFreeFieldHRTF input, frequency bins must be non-negative, increasing, and uniformly spaced. DC (0 Hz) should be present. If DC is missing and bins start at one-bin step (Delta f), hrtfpykit prepends DC with value 1+0j to keep reconstruction consistent. The normalized TF is stored on TF, so update_sofa() and save() write the DC bin back when the object is synchronized.

Mesh2HRTF compatible reconstruction options are stored on the returned object. They are reused by reset(), preserved by clone(), and forwarded by TF-domain workflows that rebuild HRIR data from the current HRTF values.

Parameters:

  • path (str | Path) – Path to the SOFA file.

  • mode (str, default=``r``) – File mode used by the SOFA API.

  • parallel (bool, default=False) – Whether to enable parallel loading in the SOFA API.

  • check_sofa_against_conventions (bool, default=True) – Whether to run convention checks when reading the SOFA file.

  • fft_length (int | None, default=None) – Optional FFT length used when deriving TF from HRIR content. For HRTF files, a provided value must match the FFT length implied by N/frequency bins.

  • mesh2hrtf_compatible (bool, default=False) – If True, use Mesh2HRTF-style TF-to-IR reconstruction when loading SimpleFreeFieldHRTF files. The selected value is stored on the returned object and reused by reset and transform workflows.

  • mesh2hrtf_n_shift (int | None, default=30) – Optional circular shift in samples applied after TF-to-IR reconstruction when mesh2hrtf_compatible=True. The selected value is stored on the returned object.

Returns:

Loaded HRTF object with IR, TF, SOFAConventions, and fft_length populated. For SimpleFreeFieldHRTF input, Mesh2HRTF compatible load options are also stored on the object.

Return type:

HRTF

Raises:

ValueError – If the SOFA file is unavailable, declares an unsupported convention, omits required SOFA variables, contains empty acoustic data, has an invalid sample rate, or provides frequency bins incompatible with the requested FFT length.

Examples

Load a SimpleFreeFieldHRIR convention SOFA file and inspect the synchronized time- and frequency-domain views:

>>> from hrtfpykit.hrtf import load_hrtf
>>> hrtf = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf.SOFAConventions
'SimpleFreeFieldHRIR'
>>> hrtf.IR.values.shape
(793, 2, 256)
>>> hrtf.TF.values.shape
(793, 2, 129)
>>> hrtf.IR.sample_rate
44100.0

Load a SimpleFreeFieldHRTF file with Mesh2HRTF compatible reconstruction and keep those reconstruction settings available for reset and later TF workflows:

>>> hrtf = load_hrtf(
...     "hrtfs/HRTF_ARI_44100.sofa",
...     mesh2hrtf_compatible=True,
...     mesh2hrtf_n_shift=30,
... )
>>> hrtf.mesh2hrtf_compatible
True
>>> hrtf.mesh2hrtf_n_shift
30