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

#include "_common.h"

Macros
#define	ARRAY2SH_NUM_FILTER_TYPES ( 4 )
	Number of available filter types.

#define	ARRAY2SH_NUM_ARRAY_TYPES ( 2 )
	Number of supported array types.

#define	ARRAY2SH_NUM_WEIGHT_TYPES ( 6 )
	Number of supported sensor directivities and array construction types.

#define	ARRAY2SH_MAX_NUM_SENSORS ( MAX_NUM_CHANNELS )
	Maximum number of sensors supported.

#define	ARRAY2SH_MAX_GAIN_MIN_VALUE ( 0.0f )
	Minimum gain value used for regularised inverse of modal coeffs, dB.

#define	ARRAY2SH_MAX_GAIN_MAX_VALUE ( 80.0f )
	Maximum gain value used for regularised inverse of modal coeffs, dB.

#define	ARRAY2SH_POST_GAIN_MIN_VALUE ( -60.0f )
	Minimum post-gain, dB.

#define	ARRAY2SH_POST_GAIN_MAX_VALUE ( 12.0f )
	Maximum post-gain, dB.

#define	ARRAY2SH_SPEED_OF_SOUND_MIN_VALUE ( 200.0f )
	Minimum speed of sound value, m/s.

#define	ARRAY2SH_SPEED_OF_SOUND_MAX_VALUE ( 2000.0f )
	Maximum speed of sound value, m/s.

#define	ARRAY2SH_ARRAY_RADIUS_MIN_VALUE ( 1.0f )
	Minimum array radius supported, mm.

#define	ARRAY2SH_ARRAY_RADIUS_MAX_VALUE ( 400.0f )
	Maximum array radius supported, mm.

#define	ARRAY2SH_BAFFLE_RADIUS_MIN_VALUE ( 1.0f )
	Minimum baffle radius supported, mm.

#define	ARRAY2SH_BAFFLE_RADIUS_MAX_VALUE ( 400.0f )
	Maximum baffle radius supported, mm.

Enumerations
enum	ARRAY2SH_MICROPHONE_ARRAY_PRESETS { MICROPHONE_ARRAY_PRESET_DEFAULT = 1 , MICROPHONE_ARRAY_PRESET_AALTO_HYDROPHONE , MICROPHONE_ARRAY_PRESET_SENNHEISER_AMBEO , MICROPHONE_ARRAY_PRESET_CORE_SOUND_TETRAMIC , MICROPHONE_ARRAY_PRESET_ZOOM_H3VR_PRESET , MICROPHONE_ARRAY_PRESET_SOUND_FIELD_SPS200 , MICROPHONE_ARRAY_PRESET_ZYLIA_1D , MICROPHONE_ARRAY_PRESET_EIGENMIKE32 , MICROPHONE_ARRAY_PRESET_EIGENMIKE64 , MICROPHONE_ARRAY_PRESET_DTU_MIC }
	Available microphone array presets. More...

enum	ARRAY2SH_FILTER_TYPES { FILTER_SOFT_LIM = 1 , FILTER_TIKHONOV , FILTER_Z_STYLE , FILTER_Z_STYLE_MAXRE }
	Available encoding filter approaches. More...

enum	ARRAY2SH_ARRAY_TYPES { ARRAY_SPHERICAL = 1 , ARRAY_CYLINDRICAL }
	List of supported array types. More...

enum	ARRAY2SH_WEIGHT_TYPES { WEIGHT_RIGID_OMNI = 1 , WEIGHT_RIGID_CARD , WEIGHT_RIGID_DIPOLE , WEIGHT_OPEN_OMNI , WEIGHT_OPEN_CARD , WEIGHT_OPEN_DIPOLE }
	List of supported sensor directivities and array construction types. More...

enum	ARRAY2SH_EVAL_STATUS { EVAL_STATUS_EVALUATED = 0 , EVAL_STATUS_RECENTLY_EVALUATED , EVAL_STATUS_NOT_EVALUATED , EVAL_STATUS_EVALUATING }
	Current status of the encoder evaluation output data. More...

Functions
void	array2sh_create (void **const phA2sh)
	Creates an instance of array2sh.

void	array2sh_destroy (void **const phA2sh)
	Destroys an instance of array2sh.

void	array2sh_init (void *const hA2sh, int samplerate)
	Initialises an instance of array2sh with default settings.

void	array2sh_evalEncoder (void *const hA2sh)
	Evaluates the encoder, based on current global/user parameters.

void	array2sh_process (void const hA2sh, const float const inputs, float const *outputs, int nInputs, int nOutputs, int nSamples)
	Spatially encode microphone/hydrophone array signals into spherical harmonic signals.

void	array2sh_refreshSettings (void *const hA2sh)
	Sets all intialisation flags to 1; re-initialising all settings/variables as array2sh is currently configured, at next available opportunity.

void	array2sh_setEncodingOrder (void *const hA2sh, int newOrder)
	Sets the encoding order (see SH_ORDERS enum)

void	array2sh_setRequestEncoderEvalFLAG (void *const hA2sh, int newState)
	Evaluates the performance of the current encoding filters when applied to a theoretical model of the currently configured array; two established objective metrics are then computed; more information in [1].

void	array2sh_setEvalStatus (void *const hA2sh, ARRAY2SH_EVAL_STATUS evalStatus)
	Sets current eval status (see ARRAY2SH_EVAL_STATUS enum)

void	array2sh_setDiffEQpastAliasing (void *const hA2sh, int newState)
	Analyses what the theoretical spatial aliasing frequency is, and conducts diffuse-field equalisation above this (enable: 1, disable: 0).

