Integrate 3D functions from sources

README.md

@@ -2,13 +2,14 @@
 
 ##### Version :
 
-Hoa.lib 1.1 for Faust (<a title="Download" href="http://www.mshparisnord.fr/hoalibrary/en/downloads/" target="_blank">Download</a>). The hoa.lib file contains the high order ambisonics functions in FAUST. This file should already be included in the last FAUST distribution. You just need to include hoa.lib before coding to use it. 
+Hoa.lib 1.3 for Faust (<a title="Download" href="http://www.mshparisnord.fr/hoalibrary/en/downloads/" target="_blank">Download</a>). The hoa.lib file contains the high order ambisonics functions in FAUST. This version  isn't included in the Faust distribution (for now).
+Home of the project : <a title="https://framagit.org/wargreen/hoalibrary-faust" href="https://framagit.org/wargreen/hoalibrary-faust" target="_blank">https://framagit.org/wargreen/hoalibrary-faust</a>
 
 ![Image Faust](https://raw.github.com/CICM/HoaLibrary/master/Ressources/PhotoFaust.png "Faust Scene")
 
 ##### Authors :
 
-Julien Colafrancesco, Pierre Guillot, Eliott Paris
+Julien Colafrancesco, Pierre Guillot, Eliott Paris, Wargreen
 
 ##### Licence : 
 
@@ -30,3 +31,6 @@ The hoa.library in under the <a title="GNU" href="http://www.gnu.org/copyleft/gp
 
 - rotate : applies a rotation of the sound field.
 
+- encoder3D : encodes a signal in the 3D circular harmonics domain depending on an order of decomposition and two angle.
+
+- optimBasic3D, optimMaxRe3D, optimInPhase3D : weights the 3D circular harmonics signals depending to the ambisonics optimization. It can be "basic" for no optimization, "maxRe" or "inPhase".

hoa.lib

@@ -204,4 +204,121 @@ with
 
 // Usage : n is the order, a the angle in radiant
 // Exemple : rotate(3, angle)
-// Informations : It rotates the sound field.
+// Informations : It rotates the sound field.
+
+
+
+//----------------------------------------------------------------------------//
+//---------------------------- 3D functions ----------------------------------//
+//----------------------------------------------------------------------------//
+
+
+//------------------------- 3D ambisonic encoder -----------------------------//
+
+
+encoder3D(N, x, theta, phi) = par(i, (N+1) * (N+1), x * y(degree(i), order(i), theta, phi))
+with
+{
+	// The degree l of the harmonic[l, m]	
+	degree(index)  = int(sqrt(index));
+	// The order m of the harmonic[l, m]	
+	order(index)   = int(index - int(degree(index) * int(degree(index) + 1)));
+
+	// The spherical harmonics
+	y(l, m, theta, phi) =  e(m, theta) * k(l, m) * p(l, m, cos(phi + PI * 0.5))
+	with
+	{	
+		// The associated Legendre polynomial
+		// If l = 0   => p = 1
+		// If l = m   => p = -1 * (2 * (l-1) + 1) * sqrt(1 - cphi*cphi) * p(l-1, l-1, cphi)
+		// If l = m+1 => p = phi * (2 * (l-1) + 1) * p(l-1, l-1, cphi)
+		// Else => p = (cphi * (2 * (l-1) + 1) * p(l-1, abs(m), cphi) - ((l-1) + abs(m)) * p(l-2, abs(m), cphi)) / ((l-1) - abs(m) + 1)
+		p(l, m, cphi) = pcalcul(((l != 0) & (l == abs(m))) + ((l != 0) & (l == abs(m)+1)) * 2 + ((l != 0) & (l != abs(m)) & (l != abs(m)+1)) * 3, l, m, cphi)
+		with
+		{
+			pcalcul(0, l, m, cphi) = 1;
+			pcalcul(1, l, m, cphi) = -1 * (2 * (l-1) + 1) * sqrt(1 - cphi*cphi) * p(l-1, l-1, cphi);
+			pcalcul(2, l, m, cphi) = cphi * (2 * (l-1) + 1) * p(l-1, l-1, cphi);
+			pcalcul(s, l, m, cphi) = (cphi * (2 * (l-1) + 1) * p(l-1, abs(m), cphi) - ((l-1) + abs(m)) * p(l-2, abs(m), cphi)) / ((l-1) - abs(m) + 1);
+		};	
+
+		// The exponential imaginary
+		// If m > 0 => e^i*m*theta = cos(m * theta)
+		// If m < 0 => e^i*m*theta = sin(-m * theta)
+		// If m = 0 => e^i*m*theta = 1
+		e(m, theta) = ecalcul((m > 0) * 2 + (m < 0), m, theta)
+		with 
+		{
+			ecalcul(2, m, theta) = cos(m * theta);
+			ecalcul(1, m, theta) = sin(abs(m) * theta);
+			ecalcul(s, m, theta) = 1;
+		}; 
+
+		// The normalization
+		// If m  = 0 => k(l, m) = 1
+		// If m != 0 => k(l, m) = sqrt((l - abs(m))! / l + abs(m))!) * sqrt(2)
+		k(l, m) = kcalcul((m != 0), l, m)
+		with
+		{	
+			kcalcul(0, l, m) = 1;
+			kcalcul(1, l, m) = sqrt(fact(l - abs(m)) / fact(l + abs(m))) * sqrt(2)
+			with
+			{
+				fact(0) = 1;
+				fact(n) = n * fact(n-1);
+			};
+		};
+
+
+	};
+};
+
+// Usage : n is the order, x the signal, theta and phi the angle of azimuth and elevation in radiant
+// Exemple : HoaEncoder3D(3, _, azimuth, elevation)
+// Informations : It encode the signal in a 3D 
+
+
+//----------------------- 3D basic optimisation ------------------------------//
+
+optimBasic3D(N) = par(i, (N+1) * (N+1), _);
+
+// Usage : n is the order
+// Exemple : optimBasic3D(3)
+// Informations : The basic optimization has no effect and should be used for a perfect circle of loudspeakers with one listener at the perfect center loudspeakers array.
+
+
+//----------------------------- 3D MaxRe -------------------------------------//
+
+optimMaxRe3D(N) = par(i, (N+1) * (N+1), MaxRe(N, degree(i), _))
+with 
+{
+	// The degree l of the harmonic[l, m]	
+	degree(index)  = int(sqrt(index));
+   	MaxRe(N, l, _)= _ * cos(l  / (2*N+2) * PI);
+};
+
+// Usage : n is the order
+// Exemple : optimMaxRe3D(3)
+// Informations : The maxRe optimization optimize energy vector. It should be used for an auditory confined in the center of the loudspeakers array.
+
+
+//----------------------------3D inPhase--------------------------------------//
+
+optimInPhase3D(N) = par(i, (N+1) * (N+1), InPhase(N, degree(i), _))
+with 
+{
+	// The degree l of the harmonic[l, m]	
+	degree(index)  = int(sqrt(index));
+   	InPhase(N, l, _)= _ * (fact(N) * fact(N)) / (fact(N - l) * fact(N + l))
+	with
+	{
+		fact(0) = 1;
+		fact(n) = n * fact(n-1);
+	};
+};
+
+// Usage : n is the order
+// Exemple : optimInPhase3D(3)
+// Informations : The inPhase Optimization optimize energy vector and put all loudspeakers signals in phase. It should be used for an auditory
+
+