HOA_Utilities.h

Go to the documentation of this file.

/*

HOA_Utilities.h -- Higher Order Ambisonic utility classes
See the copyright notice and acknowledgment of authors in the file COPYRIGHT
Higher Order Ambisonic classes written by Jorge Castellanos, Graham Wakefield, Florian Hollerweger, 2005

Utility classes used by HOA_Encoder, MOA_Encoder, HOA_Rotator, MOA_Rotator, HOA_Decoder

*/

#ifndef HOA_UTILITIES_H
#define HOA_UTILITIES_H

#include "CSL_Core.h"

#define AMBI_INVSQRT2 (1/1.414213562)

namespace csl {

/*

CONVENTIONS USED IN THIS CODE:
------------------------------

***coordinate system***
Left oriented
Azimuth = 0 on the x/z plane and increasing towards the positive y direction
Elevation = 0 on x/y plane and increasing towards the positive z direction
Internal angle representation: spherical radians

***encoding convention***
following the Furse-Malham set (Ambisonic channel weighting for uniform energy distribution)

***abbreviations used in code and comments***
M   ... Ambisonic order (in uniform order system)
M_h ... horizontal Ambisonic order (in hybrid order systems)
M_v ... horizontal Ambisonic order (in hybrid order systems)
N   ... total number of Ambisonic encoded channels (horizontal and vertical)
N_h ... number of horizontal Ambisonic channels (in hybrid order systems)
N_v ... number of vertical Ambisonic channels (in hybrid order systems)
L   ... number of available loudspeakers

***ordering and naming of Ambisonic channels = spherical harmonics***
These conventions follow the ones used in the thesis by Jerome Daniel.
The 3rd order naming convention (which Daniel doesn't provide) follows the one used in the thesis of David Malham.
Watch out for different conventions in other papers!
index           0   1   2   3   4   5   6   7   8   9   10  11  12  13  14  15
M (order)       0   1   1   1   2   2   2   2   2   3   3   3   3   3   3   3
m (=M)          0   1   1   1   2   2   2   2   2   3   3   3   3   3   3   3
n               0   1   1   0   2   2   1   1   0   3   3   2   2   1   1   0
sigma           '1' 1   -1  '1' 1   -1  1   -1  '1' 1   -1  1   -1  1   -1  '1'
name            W   X   Y   Z   U   V   S   T   R   P   Q   N   O   L   M   K
hor/vert/omni   om  h   h   v   h   h   v   v   v   h   h   v   v   v   v   v

*/

// Ambisonic order structure (separate definition of horizontal and vertical order):
typedef struct { 
    unsigned horizontalOrder, verticalOrder, greaterOrder;
    bool isUniform;
} ambisonicOrder;

// returns the Ambisonic order from the number of Ambisonic channels: M = floor(sqrt(N) - 1)
// NOTE - only works for uniform horizontal and vertical order (whereas ambiguity occurs in hybrid order systems)!
unsigned int channelsToUniformOrder(const unsigned int channels);

// compares the horizontal and vertical Ambisonic order of a hybrid order system and returns the greater one
unsigned int getGreaterOrder(const ambisonicOrder order);

// returns the number of Ambisonic channels from a hybrid Ambisonic order: N = 2*M_h + 1 + (M_v + 1)^2 - (2*M_v + 1)
unsigned int orderToChannels(const ambisonicOrder order);

// returns the number of Ambisonic channels from a uniform Ambisonic order: N = (M+1)^2
unsigned int orderToChannels(unsigned int order);

// returns the number of horizontal Ambisonic channels from a hybrid Ambisonic order: N_h = 2*M_h + 1
unsigned int orderToHorizontalChannels(const ambisonicOrder order);

// returns the number of vertical Ambisonic channels from a hybrid Ambisonic order: N_v = (M_v + 1)^2 - (2*M_v + 1)
unsigned int orderToVerticalChannels(const ambisonicOrder order);

// returns a lookup table to map Ambisonic channel index to actually used Framestream channel
unsigned int *channelIndexer(const ambisonicOrder order);

// returns a lookup table to map actually used Framestream channel to Ambisonic channel index
unsigned int *invChannelIndexer(const ambisonicOrder order);

// utility function used in calculating the inverse of a matrix, used in HOA_Decoder for the pseudoinverse method
void SingularValueDecomposition(sample** a, int m, int n, sample* w, sample** v);

// utility function that calculates fuma encoding weights for a given order, azimuth and elevation.
void fumaEncodingWeights(sample *weights, const ambisonicOrder &order, sample &azimuth, sample &elevation);

// utility function that calculates fuma encoding weights for a given order, azimuth and elevation.
void fumaIndexedEncodingWeights(sample *weights, const ambisonicOrder &order, sample &azimuth, sample &elevation);

}

#endif

---