SAF
•All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Enumerations | Functions
dirass.h File Reference

A sound-field visualiser based on the directional re-assignment of beamformer energy based on local DoA estimates [1,2]. More...

#include "_common.h"

Go to the source code of this file.

Enumerations

enum  DIRASS_UPSCALE_ORDERS {
  UPSCALE_ORDER_FIRST = 1 , UPSCALE_ORDER_SECOND , UPSCALE_ORDER_THIRD , UPSCALE_ORDER_FOURTH ,
  UPSCALE_ORDER_FIFTH , UPSCALE_ORDER_SIXTH , UPSCALE_ORDER_SEVENTH , UPSCALE_ORDER_EIGHTH ,
  UPSCALE_ORDER_NINTH , UPSCALE_ORDER_TENTH , UPSCALE_ORDER_ELEVENTH , UPSCALE_ORDER_TWELFTH ,
  UPSCALE_ORDER_THIRTEENTH , UPSCALE_ORDER_FOURTEENTH , UPSCALE_ORDER_FIFTEENTH , UPSCALE_ORDER_SIXTHTEENTH ,
  UPSCALE_ORDER_SEVENTEENTH , UPSCALE_ORDER_EIGHTEENTH , UPSCALE_ORDER_NINETEENTH , UPSCALE_ORDER_TWENTIETH
}
 Available upscaling orders. More...
 
enum  DIRASS_GRID_OPTIONS {
  T_DESIGN_3 = 1 , T_DESIGN_4 , T_DESIGN_6 , T_DESIGN_9 ,
  T_DESIGN_13 , T_DESIGN_18 , GRID_GEOSPHERE_6 , T_DESIGN_30 ,
  GRID_GEOSPHERE_8 , GRID_GEOSPHERE_9 , GRID_GEOSPHERE_10 , GRID_GEOSPHERE_12
}
 Available scanning grid options. More...
 
enum  DIRASS_REASS_MODES { REASS_MODE_OFF = 1 , REASS_NEAREST , REASS_UPSCALE }
 Available processing modes. More...
 

Functions

void dirass_create (void **const phDir)
 Creates an instance of the dirass.
 
void dirass_destroy (void **const phDir)
 Destroys an instance of the dirass.
 
void dirass_init (void *const hDir, float samplerate)
 Initialises an instance of dirass with default settings.
 
void dirass_initCodec (void *const hDir)
 Intialises the codec variables, based on current global/user parameters.
 
void dirass_analysis (void *const hDir, const float *const *inputs, int nInputs, int nSamples, int isPlaying)
 Analyses the input spherical harmonic signals to generate an activity-map as in [1,2].
 
void dirass_refreshSettings (void *const hDir)
 Sets all intialisation flags to 1; re-initialising all settings/variables as dirass is currently configured, at next available opportunity.
 
void dirass_setBeamType (void *const hDir, int newType)
 Sets the sector beamforming pattern to employ for the analysis (see STATIC_BEAM_TYPES enum).
 
void dirass_setInputOrder (void *const hDir, int newValue)
 Sets the input/analysis order (see SH_ORDERS enum)
 
void dirass_setDisplayGridOption (void *const hDir, int newOption)
 Sets a new display grid option (see DIRASS_GRID_OPTIONS enum)
 
void dirass_setDispWidth (void *const hDir, int newValue)
 Sets the output display width in pixels.
 
void dirass_setUpscaleOrder (void *const hDir, int newOrder)
 Sets the upscale order, only if DIRASS_REASS_MODES is set to REASS_UPSCALE, (see DIRASS_UPSCALE_ORDERS enum).
 
void dirass_setDiRAssMode (void *const hDir, int newMode)
 Sets the analysis directional re-assignment mode (see DIRASS_REASS_MODES enum)
 
void dirass_setMinFreq (void *const hDir, float newValue)
 Sets the minimum analysis frequency, in Hz.
 
void dirass_setMaxFreq (void *const hDir, float newValue)
 Sets the maximum analysis frequency, in Hz.
 
