GeographicLib 1.52
Loading...
Searching...
No Matches
GeodesicLine.hpp
Go to the documentation of this file.
1/**
2 * \file GeodesicLine.hpp
3 * \brief Header for GeographicLib::GeodesicLine class
4 *
5 * Copyright (c) Charles Karney (2009-2020) <charles@karney.com> and licensed
6 * under the MIT/X11 License. For more information, see
7 * https://geographiclib.sourceforge.io/
8 **********************************************************************/
9
10#if !defined(GEOGRAPHICLIB_GEODESICLINE_HPP)
11#define GEOGRAPHICLIB_GEODESICLINE_HPP 1
12
15
16namespace GeographicLib {
17
18 /**
19 * \brief A geodesic line
20 *
21 * GeodesicLine facilitates the determination of a series of points on a
22 * single geodesic. The starting point (\e lat1, \e lon1) and the azimuth \e
23 * azi1 are specified in the constructor; alternatively, the Geodesic::Line
24 * method can be used to create a GeodesicLine. GeodesicLine.Position
25 * returns the location of point 2 a distance \e s12 along the geodesic. In
26 * addition, GeodesicLine.ArcPosition gives the position of point 2 an arc
27 * length \e a12 along the geodesic.
28 *
29 * You can register the position of a reference point 3 a distance (arc
30 * length), \e s13 (\e a13) along the geodesic with the
31 * GeodesicLine.SetDistance (GeodesicLine.SetArc) functions. Points a
32 * fractional distance along the line can be found by providing, for example,
33 * 0.5 * Distance() as an argument to GeodesicLine.Position. The
34 * Geodesic::InverseLine or Geodesic::DirectLine methods return GeodesicLine
35 * objects with point 3 set to the point 2 of the corresponding geodesic
36 * problem. GeodesicLine objects created with the public constructor or with
37 * Geodesic::Line have \e s13 and \e a13 set to NaNs.
38 *
39 * The default copy constructor and assignment operators work with this
40 * class. Similarly, a vector can be used to hold GeodesicLine objects.
41 *
42 * The calculations are accurate to better than 15 nm (15 nanometers). See
43 * Sec. 9 of
44 * <a href="https://arxiv.org/abs/1102.1215v1">arXiv:1102.1215v1</a> for
45 * details. The algorithms used by this class are based on series expansions
46 * using the flattening \e f as a small parameter. These are only accurate
47 * for |<i>f</i>| &lt; 0.02; however reasonably accurate results will be
48 * obtained for |<i>f</i>| &lt; 0.2. For very eccentric ellipsoids, use
49 * GeodesicLineExact instead.
50 *
51 * The algorithms are described in
52 * - C. F. F. Karney,
53 * <a href="https://doi.org/10.1007/s00190-012-0578-z">
54 * Algorithms for geodesics</a>,
55 * J. Geodesy <b>87</b>, 43--55 (2013);
56 * DOI: <a href="https://doi.org/10.1007/s00190-012-0578-z">
57 * 10.1007/s00190-012-0578-z</a>;
58 * addenda:
59 * <a href="https://geographiclib.sourceforge.io/geod-addenda.html">
60 * geod-addenda.html</a>.
61 * .
62 * For more information on geodesics see \ref geodesic.
63 *
64 * Example of use:
65 * \include example-GeodesicLine.cpp
66 *
67 * <a href="GeodSolve.1.html">GeodSolve</a> is a command-line utility
68 * providing access to the functionality of Geodesic and GeodesicLine.
69 **********************************************************************/
70
72 private:
73 typedef Math::real real;
74 friend class Geodesic;
75 static const int nC1_ = Geodesic::nC1_;
76 static const int nC1p_ = Geodesic::nC1p_;
77 static const int nC2_ = Geodesic::nC2_;
78 static const int nC3_ = Geodesic::nC3_;
79 static const int nC4_ = Geodesic::nC4_;
80
81 real tiny_;
82 real _lat1, _lon1, _azi1;
83 real _a, _f, _b, _c2, _f1, _salp0, _calp0, _k2,
84 _salp1, _calp1, _ssig1, _csig1, _dn1, _stau1, _ctau1, _somg1, _comg1,
85 _A1m1, _A2m1, _A3c, _B11, _B21, _B31, _A4, _B41;
86 real _a13, _s13;
87 // index zero elements of _C1a, _C1pa, _C2a, _C3a are unused
88 real _C1a[nC1_ + 1], _C1pa[nC1p_ + 1], _C2a[nC2_ + 1], _C3a[nC3_],
89 _C4a[nC4_]; // all the elements of _C4a are used
90 unsigned _caps;
91
92 void LineInit(const Geodesic& g,
93 real lat1, real lon1,
94 real azi1, real salp1, real calp1,
95 unsigned caps);
96 GeodesicLine(const Geodesic& g,
97 real lat1, real lon1,
98 real azi1, real salp1, real calp1,
99 unsigned caps, bool arcmode, real s13_a13);
100
101 enum captype {
102 CAP_NONE = Geodesic::CAP_NONE,
103 CAP_C1 = Geodesic::CAP_C1,
104 CAP_C1p = Geodesic::CAP_C1p,
105 CAP_C2 = Geodesic::CAP_C2,
106 CAP_C3 = Geodesic::CAP_C3,
107 CAP_C4 = Geodesic::CAP_C4,
108 CAP_ALL = Geodesic::CAP_ALL,
109 CAP_MASK = Geodesic::CAP_MASK,
110 OUT_ALL = Geodesic::OUT_ALL,
111 OUT_MASK = Geodesic::OUT_MASK,
112 };
113 public:
114
115 /**
116 * Bit masks for what calculations to do. They signify to the
117 * GeodesicLine::GeodesicLine constructor and to Geodesic::Line what
118 * capabilities should be included in the GeodesicLine object. This is
119 * merely a duplication of Geodesic::mask.
120 **********************************************************************/
121 enum mask {
122 /**
123 * No capabilities, no output.
124 * @hideinitializer
125 **********************************************************************/
126 NONE = Geodesic::NONE,
127 /**
128 * Calculate latitude \e lat2. (It's not necessary to include this as a
129 * capability to GeodesicLine because this is included by default.)
130 * @hideinitializer
131 **********************************************************************/
132 LATITUDE = Geodesic::LATITUDE,
133 /**
134 * Calculate longitude \e lon2.
135 * @hideinitializer
136 **********************************************************************/
137 LONGITUDE = Geodesic::LONGITUDE,
138 /**
139 * Calculate azimuths \e azi1 and \e azi2. (It's not necessary to
140 * include this as a capability to GeodesicLine because this is included
141 * by default.)
142 * @hideinitializer
143 **********************************************************************/
144 AZIMUTH = Geodesic::AZIMUTH,
145 /**
146 * Calculate distance \e s12.
147 * @hideinitializer
148 **********************************************************************/
149 DISTANCE = Geodesic::DISTANCE,
150 /**
151 * Allow distance \e s12 to be used as input in the direct geodesic
152 * problem.
153 * @hideinitializer
154 **********************************************************************/
155 DISTANCE_IN = Geodesic::DISTANCE_IN,
156 /**
157 * Calculate reduced length \e m12.
158 * @hideinitializer
159 **********************************************************************/
160 REDUCEDLENGTH = Geodesic::REDUCEDLENGTH,
161 /**
162 * Calculate geodesic scales \e M12 and \e M21.
163 * @hideinitializer
164 **********************************************************************/
165 GEODESICSCALE = Geodesic::GEODESICSCALE,
166 /**
167 * Calculate area \e S12.
168 * @hideinitializer
169 **********************************************************************/
170 AREA = Geodesic::AREA,
171 /**
172 * Unroll \e lon2 in the direct calculation.
173 * @hideinitializer
174 **********************************************************************/
175 LONG_UNROLL = Geodesic::LONG_UNROLL,
176 /**
177 * All capabilities, calculate everything. (LONG_UNROLL is not
178 * included in this mask.)
179 * @hideinitializer
180 **********************************************************************/
181 ALL = Geodesic::ALL,
182 };
183
184 /** \name Constructors
185 **********************************************************************/
186 ///@{
187
188 /**
189 * Constructor for a geodesic line staring at latitude \e lat1, longitude
190 * \e lon1, and azimuth \e azi1 (all in degrees).
191 *
192 * @param[in] g A Geodesic object used to compute the necessary information
193 * about the GeodesicLine.
194 * @param[in] lat1 latitude of point 1 (degrees).
195 * @param[in] lon1 longitude of point 1 (degrees).
196 * @param[in] azi1 azimuth at point 1 (degrees).
197 * @param[in] caps bitor'ed combination of GeodesicLine::mask values
198 * specifying the capabilities the GeodesicLine object should possess,
199 * i.e., which quantities can be returned in calls to
200 * GeodesicLine::Position.
201 *
202 * \e lat1 should be in the range [&minus;90&deg;, 90&deg;].
203 *
204 * The GeodesicLine::mask values are
205 * - \e caps |= GeodesicLine::LATITUDE for the latitude \e lat2; this is
206 * added automatically;
207 * - \e caps |= GeodesicLine::LONGITUDE for the latitude \e lon2;
208 * - \e caps |= GeodesicLine::AZIMUTH for the latitude \e azi2; this is
209 * added automatically;
210 * - \e caps |= GeodesicLine::DISTANCE for the distance \e s12;
211 * - \e caps |= GeodesicLine::REDUCEDLENGTH for the reduced length \e m12;
212 * - \e caps |= GeodesicLine::GEODESICSCALE for the geodesic scales \e M12
213 * and \e M21;
214 * - \e caps |= GeodesicLine::AREA for the area \e S12;
215 * - \e caps |= GeodesicLine::DISTANCE_IN permits the length of the
216 * geodesic to be given in terms of \e s12; without this capability the
217 * length can only be specified in terms of arc length;
218 * - \e caps |= GeodesicLine::ALL for all of the above.
219 * .
220 * The default value of \e caps is GeodesicLine::ALL.
221 *
222 * If the point is at a pole, the azimuth is defined by keeping \e lon1
223 * fixed, writing \e lat1 = &plusmn;(90&deg; &minus; &epsilon;), and taking
224 * the limit &epsilon; &rarr; 0+.
225 **********************************************************************/
226 GeodesicLine(const Geodesic& g, real lat1, real lon1, real azi1,
227 unsigned caps = ALL);
228
229 /**
230 * A default constructor. If GeodesicLine::Position is called on the
231 * resulting object, it returns immediately (without doing any
232 * calculations). The object can be set with a call to Geodesic::Line.
233 * Use Init() to test whether object is still in this uninitialized state.
234 **********************************************************************/
235 GeodesicLine() : _caps(0U) {}
236 ///@}
237
238 /** \name Position in terms of distance
239 **********************************************************************/
240 ///@{
241
242 /**
243 * Compute the position of point 2 which is a distance \e s12 (meters) from
244 * point 1.
245 *
246 * @param[in] s12 distance from point 1 to point 2 (meters); it can be
247 * negative.
248 * @param[out] lat2 latitude of point 2 (degrees).
249 * @param[out] lon2 longitude of point 2 (degrees); requires that the
250 * GeodesicLine object was constructed with \e caps |=
251 * GeodesicLine::LONGITUDE.
252 * @param[out] azi2 (forward) azimuth at point 2 (degrees).
253 * @param[out] m12 reduced length of geodesic (meters); requires that the
254 * GeodesicLine object was constructed with \e caps |=
255 * GeodesicLine::REDUCEDLENGTH.
256 * @param[out] M12 geodesic scale of point 2 relative to point 1
257 * (dimensionless); requires that the GeodesicLine object was constructed
258 * with \e caps |= GeodesicLine::GEODESICSCALE.
259 * @param[out] M21 geodesic scale of point 1 relative to point 2
260 * (dimensionless); requires that the GeodesicLine object was constructed
261 * with \e caps |= GeodesicLine::GEODESICSCALE.
262 * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
263 * that the GeodesicLine object was constructed with \e caps |=
264 * GeodesicLine::AREA.
265 * @return \e a12 arc length from point 1 to point 2 (degrees).
266 *
267 * The values of \e lon2 and \e azi2 returned are in the range
268 * [&minus;180&deg;, 180&deg;].
269 *
270 * The GeodesicLine object \e must have been constructed with \e caps |=
271 * GeodesicLine::DISTANCE_IN; otherwise Math::NaN() is returned and no
272 * parameters are set. Requesting a value which the GeodesicLine object is
273 * not capable of computing is not an error; the corresponding argument
274 * will not be altered.
275 *
276 * The following functions are overloaded versions of
277 * GeodesicLine::Position which omit some of the output parameters. Note,
278 * however, that the arc length is always computed and returned as the
279 * function value.
280 **********************************************************************/
282 real& lat2, real& lon2, real& azi2,
283 real& m12, real& M12, real& M21,
284 real& S12) const {
285 real t;
286 return GenPosition(false, s12,
287 LATITUDE | LONGITUDE | AZIMUTH |
288 REDUCEDLENGTH | GEODESICSCALE | AREA,
289 lat2, lon2, azi2, t, m12, M12, M21, S12);
290 }
291
292 /**
293 * See the documentation for GeodesicLine::Position.
294 **********************************************************************/
295 Math::real Position(real s12, real& lat2, real& lon2) const {
296 real t;
297 return GenPosition(false, s12,
298 LATITUDE | LONGITUDE,
299 lat2, lon2, t, t, t, t, t, t);
300 }
301
302 /**
303 * See the documentation for GeodesicLine::Position.
304 **********************************************************************/
305 Math::real Position(real s12, real& lat2, real& lon2,
306 real& azi2) const {
307 real t;
308 return GenPosition(false, s12,
309 LATITUDE | LONGITUDE | AZIMUTH,
310 lat2, lon2, azi2, t, t, t, t, t);
311 }
312
313 /**
314 * See the documentation for GeodesicLine::Position.
315 **********************************************************************/
316 Math::real Position(real s12, real& lat2, real& lon2,
317 real& azi2, real& m12) const {
318 real t;
319 return GenPosition(false, s12,
320 LATITUDE | LONGITUDE |
321 AZIMUTH | REDUCEDLENGTH,
322 lat2, lon2, azi2, t, m12, t, t, t);
323 }
324
325 /**
326 * See the documentation for GeodesicLine::Position.
327 **********************************************************************/
328 Math::real Position(real s12, real& lat2, real& lon2,
329 real& azi2, real& M12, real& M21)
330 const {
331 real t;
332 return GenPosition(false, s12,
333 LATITUDE | LONGITUDE |
334 AZIMUTH | GEODESICSCALE,
335 lat2, lon2, azi2, t, t, M12, M21, t);
336 }
337
338 /**
339 * See the documentation for GeodesicLine::Position.
340 **********************************************************************/
342 real& lat2, real& lon2, real& azi2,
343 real& m12, real& M12, real& M21)
344 const {
345 real t;
346 return GenPosition(false, s12,
347 LATITUDE | LONGITUDE | AZIMUTH |
348 REDUCEDLENGTH | GEODESICSCALE,
349 lat2, lon2, azi2, t, m12, M12, M21, t);
350 }
351 ///@}
352
353 /** \name Position in terms of arc length
354 **********************************************************************/
355 ///@{
356
357 /**
358 * Compute the position of point 2 which is an arc length \e a12 (degrees)
359 * from point 1.
360 *
361 * @param[in] a12 arc length from point 1 to point 2 (degrees); it can
362 * be negative.
363 * @param[out] lat2 latitude of point 2 (degrees).
364 * @param[out] lon2 longitude of point 2 (degrees); requires that the
365 * GeodesicLine object was constructed with \e caps |=
366 * GeodesicLine::LONGITUDE.
367 * @param[out] azi2 (forward) azimuth at point 2 (degrees).
368 * @param[out] s12 distance from point 1 to point 2 (meters); requires
369 * that the GeodesicLine object was constructed with \e caps |=
370 * GeodesicLine::DISTANCE.
371 * @param[out] m12 reduced length of geodesic (meters); requires that the
372 * GeodesicLine object was constructed with \e caps |=
373 * GeodesicLine::REDUCEDLENGTH.
374 * @param[out] M12 geodesic scale of point 2 relative to point 1
375 * (dimensionless); requires that the GeodesicLine object was constructed
376 * with \e caps |= GeodesicLine::GEODESICSCALE.
377 * @param[out] M21 geodesic scale of point 1 relative to point 2
378 * (dimensionless); requires that the GeodesicLine object was constructed
379 * with \e caps |= GeodesicLine::GEODESICSCALE.
380 * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
381 * that the GeodesicLine object was constructed with \e caps |=
382 * GeodesicLine::AREA.
383 *
384 * The values of \e lon2 and \e azi2 returned are in the range
385 * [&minus;180&deg;, 180&deg;].
386 *
387 * Requesting a value which the GeodesicLine object is not capable of
388 * computing is not an error; the corresponding argument will not be
389 * altered.
390 *
391 * The following functions are overloaded versions of
392 * GeodesicLine::ArcPosition which omit some of the output parameters.
393 **********************************************************************/
394 void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
395 real& s12, real& m12, real& M12, real& M21,
396 real& S12) const {
397 GenPosition(true, a12,
398 LATITUDE | LONGITUDE | AZIMUTH | DISTANCE |
399 REDUCEDLENGTH | GEODESICSCALE | AREA,
400 lat2, lon2, azi2, s12, m12, M12, M21, S12);
401 }
402
403 /**
404 * See the documentation for GeodesicLine::ArcPosition.
405 **********************************************************************/
406 void ArcPosition(real a12, real& lat2, real& lon2)
407 const {
408 real t;
409 GenPosition(true, a12,
410 LATITUDE | LONGITUDE,
411 lat2, lon2, t, t, t, t, t, t);
412 }
413
414 /**
415 * See the documentation for GeodesicLine::ArcPosition.
416 **********************************************************************/
417 void ArcPosition(real a12,
418 real& lat2, real& lon2, real& azi2)
419 const {
420 real t;
421 GenPosition(true, a12,
422 LATITUDE | LONGITUDE | AZIMUTH,
423 lat2, lon2, azi2, t, t, t, t, t);
424 }
425
426 /**
427 * See the documentation for GeodesicLine::ArcPosition.
428 **********************************************************************/
429 void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
430 real& s12) const {
431 real t;
432 GenPosition(true, a12,
433 LATITUDE | LONGITUDE | AZIMUTH | DISTANCE,
434 lat2, lon2, azi2, s12, t, t, t, t);
435 }
436
437 /**
438 * See the documentation for GeodesicLine::ArcPosition.
439 **********************************************************************/
440 void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
441 real& s12, real& m12) const {
442 real t;
443 GenPosition(true, a12,
444 LATITUDE | LONGITUDE | AZIMUTH |
445 DISTANCE | REDUCEDLENGTH,
446 lat2, lon2, azi2, s12, m12, t, t, t);
447 }
448
449 /**
450 * See the documentation for GeodesicLine::ArcPosition.
451 **********************************************************************/
452 void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
453 real& s12, real& M12, real& M21)
454 const {
455 real t;
456 GenPosition(true, a12,
457 LATITUDE | LONGITUDE | AZIMUTH |
458 DISTANCE | GEODESICSCALE,
459 lat2, lon2, azi2, s12, t, M12, M21, t);
460 }
461
462 /**
463 * See the documentation for GeodesicLine::ArcPosition.
464 **********************************************************************/
465 void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
466 real& s12, real& m12, real& M12, real& M21)
467 const {
468 real t;
469 GenPosition(true, a12,
470 LATITUDE | LONGITUDE | AZIMUTH |
471 DISTANCE | REDUCEDLENGTH | GEODESICSCALE,
472 lat2, lon2, azi2, s12, m12, M12, M21, t);
473 }
474 ///@}
475
476 /** \name The general position function.
477 **********************************************************************/
478 ///@{
479
480 /**
481 * The general position function. GeodesicLine::Position and
482 * GeodesicLine::ArcPosition are defined in terms of this function.
483 *
484 * @param[in] arcmode boolean flag determining the meaning of the second
485 * parameter; if \e arcmode is false, then the GeodesicLine object must
486 * have been constructed with \e caps |= GeodesicLine::DISTANCE_IN.
487 * @param[in] s12_a12 if \e arcmode is false, this is the distance between
488 * point 1 and point 2 (meters); otherwise it is the arc length between
489 * point 1 and point 2 (degrees); it can be negative.
490 * @param[in] outmask a bitor'ed combination of GeodesicLine::mask values
491 * specifying which of the following parameters should be set.
492 * @param[out] lat2 latitude of point 2 (degrees).
493 * @param[out] lon2 longitude of point 2 (degrees); requires that the
494 * GeodesicLine object was constructed with \e caps |=
495 * GeodesicLine::LONGITUDE.
496 * @param[out] azi2 (forward) azimuth at point 2 (degrees).
497 * @param[out] s12 distance from point 1 to point 2 (meters); requires
498 * that the GeodesicLine object was constructed with \e caps |=
499 * GeodesicLine::DISTANCE.
500 * @param[out] m12 reduced length of geodesic (meters); requires that the
501 * GeodesicLine object was constructed with \e caps |=
502 * GeodesicLine::REDUCEDLENGTH.
503 * @param[out] M12 geodesic scale of point 2 relative to point 1
504 * (dimensionless); requires that the GeodesicLine object was constructed
505 * with \e caps |= GeodesicLine::GEODESICSCALE.
506 * @param[out] M21 geodesic scale of point 1 relative to point 2
507 * (dimensionless); requires that the GeodesicLine object was constructed
508 * with \e caps |= GeodesicLine::GEODESICSCALE.
509 * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
510 * that the GeodesicLine object was constructed with \e caps |=
511 * GeodesicLine::AREA.
512 * @return \e a12 arc length from point 1 to point 2 (degrees).
513 *
514 * The GeodesicLine::mask values possible for \e outmask are
515 * - \e outmask |= GeodesicLine::LATITUDE for the latitude \e lat2;
516 * - \e outmask |= GeodesicLine::LONGITUDE for the latitude \e lon2;
517 * - \e outmask |= GeodesicLine::AZIMUTH for the latitude \e azi2;
518 * - \e outmask |= GeodesicLine::DISTANCE for the distance \e s12;
519 * - \e outmask |= GeodesicLine::REDUCEDLENGTH for the reduced length \e
520 * m12;
521 * - \e outmask |= GeodesicLine::GEODESICSCALE for the geodesic scales \e
522 * M12 and \e M21;
523 * - \e outmask |= GeodesicLine::AREA for the area \e S12;
524 * - \e outmask |= GeodesicLine::ALL for all of the above;
525 * - \e outmask |= GeodesicLine::LONG_UNROLL to unroll \e lon2 instead of
526 * reducing it into the range [&minus;180&deg;, 180&deg;].
527 * .
528 * Requesting a value which the GeodesicLine object is not capable of
529 * computing is not an error; the corresponding argument will not be
530 * altered. Note, however, that the arc length is always computed and
531 * returned as the function value.
532 *
533 * With the GeodesicLine::LONG_UNROLL bit set, the quantity \e lon2 &minus;
534 * \e lon1 indicates how many times and in what sense the geodesic
535 * encircles the ellipsoid.
536 **********************************************************************/
537 Math::real GenPosition(bool arcmode, real s12_a12, unsigned outmask,
538 real& lat2, real& lon2, real& azi2,
539 real& s12, real& m12, real& M12, real& M21,
540 real& S12) const;
541 ///@}
542
543 /** \name Setting point 3
544 **********************************************************************/
545 ///@{
546
547 /**
548 * Specify position of point 3 in terms of distance.
549 *
550 * @param[in] s13 the distance from point 1 to point 3 (meters); it
551 * can be negative.
552 *
553 * This is only useful if the GeodesicLine object has been constructed
554 * with \e caps |= GeodesicLine::DISTANCE_IN.
555 **********************************************************************/
556 void SetDistance(real s13);
557
558 /**
559 * Specify position of point 3 in terms of arc length.
560 *
561 * @param[in] a13 the arc length from point 1 to point 3 (degrees); it
562 * can be negative.
563 *
564 * The distance \e s13 is only set if the GeodesicLine object has been
565 * constructed with \e caps |= GeodesicLine::DISTANCE.
566 **********************************************************************/
567 void SetArc(real a13);
568
569 /**
570 * Specify position of point 3 in terms of either distance or arc length.
571 *
572 * @param[in] arcmode boolean flag determining the meaning of the second
573 * parameter; if \e arcmode is false, then the GeodesicLine object must
574 * have been constructed with \e caps |= GeodesicLine::DISTANCE_IN.
575 * @param[in] s13_a13 if \e arcmode is false, this is the distance from
576 * point 1 to point 3 (meters); otherwise it is the arc length from
577 * point 1 to point 3 (degrees); it can be negative.
578 **********************************************************************/
579 void GenSetDistance(bool arcmode, real s13_a13);
580 ///@}
581
582 /** \name Inspector functions
583 **********************************************************************/
584 ///@{
585
586 /**
587 * @return true if the object has been initialized.
588 **********************************************************************/
589 bool Init() const { return _caps != 0U; }
590
591 /**
592 * @return \e lat1 the latitude of point 1 (degrees).
593 **********************************************************************/
595 { return Init() ? _lat1 : Math::NaN(); }
596
597 /**
598 * @return \e lon1 the longitude of point 1 (degrees).
599 **********************************************************************/
601 { return Init() ? _lon1 : Math::NaN(); }
602
603 /**
604 * @return \e azi1 the azimuth (degrees) of the geodesic line at point 1.
605 **********************************************************************/
607 { return Init() ? _azi1 : Math::NaN(); }
608
609 /**
610 * The sine and cosine of \e azi1.
611 *
612 * @param[out] sazi1 the sine of \e azi1.
613 * @param[out] cazi1 the cosine of \e azi1.
614 **********************************************************************/
615 void Azimuth(real& sazi1, real& cazi1) const
616 { if (Init()) { sazi1 = _salp1; cazi1 = _calp1; } }
617
618 /**
619 * @return \e azi0 the azimuth (degrees) of the geodesic line as it crosses
620 * the equator in a northward direction.
621 *
622 * The result lies in [&minus;90&deg;, 90&deg;].
623 **********************************************************************/
625 { return Init() ? Math::atan2d(_salp0, _calp0) : Math::NaN(); }
626
627 /**
628 * The sine and cosine of \e azi0.
629 *
630 * @param[out] sazi0 the sine of \e azi0.
631 * @param[out] cazi0 the cosine of \e azi0.
632 **********************************************************************/
633 void EquatorialAzimuth(real& sazi0, real& cazi0) const
634 { if (Init()) { sazi0 = _salp0; cazi0 = _calp0; } }
635
636 /**
637 * @return \e a1 the arc length (degrees) between the northward equatorial
638 * crossing and point 1.
639 *
640 * The result lies in (&minus;180&deg;, 180&deg;].
641 **********************************************************************/
643 return Init() ? Math::atan2d(_ssig1, _csig1) : Math::NaN();
644 }
645
646 /**
647 * @return \e a the equatorial radius of the ellipsoid (meters). This is
648 * the value inherited from the Geodesic object used in the constructor.
649 **********************************************************************/
651 { return Init() ? _a : Math::NaN(); }
652
653 /**
654 * @return \e f the flattening of the ellipsoid. This is the value
655 * inherited from the Geodesic object used in the constructor.
656 **********************************************************************/
658 { return Init() ? _f : Math::NaN(); }
659
660 /**
661 * @return \e caps the computational capabilities that this object was
662 * constructed with. LATITUDE and AZIMUTH are always included.
663 **********************************************************************/
664 unsigned Capabilities() const { return _caps; }
665
666 /**
667 * Test what capabilities are available.
668 *
669 * @param[in] testcaps a set of bitor'ed GeodesicLine::mask values.
670 * @return true if the GeodesicLine object has all these capabilities.
671 **********************************************************************/
672 bool Capabilities(unsigned testcaps) const {
673 testcaps &= OUT_ALL;
674 return (_caps & testcaps) == testcaps;
675 }
676
677 /**
678 * The distance or arc length to point 3.
679 *
680 * @param[in] arcmode boolean flag determining the meaning of returned
681 * value.
682 * @return \e s13 if \e arcmode is false; \e a13 if \e arcmode is true.
683 **********************************************************************/
684 Math::real GenDistance(bool arcmode) const
685 { return Init() ? (arcmode ? _a13 : _s13) : Math::NaN(); }
686
687 /**
688 * @return \e s13, the distance to point 3 (meters).
689 **********************************************************************/
690 Math::real Distance() const { return GenDistance(false); }
691
692 /**
693 * @return \e a13, the arc length to point 3 (degrees).
694 **********************************************************************/
695 Math::real Arc() const { return GenDistance(true); }
696
697 /**
698 * \deprecated An old name for EquatorialRadius().
699 **********************************************************************/
700 GEOGRAPHICLIB_DEPRECATED("Use EquatorialRadius()")
701 Math::real MajorRadius() const { return EquatorialRadius(); }
702 ///@}
703
704 };
705
706} // namespace GeographicLib
707
708#endif // GEOGRAPHICLIB_GEODESICLINE_HPP
Header for GeographicLib::Constants class.
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:66
#define GEOGRAPHICLIB_DEPRECATED(msg)
Definition: Constants.hpp:81
GeographicLib::Math::real real
Definition: GeodSolve.cpp:31
Header for GeographicLib::Geodesic class.
void ArcPosition(real a12, real &lat2, real &lon2, real &azi2, real &s12, real &M12, real &M21) const
void ArcPosition(real a12, real &lat2, real &lon2, real &azi2, real &s12) const
Math::real Position(real s12, real &lat2, real &lon2, real &azi2, real &m12) const
Math::real Position(real s12, real &lat2, real &lon2, real &azi2, real &M12, real &M21) const
unsigned Capabilities() const
Math::real Position(real s12, real &lat2, real &lon2) const
Math::real Latitude() const
Math::real Distance() const
Math::real EquatorialAzimuth() const
void ArcPosition(real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21) const
Math::real Azimuth() const
void Azimuth(real &sazi1, real &cazi1) const
void ArcPosition(real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21, real &S12) const
Math::real Position(real s12, real &lat2, real &lon2, real &azi2, real &m12, real &M12, real &M21, real &S12) const
Math::real GenDistance(bool arcmode) const
void ArcPosition(real a12, real &lat2, real &lon2) const
Math::real Position(real s12, real &lat2, real &lon2, real &azi2, real &m12, real &M12, real &M21) const
Math::real EquatorialRadius() const
void ArcPosition(real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12) const
void EquatorialAzimuth(real &sazi0, real &cazi0) const
Math::real Position(real s12, real &lat2, real &lon2, real &azi2) const
bool Capabilities(unsigned testcaps) const
Math::real Longitude() const
Math::real EquatorialArc() const
Math::real Flattening() const
void ArcPosition(real a12, real &lat2, real &lon2, real &azi2) const
Geodesic calculations
Definition: Geodesic.hpp:172
Mathematical functions needed by GeographicLib.
Definition: Math.hpp:76
Namespace for GeographicLib.
Definition: Accumulator.cpp:12