A sound-field visualiser, which utilises spherical harmonic signals as input; note this code is a remnant from the work conducted in [1]. More...

#include "_common.h"

Enumerations
enum	POWERMAP_MODES { PM_MODE_PWD = 1 , PM_MODE_MVDR , PM_MODE_CROPAC_LCMV , PM_MODE_MUSIC , PM_MODE_MUSIC_LOG , PM_MODE_MINNORM , PM_MODE_MINNORM_LOG }
	Available power-map/activity-map options. More...

Functions
void	powermap_create (void **const phPm)
	Creates an instance of the powermap.

void	powermap_destroy (void **const phPm)
	Destroys an instance of the powermap.

void	powermap_init (void *const hPm, float samplerate)
	Initialises an instance of powermap with default settings.

void	powermap_initCodec (void *const hPm)
	Intialises the codec variables, based on current global/user parameters.

void	powermap_analysis (void const hPm, const float const *inputs, int nInputs, int nSamples, int isPlaying)
	Analyses the input spherical harmonic signals to generate an activity-map.

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

void	powermap_setPowermapMode (void *const hPm, int newMode)
	Sets the powermap/activity-map approach, (see POWERMAP_MODES enum)

void	powermap_setMasterOrder (void *const hPm, int newValue)
	Sets the maximum input/analysis order (see SH_ORDERS enum)

void	powermap_setAnaOrder (void *const hPm, int newValue, int bandIdx)
	Sets the input/analysis order for one specific frequency band index.

void	powermap_setAnaOrderAllBands (void *const hPm, int newValue)
	Sets the input/analysis order for all frequency bands.

void	powermap_setPowermapEQ (void *const hPm, float newValue, int bandIdx)
	Sets the weighting coefficient for a particular frequency band, allowing one to "equalise" the activity-map.

void	powermap_setPowermapEQAllBands (void *const hPm, float newValue)
	Sets the weighting coefficient for all frequency bands.

void	powermap_setCovAvgCoeff (void *const hPm, float newAvg)
	Sets the covariance matrix averaging coefficient, 0..1.

