sldoa.h File Reference

A spatially-localised active-intensity (SLAI) based direction-of- arrival estimator (SLDoA) More...

#include "_common.h"

Go to the source code of this file.

Functions
void	sldoa_create (void **const phSld)
	Creates an instance of the sldoa.
void	sldoa_destroy (void **const phSld)
	Destroys an instance of the sldoa.
void	sldoa_init (void *const hSld, float samplerate)
	Initialises an instance of sldoa with default settings.
void	sldoa_initCodec (void *const hSld)
	Intialises the codec variables, based on current global/user parameters.
void	sldoa_analysis (void *const hSld, const float *const *inputs, int nInputs, int nSamples, int isPlaying)
	Applies the spatially-localised active-intensity based direction-of-arrival estimator (SLDoA) onto the input signals [1,2].
void	sldoa_setMasterOrder (void *const hSld, int newValue)
	Sets the maximum input/analysis order (see SH_ORDERS enum)
void	sldoa_refreshSettings (void *const hSld)
	Sets all intialisation flags to 1; re-initialising all settings/variables as sldoa is currently configured, at next available opportunity.
void	sldoa_setMaxFreq (void *const hSld, float newFreq)
	Sets the maximum analysis frequency, in Hz.
void	sldoa_setMinFreq (void *const hSld, float newFreq)
	Sets the minimum analysis frequency, in Hz.
void	sldoa_setAvg (void *const hSld, float newAvg)
	Sets the DoA averaging coefficient, 0..1.
void	sldoa_setAnaOrder (void *const hSld, int newValue, int bandIdx)
	Sets the input/analysis order for one specific frequency band.
void	sldoa_setAnaOrderAllBands (void *const hSld, int newValue)
	Sets the input/analysis order for all frequency bands.
void	sldoa_setChOrder (void *const hSld, int newOrder)
	Sets the Ambisonic channel ordering convention to decode with, in order to match the convention employed by the input signals (see CH_ORDER enum)
void	sldoa_setNormType (void *const hSld, int newType)
	Sets the Ambisonic normalisation convention to decode with, in order to match with the convention employed by the input signals (see NORM_TYPES enum)
void	sldoa_setSourcePreset (void *const hSld, int newPresetID)
	Sets an input preset, the microphone/hyrophone array used to capture the input signals (see MIC_PRESETS enum)
int	sldoa_getFrameSize (void)
	Returns the processing framesize (i.e., number of samples processed with every _process() call )
CODEC_STATUS	sldoa_getCodecStatus (void *const hSld)
	Returns current codec status (see CODEC_STATUS enum)
float	sldoa_getProgressBar0_1 (void *const hSld)
	(Optional) Returns current intialisation/processing progress, between 0..1
void	sldoa_getProgressBarText (void *const hSld, char *text)
	(Optional) Returns current intialisation/processing progress text
int	sldoa_getMasterOrder (void *const hSld)
	Returns the current maximum analysis/input order (see SH_ORDERS enum)
int	sldoa_getSamplingRate (void *const hSld)
	Returns the current sampling rate, in Hz.
float	sldoa_getMaxFreq (void *const hSld)
	Returns the maximum analysis frequency, in Hz.
float	sldoa_getMinFreq (void *const hSld)
	Returns the minimum analysis frequency, in Hz.
float	sldoa_getAvg (void *const hSld)
	Returns the current DoA averaging coefficient value, 0..1.
int	sldoa_getNumberOfBands (void)
	Returns the number frequency bands employed by sldoa.
int	sldoa_getNSHrequired (void *const hSld)
	Returns the number of spherical harmonic signals required by the current analysis order: (current_order + 1)^2.
void	sldoa_getDisplayData (void *const hSld, float **pAzi_deg, float **pElev_deg, float **pColourScale, float **pAlphaScale, int **pNsectorsPerBand, int *pMaxNumSectors, int *pStartBand, int *pEndBand)
	Returns the analysis output data.
int	sldoa_getAnaOrder (void *const hSld, int bandIdx)
	Returns the input/analysis order for one specific frequency band.