void	array2sh_setPreset (void *const hA2sh, ARRAY2SH_MICROPHONE_ARRAY_PRESETS preset)
	Sets a pre-defined microphone/hydrophone array preset (See ARRAY2SH_MICROPHONE_ARRAY_PRESETS enum)

void	array2sh_setSensorAzi_rad (void *const hA2sh, int index, float newAzi_rad)
	Sets a particular sensor's azimuth (radians) w.r.t to the origin of the array.

void	array2sh_setSensorElev_rad (void *const hA2sh, int index, float newElev_rad)
	Sets a particular sensor's elevation (radians) w.r.t to the origin of the array.

void	array2sh_setSensorAzi_deg (void *const hA2sh, int index, float newAzi_deg)
	Sets a particular sensor's azimuth (degrees) w.r.t to the origin of the array.

void	array2sh_setSensorElev_deg (void *const hA2sh, int index, float newElev_deg)
	Sets a particular sensor's elevation (degrees) w.r.t to the origin of the array.

void	array2sh_setNumSensors (void *const hA2sh, int newQ)
	Sets the number of sensors in the array.

void	array2sh_setr (void *const hA2sh, float newr)
	Sets the radius of the array.

void	array2sh_setR (void *const hA2sh, float newR)
	Sets the radius (in meters) of the scatterer (only for Rigid arrays).

void	array2sh_setArrayType (void *const hA2sh, int newType)
	Sets the type of array (see ARRAY2SH_ARRAY_TYPES enum)

void	array2sh_setWeightType (void *const hA2sh, int newType)
	Sets the type of weights to use (see ARRAY2SH_WEIGHT_TYPES enum)

void	array2sh_setFilterType (void *const hA2sh, int newType)
	Sets the type filter design to employ for computing the encoding matrices (see ARRAY2SH_FILTER_TYPES enum)

void	array2sh_setRegPar (void *const hA2sh, float newVal)
	Sets the value of the regularisation parameter (the maximum permitted gain of the filters), in DECIBELS.

void	array2sh_setChOrder (void *const hA2sh, int newOrder)
	Sets the Ambisonic channel ordering convention to encode with, in order to match the convention employed by the input signals (see CH_ORDER enum)

void	array2sh_setNormType (void *const hA2sh, int newType)
	Sets the Ambisonic normalisation convention to encode with, in order to match with the convention employed by the input signals (see NORM_TYPES enum)

void	array2sh_setc (void *const hA2sh, float newc)
	Sets the speed of sound of the medium (~343m/s air, ~1480m/s water), in m/s.

void	array2sh_setGain (void *const hA2sh, float newGain)
	Sets the amount of post gain to apply after the encoding, in DECIBELS.

int	array2sh_getFrameSize (void)
	Returns the processing framesize (i.e., number of samples processed with every _process() call )

ARRAY2SH_EVAL_STATUS	array2sh_getEvalStatus (void *const hA2sh)
	Returns current eval status (see ARRAY2SH_EVAL_STATUS enum)

int	array2sh_getReinitSHTmatrixFLAG (void *const hA2sh)
	Returns 0 if SHT is not be reinitialised, 1: if it is.

float	array2sh_getProgressBar0_1 (void *const hA2sh)
	(Optional) Returns current intialisation/processing progress, between 0..1

void	array2sh_getProgressBarText (void const hA2sh, char text)
	(Optional) Returns current intialisation/processing progress text

int	array2sh_getDiffEQpastAliasing (void *const hA2sh)
	Flag to enabled/disable diffuse equalisation above the spatial aliasing limit of the array (0: disabled, 1: enabled).

int	array2sh_getRequestEncoderEvalFLAG (void *const hA2sh)
	Returns a flag, which is '1' if there has been a recent request to evaluate the current encoding performance, or '0', if there hasn't.

int	array2sh_getEncodingOrder (void *const hA2sh)
	Returns the current encoding order (see SH_ORDERS enum)

float	array2sh_getSensorAzi_rad (void *const hA2sh, int index)
	Returns a particular sensor's azimuth w.r.t to the origin of the array, in RADIANS.

float	array2sh_getSensorElev_rad (void *const hA2sh, int index)
	Returns a particular sensor's elevation w.r.t to the origin of the array, in RADIANS.

float	array2sh_getSensorAzi_deg (void *const hA2sh, int index)
	Returns a particular sensor's azimuth w.r.t to the origin of the array, in DEGREES.

float	array2sh_getSensorElev_deg (void *const hA2sh, int index)
	Returns a particular sensor's elevation w.r.t to the origin of the array, in DEGREES.

int	array2sh_getNumSensors (void *const hA2sh)
	Returns the number of sensors in the array.

int	array2sh_getMaxNumSensors (void)
	Returns the maximum supported number of sensors which can be in the array.

int	array2sh_getMinNumSensors (void *const hA2sh)
	Returns the minimum number of sensors which can be in the array [(current_order+1)^2].

int	array2sh_getNSHrequired (void *const hA2sh)
	Returns the number of spherical harmonic signals required by the current encoding order: (current_order+1)^2.

float	array2sh_getr (void *const hA2sh)
	Returns the radius of the array, in meters.

float	array2sh_getR (void *const hA2sh)
	Returns the radius of the scatterer, in meters.

int	array2sh_getArrayType (void *const hA2sh)
	Returns the type of array.

int	array2sh_getWeightType (void *const hA2sh)
	Returns the type of weights to use see ARRAY2SH_WEIGHT_TYPES enum.

int	array2sh_getFilterType (void *const hA2sh)
	Returns the type filter design to employ for computing the encoding matrices (see ARRAY2SH_FILTER_TYPES enum)

