Spatially encodes spherical microphone array signals into spherical harmonic signals (aka: Ambisonic signals) utilising theoretical encoding filters. More...

#include "array2sh.h"
#include "saf.h"
#include "saf_externals.h"

Data Structures
struct	array2sh_arrayPars
	Contains variables for describing the microphone/hydrophone array. More...

struct	array2sh_data
	Main structure for array2sh. More...

Macros
#define	ARRAY2SH_FRAME_SIZE ( 128 )
	Framesize, in time-domain samples.

#define	HOP_SIZE ( 128 )
	STFT hop size.

#define	HYBRID_BANDS ( HOP_SIZE + 5 )
	Number of frequency bands.

#define	TIME_SLOTS ( ARRAY2SH_FRAME_SIZE / HOP_SIZE )
	Number of STFT timeslots.

#define	MAX_NUM_SENSORS ( ARRAY2SH_MAX_NUM_SENSORS )
	Maximum permitted number of inputs/sensors.

#define	MAX_EVAL_FREQ_HZ ( 20e3f )
	Up to which frequency should the evaluation be accurate.

#define	MAX_NUM_SENSORS_IN_PRESET ( MAX_NUM_SENSORS )
	Maximum permitted number of inputs/sensors.

Functions
void	array2sh_initTFT (void *const hA2sh)
	Initialise the filterbank used by array2sh.

void	array2sh_calculate_sht_matrix (void *const hA2sh)
	Computes the spherical harmonic transform (SHT) matrix, to spatially encode input microphone/hydrophone signals into spherical harmonic signals.

void	array2sh_apply_diff_EQ (void *const hA2sh)
	Applies diffuse-field equalisation at frequencies above the spatial aliasing limit.

void	array2sh_calculate_mag_curves (void *const hA2sh)
	Computes the magnitude responses of the equalisation filters; the absolute values of the regularised inversed modal coefficients.

void	array2sh_evaluateSHTfilters (void *hA2sh)
	Evaluates the spherical harmonic transform performance with the currently configured microphone/hydrophone array.

void	array2sh_createArray (void **const hPars)
	Creates an instance of a struct, which contains the array configuration data.

void	array2sh_destroyArray (void **const hPars)
	Destroys an instance of a struct, which contains the array configuration data.

void	array2sh_initArray (void const hPars, ARRAY2SH_MICROPHONE_ARRAY_PRESETS preset, int arrayOrder, int firstInitFLAG)
	Intialises an instance of a struct based on a preset, which contains the array configuration data.

Detailed Description

Spatially encodes spherical microphone array signals into spherical harmonic signals (aka: Ambisonic signals) utilising theoretical encoding filters.

The algorithms within array2sh were pieced together and developed in collaboration with Symeon Delikaris-Manias and Angelo Farina. A detailed explanation of the algorithms within array2sh can be found in [1]. Also included, is a diffuse-field equalisation option for frequencies past aliasing, developed in collaboration with Archontis Politis, 8.02.2019

Note: Since the algorithms are based on theory, only array designs where there are analytical solutions available are supported. i.e. only spherical or cylindrical arrays, which have phase-matched sensors. For more information, the reader is referred to [2,3].

Test: test__saf_example_array2sh()

See also: [1] McCormack, L., Delikaris-Manias, S., Farina, A., Pinardi, D., and Pulkki, V., "Real-time conversion of sensor array signals into spherical harmonic signals with applications to spatially localised sub-band sound-field analysis," in Audio Engineering Society Convention 144, Audio Engineering Society, 2018.; [2] Williams EG. Fourier acoustics: sound radiation and nearfield acoustical holography. Elsevier; 1999 Jun 10.; [3] Rafaely B. Fundamentals of spherical array processing. Berlin: Springer; 2015 Feb 18.

Author: Leo McCormack

Date: 13.09.2017

License: ISC

Definition in file array2sh_internal.h.

Macro Definition Documentation

◆ ARRAY2SH_FRAME_SIZE

#define ARRAY2SH_FRAME_SIZE ( 128 )

Framesize, in time-domain samples.

Definition at line 69 of file array2sh_internal.h.

◆ HOP_SIZE

#define HOP_SIZE ( 128 )

STFT hop size.

Definition at line 72 of file array2sh_internal.h.

◆ HYBRID_BANDS

#define HYBRID_BANDS ( HOP_SIZE + 5 )