int	sldoa_getAnaOrderAllBands (void *const hSld)
	Returns the input/analysis order for the first frequency band.
void	sldoa_getAnaOrderHandle (void *const hSld, float **pX_vector, int **pY_values, int *pNpoints)
	Returns the input/analysis order for all frequency bands.
int	sldoa_getChOrder (void *const hSld)
	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	sldoa_getNormType (void *const hSld)
	Returns the Ambisonic normalisation convention currently being usedto decode with, which should match the convention employed by the input signals.
int	sldoa_getProcessingDelay (void)
	Returns the processing delay in samples (may be used for delay compensation features)

Detailed Description

A spatially-localised active-intensity (SLAI) based direction-of- arrival estimator (SLDoA)

VBAP gain patterns are imposed on the spherical harmonic signals, such that the DoA can be estimated in a spatially-constrained region; thus mitigating the effect of interferes and reflections arriving from other directions. The DoA is estimated per sector for each frequency band.

The algorithms within sldoa were developed in collaboration with Symeon Delikaris-Manias and Angelo Farina, and are explained in more detail in [1,2]

See also

[1] McCormack, L., Delikaris-Manias, S., Politis, A., Pavlidi, D., Farina, A., Pinardi, D. and Pulkki, V., 2019. Applications of Spatially Localized Active-Intensity Vectors for Sound-Field Visualization. Journal of the Audio Engineering Society, 67(11), pp.840-854.

[2] 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.

Author

Leo McCormack

Date

18.10.2017

License

ISC

Definition in file sldoa.h.

Function Documentation

sldoa_analysis()

void sldoa_analysis	(	void *const	hSld,
		const float *const *	inputs,
		int	nInputs,
		int	nSamples,
		int	isPlaying )

Applies the spatially-localised active-intensity based direction-of-arrival estimator (SLDoA) onto the input signals [1,2].

Parameters

[in]	hSld	sldoa handle
[in]	inputs	Input channel buffers; 2-D array: nInputs x nSamples
[in]	nInputs	Number of input channels
[in]	nSamples	Number of samples in 'inputs'/'output' matrices
[in]	isPlaying	Flag to say if there is audio in the damn input buffers, 0: no audio, reduced processing, 1: audio, full processing

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] McCormack, L., Delikaris-Manias, S., Politis, A., Pavlidi, D., Farina, A., Pinardi, D. and Pulkki, V., 2019. Applications of Spatially Localized Active-Intensity Vectors for Sound-Field Visualization. Journal of the Audio Engineering Society, 67(11), pp.840-854.

Examples

sldoa.h.

Definition at line 205 of file sldoa.c.

sldoa_create()

void sldoa_create

(

void **const

phSld

)

Creates an instance of the sldoa.

Parameters

[in]

phSld

(&) address of sldoa handle

Examples

sldoa.h.

Definition at line 49 of file sldoa.c.

sldoa_destroy()

void sldoa_destroy

(

void **const

phSld

)

Destroys an instance of the sldoa.

Parameters

[in]

phSld

(&) address of sldoa handle

Examples

sldoa.h.

Definition at line 109 of file sldoa.c.

sldoa_getAnaOrder()

int sldoa_getAnaOrder	(	void *const	hSld,
		int	bandIdx )

Returns the input/analysis order for one specific frequency band.

Examples

sldoa.h.

Definition at line 595 of file sldoa.c.

sldoa_getAnaOrderAllBands()

int sldoa_getAnaOrderAllBands

(

void *const

hSld

)

Returns the input/analysis order for the first frequency band.

Examples

sldoa.h.

Definition at line 601 of file sldoa.c.

sldoa_getAnaOrderHandle()

void sldoa_getAnaOrderHandle	(	void *const	hSld,
		float **	pX_vector,
		int **	pY_values,
		int *	pNpoints )

Returns the input/analysis order for all frequency bands.

Parameters

[in]	hSld	sldoa handle
[out]	pX_vector	(&) frequency vector; pNpoints x 1
[out]	pY_values	(&) input/analysis orders; pNpoints x 1
[out]	pNpoints	(&) number of frequency bands

