1/*
2 *  Copyright (c) 2015 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef WEBRTC_MODULES_AUDIO_PROCESSING_BEAMFORMER_ARRAY_UTIL_H_
12#define WEBRTC_MODULES_AUDIO_PROCESSING_BEAMFORMER_ARRAY_UTIL_H_
13
14#include <cmath>
15#include <vector>
16
17#include "webrtc/base/optional.h"
18
19namespace webrtc {
20
21// Coordinates in meters. The convention used is:
22// x: the horizontal dimension, with positive to the right from the camera's
23//    perspective.
24// y: the depth dimension, with positive forward from the camera's
25//    perspective.
26// z: the vertical dimension, with positive upwards.
27template<typename T>
28struct CartesianPoint {
29  CartesianPoint() {
30    c[0] = 0;
31    c[1] = 0;
32    c[2] = 0;
33  }
34  CartesianPoint(T x, T y, T z) {
35    c[0] = x;
36    c[1] = y;
37    c[2] = z;
38  }
39  T x() const { return c[0]; }
40  T y() const { return c[1]; }
41  T z() const { return c[2]; }
42  T c[3];
43};
44
45using Point = CartesianPoint<float>;
46
47// Calculates the direction from a to b.
48Point PairDirection(const Point& a, const Point& b);
49
50float DotProduct(const Point& a, const Point& b);
51Point CrossProduct(const Point& a, const Point& b);
52
53bool AreParallel(const Point& a, const Point& b);
54bool ArePerpendicular(const Point& a, const Point& b);
55
56// Returns the minimum distance between any two Points in the given
57// |array_geometry|.
58float GetMinimumSpacing(const std::vector<Point>& array_geometry);
59
60// If the given array geometry is linear it returns the direction without
61// normalizing.
62rtc::Optional<Point> GetDirectionIfLinear(
63    const std::vector<Point>& array_geometry);
64
65// If the given array geometry is planar it returns the normal without
66// normalizing.
67rtc::Optional<Point> GetNormalIfPlanar(
68    const std::vector<Point>& array_geometry);
69
70// Returns the normal of an array if it has one and it is in the xy-plane.
71rtc::Optional<Point> GetArrayNormalIfExists(
72    const std::vector<Point>& array_geometry);
73
74// The resulting Point will be in the xy-plane.
75Point AzimuthToPoint(float azimuth);
76
77template<typename T>
78float Distance(CartesianPoint<T> a, CartesianPoint<T> b) {
79  return std::sqrt((a.x() - b.x()) * (a.x() - b.x()) +
80                   (a.y() - b.y()) * (a.y() - b.y()) +
81                   (a.z() - b.z()) * (a.z() - b.z()));
82}
83
84// The convention used:
85// azimuth: zero is to the right from the camera's perspective, with positive
86//          angles in radians counter-clockwise.
87// elevation: zero is horizontal, with positive angles in radians upwards.
88// radius: distance from the camera in meters.
89template <typename T>
90struct SphericalPoint {
91  SphericalPoint(T azimuth, T elevation, T radius) {
92    s[0] = azimuth;
93    s[1] = elevation;
94    s[2] = radius;
95  }
96  T azimuth() const { return s[0]; }
97  T elevation() const { return s[1]; }
98  T distance() const { return s[2]; }
99  T s[3];
100};
101
102using SphericalPointf = SphericalPoint<float>;
103
104// Helper functions to transform degrees to radians and the inverse.
105template <typename T>
106T DegreesToRadians(T angle_degrees) {
107  return M_PI * angle_degrees / 180;
108}
109
110template <typename T>
111T RadiansToDegrees(T angle_radians) {
112  return 180 * angle_radians / M_PI;
113}
114
115}  // namespace webrtc
116
117#endif  // WEBRTC_MODULES_AUDIO_PROCESSING_BEAMFORMER_ARRAY_UTIL_H_
118