hoa.lib

//################################### hoa.lib ############################################
// Faust library for high order ambisonic. Its official prefix is `ho`.
//########################################################################################

/************************************************************************
 ************************************************************************
FAUST library file
Copyright (C) 2003-2012 GRAME, Centre National de Creation Musicale
----------------------------------------------------------------------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with the GNU C Library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

EXCEPTION TO THE LGPL LICENSE : As a special exception, you may create a
larger FAUST program which directly or indirectly imports this library
file and still distribute the compiled code generated by the FAUST
compiler, or a modified version of this compiled code, under your own
copyright and license. This EXCEPTION TO THE LGPL LICENSE explicitly
grants you the right to freely choose the license for the resulting
compiled code. In particular the resulting compiled code has no obligation
to be LGPL or GPL. For example you are free to choose a commercial or
closed source license or any other license if you decide so.

 ************************************************************************
 ************************************************************************/

declare name "High Order Ambisonics library";
declare author "Pierre Guillot";
declare author "Eliott Paris";
declare author "Julien Colafrancesco";
declare author "Wargreen";
declare copyright "2012-2013 Guillot, Paris, Colafrancesco, CICM labex art H2H, U. Paris 8, 2019 Wargreen";

ma = library("maths.lib");
si = library("signals.lib");

//============================Encoding/decoding Functions=================================
//========================================================================================

//----------------------`(ho.)encoder`---------------------------------
// Ambisonic encoder. Encodes a signal in the circular harmonics domain
// depending on an order of decomposition and an angle.
//
// #### Usage
//
// ```
// encoder(n, x, a) : _
// ```
//
// Where:
//
// * `n`: the order
// * `x`: the signal
// * `a`: the angle
//----------------------------------------------------------------
encoder(0, x, a) = x;
encoder(n, x, a) = encoder(n-1, x, a), x*sin(n*a), x*cos(n*a);


//--------------------------`(ho.)decoder`--------------------------------
// Decodes an ambisonics sound field for a circular array of loudspeakers.
//
// #### Usage
//
// ```
// _ : decoder(n, p) : _
// ```
//
// Where:
//
// * `n`: the order
// * `p`: the number of speakers
//
// #### Note
//
// Number of loudspeakers must be greater or equal to 2n+1. It's preferable
// to use 2n+2 loudspeakers.
//-------------------------------------------------------------------
decoder(n, p) = par(i, 2*n+1, _) <: par(i, p, speaker(n, 2*ma.PI*i/p))
with {
   speaker(n,a)	= /(2), par(i, 2*n, _), encoder(n,2/(2*n+1),a) : si.dot(2*n+1);
};


//-----------------------`(ho.)decoderStereo`------------------------
// Decodes an ambisonic sound field for stereophonic configuration.
// An "home made" ambisonic decoder for stereophonic restitution
// (30° - 330°) : Sound field lose energy around 180°. You should
// use `inPhase` optimization with ponctual sources.
// #### Usage
//
// ```
// _ : decoderStereo(n) : _
// ```
//
// Where:
//
// * `n`: the order
//--------------------------------------------------------------
decoderStereo(n) = decoder(n, p) <: (par(i, 2*n+2, gainLeft(360 * i / p)) :> _),
	(par(i, 2*n+2, gainRight(360 * i / p)) :> _)
with {
	p = 2*n+2;

   	gainLeft(a) = _ * sin(ratio_minus + ratio_cortex)
	with {
		ratio_minus = ma.PI*.5 * abs((30 + a) / 60 * ((a <= 30)) + (a - 330) / 60 * (a >= 330));
		ratio_cortex= ma.PI*.5 * abs((120 + a) / 150 * (a > 30) * (a <= 180));
	};

	gainRight(a) = _ * sin(ratio_minus + ratio_cortex)
	with {
		ratio_minus = ma.PI*.5 * abs((390 - a) / 60 * (a >= 330) + (30 - a) / 60 * (a <= 30));
		ratio_cortex= ma.PI*.5 * abs((180 - a) / 150 * (a < 330) * (a >= 180));
	};
};


//============================Optimization Functions======================================
// Functions to weight the circular harmonics signals depending to the
// ambisonics optimization.
// It can be `basic` for no optimization, `maxRe` or `inPhase`.
//========================================================================================


//----------------`(ho.)optimBasic`-------------------------
// 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.
//
// #### Usage
//
// ```
// _ : optimBasic(n) : _
// ```
//
// Where:
//
// * `n`: the order
//-----------------------------------------------------
optimBasic(n) = par(i, 2*n+1, _);


//----------------`(ho.)optimMaxRe`-------------------------
// The maxRe optimization optimizes energy vector. It should be used for an
// auditory confined in the center of the loudspeakers array.
//
// #### Usage
//
// ```
// _ : optimMaxRe(n) : _
// ```
//
// Where:
//
// * `n`: the order
//-----------------------------------------------------
optimMaxRe(n) = par(i, 2*n+1, optim(i, n, _))
 with {
   	optim(i, n, _)= _ * cos(indexabs / (2*n+1) * ma.PI)
	with {
		numberOfharmonics = 2 *n + 1;
		indexabs = (int)((i - 1) / 2 + 1);
	};
};


