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