Make the nonlinear beamformer steerable

webrtc/modules/audio_processing/beamformer/array_util.h

Index: webrtc/modules/audio_processing/beamformer/array_util.h
diff --git a/webrtc/modules/audio_processing/beamformer/array_util.h b/webrtc/modules/audio_processing/beamformer/array_util.h
index 2ac174ea8aa04800995551d03017c9d215415921..3a240b14eddfa57ac0db8a2677cf2e41cc348ba5 100644
--- a/webrtc/modules/audio_processing/beamformer/array_util.h
+++ b/webrtc/modules/audio_processing/beamformer/array_util.h
@@ -16,7 +16,12 @@
 
 namespace webrtc {
 
-// Coordinates in meters.
+// Coordinates in meters. The convention used is:
+// x: the horizontal dimension, with positive to the right from the camera's
+//    perspective.
+// y: the depth dimension, with positive forward from the camera's
+//    perspective.
+// z: the vertical dimension, with positive upwards.
 template<typename T>
 struct CartesianPoint {
   CartesianPoint(T x, T y, T z) {
@@ -32,10 +37,33 @@ struct CartesianPoint {
 
 using Point = CartesianPoint<float>;
 
+// Calculates the direction given a pair of Points.

[Andrew MacDonald, 2015/10/28 01:57:56]

Be more specific: Calculates the direction from a to b.

[aluebs-webrtc, 2015/10/29 00:34:21]

Done.

+Point PairDirection(const Point& a, const Point& b);
+
+float DotProduct(const Point& a, const Point& b);
+Point CrossProduct(const Point& a, const Point& b);
+
+bool AreParallel(const Point& a, const Point& b);
+bool ArePerpendicular(const Point& a, const Point& b);
+
 // Returns the minimum distance between any two Points in the given
 // |array_geometry|.
 float GetMinimumSpacing(const std::vector<Point>& array_geometry);
 
+// If the given array geometry is linear it returns the direction without
+// normalizing. If it is not linear it returns a null Point.

[Andrew MacDonald, 2015/10/28 01:57:56]

I would say the origin (or zero) rather than null? And below.

But instead, this is a perfect opportunity to use kwiberg's new Maybe<T>:
https://code.google.com/p/chromium/codesearch#chromium/src/third_party/webrtc...

since the origin is a valid direction for a trivially true case (all points at
the origin).

And I would call it GetDirectionIfLinear.

[aluebs-webrtc, 2015/10/29 00:34:21]

Changed to use Maybe and renamed function.

+Point IsGeometryLinear(const std::vector<Point>& array_geometry);
+
+// If the given array geometry is planar it returns the normal without
+// normalizing. If it is not planar it returns a null Point.
+Point IsGeometryPlanar(const std::vector<Point>& array_geometry);

[Andrew MacDonald, 2015/10/28 01:57:56]

GetNormalIfPlanar

[aluebs-webrtc, 2015/10/29 00:34:21]

Done.

+
+// Returns the normal of an array in the xy-plane. If the array has no normal or
+// the normal is not in the xy-plane it returns a null Point.

[Andrew MacDonald, 2015/10/28 01:57:57]

zero or origin

[aluebs-webrtc, 2015/10/29 00:34:21]

No need since using Maybe.

+Point GetArrayNormal(const std::vector<Point>& array_geometry);

[Andrew MacDonald, 2015/10/28 01:57:56]

GetArrayNormalIfExists

[aluebs-webrtc, 2015/10/29 00:34:21]

Done.

+
+Point AzimuthToPoint(float azimuth);

[Andrew MacDonald, 2015/10/28 01:57:56]

Might be worth documenting that the point will be in the XY plane? Is that
obvious?

[aluebs-webrtc, 2015/10/29 00:34:21]

Good point. Added documentation.

+
 template<typename T>
 float Distance(CartesianPoint<T> a, CartesianPoint<T> b) {
   return std::sqrt((a.x() - b.x()) * (a.x() - b.x()) +
@@ -43,6 +71,11 @@ float Distance(CartesianPoint<T> a, CartesianPoint<T> b) {
                    (a.z() - b.z()) * (a.z() - b.z()));
 }
 
+// The convention used:
+// azimuth: zero is to the right from the camera's perspective, with positive
+//          angles in radians counter-clockwise.
+// elevation: zero is horizontal, with positive angles in radians upwards.
+// radius: distance from the camera in meters.
 template <typename T>
 struct SphericalPoint {
   SphericalPoint(T azimuth, T elevation, T radius) {
@@ -58,6 +91,17 @@ struct SphericalPoint {
 
 using SphericalPointf = SphericalPoint<float>;
 
+// Helper functions to transform degrees to radians and the inverse.
+template <typename T>
+T DegreesToRadians(T angle_degrees) {
+  return M_PI * angle_degrees / 180;
+}
+
+template <typename T>
+T RadiansToDegrees(T angle_radians) {
+  return 180 * angle_radians / M_PI;
+}
+
 }  // namespace webrtc
 
 #endif  // WEBRTC_MODULES_AUDIO_PROCESSING_BEAMFORMER_ARRAY_UTIL_H_