From 63119f4a629f23e53334fbd5a11ca856e04bd302 Mon Sep 17 00:00:00 2001
From: Joseph Anderson <joanders@uw.edu>
Date: Thu, 22 Jul 2021 14:42:53 -0700
Subject: [PATCH] add: FoaMu, FoaNF

Two new FOA soundfield indicators:

- FoaMu - indicates how much like a travelling wave: mu.real.cos

- FoaNF - estimates FOA radius
---
 Classes/ATKAnalyze.sc                  | 136 +++++++++++++++++++++++++
 Classes/AtkFoa.sc                      |  28 ++++-
 HelpSource/Classes/AtkFoa.schelp       |  20 ++++
 HelpSource/Classes/AtkHoa.schelp       |   2 +-
 HelpSource/Classes/FoaAlpha.schelp     |   2 +-
 HelpSource/Classes/FoaAnalyze.schelp   |   4 +
 HelpSource/Classes/FoaBeta.schelp      |   2 +-
 HelpSource/Classes/FoaGamma.schelp     |   2 +-
 HelpSource/Classes/FoaMu.schelp        |  40 ++++++++
 HelpSource/Classes/FoaNF.schelp        |  40 ++++++++
 HelpSource/Classes/FoaThetaPhiA.schelp |   2 +-
 HelpSource/Classes/FoaThetaPhiR.schelp |   2 +-
 12 files changed, 273 insertions(+), 7 deletions(-)
 create mode 100644 HelpSource/Classes/FoaMu.schelp
 create mode 100644 HelpSource/Classes/FoaNF.schelp

diff --git a/Classes/ATKAnalyze.sc b/Classes/ATKAnalyze.sc
index ec7f695..c7c21a3 100644
--- a/Classes/ATKAnalyze.sc
+++ b/Classes/ATKAnalyze.sc
@@ -54,9 +54,11 @@
 // 	Class: FoaAlpha
 // 	Class: FoaBeta
 // 	Class: FoaGamma
+// 	Class: FoaMu
 //
 // 	Class: FoaThetaPhiA
 // 	Class: FoaThetaPhiR
+// 	Class: FoaNF
 //
 // 	Class: FoaIa
 // 	Class: FoaIr
@@ -941,6 +943,47 @@ FoaGamma : FoaEval {
 }
 
 
+// FOA Active Admittance Balance Angle: Mu
+FoaMu : FoaEval {
+	*ar { |in, size = 2048, method = \instant|
+		var p, u;
+		var pReIm, wp, ia, magIa;
+		var wpSquared, magIaSquared;
+		var normFac;
+
+		in = this.checkChans(in);
+		p = 2.sqrt * in[0];  // w * 2.sqrt = pressure
+		u = in[1..3];  // [x, y, z] = velocity (vector)
+
+		case(
+			{ method == \instant }, {
+				pReIm = HilbertW.ar(p, size);
+				wp = pReIm.squared.sum;
+				wpSquared = wp.squared;
+
+				ia = HilbertW.ar(u, size).collect({ |item|
+					(pReIm * item).sum
+				});
+				magIaSquared = ia.squared.sum;
+				magIa = magIaSquared.sqrt;
+
+				^atan2(wpSquared - magIaSquared, (2 * wp * magIa) + DC.ar(FoaEval.reg))
+			},
+			{ method == \average }, {
+				normFac = 2 * size.reciprocal;
+
+				wp = normFac * RunningSum.ar(p.squared, size);
+				wpSquared = wp.squared;
+				ia = normFac * RunningSum.ar(p * u, size);
+				magIaSquared = ia.squared.sum;
+				magIa = magIaSquared.sqrt;
+
+				^atan2(wpSquared - magIaSquared, (2 * wp * magIa) + DC.ar(FoaEval.reg))
+			}
+		)
+	}
+}
+
 //--
 // "Third party" indicators go here....
 
@@ -1071,6 +1114,73 @@ FoaThetaPhiR : FoaEval {
 }
 
 
