NETGeographicLib  1.43
Geocentric.h
Go to the documentation of this file.
1 /**
2  * \file NETGeographicLib/Geocentric.h
3  * \brief Header for NETGeographicLib::Geocentric class
4  *
5  * NETGeographicLib is copyright (c) Scott Heiman (2013)
6  * GeographicLib is Copyright (c) Charles Karney (2010-2012)
7  * <charles@karney.com> and licensed under the MIT/X11 License.
8  * For more information, see
9  * http://geographiclib.sourceforge.net/
10  **********************************************************************/
11 #pragma once
12 
13 namespace NETGeographicLib
14 {
15  /**
16  * \brief .NET wrapper for GeographicLib::Geocentric.
17  *
18  * This class allows .NET applications to access GeographicLib::Geocentric.
19  *
20  * Convert between geodetic coordinates latitude = \e lat, longitude = \e
21  * lon, height = \e h (measured vertically from the surface of the ellipsoid)
22  * to geocentric coordinates (\e X, \e Y, \e Z). The origin of geocentric
23  * coordinates is at the center of the earth. The \e Z axis goes thru the
24  * north pole, \e lat = 90&deg;. The \e X axis goes thru \e lat = 0,
25  * \e lon = 0. %Geocentric coordinates are also known as earth centered,
26  * earth fixed (ECEF) coordinates.
27  *
28  * The conversion from geographic to geocentric coordinates is
29  * straightforward. For the reverse transformation we use
30  * - H. Vermeille,
31  * <a href="https://dx.doi.org/10.1007/s00190-002-0273-6"> Direct
32  * transformation from geocentric coordinates to geodetic coordinates</a>,
33  * J. Geodesy 76, 451--454 (2002).
34  * .
35  * Several changes have been made to ensure that the method returns accurate
36  * results for all finite inputs (even if \e h is infinite). The changes are
37  * described in Appendix B of
38  * - C. F. F. Karney,
39  * <a href="http://arxiv.org/abs/1102.1215v1">Geodesics
40  * on an ellipsoid of revolution</a>,
41  * Feb. 2011;
42  * preprint
43  * <a href="http://arxiv.org/abs/1102.1215v1">arxiv:1102.1215v1</a>.
44  * .
45  * See \ref geocentric for more information.
46  *
47  * The errors in these routines are close to round-off. Specifically, for
48  * points within 5000 km of the surface of the ellipsoid (either inside or
49  * outside the ellipsoid), the error is bounded by 7 nm (7 nanometers) for
50  * the WGS84 ellipsoid. See \ref geocentric for further information on the
51  * errors.
52  *
53  * C# Example:
54  * \include example-Geocentric.cs
55  * Managed C++ Example:
56  * \include example-Geocentric.cpp
57  * Visual Basic Example:
58  * \include example-Geocentric.vb
59  *
60  * <B>INTERFACE DIFFERENCES:</B><BR>
61  * A default constructor is provided that assumes WGS84 parameters.
62  *
63  * The MajorRadius and Flattening functions are implemented as properties.
64  *
65  * The Forward and Reverse functions return rotation matrices as 2D,
66  * 3 &times; 3 arrays rather than vectors.
67  **********************************************************************/
68  public ref class Geocentric
69  {
70  private:
71  // pointer to the unmanaged GeographicLib::Geocentric
72  const GeographicLib::Geocentric* m_pGeocentric;
73 
74  // The finalizer frees unmanaged memory when the object is destroyed.
75  !Geocentric();
76  public:
77  /**
78  * Constructor for a ellipsoid with
79  *
80  * @param[in] a equatorial radius (meters).
81  * @param[in] f flattening of ellipsoid. Setting \e f = 0 gives a sphere.
82  * Negative \e f gives a prolate ellipsoid. If \e f > 1, set flattening
83  * to 1/\e f.
84  * @exception GeographicErr if \e a or (1 &minus; \e f ) \e a is not
85  * positive.
86  **********************************************************************/
87  Geocentric(double a, double f);
88 
89  /**
90  * A default constructor which assumes WGS84.
91  **********************************************************************/
92  Geocentric();
93 
94  /**
95  * A constructor that is initialized from an unmanaged
96  * GeographicLib::Geocentric. For internal use only.
97  * @param[in] g An existing GeographicLib::Geocentric.
98  **********************************************************************/
100 
101  /**
102  * The destructor calls the finalizer.
103  **********************************************************************/
105  { this->!Geocentric(); }
106 
107  /**
108  * Convert from geodetic to geocentric coordinates.
109  *
110  * @param[in] lat latitude of point (degrees).
111  * @param[in] lon longitude of point (degrees).
112  * @param[in] h height of point above the ellipsoid (meters).
113  * @param[out] X geocentric coordinate (meters).
114  * @param[out] Y geocentric coordinate (meters).
115  * @param[out] Z geocentric coordinate (meters).
116  *
117  * \e lat should be in the range [&minus;90&deg;, 90&deg;]; \e lon
118  * should be in the range [&minus;540&deg;, 540&deg;).
119  **********************************************************************/
120  void Forward(double lat, double lon, double h,
121  [System::Runtime::InteropServices::Out] double% X,
122  [System::Runtime::InteropServices::Out] double% Y,
123  [System::Runtime::InteropServices::Out] double% Z);
124 
125  /**
126  * Convert from geodetic to geocentric coordinates and return rotation
127  * matrix.
128  *
129  * @param[in] lat latitude of point (degrees).
130  * @param[in] lon longitude of point (degrees).
131  * @param[in] h height of point above the ellipsoid (meters).
132  * @param[out] X geocentric coordinate (meters).
133  * @param[out] Y geocentric coordinate (meters).
134  * @param[out] Z geocentric coordinate (meters).
135  * @param[out] M a 3 &times; 3 rotation matrix.
136  *
137  * Let \e v be a unit vector located at (\e lat, \e lon, \e h). We can
138  * express \e v as \e column vectors in one of two ways
139  * - in east, north, up coordinates (where the components are relative to a
140  * local coordinate system at (\e lat, \e lon, \e h)); call this
141  * representation \e v1.
142  * - in geocentric \e X, \e Y, \e Z coordinates; call this representation
143  * \e v0.
144  * .
145  * Then we have \e v0 = \e M &sdot; \e v1.
146  **********************************************************************/
147  void Forward(double lat, double lon, double h,
148  [System::Runtime::InteropServices::Out] double% X,
149  [System::Runtime::InteropServices::Out] double% Y,
150  [System::Runtime::InteropServices::Out] double% Z,
151  [System::Runtime::InteropServices::Out] array<double,2>^% M);
152 
153  /**
154  * Convert from geocentric to geodetic to coordinates.
155  *
156  * @param[in] X geocentric coordinate (meters).
157  * @param[in] Y geocentric coordinate (meters).
158  * @param[in] Z geocentric coordinate (meters).
159  * @param[out] lat latitude of point (degrees).
160  * @param[out] lon longitude of point (degrees).
161  * @param[out] h height of point above the ellipsoid (meters).
162  *
163  * In general there are multiple solutions and the result which maximizes
164  * \e h is returned. If there are still multiple solutions with different
165  * latitudes (applies only if \e Z = 0), then the solution with \e lat > 0
166  * is returned. If there are still multiple solutions with different
167  * longitudes (applies only if \e X = \e Y = 0) then \e lon = 0 is
168  * returned. The value of \e h returned satisfies \e h &ge; &minus; \e a
169  * (1 &minus; <i>e</i><sup>2</sup>) / sqrt(1 &minus; <i>e</i><sup>2</sup>
170  * sin<sup>2</sup>\e lat). The value of \e lon returned is in the range
171  * [&minus;180&deg;, 180&deg;).
172  **********************************************************************/
173  void Reverse(double X, double Y, double Z,
174  [System::Runtime::InteropServices::Out] double% lat,
175  [System::Runtime::InteropServices::Out] double% lon,
176  [System::Runtime::InteropServices::Out] double% h);
177 
178  /**
179  * Convert from geocentric to geodetic to coordinates.
180  *
181  * @param[in] X geocentric coordinate (meters).
182  * @param[in] Y geocentric coordinate (meters).
183  * @param[in] Z geocentric coordinate (meters).
184  * @param[out] lat latitude of point (degrees).
185  * @param[out] lon longitude of point (degrees).
186  * @param[out] h height of point above the ellipsoid (meters).
187  * @param[out] M a 3 &times; 3 rotation matrix.
188  *
189  * Let \e v be a unit vector located at (\e lat, \e lon, \e h). We can
190  * express \e v as \e column vectors in one of two ways
191  * - in east, north, up coordinates (where the components are relative to a
192  * local coordinate system at (\e lat, \e lon, \e h)); call this
193  * representation \e v1.
194  * - in geocentric \e X, \e Y, \e Z coordinates; call this representation
195  * \e v0.
196  * .
197  * Then we have \e v1 = \e M<sup>T</sup> &sdot; \e v0, where \e
198  * M<sup>T</sup> is the transpose of \e M.
199  **********************************************************************/
200  void Reverse(double X, double Y, double Z,
201  [System::Runtime::InteropServices::Out] double% lat,
202  [System::Runtime::InteropServices::Out] double% lon,
203  [System::Runtime::InteropServices::Out] double% h,
204  [System::Runtime::InteropServices::Out] array<double,2>^% M);
205 
206  /** \name Inspector functions
207  **********************************************************************/
208  ///@{
209  /**
210  * @return a pointer to the unmanaged GeographicLib::Geocentric.
211  **********************************************************************/
212  System::IntPtr^ GetUnmanaged();
213 
214  /**
215  * @return \e a the equatorial radius of the ellipsoid (meters). This is
216  * the value used in the constructor.
217  **********************************************************************/
218  property double MajorRadius { double get(); }
219 
220  /**
221  * @return \e f the flattening of the ellipsoid. This is the
222  * value used in the constructor.
223  **********************************************************************/
224  property double Flattening { double get(); }
225  ///@}
226  };
227 } // namespace NETGeographicLib
void Forward(double lat, double lon, double h, [System::Runtime::InteropServices::Out] double% X, [System::Runtime::InteropServices::Out] double% Y, [System::Runtime::InteropServices::Out] double% Z)
.NET wrapper for GeographicLib::Geocentric.
Definition: Geocentric.h:68
void Reverse(double X, double Y, double Z, [System::Runtime::InteropServices::Out] double% lat, [System::Runtime::InteropServices::Out] double% lon, [System::Runtime::InteropServices::Out] double% h)
System::IntPtr^ GetUnmanaged()