array2sh.h

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

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

Files

array2sh.h (include), array2sh_internal.h, array2sh.c, array2sh_internal.c

Example Usage

int main(void) {
    void* hA2sh;
    int frameSize;
 
    // Create and initialise an instance of array2sh
    array2sh_create(&hA2sh);
    array2sh_init(hA2sh, hostSamplingRate);
 
    // Call any set functions, e.g.:
    array2sh_setPreset(hA2sh, MICROPHONE_ARRAY_PRESET_EIGENMIKE32);
    array2sh_setNormType(hA2sh, NORM_N3D);
    array2sh_setGain(hA2sh, 6.0f);
 
    // The framesize of this example is fixed, and can be found with
    frameSize = array2sh_getFrameSize();
 
    // Processing frame-by-frame
    ...
    // Load signals into inputSignalBuffer (numberOfInputs x frameSize)
    array2sh_process(hA2sh, inputSignalBuffer, outputSignalBuffer,
                     numberOfInputs, numberOfOutputs, frameSize);
    // Copy signals from outputSignalBuffer (numberOfOutputs x frameSize)
    ...
 
    // Destroy this instance of array2sh
    array2sh_destroy(&hA2sh);
}

Include Header

/*
 * Copyright 2017-2018 Leo McCormack
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 * OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */
 
#ifndef __ARRAY2SH_H_INCLUDED__
#define __ARRAY2SH_H_INCLUDED__
 
#include "_common.h"
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
    
/* ========================================================================== */
/*                             Presets + Constants                            */
/* ========================================================================== */
 
typedef enum {
    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
 
}ARRAY2SH_MICROPHONE_ARRAY_PRESETS;
 
typedef enum {
    FILTER_SOFT_LIM = 1, 
    FILTER_TIKHONOV,     
    FILTER_Z_STYLE,      
    FILTER_Z_STYLE_MAXRE 
}ARRAY2SH_FILTER_TYPES;
    
#define ARRAY2SH_NUM_FILTER_TYPES ( 4 )
 
typedef enum {
    ARRAY_SPHERICAL = 1, 
    ARRAY_CYLINDRICAL    
}ARRAY2SH_ARRAY_TYPES;
    
#define ARRAY2SH_NUM_ARRAY_TYPES ( 2 )
 
typedef enum {
    WEIGHT_RIGID_OMNI = 1, 
    WEIGHT_RIGID_CARD,     
    WEIGHT_RIGID_DIPOLE,   
    WEIGHT_OPEN_OMNI,      
    WEIGHT_OPEN_CARD,      
    WEIGHT_OPEN_DIPOLE     
}ARRAY2SH_WEIGHT_TYPES;
    
#define ARRAY2SH_NUM_WEIGHT_TYPES ( 6 )
    
typedef enum {
    EVAL_STATUS_EVALUATED = 0,      
    EVAL_STATUS_RECENTLY_EVALUATED, 
    EVAL_STATUS_NOT_EVALUATED,      
    EVAL_STATUS_EVALUATING          
}ARRAY2SH_EVAL_STATUS;
 
#define ARRAY2SH_MAX_NUM_SENSORS ( MAX_NUM_CHANNELS )
 
#define ARRAY2SH_MAX_GAIN_MIN_VALUE ( 0.0f )
 
#define ARRAY2SH_MAX_GAIN_MAX_VALUE ( 80.0f )
 
#define ARRAY2SH_POST_GAIN_MIN_VALUE ( -60.0f )
 
#define ARRAY2SH_POST_GAIN_MAX_VALUE ( 12.0f )
 
#define ARRAY2SH_SPEED_OF_SOUND_MIN_VALUE ( 200.0f )
 
#define ARRAY2SH_SPEED_OF_SOUND_MAX_VALUE ( 2000.0f )
 
#define ARRAY2SH_ARRAY_RADIUS_MIN_VALUE ( 1.0f )
 
#define ARRAY2SH_ARRAY_RADIUS_MAX_VALUE ( 400.0f )
 
#define ARRAY2SH_BAFFLE_RADIUS_MIN_VALUE ( 1.0f )
 
#define ARRAY2SH_BAFFLE_RADIUS_MAX_VALUE ( 400.0f ) 
 
 
/* ========================================================================== */
/*                               Main Functions                               */
/* ========================================================================== */
 
void array2sh_create(void** const phA2sh);
 
void array2sh_destroy(void** const phA2sh);
 
void array2sh_init(void* const hA2sh,
                   int samplerate);
 
void array2sh_evalEncoder(void* const hA2sh);
 
void array2sh_process(void* const hA2sh,
                      const float *const * inputs,
                      float* const* outputs,
                      int nInputs,
                      int nOutputs,
                      int nSamples);
 
 