Examples

sldoa.h.

Definition at line 607 of file sldoa.c.

sldoa_getAvg()

float sldoa_getAvg

(

void *const

hSld

)

Returns the current DoA averaging coefficient value, 0..1.

Examples

sldoa.h.

Definition at line 552 of file sldoa.c.

sldoa_getChOrder()

int sldoa_getChOrder

(

void *const

hSld

)

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

sldoa.h.

Definition at line 632 of file sldoa.c.

sldoa_getCodecStatus()

CODEC_STATUS sldoa_getCodecStatus

(

void *const

hSld

)

Returns current codec status (see CODEC_STATUS enum)

Examples

sldoa.h.

Definition at line 510 of file sldoa.c.

sldoa_getDisplayData()

void sldoa_getDisplayData	(	void *const	hSld,
		float **	pAzi_deg,
		float **	pElev_deg,
		float **	pColourScale,
		float **	pAlphaScale,
		int **	pNsectorsPerBand,
		int *	pMaxNumSectors,
		int *	pStartBand,
		int *	pEndBand )

Returns the analysis output data.

Including the DoAs per frequency, and per sector, accompanied by colour coefficients (red: high frequencies, blue: low frequencies), and alpha coefficients (more opaque: higher energy, more transpararent: less energy).

Note

nBands can be found by using sldoa_getNumberOfBands()

Parameters

[in]	hSld	sldoa handle
[out]	pAzi_deg	(&) azimuth of estimated DoAs; FLAT: pNsectorsPerBand x nBands
[out]	pElev_deg	(&) elevation of estimated DoAs; FLAT: pNsectorsPerBand x nBands
[out]	pColourScale	(&) colour scale, 0..1, 1:red, 0: blue FLAT: pNsectorsPerBand x nBands
[out]	pAlphaScale	(&) alpha scale, 0..1, 1: opaque, 0: transparent FLAT: pNsectorsPerBand x nBands
[out]	pNsectorsPerBand	(&) number of sectors per frequency; pNsectorsPerBand x 1
[out]	pMaxNumSectors	(&) maximum number of sectors
[out]	pStartBand	(&) band index corresponding to lowest frequency
[out]	pEndBand	(&) band index corresponding to highest frequency

Examples

sldoa.h.

Definition at line 559 of file sldoa.c.

sldoa_getFrameSize()

int sldoa_getFrameSize

(

void

)

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

Examples

sldoa.h.

Definition at line 505 of file sldoa.c.

sldoa_getMasterOrder()

int sldoa_getMasterOrder

(

void *const

hSld

)

Returns the current maximum analysis/input order (see SH_ORDERS enum)

Examples

sldoa.h.

Definition at line 528 of file sldoa.c.

sldoa_getMaxFreq()

float sldoa_getMaxFreq

(

void *const

hSld

)

Returns the maximum analysis frequency, in Hz.

Examples

sldoa.h.

Definition at line 540 of file sldoa.c.

sldoa_getMinFreq()

float sldoa_getMinFreq

(

void *const

hSld

)

Returns the minimum analysis frequency, in Hz.

Examples

sldoa.h.

Definition at line 546 of file sldoa.c.

sldoa_getNormType()

int sldoa_getNormType

(

void *const

hSld

)

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

sldoa.h.

Definition at line 638 of file sldoa.c.

sldoa_getNSHrequired()

int sldoa_getNSHrequired

(

void *const

hSld

)

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

Examples

sldoa.h.

Definition at line 626 of file sldoa.c.

sldoa_getNumberOfBands()

int sldoa_getNumberOfBands

(

void

)

Returns the number frequency bands employed by sldoa.

Examples

sldoa.h.

Definition at line 621 of file sldoa.c.

sldoa_getProcessingDelay()

int sldoa_getProcessingDelay

(

void

)

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

Examples

sldoa.h.

Definition at line 644 of file sldoa.c.

sldoa_getProgressBar0_1()

