GeographicLib  2.1
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-2022) <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 
16 namespace 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  _aA1m1, _aA2m1, _aA3c, _bB11, _bB21, _bB31, _aA4, _bB41;
86  real _a13, _s13;
87  // index zero elements of _cC1a, _cC1pa, _cC2a, _cC3a are unused
88  real _cC1a[nC1_ + 1], _cC1pa[nC1p_ + 1], _cC2a[nC2_ + 1], _cC3a[nC3_],
89  _cC4a[nC4_]; // all the elements of _cC4a 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  **********************************************************************/
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  * A combination of the common capabilities: GeodesicLine::LATITUDE,
152  * GeodesicLine::LONGITUDE, GeodesicLine::AZIMUTH, GeodesicLine::DISTANCE.
153  * @hideinitializer
154  **********************************************************************/
155  STANDARD = Geodesic::STANDARD,
156  /**
157  * Allow distance \e s12 to be used as input in the direct geodesic
158  * problem.
159  * @hideinitializer
160  **********************************************************************/
161  DISTANCE_IN = Geodesic::DISTANCE_IN,
162  /**
163  * Calculate reduced length \e m12.
164  * @hideinitializer
165  **********************************************************************/
166  REDUCEDLENGTH = Geodesic::REDUCEDLENGTH,
167  /**
168  * Calculate geodesic scales \e M12 and \e M21.
169  * @hideinitializer
170  **********************************************************************/
171  GEODESICSCALE = Geodesic::GEODESICSCALE,
172  /**
173  * Calculate area \e S12.
174  * @hideinitializer
175  **********************************************************************/
177  /**
178  * Unroll \e lon2 in the direct calculation.
179  * @hideinitializer
180  **********************************************************************/
181  LONG_UNROLL = Geodesic::LONG_UNROLL,
182  /**
183  * All capabilities, calculate everything. (GeodesicLine::LONG_UNROLL is
184  * not included in this mask.)
185  * @hideinitializer
186  **********************************************************************/
188  };
189 
190  /** \name Constructors
191  **********************************************************************/
192  ///@{
193 
194  /**
195  * Constructor for a geodesic line staring at latitude \e lat1, longitude
196  * \e lon1, and azimuth \e azi1 (all in degrees).
197  *
198  * @param[in] g A Geodesic object used to compute the necessary information
199  * about the GeodesicLine.
200  * @param[in] lat1 latitude of point 1 (degrees).
201  * @param[in] lon1 longitude of point 1 (degrees).
202  * @param[in] azi1 azimuth at point 1 (degrees).
203  * @param[in] caps bitor'ed combination of GeodesicLine::mask values
204  * specifying the capabilities the GeodesicLine object should possess,
205  * i.e., which quantities can be returned in calls to
206  * GeodesicLine::Position.
207  *
208  * \e lat1 should be in the range [&minus;90&deg;, 90&deg;].
209  *
210  * The GeodesicLine::mask values are
211  * - \e caps |= GeodesicLine::LATITUDE for the latitude \e lat2; this is
212  * added automatically;
213  * - \e caps |= GeodesicLine::LONGITUDE for the latitude \e lon2;
214  * - \e caps |= GeodesicLine::AZIMUTH for the latitude \e azi2; this is
215  * added automatically;
216  * - \e caps |= GeodesicLine::DISTANCE for the distance \e s12;
217  * - \e caps |= GeodesicLine::REDUCEDLENGTH for the reduced length \e m12;
218  * - \e caps |= GeodesicLine::GEODESICSCALE for the geodesic scales \e M12
219  * and \e M21;
220  * - \e caps |= GeodesicLine::AREA for the area \e S12;
221  * - \e caps |= GeodesicLine::DISTANCE_IN permits the length of the
222  * geodesic to be given in terms of \e s12; without this capability the
223  * length can only be specified in terms of arc length;
224  * - \e caps |= GeodesicLine::ALL for all of the above.
225  * .
226  * The default value of \e caps is GeodesicLine::ALL.
227  *
228  * If the point is at a pole, the azimuth is defined by keeping \e lon1
229  * fixed, writing \e lat1 = &plusmn;(90&deg; &minus; &epsilon;), and taking
230  * the limit &epsilon; &rarr; 0+.
231  **********************************************************************/
232  GeodesicLine(const Geodesic& g, real lat1, real lon1, real azi1,
233  unsigned caps = ALL);
234 
235  /**
236  * A default constructor. If GeodesicLine::Position is called on the
237  * resulting object, it returns immediately (without doing any
238  * calculations). The object can be set with a call to Geodesic::Line.
239  * Use Init() to test whether object is still in this uninitialized state.
240  **********************************************************************/
241  GeodesicLine() : _caps(0U) {}
242  ///@}
243 
244  /** \name Position in terms of distance
245  **********************************************************************/
246  ///@{
247 
248  /**
249  * Compute the position of point 2 which is a distance \e s12 (meters) from
250  * point 1.
251  *
252  * @param[in] s12 distance from point 1 to point 2 (meters); it can be
253  * negative.
254  * @param[out] lat2 latitude of point 2 (degrees).
255  * @param[out] lon2 longitude of point 2 (degrees); requires that the
256  * GeodesicLine object was constructed with \e caps |=
257  * GeodesicLine::LONGITUDE.
258  * @param[out] azi2 (forward) azimuth at point 2 (degrees).
259  * @param[out] m12 reduced length of geodesic (meters); requires that the
260  * GeodesicLine object was constructed with \e caps |=
261  * GeodesicLine::REDUCEDLENGTH.
262  * @param[out] M12 geodesic scale of point 2 relative to point 1
263  * (dimensionless); requires that the GeodesicLine object was constructed
264  * with \e caps |= GeodesicLine::GEODESICSCALE.
265  * @param[out] M21 geodesic scale of point 1 relative to point 2
266  * (dimensionless); requires that the GeodesicLine object was constructed
267  * with \e caps |= GeodesicLine::GEODESICSCALE.
268  * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
269  * that the GeodesicLine object was constructed with \e caps |=
270  * GeodesicLine::AREA.
271  * @return \e a12 arc length from point 1 to point 2 (degrees).
272  *
273  * The values of \e lon2 and \e azi2 returned are in the range
274  * [&minus;180&deg;, 180&deg;].
275  *
276  * The GeodesicLine object \e must have been constructed with \e caps |=
277  * GeodesicLine::DISTANCE_IN; otherwise Math::NaN() is returned and no
278  * parameters are set. Requesting a value which the GeodesicLine object is
279  * not capable of computing is not an error; the corresponding argument
280  * will not be altered.
281  *
282  * The following functions are overloaded versions of
283  * GeodesicLine::Position which omit some of the output parameters. Note,
284  * however, that the arc length is always computed and returned as the
285  * function value.
286  **********************************************************************/
288  real& lat2, real& lon2, real& azi2,
289  real& m12, real& M12, real& M21,
290  real& S12) const {
291  real t;
292  return GenPosition(false, s12,
293  LATITUDE | LONGITUDE | AZIMUTH |
294  REDUCEDLENGTH | GEODESICSCALE | AREA,
295  lat2, lon2, azi2, t, m12, M12, M21, S12);
296  }
297 
298  /**
299  * See the documentation for GeodesicLine::Position.
300  **********************************************************************/
301  Math::real Position(real s12, real& lat2, real& lon2) const {
302  real t;
303  return GenPosition(false, s12,
304  LATITUDE | LONGITUDE,
305  lat2, lon2, t, t, t, t, t, t);
306  }
307 
308  /**
309  * See the documentation for GeodesicLine::Position.
310  **********************************************************************/
311  Math::real Position(real s12, real& lat2, real& lon2,
312  real& azi2) const {
313  real t;
314  return GenPosition(false, s12,
315  LATITUDE | LONGITUDE | AZIMUTH,
316  lat2, lon2, azi2, 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, real& m12) const {
324  real t;
325  return GenPosition(false, s12,
326  LATITUDE | LONGITUDE |
327  AZIMUTH | REDUCEDLENGTH,
328  lat2, lon2, azi2, t, m12, t, t, t);
329  }
330 
331  /**
332  * See the documentation for GeodesicLine::Position.
333  **********************************************************************/
334  Math::real Position(real s12, real& lat2, real& lon2,
335  real& azi2, real& M12, real& M21)
336  const {
337  real t;
338  return GenPosition(false, s12,
339  LATITUDE | LONGITUDE |
340  AZIMUTH | GEODESICSCALE,
341  lat2, lon2, azi2, t, t, M12, M21, t);
342  }
343 
344  /**
345  * See the documentation for GeodesicLine::Position.
346  **********************************************************************/
348  real& lat2, real& lon2, real& azi2,
349  real& m12, real& M12, real& M21)
350  const {
351  real t;
352  return GenPosition(false, s12,
353  LATITUDE | LONGITUDE | AZIMUTH |
354  REDUCEDLENGTH | GEODESICSCALE,
355  lat2, lon2, azi2, t, m12, M12, M21, t);
356  }
357  ///@}
358 
359  /** \name Position in terms of arc length
360  **********************************************************************/
361  ///@{
362 
363  /**
364  * Compute the position of point 2 which is an arc length \e a12 (degrees)
365  * from point 1.
366  *
367  * @param[in] a12 arc length from point 1 to point 2 (degrees); it can
368  * be negative.
369  * @param[out] lat2 latitude of point 2 (degrees).
370  * @param[out] lon2 longitude of point 2 (degrees); requires that the
371  * GeodesicLine object was constructed with \e caps |=
372  * GeodesicLine::LONGITUDE.
373  * @param[out] azi2 (forward) azimuth at point 2 (degrees).
374  * @param[out] s12 distance from point 1 to point 2 (meters); requires
375  * that the GeodesicLine object was constructed with \e caps |=
376  * GeodesicLine::DISTANCE.
377  * @param[out] m12 reduced length of geodesic (meters); requires that the
378  * GeodesicLine object was constructed with \e caps |=
379  * GeodesicLine::REDUCEDLENGTH.
380  * @param[out] M12 geodesic scale of point 2 relative to point 1
381  * (dimensionless); requires that the GeodesicLine object was constructed
382  * with \e caps |= GeodesicLine::GEODESICSCALE.
383  * @param[out] M21 geodesic scale of point 1 relative to point 2
384  * (dimensionless); requires that the GeodesicLine object was constructed
385  * with \e caps |= GeodesicLine::GEODESICSCALE.
386  * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
387  * that the GeodesicLine object was constructed with \e caps |=
388  * GeodesicLine::AREA.
389  *
390  * The values of \e lon2 and \e azi2 returned are in the range
391  * [&minus;180&deg;, 180&deg;].
392  *
393  * Requesting a value which the GeodesicLine object is not capable of
394  * computing is not an error; the corresponding argument will not be
395  * altered.
396  *
397  * The following functions are overloaded versions of
398  * GeodesicLine::ArcPosition which omit some of the output parameters.
399  **********************************************************************/
400  void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
401  real& s12, real& m12, real& M12, real& M21,
402  real& S12) const {
403  GenPosition(true, a12,
404  LATITUDE | LONGITUDE | AZIMUTH | DISTANCE |
405  REDUCEDLENGTH | GEODESICSCALE | AREA,
406  lat2, lon2, azi2, s12, m12, M12, M21, S12);
407  }
408 
409  /**
410  * See the documentation for GeodesicLine::ArcPosition.
411  **********************************************************************/
412  void ArcPosition(real a12, real& lat2, real& lon2)
413  const {
414  real t;
415  GenPosition(true, a12,
416  LATITUDE | LONGITUDE,
417  lat2, lon2, t, t, t, t, t, t);
418  }
419 
420  /**
421  * See the documentation for GeodesicLine::ArcPosition.
422  **********************************************************************/
423  void ArcPosition(real a12,
424  real& lat2, real& lon2, real& azi2)
425  const {
426  real t;
427  GenPosition(true, a12,
428  LATITUDE | LONGITUDE | AZIMUTH,
429  lat2, lon2, azi2, t, t, t, t, t);
430  }
431 
432  /**
433  * See the documentation for GeodesicLine::ArcPosition.
434  **********************************************************************/
435  void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
436  real& s12) const {
437  real t;
438  GenPosition(true, a12,
439  LATITUDE | LONGITUDE | AZIMUTH | DISTANCE,
440  lat2, lon2, azi2, s12, 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, real& m12) const {
448  real t;
449  GenPosition(true, a12,
450  LATITUDE | LONGITUDE | AZIMUTH |
451  DISTANCE | REDUCEDLENGTH,
452  lat2, lon2, azi2, s12, m12, t, t, t);
453  }
454 
455  /**
456  * See the documentation for GeodesicLine::ArcPosition.
457  **********************************************************************/
458  void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
459  real& s12, real& M12, real& M21)
460  const {
461  real t;
462  GenPosition(true, a12,
463  LATITUDE | LONGITUDE | AZIMUTH |
464  DISTANCE | GEODESICSCALE,
465  lat2, lon2, azi2, s12, t, M12, M21, t);
466  }
467 
468  /**
469  * See the documentation for GeodesicLine::ArcPosition.
470  **********************************************************************/
471  void ArcPosition(real a12, real& lat2, real& lon2, real& azi2,
472  real& s12, real& m12, real& M12, real& M21)
473  const {
474  real t;
475  GenPosition(true, a12,
476  LATITUDE | LONGITUDE | AZIMUTH |
477  DISTANCE | REDUCEDLENGTH | GEODESICSCALE,
478  lat2, lon2, azi2, s12, m12, M12, M21, t);
479  }
480  ///@}
481 
482  /** \name The general position function.
483  **********************************************************************/
484  ///@{
485 
486  /**
487  * The general position function. GeodesicLine::Position and
488  * GeodesicLine::ArcPosition are defined in terms of this function.
489  *
490  * @param[in] arcmode boolean flag determining the meaning of the second
491  * parameter; if \e arcmode is false, then the GeodesicLine object must
492  * have been constructed with \e caps |= GeodesicLine::DISTANCE_IN.
493  * @param[in] s12_a12 if \e arcmode is false, this is the distance between
494  * point 1 and point 2 (meters); otherwise it is the arc length between
495  * point 1 and point 2 (degrees); it can be negative.
496  * @param[in] outmask a bitor'ed combination of GeodesicLine::mask values
497  * specifying which of the following parameters should be set.
498  * @param[out] lat2 latitude of point 2 (degrees).
499  * @param[out] lon2 longitude of point 2 (degrees); requires that the
500  * GeodesicLine object was constructed with \e caps |=
501  * GeodesicLine::LONGITUDE.
502  * @param[out] azi2 (forward) azimuth at point 2 (degrees).
503  * @param[out] s12 distance from point 1 to point 2 (meters); requires
504  * that the GeodesicLine object was constructed with \e caps |=
505  * GeodesicLine::DISTANCE.
506  * @param[out] m12 reduced length of geodesic (meters); requires that the
507  * GeodesicLine object was constructed with \e caps |=
508  * GeodesicLine::REDUCEDLENGTH.
509  * @param[out] M12 geodesic scale of point 2 relative to point 1
510  * (dimensionless); requires that the GeodesicLine object was constructed
511  * with \e caps |= GeodesicLine::GEODESICSCALE.
512  * @param[out] M21 geodesic scale of point 1 relative to point 2
513  * (dimensionless); requires that the GeodesicLine object was constructed
514  * with \e caps |= GeodesicLine::GEODESICSCALE.
515  * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
516  * that the GeodesicLine object was constructed with \e caps |=
517  * GeodesicLine::AREA.
518  * @return \e a12 arc length from point 1 to point 2 (degrees).
519  *
520  * The GeodesicLine::mask values possible for \e outmask are
521  * - \e outmask |= GeodesicLine::LATITUDE for the latitude \e lat2;
522  * - \e outmask |= GeodesicLine::LONGITUDE for the latitude \e lon2;
523  * - \e outmask |= GeodesicLine::AZIMUTH for the latitude \e azi2;
524  * - \e outmask |= GeodesicLine::DISTANCE for the distance \e s12;
525  * - \e outmask |= GeodesicLine::REDUCEDLENGTH for the reduced length \e
526  * m12;
527  * - \e outmask |= GeodesicLine::GEODESICSCALE for the geodesic scales \e
528  * M12 and \e M21;
529  * - \e outmask |= GeodesicLine::AREA for the area \e S12;
530  * - \e outmask |= GeodesicLine::ALL for all of the above;
531  * - \e outmask |= GeodesicLine::LONG_UNROLL to unroll \e lon2 instead of
532  * reducing it into the range [&minus;180&deg;, 180&deg;].
533  * .
534  * Requesting a value which the GeodesicLine object is not capable of
535  * computing is not an error; the corresponding argument will not be
536  * altered. Note, however, that the arc length is always computed and
537  * returned as the function value.
538  *
539  * With the GeodesicLine::LONG_UNROLL bit set, the quantity \e lon2 &minus;
540  * \e lon1 indicates how many times and in what sense the geodesic
541  * encircles the ellipsoid.
542  **********************************************************************/
543  Math::real GenPosition(bool arcmode, real s12_a12, unsigned outmask,
544  real& lat2, real& lon2, real& azi2,
545  real& s12, real& m12, real& M12, real& M21,
546  real& S12) const;
547  ///@}
548 
549  /** \name Setting point 3
550  **********************************************************************/
551  ///@{
552 
553  /**
554  * Specify position of point 3 in terms of distance.
555  *
556  * @param[in] s13 the distance from point 1 to point 3 (meters); it
557  * can be negative.
558  *
559  * This is only useful if the GeodesicLine object has been constructed
560  * with \e caps |= GeodesicLine::DISTANCE_IN.
561  **********************************************************************/
562  void SetDistance(real s13);
563 
564  /**
565  * Specify position of point 3 in terms of arc length.
566  *
567  * @param[in] a13 the arc length from point 1 to point 3 (degrees); it
568  * can be negative.
569  *
570  * The distance \e s13 is only set if the GeodesicLine object has been
571  * constructed with \e caps |= GeodesicLine::DISTANCE.
572  **********************************************************************/
573  void SetArc(real a13);
574 
575  /**
576  * Specify position of point 3 in terms of either distance or arc length.
577  *
578  * @param[in] arcmode boolean flag determining the meaning of the second
579  * parameter; if \e arcmode is false, then the GeodesicLine object must
580  * have been constructed with \e caps |= GeodesicLine::DISTANCE_IN.
581  * @param[in] s13_a13 if \e arcmode is false, this is the distance from
582  * point 1 to point 3 (meters); otherwise it is the arc length from
583  * point 1 to point 3 (degrees); it can be negative.
584  **********************************************************************/
585  void GenSetDistance(bool arcmode, real s13_a13);
586  ///@}
587 
588  /** \name Inspector functions
589  **********************************************************************/
590  ///@{
591 
592  /**
593  * @return true if the object has been initialized.
594  **********************************************************************/
595  bool Init() const { return _caps != 0U; }
596 
597  /**
598  * @return \e lat1 the latitude of point 1 (degrees).
599  **********************************************************************/
601  { return Init() ? _lat1 : Math::NaN(); }
602 
603  /**
604  * @return \e lon1 the longitude of point 1 (degrees).
605  **********************************************************************/
607  { return Init() ? _lon1 : Math::NaN(); }
608 
609  /**
610  * @return \e azi1 the azimuth (degrees) of the geodesic line at point 1.
611  **********************************************************************/
613  { return Init() ? _azi1 : Math::NaN(); }
614 
615  /**
616  * The sine and cosine of \e azi1.
617  *
618  * @param[out] sazi1 the sine of \e azi1.
619  * @param[out] cazi1 the cosine of \e azi1.
620  **********************************************************************/
621  void Azimuth(real& sazi1, real& cazi1) const
622  { if (Init()) { sazi1 = _salp1; cazi1 = _calp1; } }
623 
624  /**
625  * @return \e azi0 the azimuth (degrees) of the geodesic line as it crosses
626  * the equator in a northward direction.
627  *
628  * The result lies in [&minus;90&deg;, 90&deg;].
629  **********************************************************************/
631  { return Init() ? Math::atan2d(_salp0, _calp0) : Math::NaN(); }
632 
633  /**
634  * The sine and cosine of \e azi0.
635  *
636  * @param[out] sazi0 the sine of \e azi0.
637  * @param[out] cazi0 the cosine of \e azi0.
638  **********************************************************************/
639  void EquatorialAzimuth(real& sazi0, real& cazi0) const
640  { if (Init()) { sazi0 = _salp0; cazi0 = _calp0; } }
641 
642  /**
643  * @return \e a1 the arc length (degrees) between the northward equatorial
644  * crossing and point 1.
645  *
646  * The result lies in [&minus;180&deg;, 180&deg;].
647  **********************************************************************/
649  return Init() ? Math::atan2d(_ssig1, _csig1) : Math::NaN();
650  }
651 
652  /**
653  * @return \e a the equatorial radius of the ellipsoid (meters). This is
654  * the value inherited from the Geodesic object used in the constructor.
655  **********************************************************************/
657  { return Init() ? _a : Math::NaN(); }
658 
659  /**
660  * @return \e f the flattening of the ellipsoid. This is the value
661  * inherited from the Geodesic object used in the constructor.
662  **********************************************************************/
664  { return Init() ? _f : Math::NaN(); }
665 
666  /**
667  * @return \e caps the computational capabilities that this object was
668  * constructed with. LATITUDE and AZIMUTH are always included.
669  **********************************************************************/
670  unsigned Capabilities() const { return _caps; }
671 
672  /**
673  * Test what capabilities are available.
674  *
675  * @param[in] testcaps a set of bitor'ed GeodesicLine::mask values.
676  * @return true if the GeodesicLine object has all these capabilities.
677  **********************************************************************/
678  bool Capabilities(unsigned testcaps) const {
679  testcaps &= OUT_ALL;
680  return (_caps & testcaps) == testcaps;
681  }
682 
683  /**
684  * The distance or arc length to point 3.
685  *
686  * @param[in] arcmode boolean flag determining the meaning of returned
687  * value.
688  * @return \e s13 if \e arcmode is false; \e a13 if \e arcmode is true.
689  **********************************************************************/
690  Math::real GenDistance(bool arcmode) const
691  { return Init() ? (arcmode ? _a13 : _s13) : Math::NaN(); }
692 
693  /**
694  * @return \e s13, the distance to point 3 (meters).
695  **********************************************************************/
696  Math::real Distance() const { return GenDistance(false); }
697 
698  /**
699  * @return \e a13, the arc length to point 3 (degrees).
700  **********************************************************************/
701  Math::real Arc() const { return GenDistance(true); }
702  ///@}
703 
704  };
705 
706 } // namespace GeographicLib
707 
708 #endif // GEOGRAPHICLIB_GEODESICLINE_HPP
Header for GeographicLib::Constants class.
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:67
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
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