Main header for the Spherical Harmonic Transform and Spherical Array Processing module (SAF_SH_MODULE) More...

#include "../saf_utilities/saf_utility_complex.h"

Macros
#define	ORDER2NSH(order) ((order+1)*(order+1))
	Converts spherical harmonic order to number of spherical harmonic components i.e: (order+1)^2.

#define	NSH2ORDER(nSH) ( (int)(sqrt((double)nSH)-0.999) )
	Converts number of spherical harmonic components to spherical harmonic order i.e: sqrt(nSH)-1.

Enumerations
enum	ARRAY_CONSTRUCTION_TYPES { ARRAY_CONSTRUCTION_OPEN , ARRAY_CONSTRUCTION_OPEN_DIRECTIONAL , ARRAY_CONSTRUCTION_RIGID , ARRAY_CONSTRUCTION_RIGID_DIRECTIONAL }
	Microphone/Hydrophone array construction types. More...

enum	SECTOR_PATTERNS { SECTOR_PATTERN_PWD , SECTOR_PATTERN_MAXRE , SECTOR_PATTERN_CARDIOID }
	Sector pattern designs for directionally-constraining sound-fields [1]. More...

enum	ARRAY_SHT_OPTIONS { ARRAY_SHT_DEFAULT , ARRAY_SHT_REG_LS , ARRAY_SHT_REG_LSHD }
	Microphone array to spherical harmonic domain conversion options. More...

Functions
void	unnorm_legendreP (int n, double x, int lenX, double y)
	Calculates unnormalised Legendre polynomials up to order N, for all values in vector x [1].

void	unnorm_legendreP_recur (int n, float x, int lenX, float Pnm_minus1, float Pnm_minus2, float Pnm)
	Calculates unnormalised Legendre polynomials up to order N, for all values in vector x.

void	getSHreal (int order, float dirs_rad, int nDirs, float Y)
	Computes real-valued spherical harmonics [1] for each given direction on the unit sphere.

void	getSHreal_recur (int order, float dirs_rad, int nDirs, float Y)
	Computes real-valued spherical harmonics [1] for each given direction on the unit sphere.

void	getSHreal_part (int order_start, int order_end, float dirs_rad, int nDirs, float Y)

void	getSHcomplex (int order, float dirs_rad, int nDirs, float_complex Y)
	Computes complex-valued spherical harmonics [1] for each given direction on the unit sphere.

void	complex2realSHMtx (int order, float_complex *T_c2r)
	Computes a complex to real spherical harmonic transform matrix.

void	real2complexSHMtx (int order, float_complex *T_r2c)
	Computes a real to complex spherical harmonic transform matrix.

void	complex2realCoeffs (int order, float_complex C_N, int K, float R_N)
	Converts SH coefficients from the complex to real basis.

void	getSHrotMtxReal (float R[3][3], float *RotMtx, int L)
	Generates a real-valued spherical harmonic rotation matrix [1] based on a 3x3 rotation matrix (see quaternion2rotationMatrix(), euler2rotationMatrix())

void	computeVelCoeffsMtx (int sectorOrder, float_complex *A_xyz)
	Computes the matrices which generate the coefficients of a beampattern of order (sectorOrder+1) that is essentially the product of a pattern of order=sectorOrder and a dipole.

float	computeSectorCoeffsEP (int orderSec, float_complex A_xyz, SECTOR_PATTERNS pattern, float sec_dirs_deg, int nSecDirs, float *sectorCoeffs)
	Computes beamforming matrices (sector coefficients) which, when applied to input SH signals, yield energy-preserving (EP) sectors.

float	computeSectorCoeffsAP (int orderSec, float_complex A_xyz, SECTOR_PATTERNS pattern, float sec_dirs_deg, int nSecDirs, float *sectorCoeffs)
	Computes beamforming matrices (sector coefficients) which, when applied to input SH signals, yield amplitude-preserving (EP) sectors.

void	beamWeightsCardioid2Spherical (int N, float *b_n)
	Generates spherical coefficients for generating cardioid beampatterns.

void	beamWeightsDolphChebyshev2Spherical (int N, int paramType, float arrayParam, float *b_n)
	Generates beamweights in the SHD for Dolph-Chebyshev beampatterns, with mainlobe and sidelobe control [1].