float	array2sh_getRegPar (void *const hA2sh)
	Returns the value of the regurlisation parameter; the maximum permitted gain provided by the filters, in DECIBELS.

int	array2sh_getChOrder (void *const hA2sh)
	Returns the Ambisonic channel ordering convention currently being used to decode with, which should match the convention employed by the input signals (see CH_ORDER enum)

int	array2sh_getNormType (void *const hA2sh)
	Returns the Ambisonic normalisation convention currently being usedto decode with, which should match the convention employed by the input signals (see NORM_TYPES enum)

float	array2sh_getc (void *const hA2sh)
	Returns the speed of sound of the medium (~343m/s air, ~1480m/s water), in m/s.

float	array2sh_getGain (void *const hA2sh)
	Returns the amount of post gain to apply after the encoding, in DECIBELS.

float *	array2sh_getFreqVector (void const hA2sh, int nFreqPoints)
	Returns a pointer to the frequency vector.

float **	array2sh_getbN_inv (void const hA2sh, int nCurves, int *nFreqPoints)
	Returns the regularised inversion of the modal coefficients per frequency (may be used for optional plotting purposes)

float **	array2sh_getbN_modal (void const hA2sh, int nCurves, int *nFreqPoints)
	Returns the direct inversion of the modal coefficients per frequency (may be used for optional plotting purposes)

float *	array2sh_getSpatialCorrelation_Handle (void const hA2sh, int nCurves, int *nFreqPoints)
	Returns a pointer to the spatial correlation [1] data.

float *	array2sh_getLevelDifference_Handle (void const hA2sh, int nCurves, int *nFreqPoints)
	Returns a pointer to the level-difference [1] data.

int	array2sh_getSamplingRate (void *const hA2sh)
	Returns the DAW/Host sample rate.

int	array2sh_getProcessingDelay (void)
	Returns the processing delay in samples (may be used for delay compensation features)

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.h.

Macro Definition Documentation

◆ ARRAY2SH_ARRAY_RADIUS_MAX_VALUE

#define ARRAY2SH_ARRAY_RADIUS_MAX_VALUE ( 400.0f )

Maximum array radius supported, mm.

Definition at line 219 of file array2sh.h.

◆ ARRAY2SH_ARRAY_RADIUS_MIN_VALUE

#define ARRAY2SH_ARRAY_RADIUS_MIN_VALUE ( 1.0f )

Minimum array radius supported, mm.

Definition at line 216 of file array2sh.h.

◆ ARRAY2SH_BAFFLE_RADIUS_MAX_VALUE

#define ARRAY2SH_BAFFLE_RADIUS_MAX_VALUE ( 400.0f )

Maximum baffle radius supported, mm.

Definition at line 225 of file array2sh.h.

◆ ARRAY2SH_BAFFLE_RADIUS_MIN_VALUE

#define ARRAY2SH_BAFFLE_RADIUS_MIN_VALUE ( 1.0f )

Minimum baffle radius supported, mm.

Definition at line 222 of file array2sh.h.

◆ ARRAY2SH_MAX_GAIN_MAX_VALUE

#define ARRAY2SH_MAX_GAIN_MAX_VALUE ( 80.0f )

Maximum gain value used for regularised inverse of modal coeffs, dB.

Definition at line 201 of file array2sh.h.

◆ ARRAY2SH_MAX_GAIN_MIN_VALUE

#define ARRAY2SH_MAX_GAIN_MIN_VALUE ( 0.0f )

Minimum gain value used for regularised inverse of modal coeffs, dB.

Definition at line 198 of file array2sh.h.

◆ ARRAY2SH_MAX_NUM_SENSORS

#define ARRAY2SH_MAX_NUM_SENSORS ( MAX_NUM_CHANNELS )

Maximum number of sensors supported.

Definition at line 195 of file array2sh.h.

◆ ARRAY2SH_NUM_ARRAY_TYPES

#define ARRAY2SH_NUM_ARRAY_TYPES ( 2 )

Number of supported array types.

Definition at line 163 of file array2sh.h.

◆ ARRAY2SH_NUM_FILTER_TYPES

#define ARRAY2SH_NUM_FILTER_TYPES ( 4 )

Number of available filter types.

Definition at line 148 of file array2sh.h.

◆ ARRAY2SH_NUM_WEIGHT_TYPES

#define ARRAY2SH_NUM_WEIGHT_TYPES ( 6 )

Number of supported sensor directivities and array construction types.

Definition at line 178 of file array2sh.h.

◆ ARRAY2SH_POST_GAIN_MAX_VALUE

#define ARRAY2SH_POST_GAIN_MAX_VALUE ( 12.0f )

Maximum post-gain, dB.

Definition at line 207 of file array2sh.h.

◆ ARRAY2SH_POST_GAIN_MIN_VALUE

#define ARRAY2SH_POST_GAIN_MIN_VALUE ( -60.0f )

Minimum post-gain, dB.

Definition at line 204 of file array2sh.h.

◆ ARRAY2SH_SPEED_OF_SOUND_MAX_VALUE

#define ARRAY2SH_SPEED_OF_SOUND_MAX_VALUE ( 2000.0f )

Maximum speed of sound value, m/s.

Definition at line 213 of file array2sh.h.

◆ ARRAY2SH_SPEED_OF_SOUND_MIN_VALUE

#define ARRAY2SH_SPEED_OF_SOUND_MIN_VALUE ( 200.0f )

Minimum speed of sound value, m/s.

Definition at line 210 of file array2sh.h.

Enumeration Type Documentation