//----------------`(ho.)optimInPhase`-------------------------
//  The inPhase Optimization optimizes energy vector and put all loudspeakers signals
// in phase. It should be used for an auditory.
//
// #### Usage
//
// ```
// _ : optimInPhase(n) : _
// ```
//
// Where:
//
// * `n`: the order
//-----------------------------------------------------
optimInPhase(n)	= par(i, 2*n+1, optim(i, n, _))
with {
   	optim(i, n, _)= _ * (fact(n)^2.) / (fact(n+indexabs) * fact(n-indexabs))
	with {
		indexabs = (int)((i - 1) / 2 + 1);
		fact(0) = 1;
		fact(n) = n * fact(n-1);
	};
};


//----------------`(ho.)wider`-------------------------
// Can be used to wide the diffusion of a localized sound. The order
// depending signals are weighted and appear in a logarithmic way to
// have linear changes.
//
// #### Usage
//
// ```
// _ : wider(n,w) : _
// ```
//
// Where:
//
// * `n`: the order
// * `w`: the width value between 0 - 1
//-----------------------------------------------------
wider(n, w)	= par(i, 2*n+1, perform(n, w, i, _))
with {
	perform(n, w, i, _) = _ * (log(n+1) * (1 - w) + 1) * clipweight
	with {
		clipweight = weighter(n, w, i) * (weighter(n, w, i) > 0) * (weighter(n, w, i) <= 1) + (weighter(n, w, i) > 1)
		with {
			weighter(n, w, 0) = 1.;
			weighter(n, w, i) = (((w * log(n+1)) - log(indexabs)) / (log(indexabs+1) - log(indexabs)))
			with {
				indexabs = (int)((i - 1) / 2 + 1);
			};
		};
	};
};


//----------------`(ho.)map`-------------------------
// It simulates the distance of the source by applying a gain
// on the signal and a wider processing on the soundfield.
//
// #### Usage
//
// ```
// map(n, x, r, a)
// ```
//
// Where:
//
// * `n`: the order
// * `x`: the signal
// * `r`: the radius
// * `a`: the angle in radian
//-----------------------------------------------------
map(n, x, r, a)	= encoder(n, x * volume(r), a) : wider(n, ouverture(r))
with {
	volume(r) = 1. / (r * r * (r > 1) + (r <= 1));
	ouverture(r) = r * (r < 1) + (r >= 1);
};


//----------------`(ho.)rotate`-------------------------
// Rotates the sound field.
//
// #### Usage
//
// ```
// _ : rotate(n, a) : _
// ```
//
// Where:
//
// * `n`: the order
// * `a`: the angle in radian
//-----------------------------------------------------
rotate(n, a) = par(i, 2*n+1, _) <: par(i, 2*n+1, rotation(i, a))
with {
	rotation(i, a) = (par(j, 2*n+1, gain1(i, j, a)), par(j, 2*n+1, gain2(i, j, a)), par(j, 2*n+1, gain3(i, j, a)) :> _)
	with {
		indexabs = (int)((i - 1) / 2 + 1);
		gain1(i, j, a) = _ * cos(a * indexabs) * (j == i);
		gain2(i, j, a) = _ * sin(a * indexabs) * (j-1 == i) * (j != 0) * (i%2 == 1);
		gain3(i, j, a) = (_ * sin(a * indexabs)) * (j+1 == i) * (j != 0) * (i%2 == 0) * (-1);
	};
};


//============================3D Functions================================================
//========================================================================================

//----------------------`(ho.)encoder3D`---------------------------------
// Ambisonic encoder. Encodes a signal in the circular harmonics domain
// depending on an order of decomposition, an angle and an elevation.
//
// #### Usage
//
// ```
// encoder3D(n, x, a, e) : _
// ```
//
// Where:
//
// * `n`: the order
// * `x`: the signal
// * `a`: the angle
// * `e`: the elevation
//----------------------------------------------------------------

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 + ma.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);
			};
		};		
	};
};


//----------------`(ho.)optimBasic3D`-------------------------
// The basic optimization has no effect and should be used for a perfect
// sphere of loudspeakers with one listener at the perfect center loudspeakers
// array.
//
// #### Usage
//
// ```
// _ : optimBasic3D(n) : _
// ```
//
// Where:
//
// * `n`: the order
//-----------------------------------------------------

optimBasic3D(N) = par(i, (N+1) * (N+1), _);


//----------------`(ho.)optimMaxRe3D`-------------------------
// The maxRe optimization optimize energy vector. It should be used for an
// auditory confined in the center of the loudspeakers array.
//
// #### Usage
//
// ```
// _ : optimMaxRe3D(n) : _
// ```
//
// Where:
//
// * `n`: the order
//-----------------------------------------------------

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) * ma.PI);
};


//----------------`(ho.)optimInPhase3D`-------------------------
// The inPhase Optimization optimizes energy vector and put all loudspeakers signals
// in phase. It should be used for an auditory.
//
// #### Usage
//
// ```
// _ : optimInPhase3D(n) : _
// ```
//
// Where:
//
// * `n`: the order
//-----------------------------------------------------

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);
	};
};