saf_sh.h

Go to the documentation of this file.

/*
 * Copyright 2016-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 __SAF_SH_H_INCLUDED__
#define __SAF_SH_H_INCLUDED__
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
#include "../saf_utilities/saf_utility_complex.h"
 
#define ORDER2NSH(order) ((order+1)*(order+1))
#define NSH2ORDER(nSH) ( (int)(sqrt((double)nSH)-0.999) )
 
/* ========================================================================== */
/*                                    Enums                                   */
/* ========================================================================== */
 
typedef enum {
    ARRAY_CONSTRUCTION_OPEN,             
    ARRAY_CONSTRUCTION_OPEN_DIRECTIONAL, 
    ARRAY_CONSTRUCTION_RIGID,            
    ARRAY_CONSTRUCTION_RIGID_DIRECTIONAL 
}ARRAY_CONSTRUCTION_TYPES;
 
typedef enum {
    SECTOR_PATTERN_PWD,     
    SECTOR_PATTERN_MAXRE,   
    SECTOR_PATTERN_CARDIOID 
}SECTOR_PATTERNS;
 
typedef enum {
    ARRAY_SHT_DEFAULT, 
    ARRAY_SHT_REG_LS,  
    ARRAY_SHT_REG_LSHD 
} ARRAY_SHT_OPTIONS;
 
 
/* ========================================================================== */
/*                               Misc. Functions                              */
/* ========================================================================== */
 
void unnorm_legendreP(/* Input Arguments */
                      int n,
                      double* x,
                      int lenX,
                      /* Output Arguments */
                      double* y);
 
void unnorm_legendreP_recur(/* Input Arguments */
                            int n,
                            float* x,
                            int lenX,
                            float* Pnm_minus1,
                            float* Pnm_minus2,
                            /* Output Arguments */
                            float* Pnm);
 
 
/* ========================================================================== */
/*                    SH and Beamforming related Functions                    */
/* ========================================================================== */
 
void getSHreal(/* Input Arguments */
               int order,
               float* dirs_rad,
               int nDirs,
               /* Output Arguments */
               float* Y);
 
void getSHreal_recur(/* Input Arguments */
                     int order,
                     float* dirs_rad,
                     int nDirs,
                     /* Output Arguments */
                     float* Y);
 
void getSHreal_part
(
    int order_start,
    int order_end,
    float* dirs_rad,
    int nDirs,
    float* Y  /* the SH weights: (order_end+1)^2 x nDirs */
);
 
void getSHcomplex(/* Input Arguments */
                  int order,
                  float* dirs_rad,
                  int nDirs,
                  /* Output Arguments */
                  float_complex* Y);
 
void complex2realSHMtx(/* Input Arguments */
                       int order,
                       /* Output Arguments */
                       float_complex* T_c2r);
 
void real2complexSHMtx(/* Input Arguments */
                       int order,
                       /* Output Arguments */
                       float_complex* T_r2c);
 
void complex2realCoeffs(/* Input Arguments */
                        int order,
                        float_complex* C_N,
                        int K,
                        /* Output Arguments */
                        float* R_N);
 
void getSHrotMtxReal(float R[3][3],
                     float* RotMtx,
                     int L);
 
void computeVelCoeffsMtx(/* Input Arguments */
                         int sectorOrder,
                         /* Output Arguments */
                         float_complex* A_xyz);
 
float computeSectorCoeffsEP(/* Input Arguments */
                            int orderSec,
                            float_complex*  A_xyz,
                            SECTOR_PATTERNS pattern,
                            float* sec_dirs_deg,
                            int nSecDirs,
                            /* Output Arguments */
                            float* sectorCoeffs);
 
float computeSectorCoeffsAP(/* Input Arguments */
                            int orderSec,
                            float_complex* A_xyz,
                            SECTOR_PATTERNS pattern,
                            float* sec_dirs_deg,
                            int nSecDirs,
                            /* Output Arguments */
                            float* sectorCoeffs);
 
void beamWeightsCardioid2Spherical(/* Input Arguments */
                                   int N,
                                   /* Output Arguments */
                                   float* b_n);
 
void beamWeightsDolphChebyshev2Spherical(/* Input Arguments */
                                         int N,
                                         int paramType,
                                         float arrayParam,
                                         /* Output Arguments */
                                         float* b_n);
 
void beamWeightsHypercardioid2Spherical(/* Input Arguments */
                                        int N,
                                        /* Output Arguments */
                                        float* b_n);
 