◆ ARRAY2SH_ARRAY_TYPES

enum ARRAY2SH_ARRAY_TYPES

List of supported array types.

Note: Although supported, cylindrical arrays have not really been tested as we don't own one. Just to keep in mind.

Enumerator
ARRAY_SPHERICAL	Spherical arrangement of sensors (open/rigid)
ARRAY_CYLINDRICAL	Cylindrial arrangement of sensors (open/rigid)

Examples: array2sh.h.

Definition at line 156 of file array2sh.h.

◆ ARRAY2SH_EVAL_STATUS

enum ARRAY2SH_EVAL_STATUS

Current status of the encoder evaluation output data.

These are some objective metrics which you can use to ascertain the performance of the microphone array and the encoding.

Enumerator
EVAL_STATUS_EVALUATED	Encoder has been evaluated.
EVAL_STATUS_RECENTLY_EVALUATED	Encoder has recently been evaluated.
EVAL_STATUS_NOT_EVALUATED	Encoder has not been evaluated.
EVAL_STATUS_EVALUATING	Encoder is being evaluated.

Examples: array2sh.h.

Definition at line 186 of file array2sh.h.

◆ ARRAY2SH_FILTER_TYPES

enum ARRAY2SH_FILTER_TYPES

Available encoding filter approaches.

See also: [1] Bernschutz, B., Porschmann, C., Spors, S., Weinzierl, S., Versterkung, B., 2011. Soft-limiting der modalen amplitudenverst?rkung bei sph?rischen mikrofonarrays im plane wave decomposition verfahren. Proceedings of the 37. Deutsche Jahrestagung fur Akustik (DAGA 2011); [2] Moreau, S., Daniel, J., Bertet, S., 2006, 3D sound field recording with higher order ambisonics-objective measurements and validation of spherical microphone. In Audio Engineering Society Convention 120.; [3] Zotter, F. A Linear-Phase Filter-Bank Approach to Process Rigid Spherical Microphone Array Recordings.

Enumerator
FILTER_SOFT_LIM	Encoding filters based on a 'soft-limiting' regularised inversion of the modal responses [1].
FILTER_TIKHONOV	Encoding filters based on a 'Tikhonov' regularised inversion of the modal responses [2].
FILTER_Z_STYLE	Encoding filters based on a linear-phase filter- bank approach [3].
FILTER_Z_STYLE_MAXRE	Same as FILTER_Z_STYLE, only it also has max_rE weights baked in.

Examples: array2sh.h.

Definition at line 134 of file array2sh.h.

◆ ARRAY2SH_MICROPHONE_ARRAY_PRESETS

enum ARRAY2SH_MICROPHONE_ARRAY_PRESETS

Available microphone array presets.

Examples: array2sh.h.

Definition at line 105 of file array2sh.h.

◆ ARRAY2SH_WEIGHT_TYPES

enum ARRAY2SH_WEIGHT_TYPES

List of supported sensor directivities and array construction types.

Enumerator
WEIGHT_RIGID_OMNI	Rigid baffle construction with omni sensors.
WEIGHT_RIGID_CARD	Rigid baffle construction with cardioid sensors.
WEIGHT_RIGID_DIPOLE	Rigid baffle construction with dipole sensors.
WEIGHT_OPEN_OMNI	Open array construction with omni sensors.
WEIGHT_OPEN_CARD	Open array construction with cardioid sensors.
WEIGHT_OPEN_DIPOLE	Open array construction with dipole sensors.

Examples: array2sh.h.

Definition at line 166 of file array2sh.h.

Function Documentation

◆ array2sh_create()

void array2sh_create ( void **const phA2sh )

Creates an instance of array2sh.

Parameters

[in] phA2sh (&) address of array2sh handle

Examples: array2sh.h.

Definition at line 52 of file array2sh.c.

◆ array2sh_destroy()

void array2sh_destroy ( void **const phA2sh )

Destroys an instance of array2sh.

Parameters

[in] phA2sh (&) address of array2sh handle

Examples: array2sh.h.

Definition at line 104 of file array2sh.c.

◆ array2sh_evalEncoder()

void array2sh_evalEncoder ( void *const hA2sh )

Evaluates the encoder, based on current global/user parameters.

Parameters

[in] hA2sh array2sh handle

Examples: array2sh.h.

Definition at line 161 of file array2sh.c.

◆ array2sh_getArrayType()

int array2sh_getArrayType ( void *const hA2sh )

Returns the type of array.

See ARRAY2SH_ARRAY_TYPES enum

Examples: array2sh.h.

Definition at line 630 of file array2sh.c.

◆ array2sh_getbN_inv()

float ** array2sh_getbN_inv	(	void *const	hA2sh,
		int *	nCurves,
		int *	nFreqPoints )

Returns the regularised inversion of the modal coefficients per frequency (may be used for optional plotting purposes)

Parameters

[in]	hA2sh	array2sh handle
[out]	nCurves	(&) number of equalisation curves (current_order+1)
[out]	nFreqPoints	(&) number of frequencies

Returns: Equalisation curves/regularised modal coefficients; nCurves x nFreqPoints

Examples: array2sh.h.

Definition at line 687 of file array2sh.c.

◆ array2sh_getbN_modal()

float ** array2sh_getbN_modal	(	void *const	hA2sh,
		int *	nCurves,
		int *	nFreqPoints )

Returns the direct inversion of the modal coefficients per frequency (may be used for optional plotting purposes)

Parameters

[in]	hA2sh	array2sh handle
[out]	nCurves	(&) number of equalisation curves (current_order+1)
[out]	nFreqPoints	(&) number of frequencies

