Internal header for the higher-order Ambisonics module (SAF_HOA_MODULE) More...

#include "saf_hoa.h"
#include "../saf_sh/saf_sh.h"
#include "../saf_vbap/saf_vbap.h"
#include "../saf_utilities/saf_utilities.h"
#include "saf_externals.h"

Functions
void	getEPAD (int order, float ls_dirs_deg, int nLS, float decMtx)
	Computes the Energy preserving Ambisonic decoder (EPAD), as detailed in [1].

void	getAllRAD (int order, float ls_dirs_deg, int nLS, float decMtx)
	Computes the All-round Ambisonics decoder (AllRAD), as detailed in [1], which is essentially a spherical harmonic approximation of VBAP patterns for the target loudspeaker setup.

void	getBinDecoder_LS (float_complex hrtfs, float hrtf_dirs_deg, int N_dirs, int N_bands, int order, float weights, float_complex decMtx)
	Computes a standard least-squares (LS) binaural ambisonic decoder.

void	getBinDecoder_LSDIFFEQ (float_complex hrtfs, float hrtf_dirs_deg, int N_dirs, int N_bands, int order, float weights, float_complex decMtx)
	Computes a least-squares (LS) binaural ambisonic decoder with diffuse-field equalisation [1].

void	getBinDecoder_SPR (float_complex hrtfs, float hrtf_dirs_deg, int N_dirs, int N_bands, int order, float weights, float_complex decMtx)
	Computes a binaural ambisonic decoder based on spatial resampling (i.e, virtual loudspeaker decoding) [1].

void	getBinDecoder_TA (float_complex hrtfs, float hrtf_dirs_deg, int N_dirs, int N_bands, int order, float freqVector, float itd_s, float weights, float_complex decMtx)
	Computes a binaural ambisonic decoder based on the time-alignment (TA) method described in [1].

void	getBinDecoder_MAGLS (float_complex hrtfs, float hrtf_dirs_deg, int N_dirs, int N_bands, int order, float freqVector, float weights, float_complex *decMtx)
	Computes a binaural ambisonic decoder based on the magnitude least-squares (MagLS) method, first described in [1], with the algorithm given in [2].

Detailed Description

Internal header for the higher-order Ambisonics module (SAF_HOA_MODULE)

A collection of Ambisonics related functions. Many of which are derived from the MATLAB library found in [1].

See also: [1] https://github.com/polarch/Higher-Order-Ambisonics Copyright (c) 2015, Archontis Politis, BSD-3-Clause License

Author: Leo McCormack

Date: 19.03.2018

License: ISC

Definition in file saf_hoa_internal.h.

Function Documentation

◆ getAllRAD()

void getAllRAD	(	int	order,
		float *	ls_dirs_deg,
		int	nLS,
		float *	decMtx )

Computes the All-round Ambisonics decoder (AllRAD), as detailed in [1], which is essentially a spherical harmonic approximation of VBAP patterns for the target loudspeaker setup.

Parameters

[in]	order	Decoding order
[in]	ls_dirs_deg	Loudspeaker directions in DEGREES [azi elev]; FLAT: nLS x 2
[in]	nLS	Number of loudspeakers
[out]	decMtx	Decoding matrix; FLAT: nLS x (order+1)^2

See also: [1] Zotter, F., Frank, M. (2012). All-Round Ambisonic Panning and Decoding. Journal of the Audio Engineering Society, 60(10), 807:820

Definition at line 100 of file saf_hoa_internal.c.

◆ getBinDecoder_LS()

void getBinDecoder_LS	(	float_complex *	hrtfs,
		float *	hrtf_dirs_deg,
		int	N_dirs,
		int	N_bands,
		int	order,
		float *	weights,
		float_complex *	decMtx )

Computes a standard least-squares (LS) binaural ambisonic decoder.

The binaural ambisonic decoder is computed for each frequency bin/band, ready to be applied to input SH signals in the time-frequency domain, or, take the inverse-FFT and apply it via matrix convolution.

Note: This standard LS decoder typically produces strong timbral colourations in the output when using lower-order input. This is due to input order truncation, since the HRTF grid is typically of much higher modal order than that of the input order. This colouration especially affects high- frequencies, since high-frequency energy is predominantly concentrated in the higher-order components so is then lost by truncating the input order. This phenomenon therefore gets worse when increasing the number of HRTFs in the set.

Parameters

[in]	hrtfs	The HRTFs; FLAT: N_bands x NUM_EARS x N_dirs
[in]	hrtf_dirs_deg	HRTF directions; FLAT: N_dirs x 2
[in]	N_dirs	Number of HRTF directions in set
[in]	N_bands	Number of frequency bands/bins
[in]	order	Decoding order
[in]	weights	Integration weights (set to NULL if not available); N_dirs x 1
[out]	decMtx	Decoding matrix; FLAT: N_bands x NUM_EARS x (order+1)^2