void	beamWeightsHypercardioid2Spherical (int N, float *b_n)
	Generates beamweights in the SHD for hypercardioid beampatterns.

void	beamWeightsMaxEV (int N, float *b_n)
	Generates beamweights in the SHD for maximum energy-vector beampatterns.

void	beamWeightsVelocityPatternsReal (int order, float b_n, float azi_rad, float elev_rad, float_complex A_xyz, float *velCoeffs)
	Generates beamforming coefficients for velocity patterns (REAL)

void	beamWeightsVelocityPatternsComplex (int order, float b_n, float azi_rad, float elev_rad, float_complex A_xyz, float_complex *velCoeffs)
	Generates beamforming coefficients for velocity patterns (COMPLEX)

void	rotateAxisCoeffsReal (int order, float c_n, float theta_0, float phi_0, float c_nm)
	Generates spherical coefficients for a rotated axisymmetric pattern (REAL)

void	rotateAxisCoeffsComplex (int order, float c_n, float theta_0, float phi_0, float_complex c_nm)
	Generates spherical coefficients for a rotated axisymmetric pattern (COMPLEX)

void	checkCondNumberSHTReal (int order, float dirs_rad, int nDirs, float w, float *cond_N)
	Computes the condition numbers for a least-squares SHT.

int	calculateGridWeights (float dirs_rad, int nDirs, int order, float w)
	Computes approximation of quadrature/integration weights for a given grid.

void	sphPWD_create (void *const phPWD, int order, float grid_dirs_deg, int nDirs)
	Creates an instance of a spherical harmonic domain implementation of the steer-response power (SRP) approach for computing power-maps, which can then be used for sound-field visualisation/DoA estimation purposes.

void	sphPWD_destroy (void **const phPWD)
	Destroys an instance of the spherical harmonic domain PWD implementation.

void	sphPWD_compute (void const hPWD, float_complex Cx, int nSrcs, float P_map, int peak_inds)
	Computes a power-map based on determining the energy of hyper-cardioid beamformers; optionally, also returning the grid indices corresponding to the N highest peaks (N=nSrcs)

void	sphMUSIC_create (void *const phMUSIC, int order, float grid_dirs_deg, int nDirs)
	Creates an instance of the spherical harmonic domain MUSIC implementation, which may be used for computing pseudo-spectrums for visualisation/DoA estimation purposes.

void	sphMUSIC_destroy (void **const phMUSIC)
	Destroys an instance of the spherical harmonic domain MUSIC implementation.

void	sphMUSIC_compute (void const hMUSIC, float_complex Vn, int nSrcs, float P_music, int peak_inds)
	Computes a pseudo-spectrum based on the MUSIC algorithm in the spherical harmonic domain; optionally returning the grid indices corresponding to the N highest peaks (N=nSrcs)

void	sphESPRIT_create (void **const phESPRIT, int order)
	Creates an instance of the spherical harmonic domain ESPRIT-based direction of arrival estimator.

void	sphESPRIT_destroy (void **const phESPRIT)
	Destroys an instance of the spherical harmonic domain ESPRIT-based direction of arrival estimator.

void	sphESPRIT_estimateDirs (void const hESPRIT, float_complex Us, int K, float *src_dirs_rad)
	Estimates the direction-of-arrival (DoA) based on the ESPRIT-based estimator, in the spherical harmonic domain.