float sldoa_getProgressBar0_1

(

void *const

hSld

)

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

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

Examples

sldoa.h.

Definition at line 516 of file sldoa.c.

sldoa_getProgressBarText()

void sldoa_getProgressBarText	(	void *const	hSld,
		char *	text )

(Optional) Returns current intialisation/processing progress text

Note

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

Examples

sldoa.h.

Definition at line 522 of file sldoa.c.

sldoa_getSamplingRate()

int sldoa_getSamplingRate

(

void *const

hSld

)

Returns the current sampling rate, in Hz.

Examples

sldoa.h.

Definition at line 534 of file sldoa.c.

sldoa_init()

void sldoa_init	(	void *const	hSld,
		float	samplerate )

Initialises an instance of sldoa with default settings.

Warning

This should not be called while _process() is on-going!

Parameters

[in]	hSld	sldoa handle
[in]	samplerate	Host samplerate.

Examples

sldoa.h.

Definition at line 150 of file sldoa.c.

sldoa_initCodec()

void sldoa_initCodec

(

void *const

hSld

)

Intialises the codec variables, based on current global/user parameters.

Note

This function is fully threadsafe. It can even be called periodically via a timer on one thread, while calling _process() on another thread. Since, if a set function is called (that warrants a re-init), then a flag is triggered internally and the next time this function is called, it will wait until the current process() function has completed before reinitialising the relevant parameters. If the _initCodec() takes longer than the time it takes for process() to be called again, then process() is simply bypassed until the codec is ready.

This function does nothing if no re-initialisations are required.

Parameters

[in]

hSld

- sldoa handle

Examples

sldoa.h.

Definition at line 176 of file sldoa.c.

sldoa_refreshSettings()

void sldoa_refreshSettings

(

void *const

hSld

)

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

Examples

sldoa.h.

Definition at line 372 of file sldoa.c.

sldoa_setAnaOrder()

void sldoa_setAnaOrder	(	void *const	hSld,
		int	newValue,
		int	bandIdx )

Sets the input/analysis order for one specific frequency band.

Examples

sldoa.h.

Definition at line 470 of file sldoa.c.

sldoa_setAnaOrderAllBands()

void sldoa_setAnaOrderAllBands	(	void *const	hSld,
		int	newValue )

Sets the input/analysis order for all frequency bands.

Examples

sldoa.h.

Definition at line 477 of file sldoa.c.

sldoa_setAvg()

void sldoa_setAvg	(	void *const	hSld,
		float	newAvg )

Sets the DoA averaging coefficient, 0..1.

Examples

sldoa.h.

Definition at line 395 of file sldoa.c.

sldoa_setChOrder()

void sldoa_setChOrder	(	void *const	hSld,
		int	newOrder )

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

Examples

sldoa.h.

Definition at line 488 of file sldoa.c.

sldoa_setMasterOrder()

void sldoa_setMasterOrder	(	void *const	hSld,
		int	newValue )

Sets the maximum input/analysis order (see SH_ORDERS enum)

Examples

sldoa.h.

Definition at line 358 of file sldoa.c.

sldoa_setMaxFreq()

void sldoa_setMaxFreq	(	void *const	hSld,
		float	newFreq )

Sets the maximum analysis frequency, in Hz.

Examples

sldoa.h.

Definition at line 377 of file sldoa.c.

sldoa_setMinFreq()

void sldoa_setMinFreq	(	void *const	hSld,
		float	newFreq )

Sets the minimum analysis frequency, in Hz.

Examples

sldoa.h.

Definition at line 386 of file sldoa.c.

sldoa_setNormType()

void sldoa_setNormType	(	void *const	hSld,
		int	newType )

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

Examples

sldoa.h.

Definition at line 495 of file sldoa.c.

sldoa_setSourcePreset()

void sldoa_setSourcePreset	(	void *const	hSld,
		int	newPresetID )

Sets an input preset, the microphone/hyrophone array used to capture the input signals (see MIC_PRESETS enum)

Examples

sldoa.h.

Definition at line 401 of file sldoa.c.