Definition at line 162 of file saf_hoa_internal.c.

◆ getBinDecoder_LSDIFFEQ()

void getBinDecoder_LSDIFFEQ	(	float_complex *	hrtfs,
		float *	hrtf_dirs_deg,
		int	N_dirs,
		int	N_bands,
		int	order,
		float *	weights,
		float_complex *	decMtx )

Computes a least-squares (LS) binaural ambisonic decoder with diffuse-field equalisation [1].

The binaural ambisonic decoder is computed for each frequency bin/band, ready to be applied to input SH signals in the time-frequency domain, or, take the inverse-FFT and apply it via matrix convolution.

Note: This equalisation mitagates some of the timbral colourations exhibited by standard LS decoding; especially at lower input orders.

Parameters

[in]	hrtfs	The HRTFs; FLAT: N_bands x NUM_EARS x N_dirs
[in]	hrtf_dirs_deg	HRTF directions; FLAT: N_dirs x 2
[in]	N_dirs	Number of HRTF directions in set
[in]	N_bands	Number of frequency bands/bins
[in]	order	Decoding order
[in]	weights	Integration weights (set to NULL if not available); N_dirs x 1
[out]	decMtx	Decoding matrix; FLAT: N_bands x NUM_EARS x (order+1)^2

See also: [1] Z. Ben-Hur, F. Brinkmann, J. Sheaffer, S. Weinzierl, and B. Rafaely, "Spectral equalization in binaural signals represented by order- truncated spherical harmonics," The Journal of the Acoustical Society of America, vol. 141, no. 6, pp. 4087–4096, 2017.

Definition at line 230 of file saf_hoa_internal.c.

◆ getBinDecoder_MAGLS()

void getBinDecoder_MAGLS	(	float_complex *	hrtfs,
		float *	hrtf_dirs_deg,
		int	N_dirs,
		int	N_bands,
		int	order,
		float *	freqVector,
		float *	weights,
		float_complex *	decMtx )

Computes a binaural ambisonic decoder based on the magnitude least-squares (MagLS) method, first described in [1], with the algorithm given in [2].

The binaural ambisonic decoder is computed for each frequency bin/band, ready to be applied to input SH signals in the time-frequency domain, or, take the inverse-FFT and apply it via matrix convolution.

Note: Mag-LS operates under similar principles held by the TA/TAC decoder, differing in the manner in which the phase is neglected at frequencies above 1.5kHz.

Parameters

[in]	hrtfs	The HRTFs; FLAT: N_bands x NUM_EARS x N_dirs
[in]	hrtf_dirs_deg	HRTF directions; FLAT: N_dirs x 2
[in]	N_dirs	Number of HRTF directions in set
[in]	N_bands	Number of frequency bands/bins
[in]	order	Decoding order
[in]	freqVector	Frequency vector; N_bands x 1
[in]	weights	Integration weights (set to NULL if not available); N_dirs x 1
[out]	decMtx	Decoding matrix; FLAT: N_bands x NUM_EARS x (order+1)^2

See also: [1] Scho"rkhuber C, Zaunschirm M, Ho"ldrich R. Binaural Rendering of Ambisonic Signals via Magnitude Least Squares. InProceedings of the DAGA 2018 (Vol. 44, pp. 339–342).; [2] Zotter, F., & Frank, M. (2019). Ambisonics. Springer Open.

Definition at line 526 of file saf_hoa_internal.c.

◆ getBinDecoder_SPR()

void getBinDecoder_SPR	(	float_complex *	hrtfs,
		float *	hrtf_dirs_deg,
		int	N_dirs,
		int	N_bands,
		int	order,
		float *	weights,
		float_complex *	decMtx )

Computes a binaural ambisonic decoder based on spatial resampling (i.e, virtual loudspeaker decoding) [1].

The binaural ambisonic decoder is computed for each frequency bin/band, ready to be applied to input SH signals in the time-frequency domain, or, take the inverse-FFT and apply it via matrix convolution.

Note: Like getBinDecoder_LSDIFFEQ() this method mitagates some of the timbral colourations exhibited by standard LS decoding at lower input orders. However, it operates without equalisation. Instead, the modal order of the HRTF grid is brought closer to the decoding order by simply reducing the number of HRTF points. The LS decoder is then computed using this reduced HRTF set. Therefore, rather than assigning high- frequency energy to higher-order components and subsequently discarding it due to order truncation, the energy is instead aliased back into the lower-order components and preserved.

Parameters

