A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
angles.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2011, 2012 CTTC
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Nicola Baldo <nbaldo@cttc.es>
7 */
8
9#ifndef ANGLES_H
10#define ANGLES_H
11
12#include <ns3/vector.h>
13
14#include <vector>
15
16namespace ns3
17{
18
19/**
20 * \brief converts degrees to radians
21 *
22 * \param degrees the angle in degrees
23 * \return the angle in radians
24 */
25double DegreesToRadians(double degrees);
26
27/**
28 * \brief converts degrees to radians
29 *
30 * \param degrees the angles in degrees
31 * \return the angles in radians
32 */
33std::vector<double> DegreesToRadians(const std::vector<double>& degrees);
34
35/**
36 * \brief converts radians to degrees
37 *
38 * \param radians the angle in radians
39 * \return the angle in degrees
40 */
41double RadiansToDegrees(double radians);
42
43/**
44 * \brief converts radians to degrees
45 *
46 * \param radians the angles in radians
47 * \return the angles in degrees
48 */
49std::vector<double> RadiansToDegrees(const std::vector<double>& radians);
50
51/**
52 * \brief Wrap angle in [0, 360)
53 *
54 * \param a the angle in degrees
55 * \return the wrapped angle in degrees
56 */
57double WrapTo360(double a);
58
59/**
60 * \brief Wrap angle in [-180, 180)
61 *
62 * \param a the angle in degrees
63 * \return the wrapped angle in degrees
64 */
65double WrapTo180(double a);
66
67/**
68 * \brief Wrap angle in [0, 2*M_PI)
69 *
70 * \param a the angle in radians
71 * \return the wrapped angle in radians
72 */
73double WrapTo2Pi(double a);
74
75/**
76 * \brief Wrap angle in [-M_PI, M_PI)
77 *
78 * \param a the angle in radians
79 * \return the wrapped angle in radians
80 */
81double WrapToPi(double a);
82
83/**
84 *
85 * Class holding the azimuth and inclination angles of spherical coordinates.
86 * The notation is the one used in "Antenna Theory - Analysis
87 * and Design", C.A. Balanis, Wiley, 2nd Ed., section 2.2 "Radiation pattern".
88 * This notation corresponds to the standard spherical coordinates, with azimuth
89 * measured counterclockwise in the x-y plane off the x-axis, and
90 * inclination measured off the z-axis.
91 * Azimuth is consistently normalized to be in [-M_PI, M_PI).
92 *
93 * ^
94 * z |
95 * |_ inclination
96 * | \
97 * | /|
98 * |/ | y
99 * +-------->
100 * / \|
101 * /___/
102 * x / azimuth
103 * |/
104 *
105 */
107{
108 public:
109 /**
110 * This constructor allows to specify azimuth and inclination.
111 * Inclination must be in [0, M_PI], while azimuth is
112 * automatically normalized in [-M_PI, M_PI)
113 *
114 * \param azimuth the azimuth angle in radians
115 * \param inclination the inclination angle in radians
116 */
117 Angles(double azimuth, double inclination);
118
119 /**
120 * This constructor will initialize azimuth and inclination by converting the
121 * given 3D vector from cartesian coordinates to spherical coordinates
122 * Note: azimuth and inclination angles for a zero-length vector are not defined
123 * and are thus initialized to NAN
124 *
125 * \param v the 3D vector in cartesian coordinates
126 *
127 */
128 Angles(Vector v);
129
130 /**
131 * This constructor initializes an Angles instance with the angles
132 * of the spherical coordinates of point v respect to point o
133 *
134 * \param v the point (in cartesian coordinates) for which the angles are determined
135 * \param o the origin (in cartesian coordinates) of the spherical coordinate system
136 *
137 */
138 Angles(Vector v, Vector o);
139
140 /**
141 * Setter for azimuth angle
142 *
143 * \param azimuth angle in radians
144 */
145 void SetAzimuth(double azimuth);
146
147 /**
148 * Setter for inclination angle
149 *
150 * \param inclination angle in radians. Must be in [0, M_PI]
151 */
152 void SetInclination(double inclination);
153
154 /**
155 * Getter for azimuth angle
156 *
157 * \return azimuth angle in radians
158 */
159 double GetAzimuth() const;
160
161 /**
162 * Getter for inclination angle
163 *
164 * \return inclination angle in radians
165 */
166 double GetInclination() const;
167
168 // friend methods
169 /**
170 * \brief Stream insertion operator.
171 *
172 * \param [in] os The reference to the output stream.
173 * \param [in] a The angle.
174 * \returns The reference to the output stream.
175 */
176 friend std::ostream& operator<<(std::ostream& os, const Angles& a);
177 /**
178 * \brief Stream extraction operator.
179 *
180 * \param [in] is The reference to the input stream.
181 * \param [out] a The angle.
182 * \returns The reference to the input stream.
183 */
184 friend std::istream& operator>>(std::istream& is, Angles& a);
185
186 static bool m_printDeg; //!< flag for printing in radians or degrees units
187
188 private:
189 /**
190 * Default constructor is disabled
191 */
192 Angles();
193
194 /**
195 * Normalize the angle azimuth angle range between in [-M_PI, M_PI)
196 * while checking if the angle is valid, i.e., finite and within
197 * the bounds.
198 *
199 * Note: while an arbitrary value for the azimuth angle is valid
200 * and can be wrapped in [-M_PI, M_PI), an inclination angle outside
201 * the [0, M_PI] range can be ambiguous and is thus not valid.
202 */
203 void NormalizeAngles();
204
205 /**
206 * Check if Angle is valid or not
207 * Warns the user if the Angle is undefined (non-finite azimuth or inclination),
208 * throws an assert if the inclination angle is invalid (not in [0, M_PI])
209 */
210 void CheckIfValid() const;
211
212 double m_azimuth; //!< the azimuth angle in radians
213 double m_inclination; //!< the inclination angle in radians
214};
215
216} // namespace ns3
217
218#endif // ANGLES_H
Class holding the azimuth and inclination angles of spherical coordinates.
Definition angles.h:107
void NormalizeAngles()
Normalize the angle azimuth angle range between in [-M_PI, M_PI) while checking if the angle is valid...
Definition angles.cc:242
double m_inclination
the inclination angle in radians
Definition angles.h:213
double GetInclination() const
Getter for inclination angle.
Definition angles.cc:236
friend std::istream & operator>>(std::istream &is, Angles &a)
Stream extraction operator.
Definition angles.cc:172
static bool m_printDeg
flag for printing in radians or degrees units
Definition angles.h:186
void SetAzimuth(double azimuth)
Setter for azimuth angle.
Definition angles.cc:216
Angles()
Default constructor is disabled.
Definition angles.cc:183
void SetInclination(double inclination)
Setter for inclination angle.
Definition angles.cc:223
double m_azimuth
the azimuth angle in radians
Definition angles.h:212
double GetAzimuth() const
Getter for azimuth angle.
Definition angles.cc:230
friend std::ostream & operator<<(std::ostream &os, const Angles &a)
Stream insertion operator.
Definition angles.cc:148
void CheckIfValid() const
Check if Angle is valid or not Warns the user if the Angle is undefined (non-finite azimuth or inclin...
Definition angles.cc:256
Every class exported by the ns3 library is enclosed in the ns3 namespace.
double WrapToPi(double a)
Wrap angle in [-M_PI, M_PI)
Definition angles.cc:127
double WrapTo180(double a)
Wrap angle in [-180, 180)
Definition angles.cc:85
double WrapTo360(double a)
Wrap angle in [0, 360)
Definition angles.cc:64
double DegreesToRadians(double degrees)
converts degrees to radians
Definition angles.cc:28
double WrapTo2Pi(double a)
Wrap angle in [0, 2*M_PI)
Definition angles.cc:106
double RadiansToDegrees(double radians)
converts radians to degrees
Definition angles.cc:34