void beamWeightsMaxEV(/* Input Arguments */
                      int N,
                      /* Output Arguments */
                      float* b_n);
 
void beamWeightsVelocityPatternsReal(/* Input Arguments */
                                     int order,
                                     float* b_n,
                                     float azi_rad,
                                     float elev_rad,
                                     float_complex* A_xyz,
                                     /* Output Arguments */
                                     float* velCoeffs);
 
void beamWeightsVelocityPatternsComplex(/* Input Arguments */
                                        int order,
                                        float* b_n,
                                        float azi_rad,
                                        float elev_rad,
                                        float_complex* A_xyz,
                                        /* Output Arguments */
                                        float_complex* velCoeffs);
 
void rotateAxisCoeffsReal(/* Input arguments */
                          int order,
                          float* c_n,
                          float theta_0,
                          float phi_0,
                          /* Output arguments */
                          float* c_nm);          
 
void rotateAxisCoeffsComplex(/* Input arguments */
                             int order,
                             float* c_n,
                             float theta_0,
                             float phi_0,
                             /* Output arguments */
                             float_complex* c_nm);
 
void checkCondNumberSHTReal(/* Input arguments */
                            int order,
                            float* dirs_rad,
                            int nDirs,
                            float* w,
                            /* Output arguments */
                            float* cond_N);
 
int calculateGridWeights(/* Input arguments */
                         float* dirs_rad,
                         int nDirs,
                         int order,
                         /* Output arguments */
                         float* w);
 
 
/* ========================================================================== */
/*                     Localisation Functions in the SHD                      */
/* ========================================================================== */
 
void sphPWD_create(void ** const phPWD,
                   int order,
                   float* grid_dirs_deg,
                   int nDirs);
 
void sphPWD_destroy(void ** const phPWD);
 
void sphPWD_compute(/* Input arguments */
                    void* const hPWD,
                    float_complex *Cx,
                    int nSrcs,
                    /* Output arguments */
                    float* P_map,
                    int* peak_inds);
 
void sphMUSIC_create(void ** const phMUSIC,
                     int order,
                     float* grid_dirs_deg,
                     int nDirs);
 
void sphMUSIC_destroy(void ** const phMUSIC);
 
void sphMUSIC_compute(/* Input arguments */
                      void* const hMUSIC,
                      float_complex *Vn, 
                      int nSrcs,
                      /* Output arguments */
                      float* P_music,
                      int* peak_inds);
 
void sphESPRIT_create(void ** const phESPRIT,
                      int order);
 
void sphESPRIT_destroy(void ** const phESPRIT);
 
void sphESPRIT_estimateDirs(/* Input arguments */
                            void * const hESPRIT,
                            float_complex* Us,
                            int K,
                            /* Output arguments */
                            float* src_dirs_rad);
 
void generatePWDmap(/* Input arguments */
                    int order,
                    float_complex* Cx,
                    float_complex* Y_grid,
                    int nGrid_dirs,
                    /* Output arguments */
                    float* pmap);
 
void generateMVDRmap(/* Input arguments */
                     int order,
                     float_complex* Cx,
                     float_complex* Y_grid,
                     int nGrid_dirs,
                     float regPar,
                     /* Output arguments */
                     float* pmap,
                     float_complex* w_MVDR);
 
void generateCroPaCLCMVmap(/* Input arguments */
                           int order,
                           float_complex* Cx,
                           float_complex* Y_grid,
                           int nGrid_dirs,
                           float regPar,
                           float lambda,
                           /* Output arguments */
                           float* pmap);
 
void generateMUSICmap(/* Input arguments */
                      int order,
                      float_complex* Cx,
                      float_complex* Y_grid,
                      int nSources,
                      int nGrid_dirs,
                      int logScaleFlag,
                      /* Output arguments */
                      float* pmap);
 
void generateMinNormMap(/* Input arguments */
                        int order,
                        float_complex* Cx,
                        float_complex* Y_grid,
                        int nSources,
                        int nGrid_dirs,
                        int logScaleFlag,
                        /* Output arguments */
                        float* pmap);
 
 
/* ========================================================================== */
/*              Microphone/Hydrophone array processing functions              */
/* ========================================================================== */
 