Returns: Unregularised modal coefficients; nCurves x nFreqPoints

Examples: array2sh.h.

Definition at line 695 of file array2sh.c.

◆ array2sh_getc()

float array2sh_getc ( void *const hA2sh )

Returns the speed of sound of the medium (~343m/s air, ~1480m/s water), in m/s.

Examples: array2sh.h.

Definition at line 668 of file array2sh.c.

◆ array2sh_getChOrder()

int array2sh_getChOrder ( void *const hA2sh )

Returns the Ambisonic channel ordering convention currently being used to decode with, which should match the convention employed by the input signals (see CH_ORDER enum)

Examples: array2sh.h.

Definition at line 656 of file array2sh.c.

◆ array2sh_getDiffEQpastAliasing()

int array2sh_getDiffEQpastAliasing ( void *const hA2sh )

Flag to enabled/disable diffuse equalisation above the spatial aliasing limit of the array (0: disabled, 1: enabled).

Developed in collaboration with Archontis Politis.

Note: In general, theoretical encoding filters have a tendency to boost the aliased frequencies. Whereas, measurement-based filters (through a least-squares solution), tend to attenuate them. Neither of these are correct or incorrect, since, strictly (spatially) speaking, we should be placing a low-pass filter at the spatial aliasing frequency. However, since we usually do not want to remove this high frequency energy from e.g. an Ambisonic reproduction, we would argue that equalising the aliased components so that they have a flat spectrum, is probably the way to go; and is exactly what this feature does.

Examples: array2sh.h.

Definition at line 551 of file array2sh.c.

◆ array2sh_getEncodingOrder()

int array2sh_getEncodingOrder ( void *const hA2sh )

Returns the current encoding order (see SH_ORDERS enum)

Examples: array2sh.h.

Definition at line 557 of file array2sh.c.

◆ array2sh_getEvalStatus()

ARRAY2SH_EVAL_STATUS array2sh_getEvalStatus ( void *const hA2sh )

Returns current eval status (see ARRAY2SH_EVAL_STATUS enum)

Examples: array2sh.h.

Definition at line 521 of file array2sh.c.

◆ array2sh_getFilterType()

int array2sh_getFilterType ( void *const hA2sh )

Returns the type filter design to employ for computing the encoding matrices (see ARRAY2SH_FILTER_TYPES enum)

Examples: array2sh.h.

Definition at line 644 of file array2sh.c.

◆ array2sh_getFrameSize()

int array2sh_getFrameSize ( void )

Returns the processing framesize (i.e., number of samples processed with every _process() call )

Examples: array2sh.h.

Definition at line 516 of file array2sh.c.

◆ array2sh_getFreqVector()

float * array2sh_getFreqVector	(	void *const	hA2sh,
		int *	nFreqPoints )

Returns a pointer to the frequency vector.

Parameters

[in]	hA2sh	array2sh handle
[out]	nFreqPoints	(&) number of frequencies

Returns: Vector of centre frequencies; nFreqPoints x 1

Examples: array2sh.h.

Definition at line 680 of file array2sh.c.

◆ array2sh_getGain()

float array2sh_getGain ( void *const hA2sh )

Returns the amount of post gain to apply after the encoding, in DECIBELS.

Examples: array2sh.h.

Definition at line 674 of file array2sh.c.

◆ array2sh_getLevelDifference_Handle()

float * array2sh_getLevelDifference_Handle	(	void *const	hA2sh,
		int *	nCurves,
		int *	nFreqPoints )

Returns a pointer to the level-difference [1] data.

This is given per frequency, and is measure of the mean level difference between the encoded spherical harmonics using the current configuration is to ideal spherical harmonics

Note: This objective measure is based on analytical models of the currently configured array, and may differ in practice (i.e. with a real microphone array)

Parameters

[in]	hA2sh	array2sh handle
[out]	nCurves	(&) number of equalisation curves (current_order+1)
[out]	nFreqPoints	(&) number of frequencies

Returns: Level difference per order and frequency; FLAT: nCurves x nFreqPoints

See also: [1] Moreau, S., Daniel, J., Bertet, S., 2006, 3D sound field recording with higher order ambisonics-objective measurements and validation of spherical microphone. In Audio Engineering Society Convention 120.

Examples: array2sh.h.

Definition at line 711 of file array2sh.c.

◆ array2sh_getMaxNumSensors()

int array2sh_getMaxNumSensors ( void )

Returns the maximum supported number of sensors which can be in the array.

Examples: array2sh.h.

Definition at line 599 of file array2sh.c.

◆ array2sh_getMinNumSensors()

int array2sh_getMinNumSensors ( void *const hA2sh )

Returns the minimum number of sensors which can be in the array [(current_order+1)^2].

Examples: array2sh.h.

Definition at line 604 of file array2sh.c.

◆ array2sh_getNormType()

int array2sh_getNormType ( void *const hA2sh )

Returns the Ambisonic normalisation convention currently being usedto decode with, which should match the convention employed by the input signals (see NORM_TYPES enum)

Examples: array2sh.h.

Definition at line 662 of file array2sh.c.

◆ array2sh_getNSHrequired()

int array2sh_getNSHrequired ( void *const hA2sh )

Returns the number of spherical harmonic signals required by the current encoding order: (current_order+1)^2.

Examples: array2sh.h.

Definition at line 610 of file array2sh.c.

◆ array2sh_getNumSensors()

int array2sh_getNumSensors ( void *const hA2sh )

Returns the number of sensors in the array.

Examples: array2sh.h.

Definition at line 591 of file array2sh.c.

◆ array2sh_getProcessingDelay()