void	generatePWDmap (int order, float_complex Cx, float_complex Y_grid, int nGrid_dirs, float *pmap)
	Generates a powermap based on the energy of a plane-wave decomposition (PWD) (i.e.

void	generateMVDRmap (int order, float_complex Cx, float_complex Y_grid, int nGrid_dirs, float regPar, float pmap, float_complex w_MVDR)
	Generates a powermap based on the energy of adaptive Minimum-Variance Distortion-less Response (MVDR) beamformers.

void	generateCroPaCLCMVmap (int order, float_complex Cx, float_complex Y_grid, int nGrid_dirs, float regPar, float lambda, float *pmap)
	(EXPERIMENTAL) Generates a powermap utilising the CroPaC LCMV post-filter described in [1]

void	generateMUSICmap (int order, float_complex Cx, float_complex Y_grid, int nSources, int nGrid_dirs, int logScaleFlag, float *pmap)
	Generates an activity-map based on the sub-space multiple-signal classification (MUSIC) method.

void	generateMinNormMap (int order, float_complex Cx, float_complex Y_grid, int nSources, int nGrid_dirs, int logScaleFlag, float *pmap)
	Generates an activity-map based on the sub-space minimum-norm (MinNorm) method.

void	arraySHTmatrices (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, float_complex H_sht)
	Computes matrices required to transform array signals into spherical harmonic signals (frequency-domain)

void	arraySHTfilters (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, float h_sht)
	Computes filters required to transform array signals into spherical harmonic signals (time-domain)

void	arraySHTmatricesDiffEQ (float_complex H_sht, float_complex DCM, float freqVector, float alias_freq_hz, int nBins, int order, int nMics, float_complex H_sht_eq)
	Diffuse-field equalisation of SHT matrices above the spatial aliasing frequency.

void	cylModalCoeffs (int order, double kr, int nBands, ARRAY_CONSTRUCTION_TYPES arrayType, double_complex b_N)
	Calculates the modal coefficients for open/rigid cylindrical arrays.

float	sphArrayAliasLim (float r, float c, int maxN)
	Returns a simple estimate of the spatial aliasing limit (the kR = maxN rule)

void	sphArrayNoiseThreshold (int maxN, int Nsensors, float r, float c, ARRAY_CONSTRUCTION_TYPES arrayType, double dirCoeff, float maxG_db, float *f_lim)
	Computes the frequencies (per order), at which the noise of a SHT of a SMA exceeds a specified maximum level.

void	sphModalCoeffs (int order, double kr, int nBands, ARRAY_CONSTRUCTION_TYPES arrayType, double dirCoeff, double_complex b_N)
	Calculates the modal coefficients for open/rigid spherical arrays.

void	sphScattererModalCoeffs (int order, double kr, double kR, int nBands, double_complex *b_N)
	Calculates the modal coefficients for a rigid spherical scatterer with omni-directional sensors.

void	sphScattererDirModalCoeffs (int order, double kr, double kR, int nBands, double dirCoeff, double_complex *b_N)
	Calculates the modal coefficients for a rigid spherical scatterer with directional sensors.

void	sphDiffCohMtxTheory (int order, float sensor_dirs_rad, int N_sensors, ARRAY_CONSTRUCTION_TYPES arrayType, double dirCoeff, double kr, int nBands, double *M_diffcoh)
	Calculates the theoretical diffuse coherence matrix for a spherical array.

void	diffCohMtxMeas (float_complex H_array, int nBins, int N_sensors, int nGrid, float w_grid, float_complex *M_diffcoh)
	Calculates the diffuse coherence matrices for an arbitrary array.

void	diffCohMtxMeasReal (float H_array, int N_sensors, int nGrid, float w_grid, float *M_diffcoh)
	Calculates the diffuse coherence matrices for an array that uses a broad-band real-valued basis.

void	simulateCylArray (int order, double kr, int nBands, float sensor_dirs_rad, int N_sensors, float src_dirs_deg, int N_srcs, ARRAY_CONSTRUCTION_TYPES arrayType, float_complex H_array)
	Simulates a cylindrical microphone array, returning the transfer functions for each (plane wave) source direction on the surface of the cylinder.

void	simulateSphArray (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, float_complex *H_array)
	Simulates a spherical microphone array, returning the transfer functions for each (plane wave) source direction on the surface of the sphere.

void	evaluateSHTfilters (int order, float_complex M_array2SH, int nSensors, int nBands, float_complex H_array, int nDirs, float_complex Y_grid, float cSH, float *lSH)
	Generates some objective measures, which evaluate the performance of spatial encoding filters.

Detailed Description

Main header for the Spherical Harmonic Transform and Spherical Array Processing module (SAF_SH_MODULE)

A collection of spherical harmonic related functions. Many of which have been derived from the MATLAB libraries found in [1-3].

See also: [1] https://github.com/polarch/Spherical-Harmonic-Transform Copyright (c) 2015, Archontis Politis, BSD-3-Clause License; [2] https://github.com/polarch/Array-Response-Simulator Copyright (c) 2015, Archontis Politis, BSD-3-Clause License; [3] https://github.com/polarch/Spherical-Array-Processing Copyright (c) 2016, Archontis Politis, BSD-3-Clause License

Author: Leo McCormack

Date: 22.05.2016

License: ISC

Definition in file saf_sh.h.

Macros

Enumerations

Functions

Detailed Description