void arraySHTmatrices(/* Input arguments */
                      ARRAY_SHT_OPTIONS method,
                      int order,
                      float amp_thresh_dB,
                      float_complex* H_array,
                      float* grid_dirs_deg,
                      int nBins,
                      int nMics,
                      int nGrid,
                      float* w_grid,
                      /* Output arguments */
                      float_complex* H_sht);
 
void arraySHTfilters(/* Input arguments */
                     ARRAY_SHT_OPTIONS method,
                     int order,
                     float amp_thresh_dB,
                     float_complex* H_array,
                     float* grid_dirs_deg,
                     int nFFT,
                     int nMics,
                     int nGrid,
                     float* w_grid,
                     /* Output arguments */
                     float* h_sht);
 
void arraySHTmatricesDiffEQ(/* Input arguments */
                            float_complex* H_sht,
                            float_complex* DCM,
                            float* freqVector,
                            float alias_freq_hz,
                            int nBins,
                            int order,
                            int nMics,
                            /* Output arguments */
                            float_complex* H_sht_eq);
 
void cylModalCoeffs(/* Input arguments */
                    int order,
                    double* kr,
                    int nBands,
                    ARRAY_CONSTRUCTION_TYPES arrayType,
                    /* Output arguments */
                    double_complex* b_N);
 
float sphArrayAliasLim(/* Input arguments */
                       float r,
                       float c,
                       int maxN);
 
void sphArrayNoiseThreshold(/* Input arguments */
                            int maxN,
                            int Nsensors,
                            float r,
                            float c,
                            ARRAY_CONSTRUCTION_TYPES arrayType,
                            double dirCoeff,
                            float maxG_db,
                            /* Output arguments */
                            float* f_lim);
 
void sphModalCoeffs(/* Input arguments */
                    int order,
                    double* kr,
                    int nBands,
                    ARRAY_CONSTRUCTION_TYPES arrayType,
                    double dirCoeff,
                    /* Output arguments */
                    double_complex* b_N);
 
void sphScattererModalCoeffs(/* Input arguments */
                             int order,
                             double* kr,
                             double* kR,
                             int nBands,
                             /* Output arguments */
                             double_complex* b_N);
 
void sphScattererDirModalCoeffs(/* Input arguments */
                                int order,
                                double* kr,
                                double* kR,
                                int nBands,
                                double dirCoeff,
                                /* Output arguments */
                                double_complex* b_N);
    
void sphDiffCohMtxTheory(/* Input arguments */
                         int order,
                         float* sensor_dirs_rad,
                         int N_sensors,
                         ARRAY_CONSTRUCTION_TYPES arrayType,
                         double dirCoeff,
                         double* kr,
                         int nBands,
                         /* Output arguments */
                         double* M_diffcoh);
 
void diffCohMtxMeas(/* Input arguments */
                    float_complex* H_array,
                    int nBins,
                    int N_sensors,
                    int nGrid,
                    float* w_grid,
                    /* Output arguments */
                    float_complex* M_diffcoh);
 
void diffCohMtxMeasReal(/* Input arguments */
                        float* H_array,
                        int N_sensors,
                        int nGrid,
                        float* w_grid,
                        /* Output arguments */
                        float* M_diffcoh);
 
void simulateCylArray(/* Input arguments */
                      int order,
                      double* kr,
                      int nBands,
                      float* sensor_dirs_rad,
                      int N_sensors,
                      float* src_dirs_deg,
                      int N_srcs,
                      ARRAY_CONSTRUCTION_TYPES arrayType,
                      /* Output arguments */
                      float_complex* H_array);
 
void simulateSphArray(/* Input arguments */
                      int order,
                      double* kr,
                      double* kR,
                      int nBands,
                      float* sensor_dirs_rad,
                      int N_sensors,
                      float* src_dirs_deg,
                      int N_srcs,
                      ARRAY_CONSTRUCTION_TYPES arrayType,
                      double dirCoeff,
                      /* Output arguments */
                      float_complex* H_array);
 
void evaluateSHTfilters(/* Input arguments */
                        int order,
                        float_complex* M_array2SH,
                        int nSensors,
                        int nBands,
                        float_complex* H_array,
                        int nDirs,
                        float_complex* Y_grid,
                        /* Output arguments */
                        float* cSH,
                        float* lSH);
 
 
#ifdef __cplusplus
} /* extern "C" */
#endif /* __cplusplus */
 
#endif /* __SAF_SH_H_INCLUDED__ */
 
 /* doxygen addtogroup SH */