int array2sh_getProcessingDelay ( void )

Returns the processing delay in samples (may be used for delay compensation features)

Examples: array2sh.h.

Definition at line 725 of file array2sh.c.

◆ array2sh_getProgressBar0_1()

float array2sh_getProgressBar0_1 ( void *const hA2sh )

(Optional) Returns current intialisation/processing progress, between 0..1

0: intialisation/processing has started
1: intialisation/processing has ended

Examples: array2sh.h.

Definition at line 533 of file array2sh.c.

◆ array2sh_getProgressBarText()

void array2sh_getProgressBarText	(	void *const	hA2sh,
		char *	text )

(Optional) Returns current intialisation/processing progress text

Note: "text" string should be (at least) of length: PROGRESSBARTEXT_CHAR_LENGTH

Examples: array2sh.h.

Definition at line 539 of file array2sh.c.

◆ array2sh_getr()

float array2sh_getr ( void *const hA2sh )

Returns the radius of the array, in meters.

Examples: array2sh.h.

Definition at line 616 of file array2sh.c.

◆ array2sh_getR()

float array2sh_getR ( void *const hA2sh )

Returns the radius of the scatterer, in meters.

Examples: array2sh.h.

Definition at line 623 of file array2sh.c.

◆ array2sh_getRegPar()

float array2sh_getRegPar ( void *const hA2sh )

Returns the value of the regurlisation parameter; the maximum permitted gain provided by the filters, in DECIBELS.

Examples: array2sh.h.

Definition at line 650 of file array2sh.c.

◆ array2sh_getReinitSHTmatrixFLAG()

int array2sh_getReinitSHTmatrixFLAG ( void *const hA2sh )

Returns 0 if SHT is not be reinitialised, 1: if it is.

Examples: array2sh.h.

Definition at line 527 of file array2sh.c.

◆ array2sh_getRequestEncoderEvalFLAG()

int array2sh_getRequestEncoderEvalFLAG ( void *const hA2sh )

Returns a flag, which is '1' if there has been a recent request to evaluate the current encoding performance, or '0', if there hasn't.

Examples: array2sh.h.

Definition at line 545 of file array2sh.c.

◆ array2sh_getSamplingRate()

int array2sh_getSamplingRate ( void *const hA2sh )

Returns the DAW/Host sample rate.

Examples: array2sh.h.

Definition at line 719 of file array2sh.c.

◆ array2sh_getSensorAzi_deg()

float array2sh_getSensorAzi_deg	(	void *const	hA2sh,
		int	index )

Returns a particular sensor's azimuth w.r.t to the origin of the array, in DEGREES.

Examples: array2sh.h.

Definition at line 577 of file array2sh.c.

◆ array2sh_getSensorAzi_rad()

float array2sh_getSensorAzi_rad	(	void *const	hA2sh,
		int	index )

Returns a particular sensor's azimuth w.r.t to the origin of the array, in RADIANS.

Examples: array2sh.h.

Definition at line 563 of file array2sh.c.

◆ array2sh_getSensorElev_deg()

float array2sh_getSensorElev_deg	(	void *const	hA2sh,
		int	index )

Returns a particular sensor's elevation w.r.t to the origin of the array, in DEGREES.

Examples: array2sh.h.

Definition at line 584 of file array2sh.c.

◆ array2sh_getSensorElev_rad()

float array2sh_getSensorElev_rad	(	void *const	hA2sh,
		int	index )

Returns a particular sensor's elevation w.r.t to the origin of the array, in RADIANS.

Examples: array2sh.h.

Definition at line 570 of file array2sh.c.

◆ array2sh_getSpatialCorrelation_Handle()

float * array2sh_getSpatialCorrelation_Handle	(	void *const	hA2sh,
		int *	nCurves,
		int *	nFreqPoints )

Returns a pointer to the spatial correlation [1] data.

This is given per frequency, and is measure of how similar the encoded spherical harmonics using the current configuration is to ideal spherical harmonics. 1=perfect <1: less good/ aliasing

Note: This objective measure is based on analytical models of the currently configured array, and may differ in practice (i.e. with a real microphone array)

Parameters

[in]	hA2sh	array2sh handle
[out]	nCurves	(&) number of equalisation curves (current_order+1)
[out]	nFreqPoints	(&) number of frequencies

Returns: Spatial correlation per order and frequency; FLAT: nCurves x nFreqPoints

See also: [1] Moreau, S., Daniel, J., Bertet, S., 2006, 3D sound field recording with higher order ambisonics-objective measurements and validation of spherical microphone. In Audio Engineering Society Convention 120.

Examples: array2sh.h.

Definition at line 703 of file array2sh.c.

◆ array2sh_getWeightType()

int array2sh_getWeightType ( void *const hA2sh )

Returns the type of weights to use see ARRAY2SH_WEIGHT_TYPES enum.

Examples: array2sh.h.

Definition at line 637 of file array2sh.c.

◆ array2sh_init()

void array2sh_init	(	void *const	hA2sh,
		int	samplerate )

Initialises an instance of array2sh with default settings.

Parameters

[in]	hA2sh	array2sh handle
[in]	samplerate	Host samplerate.

Examples: array2sh.h.

Definition at line 148 of file array2sh.c.

◆ array2sh_process()

void array2sh_process	(	void *const	hA2sh,
		const float const	inputs,
		float const	outputs,
		int	nInputs,
		int	nOutputs,
		int	nSamples )

Spatially encode microphone/hydrophone array signals into spherical harmonic signals.

Parameters