+//------------------------------------------------------------------------
+// FOA SOUNDFIELD RADIUS
+
+// FOA Nearfield (Spherical) Radius
+FoaNF : FoaEval {
+	*ar { |in, size = 2048, method = \instant|
+		var p, u;
+		var pInteg, uInteg;
+		var pReIm, wp, ia, aa;
+		var pReImInteg, wpInteg, iaInteg, aaInteg;
+		var normFac;
+		var radius;
+
+		var freq = AtkFoa.speedOfSound / 2pi;  // 2nd order HP, precondition
+		var a0 = 0.5;  // integrator
+		var a1 = 0.5;
+		var b1 = 1.0;
+
+
+		in = this.checkChans(in);
+		p = 2.sqrt * in[0];  // w * 2.sqrt = pressure
+		u = in[1..3];  // [x, y, z] = velocity (vector)
+
+		pInteg = FOS.ar(HPF.ar(p, freq), a0, a1, b1);  // precondition, integrate p
+		uInteg = HPF.ar(u, freq);  // precondition u
+
+		case(
+			{ method == \instant }, {
+				pReIm = HilbertW.ar(p, size);
+				wp = pReIm.squared.sum;
+				ia = HilbertW.ar(u, size).collect({ |item|
+					(pReIm * item).sum
+				});
+				aa = ia / (wp + DC.ar(FoaEval.reg));
+
+				pReImInteg = HilbertW.ar(pInteg, size);
+				wpInteg = pReImInteg.squared.sum;
+				iaInteg = HilbertW.ar(uInteg, size).collect({ |item|
+					(pReImInteg * item).sum
+				});
+				aaInteg = iaInteg / (wpInteg + DC.ar(FoaEval.reg));
+
+				radius = (AtkFoa.speedOfSound * SampleDur.ir) * (aa.squared.sum / ((aa * aaInteg).sum + DC.ar(FoaEval.reg)));
+
+				^radius
+			},
+			{ method == \average }, {
+				normFac = 2 * size.reciprocal;
+
+				wp = normFac * RunningSum.ar(p.squared, size);
+				ia = normFac * RunningSum.ar(p * u, size);
+				aa = ia / (wp + DC.ar(FoaEval.reg));
+
+				wpInteg = normFac * RunningSum.ar(pInteg.squared, size);
+				iaInteg = normFac * RunningSum.ar(pInteg * uInteg, size);
+				aaInteg = iaInteg / (wpInteg + DC.ar(FoaEval.reg));
+
+				radius = (AtkFoa.speedOfSound * SampleDur.ir) * (aa.squared.sum / ((aa * aaInteg).sum + DC.ar(FoaEval.reg)));
+
+				^radius
+			}
+		)
+	}
+}
+
+
+
 //------------------------------------------------------------------------
 // FOA INTENSITY - vectors
 
@@ -1720,6 +1830,19 @@ FoaAnalyze : FoaEval {
 				)
 			},
 
+			\mu, {
+
+				ugen = FoaMu;
+				argDefaults = [2048, \instant];
+
+				argDict = this.argDict(ugen, args, argDefaults);
+
+				^ugen.ar(
+					in,
+					argDict.at(\size), argDict.at(\method)
+				)
+			},
+
 			\thetaPhia, {
 
 				ugen = FoaThetaPhiA;
@@ -1746,6 +1869,19 @@ FoaAnalyze : FoaEval {
 				)
 			},
 