void dirass_setChOrder (void *const hDir, 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 dirass_setNormType (void *const hDir, 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 dirass_setDispFOV (void *const hDir, int newOption)
 Sets the visualisation display window horizontal field-of-view (FOV) (see HFOV_OPTIONS enum)
 
void dirass_setAspectRatio (void *const hDir, int newOption)
 Sets the visualisation display window aspect-ratio (see ASPECT_RATIO_OPTIONS enum)
 
void dirass_setMapAvgCoeff (void *const hDir, float newValue)
 Sets the activity-map averaging coefficient, 0..1.
 
void dirass_requestPmapUpdate (void *const hDir)
 Informs dirass that it should compute a new activity-map.
 
int dirass_getFrameSize (void)
 Returns the processing framesize (i.e., number of samples processed with every _process() call )
 
CODEC_STATUS dirass_getCodecStatus (void *const hDir)
 Returns current codec status (see CODEC_STATUS enum)
 
float dirass_getProgressBar0_1 (void *const hDir)
 (Optional) Returns current intialisation/processing progress, between 0..1
 
void dirass_getProgressBarText (void *const hDir, char *text)
 (Optional) Returns current intialisation/processing progress text
 
int dirass_getInputOrder (void *const hDir)
 Returns the current analysis/input order (see SH_ORDERS enum)
 
int dirass_getBeamType (void *const hDir)
 Returns the sector beamforming pattern to employed for the analysis (see STATIC_BEAM_TYPES enum)
 
int dirass_getDisplayGridOption (void *const hDir)
 Returns the current display grid option (see DIRASS_GRID_OPTIONS enum)
 
int dirass_getDispWidth (void *const hDir)
 Returns the current output display width in pixels.
 
int dirass_getUpscaleOrder (void *const hDir)
 Returns the current upscale order (see DIRASS_UPSCALE_ORDERS enum)
 
int dirass_getDiRAssMode (void *const hDir)
 Returns the current analysis directional re-assignment mode (see DIRASS_REASS_MODES enum)
 
float dirass_getMinFreq (void *const hDir)
 Returns the current minimum analysis frequency, in Hz.
 
float dirass_getMaxFreq (void *const hDir)
 Returns the current maximum analysis frequency, in Hz.
 
int dirass_getSamplingRate (void *const hDir)
 Returns the current sampling rate, in Hz.
 
int dirass_getNSHrequired (void *const hDir)
 Returns the number of spherical harmonic signals required by the current analysis order: (current_order + 1)^2.
 
int dirass_getChOrder (void *const hDir)
 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 dirass_getNormType (void *const hDir)
 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 dirass_getDispFOV (void *const hDir)
 Returns the current visualisation display window horizontal field-of-view (FOV) (see HFOV_OPTIONS enum)
 
int dirass_getAspectRatio (void *const hDir)
 Returns the current visualisation display window aspect-ratio (see ASPECT_RATIO_OPTIONS enum)
 
float dirass_getMapAvgCoeff (void *const hDir)
 Returns the current activity-map averaging coefficient, 0..1.
 
int dirass_getPmap (void *const hDir, float **grid_dirs, float **pmap, int *nDirs, int *pmapWidth, int *hfov, float *aspectRatio)
 Returns the latest computed activity-map if it is ready; otherwise it returns 0, and you'll just have to wait a bit.
 
int dirass_getProcessingDelay (void)
 Returns the processing delay in samples (may be used for delay compensation features)
 

Detailed Description

A sound-field visualiser based on the directional re-assignment of beamformer energy based on local DoA estimates [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., Politis, A., and Pulkki, V. (2019). "Sharpening of angular spectra based on a directional re-assignment approach for ambisonic sound-field visualisation". IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP).
Author
Leo McCormack
Date
21.02.2019
License
ISC

Definition in file dirass.h.

Enumeration Type Documentation

◆ DIRASS_GRID_OPTIONS

enum DIRASS_GRID_OPTIONS

Available scanning grid options.

Enumerator
T_DESIGN_3 

T_DESIGN_3 - 6 points.

T_DESIGN_4 

T_DESIGN_4 - 12 points.

T_DESIGN_6 

T_DESIGN_6 - 24 points.

T_DESIGN_9 

T_DESIGN_9 - 48 points.

T_DESIGN_13 

T_DESIGN_13 - 94 points.

T_DESIGN_18 

T_DESIGN_18 - 180 points.

GRID_GEOSPHERE_6 

GRID_GEOSPHERE_6 - 362 points.

T_DESIGN_30 

T_DESIGN_30 - 480 points.

GRID_GEOSPHERE_8 

GRID_GEOSPHERE_8 - 642 points.

GRID_GEOSPHERE_9 

GRID_GEOSPHERE_9 - 812 points.

GRID_GEOSPHERE_10 

GRID_GEOSPHERE_10 - 1002 points.

GRID_GEOSPHERE_12 

GRID_GEOSPHERE_12 - 1442 points.

Definition at line 86 of file dirass.h.

◆ DIRASS_REASS_MODES

enum DIRASS_REASS_MODES

Available processing modes.

More information can be found in [1]

See also
[1] McCormack, L., Politis, A., and Pulkki, V. (2019). "Sharpening of angular spectra based on a directional re-assignment approach for ambisonic sound-field visualisation". IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP).
Enumerator
REASS_MODE_OFF 

Re-assignment is disabled.

i.e. dirass generates a standard (beamformer)energy-based map

REASS_NEAREST 

Each sector beamformer energy is re-assigned to the nearest interpolation grid point, based on the analysed DoA.

REASS_UPSCALE 

Each sector beamformer is re-encoded into spherical harmonics of a higher order.

The map is then derived from the upscaled SHs as normal.

Definition at line 110 of file dirass.h.

◆ DIRASS_UPSCALE_ORDERS

enum DIRASS_UPSCALE_ORDERS

Available upscaling orders.

Enumerator
UPSCALE_ORDER_FIRST 

First-order upscaling.

UPSCALE_ORDER_SECOND 

Second-order upscaling.

UPSCALE_ORDER_THIRD 

Third-order upscaling.

UPSCALE_ORDER_FOURTH 

Fourth-order upscaling.

UPSCALE_ORDER_FIFTH 

Fifth-order upscaling.

UPSCALE_ORDER_SIXTH 

Sixth-order upscaling.

UPSCALE_ORDER_SEVENTH 

Seventh-order upscaling.

UPSCALE_ORDER_EIGHTH 

Eighth-order upscaling.

UPSCALE_ORDER_NINTH 

Ninth-order upscaling.

UPSCALE_ORDER_TENTH 

Tenth-order upscaling.

UPSCALE_ORDER_ELEVENTH 

Eleventh-order upscaling.

UPSCALE_ORDER_TWELFTH 

Twelfth-order upscaling.

UPSCALE_ORDER_THIRTEENTH 

Thirteenth-order upscaling.

UPSCALE_ORDER_FOURTEENTH 

Fourteenth-order upscaling.

UPSCALE_ORDER_FIFTEENTH 

Fifteenth-order upscaling.

UPSCALE_ORDER_SIXTHTEENTH 

Sixthteenth-order upscaling.

UPSCALE_ORDER_SEVENTEENTH 

Seventeenth-order upscaling.

UPSCALE_ORDER_EIGHTEENTH 

Eighteenth-order upscaling.

UPSCALE_ORDER_NINETEENTH 

Ninteenth-order upscaling.

UPSCALE_ORDER_TWENTIETH 

Twentieth-order upscaling.

Definition at line 61 of file dirass.h.

Function Documentation

◆ dirass_analysis()

void dirass_analysis ( void *const hDir,
const float *const * inputs,
int nInputs,
int nSamples,
int isPlaying )

Analyses the input spherical harmonic signals to generate an activity-map as in [1,2].

Parameters
[in]hDirdirass handle
[in]inputsInput channel buffers; 2-D array: nInputs x nSamples
[in]nInputsNumber of input channels
[in]nSamplesNumber of samples in 'inputs'/'output' matrices
[in]isPlayingFlag to indicate if there is audio in the input buffers, 0: no audio, reduced processing, 1: audio, full processing
See also
[1] McCormack, L., Politis, A., and Pulkki, V. (2019). "Sharpening of angular spectra based on a directional re-assignment approach for ambisonic sound-field visualisation". IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP).
[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
dirass.h.

Definition at line 197 of file dirass.c.

◆ dirass_create()

void dirass_create ( void **const phDir)

Creates an instance of the dirass.

Parameters
[in]phDir(&) address of dirass handle
Examples
dirass.h.

Definition at line 40 of file dirass.c.

◆ dirass_destroy()

void dirass_destroy ( void **const phDir)

Destroys an instance of the dirass.

Parameters
[in]phDir(&) address of dirass handle
Examples
dirass.h.

Definition at line 102 of file dirass.c.

◆ dirass_getAspectRatio()

int dirass_getAspectRatio ( void *const hDir)

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

Examples
dirass.h.

Definition at line 647 of file dirass.c.

◆ dirass_getBeamType()

int dirass_getBeamType ( void *const hDir)

Returns the sector beamforming pattern to employed for the analysis (see STATIC_BEAM_TYPES enum)

Examples
dirass.h.

Definition at line 575 of file dirass.c.

◆ dirass_getChOrder()

int dirass_getChOrder ( void *const hDir)

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

Definition at line 629 of file dirass.c.

◆ dirass_getCodecStatus()

CODEC_STATUS dirass_getCodecStatus ( void *const hDir)

Returns current codec status (see CODEC_STATUS enum)

Examples
dirass.h.

Definition at line 551 of file dirass.c.

◆ dirass_getDiRAssMode()

int dirass_getDiRAssMode ( void *const hDir)

Returns the current analysis directional re-assignment mode (see DIRASS_REASS_MODES enum)

Examples
dirass.h.

Definition at line 599 of file dirass.c.

◆ dirass_getDispFOV()

int dirass_getDispFOV ( void *const hDir)

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

Examples
dirass.h.

Definition at line 641 of file dirass.c.

◆ dirass_getDisplayGridOption()

int dirass_getDisplayGridOption ( void *const hDir)

Returns the current display grid option (see DIRASS_GRID_OPTIONS enum)

Examples
dirass.h.

Definition at line 581 of file dirass.c.

◆ dirass_getDispWidth()

int dirass_getDispWidth ( void *const hDir)

Returns the current output display width in pixels.

Examples
dirass.h.

Definition at line 587 of file dirass.c.

◆ dirass_getFrameSize()

int dirass_getFrameSize ( void )

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

Examples
dirass.h.

Definition at line 546 of file dirass.c.

◆ dirass_getInputOrder()

int dirass_getInputOrder ( void *const hDir)

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

Examples
dirass.h.

Definition at line 569 of file dirass.c.

◆ dirass_getMapAvgCoeff()

float dirass_getMapAvgCoeff ( void *const hDir)

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

Examples
dirass.h.

Definition at line 653 of file dirass.c.

◆ dirass_getMaxFreq()

float dirass_getMaxFreq ( void *const hDir)

Returns the current maximum analysis frequency, in Hz.

Examples
dirass.h.

Definition at line 611 of file dirass.c.

◆ dirass_getMinFreq()

float dirass_getMinFreq ( void *const hDir)

Returns the current minimum analysis frequency, in Hz.

Examples
dirass.h.

Definition at line 605 of file dirass.c.

◆ dirass_getNormType()

int dirass_getNormType ( void *const hDir)

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

Definition at line 635 of file dirass.c.

◆ dirass_getNSHrequired()

int dirass_getNSHrequired ( void *const hDir)

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

Examples
dirass.h.

Definition at line 623 of file dirass.c.

◆ dirass_getPmap()

int dirass_getPmap ( void *const hDir,
float ** grid_dirs,
float ** pmap,
int * nDirs,
int * pmapWidth,
int * hfov,
float * 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]hDir(&) dirass 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
dirass.h.

Definition at line 659 of file dirass.c.

◆ dirass_getProcessingDelay()

int dirass_getProcessingDelay ( void )

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

Examples
dirass.h.

Definition at line 685 of file dirass.c.

◆ dirass_getProgressBar0_1()

float dirass_getProgressBar0_1 ( void *const hDir)

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

  • 0: intialisation/processing has started
  • 1: intialisation/processing has ended
Examples
dirass.h.

Definition at line 557 of file dirass.c.

◆ dirass_getProgressBarText()

void dirass_getProgressBarText ( void *const hDir,
char * text )

(Optional) Returns current intialisation/processing progress text

Note
"text" string should be (at least) of length: PROGRESSBARTEXT_CHAR_LENGTH
Parameters
[in]hDirdirass handle
[out]textProcess bar text; PROGRESSBARTEXT_CHAR_LENGTH x 1
Examples
dirass.h.

Definition at line 563 of file dirass.c.

◆ dirass_getSamplingRate()

int dirass_getSamplingRate ( void *const hDir)

Returns the current sampling rate, in Hz.

Examples
dirass.h.

Definition at line 617 of file dirass.c.

◆ dirass_getUpscaleOrder()

int dirass_getUpscaleOrder ( void *const hDir)

Returns the current upscale order (see DIRASS_UPSCALE_ORDERS enum)

Examples
dirass.h.

Definition at line 593 of file dirass.c.

◆ dirass_init()

void dirass_init ( void *const hDir,
float samplerate )

Initialises an instance of dirass with default settings.

Warning
This should not be called while _process() is on-going!
Parameters
[in]hDirdirass handle
[in]samplerateHost samplerate.
Examples
dirass.h.

Definition at line 147 of file dirass.c.

◆ dirass_initCodec()

void dirass_initCodec ( void *const hDir)

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]hDirdirass handle
Examples
dirass.h.