[in]	hA2sh	array2sh handle
[in]	inputs	Input channel buffers; 2-D array: nInputs x nSamples
[in]	outputs	Output channel buffers; 2-D array: nOutputs x nSamples
[in]	nInputs	Number of input channels
[in]	nOutputs	Number of output channels
[in]	nSamples	Number of samples in 'inputs'/'output' matrices

Examples: array2sh.h.

Definition at line 185 of file array2sh.c.

◆ array2sh_refreshSettings()

void array2sh_refreshSettings ( void *const hA2sh )

Sets all intialisation flags to 1; re-initialising all settings/variables as array2sh is currently configured, at next available opportunity.

Examples: array2sh.h.

Definition at line 277 of file array2sh.c.

◆ array2sh_setArrayType()

void array2sh_setArrayType	(	void *const	hA2sh,
		int	newType )

Sets the type of array (see ARRAY2SH_ARRAY_TYPES enum)

Examples: array2sh.h.

Definition at line 436 of file array2sh.c.

◆ array2sh_setc()

void array2sh_setc	(	void *const	hA2sh,
		float	newc )

Sets the speed of sound of the medium (~343m/s air, ~1480m/s water), in m/s.

Examples: array2sh.h.

Definition at line 496 of file array2sh.c.

◆ array2sh_setChOrder()

void array2sh_setChOrder	(	void *const	hA2sh,
		int	newOrder )

Sets the Ambisonic channel ordering convention to encode with, in order to match the convention employed by the input signals (see CH_ORDER enum)

Examples: array2sh.h.

Definition at line 482 of file array2sh.c.

◆ array2sh_setDiffEQpastAliasing()

void array2sh_setDiffEQpastAliasing	(	void *const	hA2sh,
		int	newState )

Analyses what the theoretical spatial aliasing frequency is, and conducts diffuse-field equalisation above this (enable: 1, disable: 0).

Thanks to Dr. Archontis Politis for suggesting and designing this feature.

Examples: array2sh.h.

Definition at line 317 of file array2sh.c.

◆ array2sh_setEncodingOrder()

void array2sh_setEncodingOrder	(	void *const	hA2sh,
		int	newOrder )

Sets the encoding order (see SH_ORDERS enum)

Examples: array2sh.h.

Definition at line 284 of file array2sh.c.

◆ array2sh_setEvalStatus()

void array2sh_setEvalStatus	(	void *const	hA2sh,
		ARRAY2SH_EVAL_STATUS	evalStatus )

Sets current eval status (see ARRAY2SH_EVAL_STATUS enum)

Examples: array2sh.h.

Definition at line 306 of file array2sh.c.

◆ array2sh_setFilterType()

void array2sh_setFilterType	(	void *const	hA2sh,
		int	newType )

Sets the type filter design to employ for computing the encoding matrices (see ARRAY2SH_FILTER_TYPES enum)

Examples: array2sh.h.

Definition at line 460 of file array2sh.c.

◆ array2sh_setGain()

void array2sh_setGain	(	void *const	hA2sh,
		float	newGain )

Sets the amount of post gain to apply after the encoding, in DECIBELS.

Examples: array2sh.h.

Definition at line 507 of file array2sh.c.

◆ array2sh_setNormType()

void array2sh_setNormType	(	void *const	hA2sh,
		int	newType )

Sets the Ambisonic normalisation convention to encode with, in order to match with the convention employed by the input signals (see NORM_TYPES enum)

Examples: array2sh.h.

Definition at line 489 of file array2sh.c.

◆ array2sh_setNumSensors()

void array2sh_setNumSensors	(	void *const	hA2sh,
		int	newQ )

Sets the number of sensors in the array.

Examples: array2sh.h.

Definition at line 391 of file array2sh.c.

◆ array2sh_setPreset()

void array2sh_setPreset	(	void *const	hA2sh,
		ARRAY2SH_MICROPHONE_ARRAY_PRESETS	preset )

Sets a pre-defined microphone/hydrophone array preset (See ARRAY2SH_MICROPHONE_ARRAY_PRESETS enum)

Examples: array2sh.h.

Definition at line 327 of file array2sh.c.

◆ array2sh_setr()

void array2sh_setr	(	void *const	hA2sh,
		float	newr )

Sets the radius of the array.

Examples: array2sh.h.

Definition at line 410 of file array2sh.c.

◆ array2sh_setR()

void array2sh_setR	(	void *const	hA2sh,
		float	newR )

Sets the radius (in meters) of the scatterer (only for Rigid arrays).

Note: R <= r. i.e. the sensors may protrude from the rigid scattering surface, or be flush with the surface of the array

Examples: array2sh.h.

Definition at line 423 of file array2sh.c.

◆ array2sh_setRegPar()

void array2sh_setRegPar	(	void *const	hA2sh,
		float	newVal )

Sets the value of the regularisation parameter (the maximum permitted gain of the filters), in DECIBELS.

Examples: array2sh.h.

Definition at line 471 of file array2sh.c.

◆ array2sh_setRequestEncoderEvalFLAG()

void array2sh_setRequestEncoderEvalFLAG	(	void *const	hA2sh,
		int	newState )

Evaluates the performance of the current encoding filters when applied to a theoretical model of the currently configured array; two established objective metrics are then computed; more information in [1].

See also: [1] Moreau, S., Daniel, J., Bertet, S., 2006, 3D sound field recording with higher order ambisonics-objective measurements and validation of spherical microphone. In Audio Engineering Society Convention 120.

Examples: array2sh.h.

Definition at line 300 of file array2sh.c.

◆ array2sh_setSensorAzi_deg()

void array2sh_setSensorAzi_deg	(	void *const	hA2sh,
		int	index,
		float	newAzi_deg )