[in]	hrtfs	The HRTFs; FLAT: N_bands x NUM_EARS x N_dirs
[in]	hrtf_dirs_deg	HRTF directions; FLAT: N_dirs x 2
[in]	N_dirs	Number of HRTF directions in set
[in]	N_bands	Number of frequency bands/bins
[in]	order	Decoding order
[in]	weights	Integration weights (set to NULL if not available); N_dirs x 1
[out]	decMtx	Decoding matrix; FLAT: N_bands x NUM_EARS x (order+1)^2

See also: [1] B. Bernschu"tz, A. V. Giner, C. Po"rschmann, and J. Arend, "Binaural reproduction of plane waves with reduced modal order" Acta Acustica united with Acustica, vol. 100, no. 5, pp. 972–983, 2014.

Definition at line 332 of file saf_hoa_internal.c.

◆ getBinDecoder_TA()

void getBinDecoder_TA	(	float_complex *	hrtfs,
		float *	hrtf_dirs_deg,
		int	N_dirs,
		int	N_bands,
		int	order,
		float *	freqVector,
		float *	itd_s,
		float *	weights,
		float_complex *	decMtx )

Computes a binaural ambisonic decoder based on the time-alignment (TA) method described in [1].

The binaural ambisonic decoder is computed for each frequency bin/band, ready to be applied to input SH signals in the time-frequency domain, or, take the inverse-FFT and apply it via matrix convolution.

Note: Since the standard LS decoder is unable to sufficiently fit lower-order spherical harmonics to the highly directive HRTF patterns, this approach addresses this by conducting preliminary time-alignment of the Head-related impulse responses (HRIRs), which aids the LS fitting. This method essentially exploits prior knowledge of the bandwidth in which the inter-aural level differences (ILDs) are the dominant localisation cues; which is above approximately 1.5 kHz. By discarding the phase information of the HRTFs at frequencies above 1.5 kHz, the LS fitting instead prioritises the delivery of the correct magnitude responses; rather than the phase. Thus it ultimately yields improved ILD cues and diminished inter-aural time difference (ITD) cues, but in a frequency range where ILD cues are more important for localisation. This method, therefore, mitagates many of the localisation deficiencies compared with the standard LS decoding at lower input orders.; The paper [1] also detailed a diffuse-field covariance constraint, and the original accronym was TAC (C=contrained), however, in SAF, this constraint is implemented as an independent operation. One may impose this constraint on any binaural decoder using the applyDiffCovMatching() function.

Parameters

[in]	hrtfs	The HRTFs; FLAT: N_bands x NUM_EARS x N_dirs
[in]	hrtf_dirs_deg	HRTF directions; FLAT: N_dirs x 2
[in]	N_dirs	Number of HRTF directions in set
[in]	N_bands	Number of frequency bands/bins
[in]	order	Decoding order
[in]	freqVector	Frequency vector; N_bands x 1
[in]	itd_s	Interaural time differences (ITDs), seconds; N_dirs x 1
[in]	weights	Integration weights (set to NULL if not available); N_dirs x 1
[out]	decMtx	Decoding matrix; FLAT: N_bands x NUM_EARS x (order+1)^2

See also: [1] Zaunschirm M, Scho"rkhuber C, Ho"ldrich R. Binaural rendering of Ambisonic signals by head-related impulse response time alignment and a diffuseness constraint. The Journal of the Acoustical Society of America. 2018 Jun 19;143(6):3616–27

Definition at line 432 of file saf_hoa_internal.c.

◆ getEPAD()

void getEPAD	(	int	order,
		float *	ls_dirs_deg,
		int	nLS,
		float *	decMtx )

Computes the Energy preserving Ambisonic decoder (EPAD), as detailed in [1].

Note: The function has been written to also work when the number of spherical harmonic components exceeds the number of loudspeakers. In which case, the 'U' matrix from the SVD is truncated instead. However, ideally, nLS > nSH.; Additional scaling is applied so that when the loudspeakers are uniformly arranged, the decoding matrix gains are equivalent to those produced by SAD/MMD.

Parameters

[in]	order	Decoding order
[in]	ls_dirs_deg	Loudspeaker directions in DEGREES [azi elev]; FLAT: nLS x 2
[in]	nLS	Number of loudspeakers
[out]	decMtx	Decoding matrix; FLAT: nLS x (order+1)^2

See also: [1] Zotter, F., Pomberger, H., Noisternig, M. (2012). Energy-Preserving Ambisonic Decoding. Acta Acustica United with Acustica, 98(1), 37:47

Definition at line 41 of file saf_hoa_internal.c.

Functions

Detailed Description

Function Documentation

◆ getAllRAD()

◆ getBinDecoder_LS()

◆ getBinDecoder_LSDIFFEQ()

◆ getBinDecoder_MAGLS()

◆ getBinDecoder_SPR()

◆ getBinDecoder_TA()

◆ getEPAD()