Definition at line 169 of file dirass.c.

◆ dirass_refreshSettings()

void dirass_refreshSettings ( void *const hDir)

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

Examples
dirass.h.

Definition at line 420 of file dirass.c.

◆ dirass_requestPmapUpdate()

void dirass_requestPmapUpdate ( void *const hDir)

Informs dirass that it should compute a new activity-map.

Examples
dirass.h.

Definition at line 537 of file dirass.c.

◆ dirass_setAspectRatio()

void dirass_setAspectRatio ( void *const hDir,
int newOption )

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

Examples
dirass.h.

Definition at line 522 of file dirass.c.

◆ dirass_setBeamType()

void dirass_setBeamType ( void *const hDir,
int newType )

Sets the sector beamforming pattern to employ for the analysis (see STATIC_BEAM_TYPES enum).

Examples
dirass.h.

Definition at line 425 of file dirass.c.

◆ dirass_setChOrder()

void dirass_setChOrder ( void *const hDir,
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
dirass.h.

Definition at line 499 of file dirass.c.

◆ dirass_setDiRAssMode()

void dirass_setDiRAssMode ( void *const hDir,
int newMode )

Sets the analysis directional re-assignment mode (see DIRASS_REASS_MODES enum)

Examples
dirass.h.

Definition at line 475 of file dirass.c.

◆ dirass_setDispFOV()

void dirass_setDispFOV ( void *const hDir,
int newOption )

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

Examples
dirass.h.

Definition at line 513 of file dirass.c.

◆ dirass_setDisplayGridOption()

void dirass_setDisplayGridOption ( void *const hDir,
int newOption )

Sets a new display grid option (see DIRASS_GRID_OPTIONS enum)

Warning
Not safe to call while simultaneously calling dirass_analysis()!
Examples
dirass.h.

Definition at line 448 of file dirass.c.

◆ dirass_setDispWidth()

void dirass_setDispWidth ( void *const hDir,
int newValue )

Sets the output display width in pixels.

Warning
Not safe to call while simultaneously calling dirass_analysis()!
Examples
dirass.h.

Definition at line 457 of file dirass.c.

◆ dirass_setInputOrder()

void dirass_setInputOrder ( void *const hDir,
int newValue )

Sets the input/analysis order (see SH_ORDERS enum)

Examples
dirass.h.

Definition at line 434 of file dirass.c.

◆ dirass_setMapAvgCoeff()

void dirass_setMapAvgCoeff ( void *const hDir,
float newValue )

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

Examples
dirass.h.

Definition at line 531 of file dirass.c.

◆ dirass_setMaxFreq()

void dirass_setMaxFreq ( void *const hDir,
float newValue )

Sets the maximum analysis frequency, in Hz.

Examples
dirass.h.

Definition at line 493 of file dirass.c.

◆ dirass_setMinFreq()

void dirass_setMinFreq ( void *const hDir,
float newValue )

Sets the minimum analysis frequency, in Hz.

Examples
dirass.h.

Definition at line 487 of file dirass.c.

◆ dirass_setNormType()

void dirass_setNormType ( void *const hDir,
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
dirass.h.

Definition at line 506 of file dirass.c.

◆ dirass_setUpscaleOrder()

void dirass_setUpscaleOrder ( void *const hDir,
int newOrder )

Sets the upscale order, only if DIRASS_REASS_MODES is set to REASS_UPSCALE, (see DIRASS_UPSCALE_ORDERS enum).

Examples
dirass.h.

Definition at line 466 of file dirass.c.