Files
file	saf_sofa_reader.c
	Public source for the sofa reader module (SAF_SOFA_READER_MODULE)

file	saf_sofa_reader.h
	Main header for the sofa reader module (SAF_SOFA_READER_MODULE)

Data Structures
struct	saf_sofa_container
	SOFA container struct comprising all possible data that can be extracted from SOFA 1.0 files; as laid down in the GeneralFIR and SimpleFreeFieldHRIR specifications: https://www.sofaconventions.org/mediawiki/index.php/GeneralFIR https://www.sofaconventions.org/mediawiki/index.php/SimpleFreeFieldHRIR. More...

Enumerations
enum	SAF_SOFA_READER_OPTIONS { SAF_SOFA_READER_OPTION_DEFAULT , SAF_SOFA_READER_OPTION_LIBMYSOFA , SAF_SOFA_READER_OPTION_NETCDF }
	SOFA file reader options. More...

enum	SAF_SOFA_ERROR_CODES { SAF_SOFA_OK , SAF_SOFA_ERROR_INVALID_FILE_OR_FILE_PATH , SAF_SOFA_ERROR_DIMENSIONS_UNEXPECTED , SAF_SOFA_ERROR_FORMAT_UNEXPECTED , SAF_SOFA_ERROR_NETCDF_IN_USE }
	SOFA loader error codes. More...

Functions
SAF_SOFA_ERROR_CODES	saf_sofa_open (saf_sofa_container hSOFA, char sofa_filepath, SAF_SOFA_READER_OPTIONS option)
	Fills a 'sofa_container' with data found in a SOFA file (GeneralFIR or SimpleFreeFieldHRIR), as detailed in the SOFA 1.0 standard [1,2,3].

void	saf_sofa_close (saf_sofa_container *hSOFA)
	Frees all SOFA data in a sofa_container.

Detailed Description

SOFA file reading module

Enumeration Type Documentation

◆ SAF_SOFA_ERROR_CODES

enum SAF_SOFA_ERROR_CODES

SOFA loader error codes.

Enumerator
SAF_SOFA_OK	None of the error checks failed.
SAF_SOFA_ERROR_INVALID_FILE_OR_FILE_PATH	Not a SOFA file, or no such file was found in the specified location.
SAF_SOFA_ERROR_DIMENSIONS_UNEXPECTED	Dimensions of the SOFA data were not as expected.
SAF_SOFA_ERROR_FORMAT_UNEXPECTED	The data-type of the SOFA data was not as expected.
SAF_SOFA_ERROR_NETCDF_IN_USE	NetCDF is not thread safe!

Definition at line 165 of file saf_sofa_reader.h.

◆ SAF_SOFA_READER_OPTIONS

enum SAF_SOFA_READER_OPTIONS

SOFA file reader options.

Enumerator

SAF_SOFA_READER_OPTION_DEFAULT

The default option is SAF_SOFA_READER_OPTION_LIBMYSOFA.

SAF_SOFA_READER_OPTION_LIBMYSOFA

This option uses the libmysofa library to load SOFA files, which is adopted from: https://github.com/hoene/libmysofa (BSD-3-Clause license)

The benefits of this option is that it only depends on zlib, which is included in SAF. While the downsides of this option, is that zlib has file size limits for each chunk (<4GB) and it is quite slow at decompressing large files.

SAF_SOFA_READER_OPTION_NETCDF

If SAF_ENABLE_NETCDF is defined, then an alternative SOFA reader may be used.

This version requires netcdf to be linked to SAF, along with its dependencies. The netcdf loader gets around the file size limits of the libmysofa loader and is also approximately 3 times faster. Therefore, if you intend to load many large SOFA files (especially microphone arrays or Ambisonic IRs), then this alternative SOFA reader is either required (to get around the file size limit) or may be preferred due to the shorter loading times. The downsides of using the netcdf option is that it is NOT thread-safe! and requires these additional external libraries to be linked to SAF.

Definition at line 47 of file saf_sofa_reader.h.

Function Documentation

◆ saf_sofa_close()

void saf_sofa_close ( saf_sofa_container * hSOFA )

Frees all SOFA data in a sofa_container.

Parameters

[in] hSOFA The sofa_container

Definition at line 634 of file saf_sofa_reader.c.

◆ saf_sofa_open()

SAF_SOFA_ERROR_CODES saf_sofa_open	(	saf_sofa_container *	hSOFA,
		char *	sofa_filepath,
		SAF_SOFA_READER_OPTIONS	option )

Fills a 'sofa_container' with data found in a SOFA file (GeneralFIR or SimpleFreeFieldHRIR), as detailed in the SOFA 1.0 standard [1,2,3].

Warning: This loader currently does not support TF SOFA files!

Note: If you encounter a SOFA file that this SOFA loader cannot load, (or it misses some of the data) then please send it to the developers :-)

Test: test__saf_sofa_open(), test__mysofa_load(), test__sofa_comparison()

Parameters

[in]	hSOFA	The sofa_container
[in]	sofa_filepath	SOFA file path (including .sofa extension)
[in]	option	See SAF_SOFA_READER_OPTIONS

Returns: An error code (see SAF_SOFA_ERROR_CODES)

See also: [1] Majdak, P., Iwaya, Y., Carpentier, T., Nicol, R., Parmentier, M., Roginska, A., Suzuki, Y., Watanabe, K., Wierstorf, H., Ziegelwanger, H. and Noisternig, M., 2013, May. Spatially oriented format for acoustics: A data exchange format representing head-related transfer functions. In Audio Engineering Society Convention 134. Audio Engineering Society.; [2] https://www.sofaconventions.org/mediawiki/index.php/GeneralFIR; [3] https://www.sofaconventions.org/mediawiki/index.php/SimpleFreeFieldHRIR

Definition at line 44 of file saf_sofa_reader.c.

Files

Data Structures

Enumerations