+			\NF, {
+
+				ugen = FoaNF;
+				argDefaults = [2048, \instant];
+
+				argDict = this.argDict(ugen, args, argDefaults);
+
+				^ugen.ar(
+					in,
+					argDict.at(\size), argDict.at(\method)
+				)
+			},
+
 			\Ia, {
 
 				ugen = FoaIa;
diff --git a/Classes/AtkFoa.sc b/Classes/AtkFoa.sc
index d4254a7..73a8a51 100644
--- a/Classes/AtkFoa.sc
+++ b/Classes/AtkFoa.sc
@@ -1,9 +1,23 @@
 AtkFoa {
-	classvar <refRadius;
+	classvar <speedOfSound, <refRadius;
 	classvar <defaultOrder;
 	classvar format;
 
 	*initClass {
+		speedOfSound = 333.0;  // (m/s)
+		/*
+		NOTE: this value is implied by the current setting of the cutoff
+		frequency (53 Hz) found in the sc3-plugins code for FoaProximity & FoaNFC
+
+		freq = speedOfSound / 2pi  // wavenumber = 1
+		speedOfSound = 53 * 2pi  // 333.0
+
+		this value is the speed of sound @ 3C
+		https://www.weather.gov/epz/wxcalc_speedofsound
+
+		TODO: consider updating sc3-plugins to align with
+		AtkHoa.speedOfSound = 343.0
+		*/
 		refRadius = inf;  // reference encoding / decoding radius, i.e., basic radius
 
 		defaultOrder = 1;
@@ -22,4 +36,16 @@ AtkFoa {
 	*normalisation {
 		^format[1]
 	}
+
+	*setSpeedOfSound { |mps|
+		var mpsAsFloat;
+
+		mpsAsFloat = mps.asFloat;
+		/*
+		NOTE: this is a convenience value, only effecting FoaNF (radial analysis);
+		does NOT currently update FoaProximity & FoaNFC
+		*/
+		speedOfSound = mpsAsFloat;
+		^mpsAsFloat
+	}
 }
diff --git a/HelpSource/Classes/AtkFoa.schelp b/HelpSource/Classes/AtkFoa.schelp
index 8539002..b159e7e 100644
--- a/HelpSource/Classes/AtkFoa.schelp
+++ b/HelpSource/Classes/AtkFoa.schelp
@@ -60,6 +60,26 @@ AtkFoa.refRadius
 ::
 
 
+METHOD:: speedOfSound
+Ambisonic Toolkit (FOA) speed of sound, in meters per second.
+
+code::
+AtkFoa.speedOfSound
+::
+
+
+METHOD:: setSpeedOfSound
+Setter for link::#*speedOfSound::.
+
+note::
+Setting this value only effects the speed of sound for soundfield analysis via link::Classes/FoaNF::, and does NOT currently update the value used by link::Classes/FoaProximity:: & link::Classes/FoaNFC::.
+::
+
+
+ARGUMENT:: mps
+Speed of sound, in meters per second.
+
+
 
 EXAMPLES::
 
diff --git a/HelpSource/Classes/AtkHoa.schelp b/HelpSource/Classes/AtkHoa.schelp
index 4e30ec5..648ea59 100644
--- a/HelpSource/Classes/AtkHoa.schelp
+++ b/HelpSource/Classes/AtkHoa.schelp
@@ -90,7 +90,7 @@ Radius, in meters.
 
 
 METHOD:: speedOfSound
-Ambisonic Toolkit speed of sound, in meters per second.
+Ambisonic Toolkit (HOA) speed of sound, in meters per second.
 
 code::
 AtkHoa.speedOfSound
diff --git a/HelpSource/Classes/FoaAlpha.schelp b/HelpSource/Classes/FoaAlpha.schelp
index a52621d..f5af54a 100644
--- a/HelpSource/Classes/FoaAlpha.schelp
+++ b/HelpSource/Classes/FoaAlpha.schelp
@@ -1,7 +1,7 @@
 CLASS:: FoaAlpha
 summary:: First Order Ambisonic (FOA) Soundfield Active-Reactive Intensity Balance
 categories:: Libraries>Ambisonic Toolkit>UGens>FOA>Analyzer, UGens>Multichannel>Ambisonics, UGens>Analysis>Ambisonics
-related:: Classes/FoaBeta, Classes/FoaGamma, Classes/FoaMagIa, Classes/FoaMagIr
+related:: Classes/FoaBeta, Classes/FoaGamma, Classes/FoaMu, Classes/FoaMagIa, Classes/FoaMagIr
 
 DESCRIPTION::
 Return the emphasis::Active-Reactive Intensity Balance:: of a first order ambisonic (B-format) signal, in radians.
diff --git a/HelpSource/Classes/FoaAnalyze.schelp b/HelpSource/Classes/FoaAnalyze.schelp
index d1352af..ee5e209 100644
--- a/HelpSource/Classes/FoaAnalyze.schelp
+++ b/HelpSource/Classes/FoaAnalyze.schelp
@@ -35,6 +35,7 @@ definitionList::
 ## code:: 'alpha' :: || link::Classes/FoaAlpha::
 ## code:: 'beta' :: || link::Classes/FoaBeta::
 ## code:: 'gamma' :: || link::Classes/FoaGamma::
+## code:: 'mu' :: || link::Classes/FoaMu::
 
 ## Soundfield Energies
 ## code:: 'Wp' :: || link::Classes/FoaWp::
@@ -60,6 +61,9 @@ definitionList::
 ## code:: 'thetaPhiA' :: || link::Classes/FoaThetaPhiA::
 ## code:: 'thetaPhiR' :: || link::Classes/FoaThetaPhiR::
 
+## Soundfield Radius
+## code:: 'NF' :: || link::Classes/FoaNF::
+
 ## Soundfield Intensities - vectors
 ## code:: 'Ia' :: || link::Classes/FoaIa::
 ## code:: 'Ir' :: || link::Classes/FoaIr::
diff --git a/HelpSource/Classes/FoaBeta.schelp b/HelpSource/Classes/FoaBeta.schelp
index 292541a..26e9772 100644
--- a/HelpSource/Classes/FoaBeta.schelp
+++ b/HelpSource/Classes/FoaBeta.schelp
@@ -1,7 +1,7 @@
 CLASS:: FoaBeta
 summary:: First Order Ambisonic (FOA) Soundfield Potential-Kinetic Energy Balance
 categories:: Libraries>Ambisonic Toolkit>UGens>FOA>Analyzer, UGens>Multichannel>Ambisonics, UGens>Analysis>Ambisonics
-related:: Classes/FoaBeta, Classes/FoaGamma, Classes/FoaWd, Classes/FoaMagI
+related:: Classes/FoaAlpha, Classes/FoaGamma, Classes/FoaMu, Classes/FoaWd, Classes/FoaMagI
 
 DESCRIPTION::
 Return the emphasis::Potential-Kinetic Energy Balance:: of a first order ambisonic (B-format) signal, in radians.
diff --git a/HelpSource/Classes/FoaGamma.schelp b/HelpSource/Classes/FoaGamma.schelp
index 470fa1e..d013c2d 100644
--- a/HelpSource/Classes/FoaGamma.schelp
+++ b/HelpSource/Classes/FoaGamma.schelp
@@ -1,7 +1,7 @@
 CLASS:: FoaGamma
 summary:: First Order Ambisonic (FOA) Soundfield Active-Reactive Intensity Alignment
 categories:: Libraries>Ambisonic Toolkit>UGens>FOA>Analyzer, UGens>Multichannel>Ambisonics, UGens>Analysis>Ambisonics
-related:: Classes/FoaAlpha, Classes/FoaGamma, Classes/FoaIa, Classes/FoaIr
+related:: Classes/FoaAlpha, Classes/FoaBeta, Classes/FoaMu, Classes/FoaIa, Classes/FoaIr
 
 DESCRIPTION::
 Return the emphasis::Active-Reactive Intensity Alignment:: of a first order ambisonic (B-format) signal, in radians.
diff --git a/HelpSource/Classes/FoaMu.schelp b/HelpSource/Classes/FoaMu.schelp
new file mode 100644
index 0000000..5952916
--- /dev/null
+++ b/HelpSource/Classes/FoaMu.schelp
@@ -0,0 +1,40 @@
+CLASS:: FoaMu
+summary:: First Order Ambisonic (FOA) Soundfield Active Admittance Balance
+categories:: Libraries>Ambisonic Toolkit>UGens>FOA>Analyzer, UGens>Multichannel>Ambisonics, UGens>Analysis>Ambisonics
+related:: Classes/FoaAlpha, Classes/FoaBeta, Classes/FoaGamma, Classes/FoaMagIa, Classes/FoaWp
+
+DESCRIPTION::
+Return the emphasis::Active Admittance Balance:: of a first order ambisonic (B-format) signal, in radians.
+
+
+NOTE::
+link::Classes/FoaMu:: is usually called via the convenience wrapper link::Classes/FoaAnalyze::.
+::
+
+
+CLASSMETHODS::
+
+METHOD:: ar
+
+argument:: in
+The B-format signal, an array: [w, x, y, z]
+
+argument:: size
+Analysis filter kernel size.
+
+NOTE::For strong::method::: code::'instant'::, must be a power of 2.::
+
+argument:: method
+The Soundfield analysis method:
+
+list::
+## code::'instant'::
+## code::'average'::
+::
+
+Please see discussion of strong::method:: link::Classes/FoaAnalyze#Analysis%20method#here::.
+
+
+EXAMPLES::
+
+Please see various examples link::Classes/FoaAnalyze#examples#here::.
diff --git a/HelpSource/Classes/FoaNF.schelp b/HelpSource/Classes/FoaNF.schelp
new file mode 100644
index 0000000..1a44b68
--- /dev/null
+++ b/HelpSource/Classes/FoaNF.schelp
@@ -0,0 +1,40 @@
+CLASS:: FoaNF
+summary:: First Order Ambisonic (FOA) near-field distance estimate
+categories:: Libraries>Ambisonic Toolkit>UGens>FOA>Analyzer, UGens>Multichannel>Ambisonics, UGens>Analysis>Ambisonics
+related:: Classes/FoaThetaPhiA, Classes/FoaThetaPhiR, Classes/FoaIa, Classes/FoaMagIa
+
+DESCRIPTION::
+Return the emphasis::near-field distance estimate:: of a first order ambisonic (B-format) signal, in meters.
+
+
+NOTE::
+link::Classes/FoaNF:: is usually called via the convenience wrapper link::Classes/FoaAnalyze::.
+::
+
+
+CLASSMETHODS::
+
+METHOD:: ar
+
+argument:: in
+The B-format signal, an array: [w, x, y, z]
+
+argument:: size
+Analysis filter kernel size.
+
+NOTE::For strong::method::: code::'instant'::, must be a power of 2.::
+
+argument:: method
+The Soundfield analysis method:
+
+list::
+## code::'instant'::
+## code::'average'::
+::
+
+Please see discussion of strong::method:: link::Classes/FoaAnalyze#Analysis%20method#here::.
+
+
+EXAMPLES::
+
+Please see various examples link::Classes/FoaAnalyze#examples#here::.
diff --git a/HelpSource/Classes/FoaThetaPhiA.schelp b/HelpSource/Classes/FoaThetaPhiA.schelp
index 2c3fc2e..a40b7c7 100644
--- a/HelpSource/Classes/FoaThetaPhiA.schelp
+++ b/HelpSource/Classes/FoaThetaPhiA.schelp
@@ -1,7 +1,7 @@
 CLASS:: FoaThetaPhiA
 summary:: First Order Ambisonic (FOA) Azimuth & Elevation of Soundfield Active Intensity Vector
 categories:: Libraries>Ambisonic Toolkit>UGens>FOA>Analyzer, UGens>Multichannel>Ambisonics, UGens>Analysis>Ambisonics
-related:: Classes/FoaIa, Classes/FoaMagIa, Classes/FoaThetaPhiR
+related:: Classes/FoaIa, Classes/FoaMagIa, Classes/FoaThetaPhiR, Classes/FoaNF
 
 DESCRIPTION::
 Return the emphasis::Azimuth & Elevation of Active Intensity Vector:: of a first order ambisonic (B-format) signal.
diff --git a/HelpSource/Classes/FoaThetaPhiR.schelp b/HelpSource/Classes/FoaThetaPhiR.schelp
index db5ebac..8a46061 100644
--- a/HelpSource/Classes/FoaThetaPhiR.schelp
+++ b/HelpSource/Classes/FoaThetaPhiR.schelp
@@ -1,7 +1,7 @@
 CLASS:: FoaThetaPhiR
 summary:: First Order Ambisonic (FOA) Azimuth & Elevation of Soundfield Reactive Intensity Vector
 categories:: Libraries>Ambisonic Toolkit>UGens>FOA>Analyzer, UGens>Multichannel>Ambisonics, UGens>Analysis>Ambisonics
-related:: Classes/FoaIr, Classes/FoaMagIr, Classes/FoaThetaPhiA
+related:: Classes/FoaIr, Classes/FoaMagIr, Classes/FoaThetaPhiA, Classes/FoaNF
 
 DESCRIPTION::
 Return the emphasis::Azimuth & Elevation of Reactive Intensity Vector:: of a first order ambisonic (B-format) signal.