HOA_SpeakerLayout.h

Go to the documentation of this file.

/*

HOA_SpeakerLayout.h -- Higher Order Ambisonic speaker layout class
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

Higher Order Ambisonic class for loading and parsing loudspeaker position information used by the "HOA_Decoder" class.
Loudspeaker layouts should be provided as textfiles folowing the following format:
-> A / indicates the start of a comment, which lasts until the end of the line (??????????????????????).
-> The Keywords CARTESIAN, SPHERICAL-DEGREES, SPHERICAL-RADIANS are used to specify the format of the provided speaker positions.
   The class will do necessary conversions to the internal representation in spherical radians.
   If no keyword is specified, spherical radians are assumed(??????????????????????).
-> Non-comment or non-keyword lines should contain speaker position information as three tab-separated coordinates.
   Each line will be interpreted as a new speaker.
Examples of parsable speaker layout files are provided with the code (.dat files).

*/

#ifndef HOA_SPEAKERLAYOUT_H
#define HOA_SPEAKERLAYOUT_H

#include "CSL_Core.h"
#include "Variable.h"
#include "CPoint.h"

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

*/

// a type to represent speaker position, relative to listener
typedef struct speaker 
{
    float coord1, coord2, coord3;
}; 

class HOA_SpeakerLayout {

private:
    unsigned int mNumSpeakers;          // the number of loudspeakers in the layout
    speaker *mSpeakers;                 // pointer to the loudspeakers
    char *file;                         // pointer to the speaker layout file
    void cartesianToSphericalRadians(); // convert speaker layout given in cartesian coordinates to spherical radians
    
public:
    
    // Constructors & destructor:
    HOA_SpeakerLayout();                // default constructor, uses regular tetrahedron with 4 speakers
    HOA_SpeakerLayout(char *filePath);  // reads loudspeaker layout from file
    ~HOA_SpeakerLayout();               // destructor
    
    int getNumSpeakers();               // getter for the number of loudspeakers in the layout
    speaker getSpeaker(int n);

    void limitSpeakers(int n) { mNumSpeakers = n; }; // ignore extra speakers if there are more than n defined


};

}

#endif

---