Number of frequency bands.

Definition at line 73 of file array2sh_internal.h.

◆ MAX_EVAL_FREQ_HZ

#define MAX_EVAL_FREQ_HZ ( 20e3f )

Up to which frequency should the evaluation be accurate.

Definition at line 76 of file array2sh_internal.h.

◆ MAX_NUM_SENSORS

#define MAX_NUM_SENSORS ( ARRAY2SH_MAX_NUM_SENSORS )

Maximum permitted number of inputs/sensors.

Definition at line 75 of file array2sh_internal.h.

◆ MAX_NUM_SENSORS_IN_PRESET

#define MAX_NUM_SENSORS_IN_PRESET ( MAX_NUM_SENSORS )

Maximum permitted number of inputs/sensors.

Definition at line 77 of file array2sh_internal.h.

◆ TIME_SLOTS

#define TIME_SLOTS ( ARRAY2SH_FRAME_SIZE / HOP_SIZE )

Number of STFT timeslots.

Definition at line 74 of file array2sh_internal.h.

Function Documentation

◆ array2sh_apply_diff_EQ()

void array2sh_apply_diff_EQ ( void *const hA2sh )

Applies diffuse-field equalisation at frequencies above the spatial aliasing limit.

Definition at line 380 of file array2sh_internal.c.

◆ array2sh_calculate_mag_curves()

void array2sh_calculate_mag_curves ( void *const hA2sh )

Computes the magnitude responses of the equalisation filters; the absolute values of the regularised inversed modal coefficients.

Definition at line 496 of file array2sh_internal.c.

◆ array2sh_calculate_sht_matrix()

void array2sh_calculate_sht_matrix ( void *const hA2sh )

Computes the spherical harmonic transform (SHT) matrix, to spatially encode input microphone/hydrophone signals into spherical harmonic signals.

Definition at line 95 of file array2sh_internal.c.

◆ array2sh_createArray()

void array2sh_createArray ( void **const hPars )

Creates an instance of a struct, which contains the array configuration data.

Parameters

[in] hPars (&) array configuration handle

Definition at line 606 of file array2sh_internal.c.

◆ array2sh_destroyArray()

void array2sh_destroyArray ( void **const hPars )

Destroys an instance of a struct, which contains the array configuration data.

Parameters

[in] hPars (&) array configuration handle

Definition at line 612 of file array2sh_internal.c.

◆ array2sh_evaluateSHTfilters()

void array2sh_evaluateSHTfilters ( void * hA2sh )

Evaluates the spherical harmonic transform performance with the currently configured microphone/hydrophone array.

Note: This is based on an analytical model of the array, so may differ in practice (although, it is usually pretty close, and saves from having to measure the array)

Definition at line 509 of file array2sh_internal.c.

◆ array2sh_initArray()

void array2sh_initArray	(	void *const	hPars,
		ARRAY2SH_MICROPHONE_ARRAY_PRESETS	preset,
		int *	arrayOrder,
		int	firstInitFLAG )

Intialises an instance of a struct based on a preset, which contains the array configuration data.

Parameters

[in]	hPars	(&) array configuration handle
[in]	preset	Array preset (see ARRAY2SH_MICROPHONE_ARRAY_PRESETS enum)
[in]	arrayOrder	(&) maximum encoding order of the current preset
[in]	firstInitFLAG	'1' this is the first time function is being called

Definition at line 621 of file array2sh_internal.c.

◆ array2sh_initTFT()

void array2sh_initTFT ( void *const hA2sh )

Initialise the filterbank used by array2sh.

Note: Call this function before array2sh_calculate_sht_matrix()

Definition at line 74 of file array2sh_internal.c.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ARRAY2SH_FRAME_SIZE

◆ HOP_SIZE

◆ HYBRID_BANDS

◆ MAX_EVAL_FREQ_HZ

◆ MAX_NUM_SENSORS

◆ MAX_NUM_SENSORS_IN_PRESET

◆ TIME_SLOTS

Function Documentation

◆ array2sh_apply_diff_EQ()

◆ array2sh_calculate_mag_curves()

◆ array2sh_calculate_sht_matrix()

◆ array2sh_createArray()

◆ array2sh_destroyArray()

◆ array2sh_evaluateSHTfilters()

◆ array2sh_initArray()

◆ array2sh_initTFT()