GeographicLib 2.7

Loading...
Searching...
No Matches
AuxAngle.hpp
Go to the documentation of this file.
1/**
2 * \file AuxAngle.hpp
3 * \brief Header for the GeographicLib::AuxAngle class
4 *
5 * This file is an implementation of the methods described in
6 * - C. F. F. Karney,
7 * <a href="https://doi.org/10.1080/00396265.2023.2217604">
8 * On auxiliary latitudes,</a>
9 * Survey Review 56(395), 165--180 (2024);
10 * preprint
11 * <a href="https://arxiv.org/abs/2212.05818">arXiv:2212.05818</a>.
12 * .
13 * Copyright (c) Charles Karney (2022-2023) <karney@alum.mit.edu> and licensed
14 * under the MIT/X11 License. For more information, see
15 * https://geographiclib.sourceforge.io/
16 **********************************************************************/
17
18#if !defined(GEOGRAPHICLIB_AUXANGLE_HPP)
19#define GEOGRAPHICLIB_AUXANGLE_HPP 1
20
21#include <GeographicLib/Math.hpp>
22
23 namespace GeographicLib {
24
25 /**
26 * \brief An accurate representation of angles.
27 *
28 * This class is an implementation of the methods described in
29 * - C. F. F. Karney,
30 * <a href="https://doi.org/10.1080/00396265.2023.2217604">
31 * On auxiliary latitudes,</a>
32 * Survey Review 56(395), 165--180 (2024);
33 * preprint
34 * <a href="https://arxiv.org/abs/2212.05818">arXiv:2212.05818</a>.
35 *
36 * An angle is represented be the \e y and \e x coordinates of a point in the
37 * 2d plane. The two coordinates are proportional to the sine and cosine of
38 * the angle. This allows angles close to the cardinal points to be
39 * represented accurately. It also saves on unnecessary recomputations of
40 * trigonometric functions of the angle. Only angles in [&minus;180&deg;,
41 * 180&deg;] can be represented. (A possible extension would be to keep
42 * count of the number of turns.)
43 *
44 * Example of use:
45 * \include example-AuxAngle.cpp
46 *
47 * \deprecated The functionality offer by this class is also provided by the
48 * more general class Angle. It is recommended to use Angle for new
49 * applications.
50 **********************************************************************/
51 class GEOGRAPHICLIB_EXPORT AuxAngle {
52 private:
53 typedef Math::real real;
54 real _y, _x;
55 public:
56 /**
57 * The constructor.
58 *
59 * @param[in] y the \e y coordinate.
60 * @param[in] x the \e x coordinate.
61 *
62 * \note the \e y coordinate is specified \e first.
63 * \warning either \e x or \e y can be infinite, but not both.
64 *
65 * The defaults (\e x = 1 and \e y = 0) are such that
66 * + no arguments gives an angle of 0;
67 * + 1 argument specifies the tangent of the angle.
68 **********************************************************************/
69 explicit AuxAngle(real y = 0, real x = 1) : _y(y), _x(x) {}
70 /**
71 * @return the \e y component. This is the sine of the angle if the
72 * AuxAngle has been normalized.
73 **********************************************************************/
74 Math::real y() const { return _y; }
75 /**
76 * @return the \e x component. This is the cosine of the angle if the
77 * AuxAngle has been normalized.
78 **********************************************************************/
79 Math::real x() const { return _x; }
80 /**
81 * @return a reference to the \e y component. This allows this component
82 * to be altered.
83 **********************************************************************/
84 Math::real& y() { return _y; }
85 /**
86 * @return a reference to the \e x component. This allows this component
87 * to be altered.
88 **********************************************************************/
89 Math::real& x() { return _x; }
90 /**
91 * @return the AuxAngle converted to the conventional angle measured in
92 * degrees.
93 **********************************************************************/
94 Math::real degrees() const;
95 /**
96 * @return the AuxAngle converted to the conventional angle measured in
97 * radians.
98 **********************************************************************/
99 Math::real radians() const;
100 /**
101 * @return the lambertian of the AuxAngle.
102 *
103 * \note the lambertian of an angle &chi; is
104 * lam(&chi;) = asinh(tan(&chi;)).
105 **********************************************************************/
106 Math::real lam() const;
107 /**
108 * @return the lambertian of the AuxAngle in degrees.
109 *
110 * \note the lambertian of an angle &chi; is
111 * lam(&chi;) = asinh(tan(&chi;)).
112 **********************************************************************/
113 Math::real lamd() const;
114 /**
115 * @return the tangent of the angle.
116 **********************************************************************/
117 Math::real tan() const { return _y / _x; }
118 /**
119 * @return a new normalized AuxAngle with the point lying on the unit
120 * circle and the \e y and \e x components are equal to the sine and
121 * cosine of the angle.
122 **********************************************************************/
123 AuxAngle normalized() const;
124 /**
125 * Normalize the AuxAngle in place so that the \e y and \e x components are
126 * equal to the sine and cosine of the angle.
127 **********************************************************************/
128 void normalize() { *this = normalized(); }
129 /**
130 * Set the quadrant for the AuxAngle.
131 *
132 * @param[in] p the AuxAngle from which the quadrant information is taken.
133 * @return the new AuxAngle in the same quadrant as \e p.
134 **********************************************************************/
135 AuxAngle copyquadrant(const AuxAngle& p) const;
136 /**
137 * Add an AuxAngle.
138 *
139 * @param[in] p the AuxAngle to be added.
140 * @return a reference to the new AuxAngle.
141 *
142 * The addition is done in place, altering the current AuxAngle.
143 *
144 * \warning Neither *this nor \e p should have an infinite component. If
145 * necessary, invoke AuxAngle::normalize on these angles first.
146 **********************************************************************/
147 AuxAngle& operator+=(const AuxAngle& p);
148 /**
149 * Construct and return an AuxAngle specied as an angle in degrees.
150 *
151 * @param[in] d the angle measured in degrees.
152 * @return the corresponding AuxAngle.
153 *
154 * This allows a new AuxAngle to be initialized as an angle in degrees with
155 * @code
156 * AuxAngle phi(AuxAngle::degrees(d));
157 * @endcode
158 **********************************************************************/
159 static AuxAngle degrees(real d);
160 /**
161 * Construct and return an AuxAngle specied as an angle in radians.
162 *
163 * @param[in] r the angle measured in radians.
164 * @return the corresponding AuxAngle.
165 *
166 * This allows a new AuxAngle to be initialized as an angle in radians with
167 * @code
168 * AuxAngle phi(AuxAngle::radians(r));
169 * @endcode
170 **********************************************************************/
171 static AuxAngle radians(real r);
172 /**
173 * Construct and return an AuxAngle specied by the lambertian of the angle.
174 *
175 * @param[in] psi the lambertian of the angle.
176 * @return the corresponding AuxAngle.
177 *
178 * This allows a new AuxAngle to be initialized given the lambertian with
179 * @code
180 * AuxAngle chi(AuxAngle::lam(psi));
181 * @endcode
182 *
183 * \note this sets the angle &chi; to gd(&psi;) = atan(sinh(&psi;)).
184 **********************************************************************/
185 static AuxAngle lam(real psi);
186 /**
187 * Construct and return an AuxAngle specied by the lambertian of the angle
188 * in degrees.
189 *
190 * @param[in] psid the lambertian of the angle in degrees.
191 * @return the corresponding AuxAngle.
192 *
193 * This allows a new AuxAngle to be initialized given the lambertian with
194 * @code
195 * AuxAngle chi(AuxAngle::lamd(psid));
196 * @endcode
197 *
198 * \note this sets the angle &chi; to gd(&psi;) = atan(sinh(&psi;)).
199 **********************************************************************/
200 static AuxAngle lamd(real psid);
201 /**
202 * @return a "NaN" AuxAngle.
203 **********************************************************************/
204 static AuxAngle NaN();
205 };
206
207 inline AuxAngle AuxAngle::degrees(real d) {
208 real y, x;
209 Math::sincosd(d, y, x);
210 return AuxAngle(y, x);
211 }
212
213 inline AuxAngle AuxAngle::radians(real r) {
214 using std::sin, std::cos;
215 return AuxAngle(sin(r), cos(r));
216 }
217
218 inline AuxAngle AuxAngle::lam(real psi) {
219 using std::sinh;
220 return AuxAngle(sinh(psi));
221 }
222
223 inline AuxAngle AuxAngle::lamd(real psid) {
224 using std::sinh;
225 return AuxAngle(sinh(psid * Math::degree()));
226 }
227
228 inline Math::real AuxAngle::degrees() const {
229 return Math::atan2d(_y, _x);
230 }
231
232 inline Math::real AuxAngle::radians() const {
233 using std::atan2; return atan2(_y, _x);
234 }
235
236 inline Math::real AuxAngle::lam() const {
237 using std::asinh; return asinh( tan() );
238 }
239
240 inline Math::real AuxAngle::lamd() const {
241 using std::asinh; return asinh( tan() ) / Math::degree();
242 }
243
244} // namespace GeographicLib
245
246#endif // GEOGRAPHICLIB_AUXANGLE_HPP
GEOGRAPHICLIB_EXPORT
#define GEOGRAPHICLIB_EXPORT
Definition Constants.hpp:59
real
GeographicLib::Math::real real
Definition Geod3Solve.cpp:25
Math.hpp
Header for GeographicLib::Math class.
GeographicLib::AuxAngle
An accurate representation of angles.
Definition AuxAngle.hpp:51
GeographicLib::AuxAngle::y
Math::real y() const
Definition AuxAngle.hpp:74
GeographicLib::AuxAngle::x
Math::real x() const
Definition AuxAngle.hpp:79
GeographicLib::AuxAngle::radians
Math::real radians() const
Definition AuxAngle.hpp:232
GeographicLib::AuxAngle::normalized
AuxAngle normalized() const
Definition AuxAngle.cpp:28
GeographicLib::AuxAngle::degrees
Math::real degrees() const
Definition AuxAngle.hpp:228
GeographicLib::AuxAngle::y
Math::real & y()
Definition AuxAngle.hpp:84
GeographicLib::AuxAngle::lamd
Math::real lamd() const
Definition AuxAngle.hpp:240
GeographicLib::AuxAngle::normalize
void normalize()
Definition AuxAngle.hpp:128
GeographicLib::AuxAngle::lam
Math::real lam() const
Definition AuxAngle.hpp:236
GeographicLib::AuxAngle::tan
Math::real tan() const
Definition AuxAngle.hpp:117
GeographicLib::AuxAngle::AuxAngle
AuxAngle(real y=0, real x=1)
Definition AuxAngle.hpp:69
GeographicLib::AuxAngle::x
Math::real & x()
Definition AuxAngle.hpp:89
GeographicLib::Math::degree
static T degree()
Definition Math.hpp:197
GeographicLib::Math::sincosd
static void sincosd(T x, T &sinx, T &cosx)
Definition Math.cpp:104
GeographicLib::Math::atan2d
static T atan2d(T y, T x)
Definition Math.cpp:212
GeographicLib::Math::real
double real
Definition Math.hpp:115
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12