NETGeographicLib  1.38
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Pages
Rhumb.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/Rhumb.h
4  * \brief Header for NETGeographicLib::Rhumb and NETGeographicLib::RhumbLine classes
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 
13 namespace NETGeographicLib {
14 
15  ref class RhumbLine;
16 
17  /**
18  * \brief .NET wrapper for GeographicLib::Rhumb.
19  *
20  * This class allows .NET applications to access GeographicLib::Rhumb.
21  *
22  * Solve of the direct and inverse rhumb problems.
23  *
24  * The path of constant azimuth between two points on a ellipsoid at (\e
25  * lat1, \e lon1) and (\e lat2, \e lon2) is called the rhumb line (also
26  * called the loxodrome). Its length is \e s12 and its azimuth is \e azi12
27  * and \e azi2. (The azimuth is the heading measured clockwise from north.)
28  *
29  * Given \e lat1, \e lon1, \e azi12, and \e s12, we can determine \e lat2,
30  * and \e lon2. This is the \e direct rhumb problem and its solution is
31  * given by the function Rhumb::Direct.
32  *
33  * Given \e lat1, \e lon1, \e lat2, and \e lon2, we can determine \e azi12
34  * and \e s12. This is the \e inverse rhumb problem, whose solution is
35  * given by Rhumb::Inverse. This finds the shortest such rhumb line, i.e.,
36  * the one that wraps no more than half way around the earth .
37  *
38  * Note that rhumb lines may be appreciably longer (up to 50%) than the
39  * corresponding Geodesic. For example the distance between London Heathrow
40  * and Tokyo Narita via the rhumb line is 11400 km which is 18% longer than
41  * the geodesic distance 9600 km.
42  *
43  * For more information on rhumb lines see \ref rhumb.
44  *
45  * C# Example:
46  * \include example-Rhumb.cs
47  * Managed C++ Example:
48  * \include example-Rhumb.cpp
49  * Visual Basic Example:
50  * \include example-Rhumb.vb
51  *
52  * <B>INTERFACE DIFFERENCES:</B><BR>
53  * The MajorRadius and Flattening functions are implemented as properties.
54  **********************************************************************/
55 
56  public ref class Rhumb {
57  private:
58  // pointer to the unmanaged Rhumb object
59  GeographicLib::Rhumb* m_pRhumb;
60 
61  // The finalizer destroys m_pRhumb when this object is destroyed.
62  !Rhumb(void);
63  public:
64 
65  /**
66  * Constructor for a ellipsoid with
67  *
68  * @param[in] a equatorial radius (meters).
69  * @param[in] f flattening of ellipsoid. Setting \e f = 0 gives a sphere.
70  * Negative \e f gives a prolate ellipsoid. If \e f &gt; 1, set
71  * flattening to 1/\e f.
72  * @param[in] exact if true (the default) use an addition theorem for
73  * elliptic integrals to compute divided differences; otherwise use
74  * series expansion (accurate for |<i>f</i>| < 0.01).
75  * @exception GeographicErr if \e a or (1 &minus; \e f) \e a is not
76  * positive.
77  *
78  * See \ref rhumb, for a detailed description of the \e exact parameter.
79  **********************************************************************/
80  Rhumb(double a, double f, bool exact);
81 
82  /**
83  * \brief The destructor calls the finalizer.
84  **********************************************************************/
85  ~Rhumb() { this->!Rhumb(); }
86 
87  /**
88  * Solve the direct rhumb problem.
89  *
90  * @param[in] lat1 latitude of point 1 (degrees).
91  * @param[in] lon1 longitude of point 1 (degrees).
92  * @param[in] azi12 azimuth of the rhumb line (degrees).
93  * @param[in] s12 distance between point 1 and point 2 (meters); it can be
94  * negative.
95  * @param[out] lat2 latitude of point 2 (degrees).
96  * @param[out] lon2 longitude of point 2 (degrees).
97  *
98  * \e lat1 should be in the range [&minus;90&deg;, 90&deg;]; \e lon1 and \e
99  * azi1 should be in the range [&minus;540&deg;, 540&deg;). The values of
100  * \e lon2 and \e azi2 returned are in the range [&minus;180&deg;,
101  * 180&deg;).
102  *
103  * If point 1 is a pole, the cosine of its latitude is taken to be
104  * 1/&epsilon;<sup>2</sup> (where &epsilon; is 2<sup>-52</sup>). This
105  * position, which is extremely close to the actual pole, allows the
106  * calculation to be carried out in finite terms. If \e s12 is large
107  * enough that the rhumb line crosses a pole, the longitude of point 2
108  * is indeterminate (a NaN is returned for \e lon2).
109  **********************************************************************/
110  void Direct(double lat1, double lon1, double azi12, double s12,
111  [System::Runtime::InteropServices::Out] double% lat2,
112  [System::Runtime::InteropServices::Out] double% lon2);
113 
114  /**
115  * Solve the inverse rhumb problem.
116  *
117  * @param[in] lat1 latitude of point 1 (degrees).
118  * @param[in] lon1 longitude of point 1 (degrees).
119  * @param[in] lat2 latitude of point 2 (degrees).
120  * @param[in] lon2 longitude of point 2 (degrees).
121  * @param[out] s12 rhumb distance between point 1 and point 2 (meters).
122  * @param[out] azi12 azimuth of the rhumb line (degrees).
123  *
124  * The shortest rhumb line is found. \e lat1 and \e lat2 should be in the
125  * range [&minus;90&deg;, 90&deg;]; \e lon1 and \e lon2 should be in the
126  * range [&minus;540&deg;, 540&deg;). The value of \e azi12 returned is in
127  * the range [&minus;180&deg;, 180&deg;).
128  *
129  * If either point is a pole, the cosine of its latitude is taken to be
130  * 1/&epsilon;<sup>2</sup> (where &epsilon; is 2<sup>-52</sup>). This
131  * position, which is extremely close to the actual pole, allows the
132  * calculation to be carried out in finite terms.
133  **********************************************************************/
134  void Inverse(double lat1, double lon1, double lat2, double lon2,
135  [System::Runtime::InteropServices::Out] double% s12,
136  [System::Runtime::InteropServices::Out] double% azi12);
137 
138  /**
139  * Set up to compute several points on a single rhumb line.
140  *
141  * @param[in] lat1 latitude of point 1 (degrees).
142  * @param[in] lon1 longitude of point 1 (degrees).
143  * @param[in] azi12 azimuth of the rhumb line (degrees).
144  * @return a RhumbLine object.
145  *
146  * \e lat1 should be in the range [&minus;90&deg;, 90&deg;]; \e lon1 and \e
147  * azi12 should be in the range [&minus;540&deg;, 540&deg;).
148  *
149  * If point 1 is a pole, the cosine of its latitude is taken to be
150  * 1/&epsilon;<sup>2</sup> (where &epsilon; is 2<sup>-52</sup>). This
151  * position, which is extremely close to the actual pole, allows the
152  * calculation to be carried out in finite terms.
153  **********************************************************************/
154  RhumbLine^ Line(double lat1, double lon1, double azi12);
155 
156  /** \name Inspector functions.
157  **********************************************************************/
158  ///@{
159 
160  /**
161  * @return the equatorial radius of the ellipsoid (meters). This is
162  * the value used in the constructor.
163  **********************************************************************/
164  property double MajorRadius { double get(); }
165 
166  /**
167  * @return f the flattening of the ellipsoid. This is the
168  * value used in the constructor.
169  **********************************************************************/
170  property double Flattening { double get(); }
171 
172  /**
173  * A global instantiation of Rhumb with the parameters for the WGS84
174  * ellipsoid.
175  **********************************************************************/
176  static Rhumb^ WGS84();
177  };
178 
179  /**
180  * \brief .NET wrapper for GeographicLib::RhumbLine.
181  *
182  * This class allows .NET applications to access GeographicLib::RhumbLine.
183  *
184  * Find a sequence of points on a single rhumb line.
185  *
186  * RhumbLine facilitates the determination of a series of points on a single
187  * rhumb line. The starting point (\e lat1, \e lon1) and the azimuth \e
188  * azi12 are specified in the call to Rhumb::Line which returns a RhumbLine
189  * object. RhumbLine.Position returns the location of point 2 a distance \e
190  * s12 along the rhumb line.
191 
192  * There is no public constructor for this class. (Use Rhumb::Line to create
193  * an instance.) The Rhumb object used to create a RhumbLine must stay in
194  * scope as long as the RhumbLine.
195  *
196  **********************************************************************/
197 
198  public ref class RhumbLine {
199  private:
200  // pointer to the unmanaged RhumbLine object.
201  GeographicLib::RhumbLine* m_pRhumbLine;
202 
203  // The finalizer destroys m_pRhumbLine when this object is destroyed.
204  !RhumbLine(void);
205  public:
206  /**
207  * \brief Constructor.
208  *
209  * For internal use only. Developers should not call this constructor
210  * directly. Use the Rhumb::Line function to create RhumbLine objects.
211  **********************************************************************/
212  RhumbLine( GeographicLib::RhumbLine* pRhumbLine );
213 
214  /**
215  * \brief The destructor calls the finalizer.
216  **********************************************************************/
217  ~RhumbLine() { this->!RhumbLine(); }
218 
219  /**
220  * Compute the position of point 2 which is a distance \e s12 (meters) from
221  * point 1.
222  *
223  * @param[in] s12 distance between point 1 and point 2 (meters); it can be
224  * negative.
225  * @param[out] lat2 latitude of point 2 (degrees).
226  * @param[out] lon2 longitude of point 2 (degrees).
227  *
228  * The values of \e lon2 and \e azi2 returned are in the range
229  * [&minus;180&deg;, 180&deg;).
230  *
231  * If \e s12 is large enough that the rhumb line crosses a pole, the
232  * longitude of point 2 is indeterminate (a NaN is returned for \e lon2).
233  **********************************************************************/
234  void Position(double s12,
235  [System::Runtime::InteropServices::Out] double% lat2,
236  [System::Runtime::InteropServices::Out] double% lon2);
237 
238  /** \name Inspector functions
239  **********************************************************************/
240  ///@{
241 
242  /**
243  * @return the latitude of point 1 (degrees).
244  **********************************************************************/
245  property double Latitude { double get(); }
246 
247  /**
248  * @return the longitude of point 1 (degrees).
249  **********************************************************************/
250  property double Longitude { double get(); }
251 
252  /**
253  * @return the azimuth of the rhumb line (degrees).
254  **********************************************************************/
255  property double Azimuth { double get(); }
256 
257  /**
258  * @return the equatorial radius of the ellipsoid (meters). This is
259  * the value inherited from the Rhumb object used in the constructor.
260  **********************************************************************/
261  property double MajorRadius { double get(); }
262 
263  /**
264  * @return the flattening of the ellipsoid. This is the value
265  * inherited from the Rhumb object used in the constructor.
266  **********************************************************************/
267  property double Flattening { double get(); }
268  };
269 
270 } // namespace NETGeographicLib