load_sofa

hrtfpykit.sofa.load_sofa(path, mode='r', parallel=False, check_sofa_against_conventions=True)

Load a SOFA file into a SOFA object.

This is the public entry point for inspecting or editing SOFA files with hrtfpykit. The file is opened with netCDF4, wrapped in a SOFA instance, and optionally checked against the SOFA convention declared by its global attributes. HRTF objects use this function internally when loading SimpleFreeFieldHRIR and SimpleFreeFieldHRTF files.

Parameters:

  • path (Union[str, pathlib.Path]) – Path to an existing .sofa file.

  • mode (str, default=``r``) – netCDF4 open mode used to open the file, such as r for read-only access or r+ for direct in-place edits.

  • parallel (bool, default=False) – Whether to request netCDF4 parallel I/O support when opening the netCDF4 object. This is forwarded directly to netCDF4.Dataset.

  • check_sofa_against_conventions (bool, default=True) – Whether to validate the file against its declared SOFAConventions metadata before opening it as a SOFA object. Convention mismatches are reported by the validation utility, usually as SOFA convention warnings.

Returns:

SOFA object whose netCDF4_dataset attribute is an open netCDF4 storage handle and whose path attribute points to path.

Return type:

SOFA

Raises:

  • FileNotFoundError – If path does not exist.

  • ValueError – If path does not end in .sofa.

  • OSError – If netCDF4 cannot open the file with the requested mode or parallel setting.

Notes

The returned object owns an open netCDF4 handle. Close netCDF4_dataset when the loaded file is no longer needed, or save to a separate path with save() when working from a clone.

Examples

Open a SimpleFreeFieldHRIR convention SOFA file and inspect its convention metadata, source grid, and HRIR array through the SOFA wrappers:

>>> from hrtfpykit.sofa import load_sofa
>>> sofa = load_sofa("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> sofa.GlobalAttributes.get("SOFAConventions").value
'SimpleFreeFieldHRIR'
>>> sofa.Variables.get("SourcePosition").value.shape
(793, 3)
>>> sofa.Variables.get("Data.IR").value.shape
(793, 2, 256)