NETGeographicLib  1.38
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Pages
GeodesicLineExact.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/GeodesicLineExact.h
4  * \brief Header for NETGeographicLib::GeodesicLineExact class
5  *
6  * NETGeographicLib is copyright (c) Scott Heiman (2013)
7  * GeographicLib is Copyright (c) Charles Karney (2010-2012)
8  * <charles@karney.com> and licensed under the MIT/X11 License.
9  * For more information, see
10  * http://geographiclib.sourceforge.net/
11  **********************************************************************/
12 #include "NETGeographicLib.h"
13 
14 namespace NETGeographicLib
15 {
16  ref class GeodesicExact;
17  /**
18  * \brief .NET wrapper for GeographicLib::GeodesicLineExact.
19  *
20  * This class allows .NET applications to access GeographicLib::GeodesicLineExact.
21  *
22  * GeodesicLineExact facilitates the determination of a series of points on a
23  * single geodesic. This is a companion to the GeodesicExact class. For
24  * additional information on this class see the documentation on the
25  * GeodesicLine class.
26  *
27  * C# Example:
28  * \include example-GeodesicLineExact.cs
29  * Managed C++ Example:
30  * \include example-GeodesicLineExact.cpp
31  * Visual Basic Example:
32  * \include example-GeodesicLineExact.vb
33  *
34  * <B>INTERFACE DIFFERENCES:</B><BR>
35  * A constructor has been provided that assumes WGS84 parameters.
36  *
37  * The following functions are implemented as properties:
38  * Latitude, Longitude, Azimuth, EquatorialAzimuth, EquatorialArc,
39  * MajorRadius, and Flattening.
40  *
41  * The constructors, GenPosition, and Capabilities functions accept the
42  * "capabilities mask" as a NETGeographicLib::Mask rather than an
43  * unsigned. The Capabilities function returns a NETGeographicLib::Mask
44  * rather than an unsigned.
45  **********************************************************************/
46  public ref class GeodesicLineExact
47  {
48  private:
49  // a pointer to the GeographicLib::GeodesicLineExact.
50  const GeographicLib::GeodesicLineExact* m_pGeodesicLineExact;
51 
52  // the finalizer frees the unmanaged memory when the object is destroyed.
53  !GeodesicLineExact(void);
54  public:
55 
56  /** \name Constructors
57  **********************************************************************/
58  ///@{
59 
60  /**
61  * Constructor for a geodesic line staring at latitude \e lat1, longitude
62  * \e lon1, and azimuth \e azi1 (all in degrees).
63  *
64  * @param[in] g A GeodesicExact object used to compute the necessary
65  * information about the GeodesicLineExact.
66  * @param[in] lat1 latitude of point 1 (degrees).
67  * @param[in] lon1 longitude of point 1 (degrees).
68  * @param[in] azi1 azimuth at point 1 (degrees).
69  * @param[in] caps bitor'ed combination of NETGeographicLib::Mask values
70  * specifying the capabilities the GeodesicLineExact object should
71  * possess, i.e., which quantities can be returned in calls to
72  * GeodesicLine::Position.
73  *
74  * \e lat1 should be in the range [&minus;90&deg;, 90&deg;]; \e lon1 and \e
75  * azi1 should be in the range [&minus;540&deg;, 540&deg;).
76  *
77  * The NETGeographicLib::Mask values are
78  * - \e caps |= GeodesicLineExact::LATITUDE for the latitude \e lat2; this
79  * is added automatically;
80  * - \e caps |= NETGeographicLib::Mask::LONGITUDE for the latitude \e lon2;
81  * - \e caps |= NETGeographicLib::Mask::AZIMUTH for the latitude \e azi2; this is
82  * added automatically;
83  * - \e caps |= NETGeographicLib::Mask::DISTANCE for the distance \e s12;
84  * - \e caps |= NETGeographicLib::Mask::REDUCEDLENGTH for the reduced length \e
85  m12;
86  * - \e caps |= NETGeographicLib::Mask::GEODESICSCALE for the geodesic scales \e
87  * M12 and \e M21;
88  * - \e caps |= NETGeographicLib::Mask::AREA for the area \e S12;
89  * - \e caps |= NETGeographicLib::Mask::DISTANCE_IN permits the length of the
90  * geodesic to be given in terms of \e s12; without this capability the
91  * length can only be specified in terms of arc length;
92  * - \e caps |= NETGeographicLib::Mask::ALL for all of the above.
93  * .
94  *
95  * If the point is at a pole, the azimuth is defined by keeping \e lon1
96  * fixed, writing \e lat1 = &plusmn;(90&deg; &minus; &epsilon;), and taking
97  * the limit &epsilon; &rarr; 0+.
98  **********************************************************************/
99  GeodesicLineExact(GeodesicExact^ g, double lat1, double lon1, double azi1,
100  NETGeographicLib::Mask caps );
101 
102  /**
103  * A default constructor which assumes the WGS84 ellipsoid. See
104  * constructor comments for details.
105  **********************************************************************/
106  GeodesicLineExact(double lat1, double lon1, double azi1,
108  ///@}
109 
110  /**
111  * The destructor calls the finalizer
112  **********************************************************************/
114  { this->!GeodesicLineExact(); }
115 
116  /** \name Position in terms of distance
117  **********************************************************************/
118  ///@{
119 
120  /**
121  * Compute the position of point 2 which is a distance \e s12 (meters)
122  * from point 1.
123  *
124  * @param[in] s12 distance between point 1 and point 2 (meters); it can be
125  * signed.
126  * @param[out] lat2 latitude of point 2 (degrees).
127  * @param[out] lon2 longitude of point 2 (degrees); requires that the
128  * GeodesicLineExact object was constructed with \e caps |=
129  * GeodesicLineExact::LONGITUDE.
130  * @param[out] azi2 (forward) azimuth at point 2 (degrees).
131  * @param[out] m12 reduced length of geodesic (meters); requires that the
132  * GeodesicLineExact object was constructed with \e caps |=
133  * GeodesicLineExact::REDUCEDLENGTH.
134  * @param[out] M12 geodesic scale of point 2 relative to point 1
135  * (dimensionless); requires that the GeodesicLineExact object was
136  * constructed with \e caps |= GeodesicLineExact::GEODESICSCALE.
137  * @param[out] M21 geodesic scale of point 1 relative to point 2
138  * (dimensionless); requires that the GeodesicLineExact object was
139  * constructed with \e caps |= GeodesicLineExact::GEODESICSCALE.
140  * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
141  * that the GeodesicLineExact object was constructed with \e caps |=
142  * GeodesicLineExact::AREA.
143  * @return \e a12 arc length of between point 1 and point 2 (degrees).
144  *
145  * The values of \e lon2 and \e azi2 returned are in the range
146  * [&minus;180&deg;, 180&deg;).
147  *
148  * The GeodesicLineExact object \e must have been constructed with \e caps
149  * |= GeodesicLineExact::DISTANCE_IN; otherwise Math::NaN() is returned and
150  * no parameters are set. Requesting a value which the GeodesicLineExact
151  * object is not capable of computing is not an error; the corresponding
152  * argument will not be altered.
153  *
154  * The following functions are overloaded versions of
155  * GeodesicLineExact::Position which omit some of the output parameters.
156  * Note, however, that the arc length is always computed and returned as
157  * the function value.
158  **********************************************************************/
159  double Position(double s12,
160  [System::Runtime::InteropServices::Out] double% lat2,
161  [System::Runtime::InteropServices::Out] double% lon2,
162  [System::Runtime::InteropServices::Out] double% azi2,
163  [System::Runtime::InteropServices::Out] double% m12,
164  [System::Runtime::InteropServices::Out] double% M12,
165  [System::Runtime::InteropServices::Out] double% M21,
166  [System::Runtime::InteropServices::Out] double% S12);
167 
168  /**
169  * See the documentation for GeodesicLineExact::Position.
170  **********************************************************************/
171  double Position(double s12,
172  [System::Runtime::InteropServices::Out] double% lat2,
173  [System::Runtime::InteropServices::Out] double% lon2);
174 
175  /**
176  * See the documentation for GeodesicLineExact::Position.
177  **********************************************************************/
178  double Position(double s12,
179  [System::Runtime::InteropServices::Out] double% lat2,
180  [System::Runtime::InteropServices::Out] double% lon2,
181  [System::Runtime::InteropServices::Out] double% azi2);
182 
183  /**
184  * See the documentation for GeodesicLineExact::Position.
185  **********************************************************************/
186  double Position(double s12,
187  [System::Runtime::InteropServices::Out] double% lat2,
188  [System::Runtime::InteropServices::Out] double% lon2,
189  [System::Runtime::InteropServices::Out] double% azi2,
190  [System::Runtime::InteropServices::Out] double% m12);
191 
192  /**
193  * See the documentation for GeodesicLineExact::Position.
194  **********************************************************************/
195  double Position(double s12,
196  [System::Runtime::InteropServices::Out] double% lat2,
197  [System::Runtime::InteropServices::Out] double% lon2,
198  [System::Runtime::InteropServices::Out] double% azi2,
199  [System::Runtime::InteropServices::Out] double% M12,
200  [System::Runtime::InteropServices::Out] double% M21);
201 
202  /**
203  * See the documentation for GeodesicLineExact::Position.
204  **********************************************************************/
205  double Position(double s12,
206  [System::Runtime::InteropServices::Out] double% lat2,
207  [System::Runtime::InteropServices::Out] double% lon2,
208  [System::Runtime::InteropServices::Out] double% azi2,
209  [System::Runtime::InteropServices::Out] double% m12,
210  [System::Runtime::InteropServices::Out] double% M12,
211  [System::Runtime::InteropServices::Out] double% M21);
212 
213  ///@}
214 
215  /** \name Position in terms of arc length
216  **********************************************************************/
217  ///@{
218 
219  /**
220  * Compute the position of point 2 which is an arc length \e a12 (degrees)
221  * from point 1.
222  *
223  * @param[in] a12 arc length between point 1 and point 2 (degrees); it can
224  * be signed.
225  * @param[out] lat2 latitude of point 2 (degrees).
226  * @param[out] lon2 longitude of point 2 (degrees); requires that the
227  * GeodesicLineExact object was constructed with \e caps |=
228  * GeodesicLineExact::LONGITUDE.
229  * @param[out] azi2 (forward) azimuth at point 2 (degrees).
230  * @param[out] s12 distance between point 1 and point 2 (meters); requires
231  * that the GeodesicLineExact object was constructed with \e caps |=
232  * GeodesicLineExact::DISTANCE.
233  * @param[out] m12 reduced length of geodesic (meters); requires that the
234  * GeodesicLineExact object was constructed with \e caps |=
235  * GeodesicLineExact::REDUCEDLENGTH.
236  * @param[out] M12 geodesic scale of point 2 relative to point 1
237  * (dimensionless); requires that the GeodesicLineExact object was
238  * constructed with \e caps |= GeodesicLineExact::GEODESICSCALE.
239  * @param[out] M21 geodesic scale of point 1 relative to point 2
240  * (dimensionless); requires that the GeodesicLineExact object was
241  * constructed with \e caps |= GeodesicLineExact::GEODESICSCALE.
242  * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
243  * that the GeodesicLineExact object was constructed with \e caps |=
244  * GeodesicLineExact::AREA.
245  *
246  * The values of \e lon2 and \e azi2 returned are in the range
247  * [&minus;180&deg;, 180&deg;).
248  *
249  * Requesting a value which the GeodesicLineExact object is not capable of
250  * computing is not an error; the corresponding argument will not be
251  * altered.
252  *
253  * The following functions are overloaded versions of
254  * GeodesicLineExact::ArcPosition which omit some of the output parameters.
255  **********************************************************************/
256  void ArcPosition(double a12,
257  [System::Runtime::InteropServices::Out] double% lat2,
258  [System::Runtime::InteropServices::Out] double% lon2,
259  [System::Runtime::InteropServices::Out] double% azi2,
260  [System::Runtime::InteropServices::Out] double% s12,
261  [System::Runtime::InteropServices::Out] double% m12,
262  [System::Runtime::InteropServices::Out] double% M12,
263  [System::Runtime::InteropServices::Out] double% M21,
264  [System::Runtime::InteropServices::Out] double% S12);
265 
266  /**
267  * See the documentation for GeodesicLineExact::ArcPosition.
268  **********************************************************************/
269  void ArcPosition(double a12,
270  [System::Runtime::InteropServices::Out] double% lat2,
271  [System::Runtime::InteropServices::Out] double% lon2);
272 
273  /**
274  * See the documentation for GeodesicLineExact::ArcPosition.
275  **********************************************************************/
276  void ArcPosition(double a12,
277  [System::Runtime::InteropServices::Out] double% lat2,
278  [System::Runtime::InteropServices::Out] double% lon2,
279  [System::Runtime::InteropServices::Out] double% azi2);
280 
281  /**
282  * See the documentation for GeodesicLineExact::ArcPosition.
283  **********************************************************************/
284  void ArcPosition(double a12,
285  [System::Runtime::InteropServices::Out] double% lat2,
286  [System::Runtime::InteropServices::Out] double% lon2,
287  [System::Runtime::InteropServices::Out] double% azi2,
288  [System::Runtime::InteropServices::Out] double% s12);
289 
290  /**
291  * See the documentation for GeodesicLineExact::ArcPosition.
292  **********************************************************************/
293  void ArcPosition(double a12,
294  [System::Runtime::InteropServices::Out] double% lat2,
295  [System::Runtime::InteropServices::Out] double% lon2,
296  [System::Runtime::InteropServices::Out] double% azi2,
297  [System::Runtime::InteropServices::Out] double% s12,
298  [System::Runtime::InteropServices::Out] double% m12);
299 
300  /**
301  * See the documentation for GeodesicLineExact::ArcPosition.
302  **********************************************************************/
303  void ArcPosition(double a12,
304  [System::Runtime::InteropServices::Out] double% lat2,
305  [System::Runtime::InteropServices::Out] double% lon2,
306  [System::Runtime::InteropServices::Out] double% azi2,
307  [System::Runtime::InteropServices::Out] double% s12,
308  [System::Runtime::InteropServices::Out] double% M12,
309  [System::Runtime::InteropServices::Out] double% M21);
310 
311  /**
312  * See the documentation for GeodesicLineExact::ArcPosition.
313  **********************************************************************/
314  void ArcPosition(double a12,
315  [System::Runtime::InteropServices::Out] double% lat2,
316  [System::Runtime::InteropServices::Out] double% lon2,
317  [System::Runtime::InteropServices::Out] double% azi2,
318  [System::Runtime::InteropServices::Out] double% s12,
319  [System::Runtime::InteropServices::Out] double% m12,
320  [System::Runtime::InteropServices::Out] double% M12,
321  [System::Runtime::InteropServices::Out] double% M21);
322  ///@}
323 
324  /** \name The general position function.
325  **********************************************************************/
326  ///@{
327 
328  /**
329  * The general position function. GeodesicLineExact::Position and
330  * GeodesicLineExact::ArcPosition are defined in terms of this function.
331  *
332  * @param[in] arcmode boolean flag determining the meaning of the second
333  * parameter; if arcmode is false, then the GeodesicLineExact object must
334  * have been constructed with \e caps |= GeodesicLineExact::DISTANCE_IN.
335  * @param[in] s12_a12 if \e arcmode is false, this is the distance between
336  * point 1 and point 2 (meters); otherwise it is the arc length between
337  * point 1 and point 2 (degrees); it can be signed.
338  * @param[in] outmask a bitor'ed combination of NETGeographicLib::Mask
339  * values specifying which of the following parameters should be set.
340  * @param[out] lat2 latitude of point 2 (degrees).
341  * @param[out] lon2 longitude of point 2 (degrees); requires that the
342  * GeodesicLineExact object was constructed with \e caps |=
343  * GeodesicLineExact::LONGITUDE.
344  * @param[out] azi2 (forward) azimuth at point 2 (degrees).
345  * @param[out] s12 distance between point 1 and point 2 (meters); requires
346  * that the GeodesicLineExact object was constructed with \e caps |=
347  * GeodesicLineExact::DISTANCE.
348  * @param[out] m12 reduced length of geodesic (meters); requires that the
349  * GeodesicLineExact object was constructed with \e caps |=
350  * GeodesicLineExact::REDUCEDLENGTH.
351  * @param[out] M12 geodesic scale of point 2 relative to point 1
352  * (dimensionless); requires that the GeodesicLineExact object was
353  * constructed with \e caps |= GeodesicLineExact::GEODESICSCALE.
354  * @param[out] M21 geodesic scale of point 1 relative to point 2
355  * (dimensionless); requires that the GeodesicLineExact object was
356  * constructed with \e caps |= GeodesicLineExact::GEODESICSCALE.
357  * @param[out] S12 area under the geodesic (meters<sup>2</sup>); requires
358  * that the GeodesicLineExact object was constructed with \e caps |=
359  * GeodesicLineExact::AREA.
360  * @return \e a12 arc length of between point 1 and point 2 (degrees).
361  *
362  * The NETGeographicLib::Mask values possible for \e outmask are
363  * - \e outmask |= NETGeographicLib::Mask::LATITUDE for the latitude \e lat2;
364  * - \e outmask |= NETGeographicLib::Mask::LONGITUDE for the latitude \e lon2;
365  * - \e outmask |= NETGeographicLib::Mask::AZIMUTH for the latitude \e azi2;
366  * - \e outmask |= NETGeographicLib::Mask::DISTANCE for the distance \e s12;
367  * - \e outmask |= NETGeographicLib::Mask::REDUCEDLENGTH for the reduced length
368  * \e m12;
369  * - \e outmask |= NETGeographicLib::Mask::GEODESICSCALE for the geodesic scales
370  * \e M12 and \e M21;
371  * - \e outmask |= NETGeographicLib::Mask::AREA for the area \e S12;
372  * - \e outmask |= NETGeographicLib::Mask::ALL for all of the above.
373  * .
374  * Requesting a value which the GeodesicLineExact object is not capable of
375  * computing is not an error; the corresponding argument will not be
376  * altered. Note, however, that the arc length is always computed and
377  * returned as the function value.
378  **********************************************************************/
379  double GenPosition(bool arcmode, double s12_a12,
380  NETGeographicLib::Mask outmask,
381  [System::Runtime::InteropServices::Out] double% lat2,
382  [System::Runtime::InteropServices::Out] double% lon2,
383  [System::Runtime::InteropServices::Out] double% azi2,
384  [System::Runtime::InteropServices::Out] double% s12,
385  [System::Runtime::InteropServices::Out] double% m12,
386  [System::Runtime::InteropServices::Out] double% M12,
387  [System::Runtime::InteropServices::Out] double% M21,
388  [System::Runtime::InteropServices::Out] double% S12);
389 
390  ///@}
391 
392  /** \name Inspector functions
393  **********************************************************************/
394  ///@{
395  /**
396  * @return \e lat1 the latitude of point 1 (degrees).
397  **********************************************************************/
398  property double Latitude { double get(); }
399 
400  /**
401  * @return \e lon1 the longitude of point 1 (degrees).
402  **********************************************************************/
403  property double Longitude { double get(); }
404 
405  /**
406  * @return \e azi1 the azimuth (degrees) of the geodesic line at point 1.
407  **********************************************************************/
408  property double Azimuth { double get(); }
409 
410  /**
411  * @return \e azi0 the azimuth (degrees) of the geodesic line as it crosses
412  * the equator in a northward direction.
413  **********************************************************************/
414  property double EquatorialAzimuth { double get(); }
415 
416  /**
417  * @return \e a1 the arc length (degrees) between the northward equatorial
418  * crossing and point 1.
419  **********************************************************************/
420  property double EquatorialArc { double get(); }
421 
422  /**
423  * @return \e a the equatorial radius of the ellipsoid (meters). This is
424  * the value inherited from the GeodesicExact object used in the
425  * constructor.
426  **********************************************************************/
427  property double MajorRadius { double get(); }
428 
429  /**
430  * @return \e f the flattening of the ellipsoid. This is the value
431  * inherited from the GeodesicExact object used in the constructor.
432  **********************************************************************/
433  property double Flattening { double get(); }
434 
435  /**
436  * @return \e caps the computational capabilities that this object was
437  * constructed with. LATITUDE and AZIMUTH are always included.
438  **********************************************************************/
440 
441  /**
442  * @param[in] testcaps a set of bitor'ed GeodesicLineExact::mask values.
443  * @return true if the GeodesicLineExact object has all these capabilities.
444  **********************************************************************/
445  bool Capabilities(NETGeographicLib::Mask testcaps);
446  ///@}
447  };
448 } // namespace NETGeographicLib
Header for NETGeographicLib::NETGeographicLib objects.
void ArcPosition(double a12, [System::Runtime::InteropServices::Out] double% lat2, [System::Runtime::InteropServices::Out] double% lon2, [System::Runtime::InteropServices::Out] double% azi2, [System::Runtime::InteropServices::Out] double% s12, [System::Runtime::InteropServices::Out] double% m12, [System::Runtime::InteropServices::Out] double% M12, [System::Runtime::InteropServices::Out] double% M21, [System::Runtime::InteropServices::Out] double% S12)
double GenPosition(bool arcmode, double s12_a12, NETGeographicLib::Mask outmask, [System::Runtime::InteropServices::Out] double% lat2, [System::Runtime::InteropServices::Out] double% lon2, [System::Runtime::InteropServices::Out] double% azi2, [System::Runtime::InteropServices::Out] double% s12, [System::Runtime::InteropServices::Out] double% m12, [System::Runtime::InteropServices::Out] double% M12, [System::Runtime::InteropServices::Out] double% M21, [System::Runtime::InteropServices::Out] double% S12)
GeodesicLineExact(GeodesicExact^ g, double lat1, double lon1, double azi1, NETGeographicLib::Mask caps)
.NET wrapper for GeographicLib::GeodesicLineExact.
.NET wrapper for GeographicLib::GeodesicExact.
Definition: GeodesicExact.h:86
double Position(double s12, [System::Runtime::InteropServices::Out] double% lat2, [System::Runtime::InteropServices::Out] double% lon2, [System::Runtime::InteropServices::Out] double% azi2, [System::Runtime::InteropServices::Out] double% m12, [System::Runtime::InteropServices::Out] double% M12, [System::Runtime::InteropServices::Out] double% M21, [System::Runtime::InteropServices::Out] double% S12)
NETGeographicLib::Mask Capabilities()