Sets a particular sensor's azimuth (degrees) w.r.t to the origin of the array.

Input Arguments: hA2sh - array2sh handle index - sensor index newAzi_deg - sensor azimuth in DEGREES

Examples: array2sh.h.

Definition at line 364 of file array2sh.c.

◆ array2sh_setSensorAzi_rad()

void array2sh_setSensorAzi_rad	(	void *const	hA2sh,
		int	index,
		float	newAzi_rad )

Sets a particular sensor's azimuth (radians) w.r.t to the origin of the array.

Parameters

[in]	hA2sh	array2sh handle
[in]	index	Sensor index
[in]	newAzi_rad	Sensor azimuth in RADIANS

Examples: array2sh.h.

Definition at line 338 of file array2sh.c.

◆ array2sh_setSensorElev_deg()

void array2sh_setSensorElev_deg	(	void *const	hA2sh,
		int	index,
		float	newElev_deg )

Sets a particular sensor's elevation (degrees) w.r.t to the origin of the array.

Parameters

[in]	hA2sh	array2sh handle
[in]	index	Sensor index
[in]	newElev_deg	Sensor elevation in DEGREES

Examples: array2sh.h.

Definition at line 378 of file array2sh.c.

◆ array2sh_setSensorElev_rad()

void array2sh_setSensorElev_rad	(	void *const	hA2sh,
		int	index,
		float	newElev_rad )

Sets a particular sensor's elevation (radians) w.r.t to the origin of the array.

Parameters

[in]	hA2sh	array2sh handle
[in]	index	Sensor index
[in]	newElev_rad	Sensor elevation in RADIANS

Examples: array2sh.h.

Definition at line 351 of file array2sh.c.

◆ array2sh_setWeightType()

void array2sh_setWeightType	(	void *const	hA2sh,
		int	newType )

Sets the type of weights to use (see ARRAY2SH_WEIGHT_TYPES enum)

Examples: array2sh.h.

Definition at line 448 of file array2sh.c.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ARRAY2SH_ARRAY_RADIUS_MAX_VALUE

◆ ARRAY2SH_ARRAY_RADIUS_MIN_VALUE

◆ ARRAY2SH_BAFFLE_RADIUS_MAX_VALUE

◆ ARRAY2SH_BAFFLE_RADIUS_MIN_VALUE

◆ ARRAY2SH_MAX_GAIN_MAX_VALUE

◆ ARRAY2SH_MAX_GAIN_MIN_VALUE

◆ ARRAY2SH_MAX_NUM_SENSORS

◆ ARRAY2SH_NUM_ARRAY_TYPES

◆ ARRAY2SH_NUM_FILTER_TYPES

◆ ARRAY2SH_NUM_WEIGHT_TYPES

◆ ARRAY2SH_POST_GAIN_MAX_VALUE

◆ ARRAY2SH_POST_GAIN_MIN_VALUE

◆ ARRAY2SH_SPEED_OF_SOUND_MAX_VALUE

◆ ARRAY2SH_SPEED_OF_SOUND_MIN_VALUE

Enumeration Type Documentation

◆ ARRAY2SH_ARRAY_TYPES

◆ ARRAY2SH_EVAL_STATUS

◆ ARRAY2SH_FILTER_TYPES

◆ ARRAY2SH_MICROPHONE_ARRAY_PRESETS

◆ ARRAY2SH_WEIGHT_TYPES

Function Documentation

◆ array2sh_create()

◆ array2sh_destroy()

◆ array2sh_evalEncoder()

◆ array2sh_getArrayType()

◆ array2sh_getbN_inv()

◆ array2sh_getbN_modal()

◆ array2sh_getc()

◆ array2sh_getChOrder()

◆ array2sh_getDiffEQpastAliasing()

◆ array2sh_getEncodingOrder()

◆ array2sh_getEvalStatus()

◆ array2sh_getFilterType()

◆ array2sh_getFrameSize()

◆ array2sh_getFreqVector()

◆ array2sh_getGain()

◆ array2sh_getLevelDifference_Handle()

◆ array2sh_getMaxNumSensors()

◆ array2sh_getMinNumSensors()

◆ array2sh_getNormType()

◆ array2sh_getNSHrequired()

◆ array2sh_getNumSensors()

◆ array2sh_getProcessingDelay()

◆ array2sh_getProgressBar0_1()

◆ array2sh_getProgressBarText()

◆ array2sh_getr()

◆ array2sh_getR()

◆ array2sh_getRegPar()

◆ array2sh_getReinitSHTmatrixFLAG()

◆ array2sh_getRequestEncoderEvalFLAG()

◆ array2sh_getSamplingRate()

◆ array2sh_getSensorAzi_deg()

◆ array2sh_getSensorAzi_rad()

◆ array2sh_getSensorElev_deg()

◆ array2sh_getSensorElev_rad()

◆ array2sh_getSpatialCorrelation_Handle()

◆ array2sh_getWeightType()

◆ array2sh_init()

◆ array2sh_process()

◆ array2sh_refreshSettings()

◆ array2sh_setArrayType()

◆ array2sh_setc()

◆ array2sh_setChOrder()

◆ array2sh_setDiffEQpastAliasing()

◆ array2sh_setEncodingOrder()

◆ array2sh_setEvalStatus()

◆ array2sh_setFilterType()

◆ array2sh_setGain()

◆ array2sh_setNormType()

◆ array2sh_setNumSensors()

◆ array2sh_setPreset()

◆ array2sh_setr()

◆ array2sh_setR()

◆ array2sh_setRegPar()

◆ array2sh_setRequestEncoderEvalFLAG()