void	powermap_setChOrder (void *const hPm, 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	powermap_setNormType (void *const hPm, 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	powermap_setSourcePreset (void *const hPm, int newPresetID)
	Sets an input preset; the microphone/hyrophone array used to capture the input signals, (see MIC_PRESETS enum)

void	powermap_setNumSources (void *const hPm, int newValue)
	Sets the number of sources present in the input sound scene.

void	powermap_setDispFOV (void *const hPm, int newOption)
	Sets the visualisation display window horizontal field-of-view (FOV) (see HFOV_OPTIONS enum)

void	powermap_setAspectRatio (void *const hPm, int newOption)
	Sets the visualisation display window aspect-ratio (see ASPECT_RATIO_OPTIONS enum)

void	powermap_setPowermapAvgCoeff (void *const hPm, float newValue)
	Sets the activity-map averaging coefficient, 0..1.

void	powermap_requestPmapUpdate (void *const hPm)
	Informs powermap that it should compute a new activity-map at its own convenience, if it would be so kind; thank you, God bless.

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

CODEC_STATUS	powermap_getCodecStatus (void *const hPm)
	Returns current codec status (see CODEC_STATUS enum)

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

void	powermap_getProgressBarText (void const hPm, char text)
	(Optional) Returns current intialisation/processing progress text

int	powermap_getMasterOrder (void *const hPm)
	Returns the current maximum analysis/input order (see SH_ORDERS enum)

int	powermap_getPowermapMode (void *const hPm)
	Returns the powermap/activity-map mode to employed for the analysis see POWERMAP_MODES enum.

int	powermap_getSamplingRate (void *const hPm)
	Returns the current sampling rate, in Hz.

float	powermap_getCovAvgCoeff (void *const hPm)
	Returns the current covariance averaging coefficient value, in Hz.

int	powermap_getNumberOfBands (void)
	Returns the number of frequency bands used for the analysis.

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

float	powermap_getPowermapEQ (void *const hPm, int bandIdx)
	Returns the weighting coefficient for a particular frequency band index, allowing one to "equalise" the activity-map.

float	powermap_getPowermapEQAllBands (void *const hPm)
	Returns the weighting coefficient for the first frequency band.

void	powermap_getPowermapEQHandle (void const hPm, float pX_vector, float pY_values, int pNpoints)
	Returns the weighting coefficient for all frequency bands.

int	powermap_getAnaOrder (void *const hPm, int bandIdx)
	Returns the input/analysis order for one specific frequency band.

int	powermap_getAnaOrderAllBands (void *const hPm)
	Returns the input/analysis order for the first frequency band.

void	powermap_getAnaOrderHandle (void const hPm, float pX_vector, int pY_values, int pNpoints)
	Returns the input/analysis order for all frequency bands.

int	powermap_getChOrder (void *const hPm)
	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	powermap_getNormType (void *const hPm)
	Returns the Ambisonic normalisation convention currently being usedto decode with, which should match the convention employed by the input signals (see NORM_TYPES enum)

int	powermap_getNumSources (void *const hPm)
	Returns the number of sources present in the input sound scene.

int	powermap_getDispFOV (void *const hPm)
	Returns the current visualisation display window horizontal field-of-view (FOV) (see HFOV_OPTIONS enum)

int	powermap_getAspectRatio (void *const hPm)
	Returns the current visualisation display window aspect-ratio (see ASPECT_RATIO_OPTIONS enum)

float	powermap_getPowermapAvgCoeff (void *const hPm)
	Returns the current activity-map averaging coefficient, 0..1.

int	powermap_getPmap (void const hPm, float grid_dirs, float pmap, int nDirs, int pmapWidth, int hfov, int *aspectRatio)
	Returns the latest computed activity-map if it is ready.

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

Detailed Description

A sound-field visualiser, which utilises spherical harmonic signals as input; note this code is a remnant from the work conducted in [1].

See also: [1] McCormack, L., Delikaris-Manias, S. and Pulkki, V., 2017. Parametric acoustic camera for real-time sound capture, analysis and tracking. In Proceedings of the 20th International Conference on Digital Audio Effects (DAFx-17) (pp. 412-419)

Author: Leo McCormack

Date: 26.04.2016

License: ISC

Definition in file powermap.h.

Enumeration Type Documentation

◆ POWERMAP_MODES

enum POWERMAP_MODES

Available power-map/activity-map options.

Enumerator
PM_MODE_PWD	Activity-map based on the energy of hyper-cardioid [plane-wave decomposition (PWD)] beamformers.
PM_MODE_MVDR	Activity-map based on the energy of minimum- variance distortionless response (MVDR) beamformers.
PM_MODE_CROPAC_LCMV	Experimental! activity-map based on a linearly- contrained minimum-variance (LCMV) formulation of the Cross-Pattern Coherence (CroPaC) spatial filter
PM_MODE_MUSIC	Activity-map based on the sub-space method: multiple signal classification (MUSIC)
PM_MODE_MUSIC_LOG	Same as PM_MODE_MUSIC, but log(out_values)
PM_MODE_MINNORM	Activity-map based on the sub-space method: minimum-norm (Min-Norm)
PM_MODE_MINNORM_LOG	Same as PM_MODE_MINNORM, but log(out_values)

Definition at line 58 of file powermap.h.

Function Documentation

◆ powermap_analysis()

void powermap_analysis	(	void *const	hPm,
		const float const	inputs,
		int	nInputs,
		int	nSamples,
		int	isPlaying )

Analyses the input spherical harmonic signals to generate an activity-map.

Parameters

[in]	hPm	powermap 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 input buffers, 0: no audio, reduced processing, 1: audio, full processing

Examples: powermap.h.

Definition at line 188 of file powermap.c.

◆ powermap_create()

void powermap_create ( void **const phPm )

Creates an instance of the powermap.

Parameters

[in] phPm (&) address of powermap handle

Examples: powermap.h.

Definition at line 35 of file powermap.c.

◆ powermap_destroy()

void powermap_destroy ( void **const phPm )

Destroys an instance of the powermap.

Parameters

[in] phPm (&) address of powermap handle

Examples: powermap.h.

Definition at line 96 of file powermap.c.

◆ powermap_getAnaOrder()

int powermap_getAnaOrder	(	void *const	hPm,
		int	bandIdx )

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

Examples: powermap.h.

Definition at line 649 of file powermap.c.

◆ powermap_getAnaOrderAllBands()

int powermap_getAnaOrderAllBands ( void *const hPm )

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

Examples: powermap.h.

Definition at line 655 of file powermap.c.

◆ powermap_getAnaOrderHandle()

void powermap_getAnaOrderHandle	(	void *const	hPm,
		float **	pX_vector,
		int **	pY_values,
		int *	pNpoints )

Returns the input/analysis order for all frequency bands.

Parameters

[in]	hPm	powermap 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: powermap.h.

Definition at line 661 of file powermap.c.

◆ powermap_getAspectRatio()

int powermap_getAspectRatio ( void *const hPm )

Returns the current visualisation display window aspect-ratio (see ASPECT_RATIO_OPTIONS enum)

Examples: powermap.h.

Definition at line 710 of file powermap.c.

◆ powermap_getChOrder()

int powermap_getChOrder ( void *const hPm )

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

Definition at line 686 of file powermap.c.

◆ powermap_getCodecStatus()

CODEC_STATUS powermap_getCodecStatus ( void *const hPm )

Returns current codec status (see CODEC_STATUS enum)

Examples: powermap.h.

Definition at line 581 of file powermap.c.

◆ powermap_getCovAvgCoeff()

float powermap_getCovAvgCoeff ( void *const hPm )

Returns the current covariance averaging coefficient value, in Hz.

Examples: powermap.h.

Definition at line 617 of file powermap.c.

◆ powermap_getDispFOV()

int powermap_getDispFOV ( void *const hPm )

Returns the current visualisation display window horizontal field-of-view (FOV) (see HFOV_OPTIONS enum)

Examples: powermap.h.

Definition at line 704 of file powermap.c.

◆ powermap_getFrameSize()

int powermap_getFrameSize ( void )

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

Examples: powermap.h.

Definition at line 576 of file powermap.c.

◆ powermap_getMasterOrder()

int powermap_getMasterOrder ( void *const hPm )

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

Examples: powermap.h.

Definition at line 599 of file powermap.c.

◆ powermap_getNormType()

int powermap_getNormType ( void *const hPm )

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

Definition at line 692 of file powermap.c.

◆ powermap_getNSHrequired()

int powermap_getNSHrequired ( void *const hPm )

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

Examples: powermap.h.

Definition at line 680 of file powermap.c.

◆ powermap_getNumberOfBands()

int powermap_getNumberOfBands ( void )

Returns the number of frequency bands used for the analysis.

Examples: powermap.h.

Definition at line 675 of file powermap.c.

◆ powermap_getNumSources()

int powermap_getNumSources ( void *const hPm )

Returns the number of sources present in the input sound scene.

Examples: powermap.h.

Definition at line 698 of file powermap.c.

◆ powermap_getPmap()

int powermap_getPmap	(	void *const	hPm,
		float **	grid_dirs,
		float **	pmap,
		int *	nDirs,
		int *	pmapWidth,
		int *	hfov,
		int *	aspectRatio )

Returns the latest computed activity-map if it is ready.

Otherwise it returns 0, and you'll just have to wait a bit

Parameters

[in]	hPm	powermap handle
[out]	grid_dirs	(&) scanning grid directions, in DEGREES; nDirs x 1
[out]	pmap	(&) activity-map values; nDirs x 1
[out]	nDirs	(&) number of directions
[out]	pmapWidth	(&) activity-map width in pixels
[out]	hfov	(&) horizontal FOV used to generate activity-map
[out]	aspectRatio	(&) aspect ratio used to generate activity-map

Returns: flag, if activity-map is ready, 1: it is, 0: it is NOT

Examples: powermap.h.

Definition at line 722 of file powermap.c.

◆ powermap_getPowermapAvgCoeff()

float powermap_getPowermapAvgCoeff ( void *const hPm )

Returns the current activity-map averaging coefficient, 0..1.

Examples: powermap.h.

Definition at line 716 of file powermap.c.

◆ powermap_getPowermapEQ()

float powermap_getPowermapEQ	(	void *const	hPm,
		int	bandIdx )

Returns the weighting coefficient for a particular frequency band index, allowing one to "equalise" the activity-map.

Examples: powermap.h.

Definition at line 623 of file powermap.c.

◆ powermap_getPowermapEQAllBands()

float powermap_getPowermapEQAllBands ( void *const hPm )

Returns the weighting coefficient for the first frequency band.

Examples: powermap.h.

Definition at line 629 of file powermap.c.

◆ powermap_getPowermapEQHandle()

void powermap_getPowermapEQHandle	(	void *const	hPm,
		float **	pX_vector,
		float **	pY_values,
		int *	pNpoints )

Returns the weighting coefficient for all frequency bands.

Parameters

[in]	hPm	powermap handle
[out]	pX_vector	(&) frequency vector; pNpoints x 1
[out]	pY_values	(&) weighting coefficients; pNpoints x 1
[out]	pNpoints	(&) number of frequency bands

Examples: powermap.h.

Definition at line 635 of file powermap.c.

◆ powermap_getPowermapMode()

int powermap_getPowermapMode ( void *const hPm )

Returns the powermap/activity-map mode to employed for the analysis see POWERMAP_MODES enum.

Examples: powermap.h.

Definition at line 605 of file powermap.c.

◆ powermap_getProcessingDelay()

int powermap_getProcessingDelay ( void )

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

Examples: powermap.h.

Definition at line 747 of file powermap.c.

◆ powermap_getProgressBar0_1()

float powermap_getProgressBar0_1 ( void *const hPm )

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

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

Examples: powermap.h.

Definition at line 587 of file powermap.c.

◆ powermap_getProgressBarText()

void powermap_getProgressBarText	(	void *const	hPm,
		char *	text )

(Optional) Returns current intialisation/processing progress text

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

Examples: powermap.h.

Definition at line 593 of file powermap.c.

◆ powermap_getSamplingRate()

int powermap_getSamplingRate ( void *const hPm )

Returns the current sampling rate, in Hz.

Examples: powermap.h.

Definition at line 611 of file powermap.c.

◆ powermap_init()

void powermap_init	(	void *const	hPm,
		float	samplerate )

Initialises an instance of powermap with default settings.

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

Parameters

[in]	hPm	powermap handle
[in]	samplerate	Host samplerate.

Examples: powermap.h.

Definition at line 137 of file powermap.c.

◆ powermap_initCodec()

void powermap_initCodec ( void *const hPm )

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] hPm powermap handle

Examples: powermap.h.

Definition at line 159 of file powermap.c.

◆ powermap_refreshSettings()

void powermap_refreshSettings ( void *const hPm )

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

Examples: powermap.h.

Definition at line 387 of file powermap.c.

◆ powermap_requestPmapUpdate()

void powermap_requestPmapUpdate ( void *const hPm )

Informs powermap that it should compute a new activity-map at its own convenience, if it would be so kind; thank you, God bless.

Examples: powermap.h.

Definition at line 568 of file powermap.c.

◆ powermap_setAnaOrder()

void powermap_setAnaOrder	(	void *const	hPm,
		int	newValue,
		int	bandIdx )

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

Examples: powermap.h.

Definition at line 500 of file powermap.c.

◆ powermap_setAnaOrderAllBands()

void powermap_setAnaOrderAllBands	(	void *const	hPm,
		int	newValue )

Sets the input/analysis order for all frequency bands.

Examples: powermap.h.

Definition at line 506 of file powermap.c.

◆ powermap_setAspectRatio()

void powermap_setAspectRatio	(	void *const	hPm,
		int	newOption )

Sets the visualisation display window aspect-ratio (see ASPECT_RATIO_OPTIONS enum)

Examples: powermap.h.

Definition at line 553 of file powermap.c.

◆ powermap_setChOrder()

void powermap_setChOrder	(	void *const	hPm,
		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: powermap.h.

Definition at line 530 of file powermap.c.

◆ powermap_setCovAvgCoeff()

void powermap_setCovAvgCoeff	(	void *const	hPm,
		float	newAvg )

Sets the covariance matrix averaging coefficient, 0..1.

Examples: powermap.h.

Definition at line 415 of file powermap.c.

◆ powermap_setDispFOV()

void powermap_setDispFOV	(	void *const	hPm,
		int	newOption )

Sets the visualisation display window horizontal field-of-view (FOV) (see HFOV_OPTIONS enum)

Examples: powermap.h.

Definition at line 544 of file powermap.c.

◆ powermap_setMasterOrder()

void powermap_setMasterOrder	(	void *const	hPm,
		int	newValue )

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

Examples: powermap.h.

Definition at line 401 of file powermap.c.

◆ powermap_setNormType()

void powermap_setNormType	(	void *const	hPm,
		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: powermap.h.

Definition at line 537 of file powermap.c.

◆ powermap_setNumSources()

void powermap_setNumSources	(	void *const	hPm,
		int	newValue )

Sets the number of sources present in the input sound scene.

Examples: powermap.h.

Definition at line 421 of file powermap.c.

◆ powermap_setPowermapAvgCoeff()

void powermap_setPowermapAvgCoeff	(	void *const	hPm,
		float	newValue )

Sets the activity-map averaging coefficient, 0..1.

Examples: powermap.h.

Definition at line 562 of file powermap.c.

◆ powermap_setPowermapEQ()

void powermap_setPowermapEQ	(	void *const	hPm,
		float	newValue,
		int	bandIdx )

Sets the weighting coefficient for a particular frequency band, allowing one to "equalise" the activity-map.

Examples: powermap.h.

Definition at line 515 of file powermap.c.

◆ powermap_setPowermapEQAllBands()

void powermap_setPowermapEQAllBands	(	void *const	hPm,
		float	newValue )

Sets the weighting coefficient for all frequency bands.

Examples: powermap.h.

Definition at line 521 of file powermap.c.

◆ powermap_setPowermapMode()

void powermap_setPowermapMode	(	void *const	hPm,
		int	newMode )

Sets the powermap/activity-map approach, (see POWERMAP_MODES enum)

Examples: powermap.h.

Definition at line 392 of file powermap.c.

◆ powermap_setSourcePreset()

void powermap_setSourcePreset	(	void *const	hPm,
		int	newPresetID )

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

Examples: powermap.h.

Definition at line 427 of file powermap.c.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ POWERMAP_MODES

Function Documentation

◆ powermap_analysis()

◆ powermap_create()

◆ powermap_destroy()

◆ powermap_getAnaOrder()

◆ powermap_getAnaOrderAllBands()

◆ powermap_getAnaOrderHandle()

◆ powermap_getAspectRatio()

◆ powermap_getChOrder()

◆ powermap_getCodecStatus()

◆ powermap_getCovAvgCoeff()

◆ powermap_getDispFOV()

◆ powermap_getFrameSize()

◆ powermap_getMasterOrder()

◆ powermap_getNormType()

◆ powermap_getNSHrequired()

◆ powermap_getNumberOfBands()

◆ powermap_getNumSources()

◆ powermap_getPmap()

◆ powermap_getPowermapAvgCoeff()

◆ powermap_getPowermapEQ()

◆ powermap_getPowermapEQAllBands()

◆ powermap_getPowermapEQHandle()

◆ powermap_getPowermapMode()

◆ powermap_getProcessingDelay()

◆ powermap_getProgressBar0_1()

◆ powermap_getProgressBarText()

◆ powermap_getSamplingRate()

◆ powermap_init()

◆ powermap_initCodec()

◆ powermap_refreshSettings()

◆ powermap_requestPmapUpdate()

◆ powermap_setAnaOrder()

◆ powermap_setAnaOrderAllBands()

◆ powermap_setAspectRatio()

◆ powermap_setChOrder()

◆ powermap_setCovAvgCoeff()

◆ powermap_setDispFOV()

◆ powermap_setMasterOrder()

◆ powermap_setNormType()

◆ powermap_setNumSources()

◆ powermap_setPowermapAvgCoeff()

◆ powermap_setPowermapEQ()

◆ powermap_setPowermapEQAllBands()

◆ powermap_setPowermapMode()

◆ powermap_setSourcePreset()