/* ========================================================================== */
/*                                Set Functions                               */
/* ========================================================================== */
 
void array2sh_refreshSettings(void* const hA2sh);
 
void array2sh_setEncodingOrder(void* const hA2sh, int newOrder);
 
void array2sh_setRequestEncoderEvalFLAG(void* const hA2sh, int newState);
    
void array2sh_setEvalStatus(void* const hA2sh, ARRAY2SH_EVAL_STATUS evalStatus);
 
void array2sh_setDiffEQpastAliasing(void* const hA2sh, int newState);
 
void array2sh_setPreset(void* const hA2sh,
                        ARRAY2SH_MICROPHONE_ARRAY_PRESETS preset);
    
void array2sh_setSensorAzi_rad(void* const hA2sh, int index, float newAzi_rad);
    
void array2sh_setSensorElev_rad(void* const hA2sh, int index, float newElev_rad);
    
void array2sh_setSensorAzi_deg(void* const hA2sh, int index, float newAzi_deg);
    
void array2sh_setSensorElev_deg(void* const hA2sh, int index, float newElev_deg);
    
void array2sh_setNumSensors(void* const hA2sh, int newQ);
    
void array2sh_setr(void* const hA2sh, float newr);
    
void array2sh_setR(void* const hA2sh, float newR);
    
void array2sh_setArrayType(void* const hA2sh, int newType);
 
void array2sh_setWeightType(void* const hA2sh, int newType);
    
void array2sh_setFilterType(void* const hA2sh, int newType);
    
void array2sh_setRegPar(void* const hA2sh, float newVal);
    
void array2sh_setChOrder(void* const hA2sh, int newOrder);
    
void array2sh_setNormType(void* const hA2sh, int newType);
 
void array2sh_setc(void* const hA2sh, float newc);
    
void array2sh_setGain(void* const hA2sh, float newGain);
 
 
/* ========================================================================== */
/*                                Get Functions                               */
/* ========================================================================== */
 
int array2sh_getFrameSize(void);
 
ARRAY2SH_EVAL_STATUS array2sh_getEvalStatus(void* const hA2sh);
 
int array2sh_getReinitSHTmatrixFLAG(void* const hA2sh);
 
float array2sh_getProgressBar0_1(void* const hA2sh);
 
void array2sh_getProgressBarText(void* const hA2sh, char* text);
 
int array2sh_getDiffEQpastAliasing(void* const hA2sh);
 
int array2sh_getRequestEncoderEvalFLAG(void* const hA2sh);
    
int array2sh_getEncodingOrder(void* const hA2sh);
    
float array2sh_getSensorAzi_rad(void* const hA2sh, int index);
    
float array2sh_getSensorElev_rad(void* const hA2sh, int index);
    
float array2sh_getSensorAzi_deg(void* const hA2sh, int index);
    
float array2sh_getSensorElev_deg(void* const hA2sh, int index);
 
int array2sh_getNumSensors(void* const hA2sh);
    
int array2sh_getMaxNumSensors(void);
    
int array2sh_getMinNumSensors(void* const hA2sh);
    
int array2sh_getNSHrequired(void* const hA2sh);
    
float array2sh_getr(void* const hA2sh);
    
float array2sh_getR(void* const hA2sh);
    
int array2sh_getArrayType(void* const hA2sh);
 
int array2sh_getWeightType(void* const hA2sh);
 
int array2sh_getFilterType(void* const hA2sh);
 
float array2sh_getRegPar(void* const hA2sh);
    
int array2sh_getChOrder(void* const hA2sh);
 
int array2sh_getNormType(void* const hA2sh);
    
float array2sh_getc(void* const hA2sh);
 
float array2sh_getGain(void* const hA2sh);
 
float* array2sh_getFreqVector(void* const hA2sh, int* nFreqPoints);
    
float** array2sh_getbN_inv(void* const hA2sh, int* nCurves, int* nFreqPoints);
    
float** array2sh_getbN_modal(void* const hA2sh, int* nCurves, int* nFreqPoints);
 
float* array2sh_getSpatialCorrelation_Handle(void* const hA2sh,
                                             int* nCurves,
                                             int* nFreqPoints);
 
float* array2sh_getLevelDifference_Handle(void* const hA2sh, int* nCurves, int* nFreqPoints);
    
int array2sh_getSamplingRate(void* const hA2sh);
    
int array2sh_getProcessingDelay(void);
   
    
#ifdef __cplusplus
} /* extern "C" { */
#endif /* __cplusplus */
 
#endif /* __ARRAY2SH_H_INCLUDED__ */