NETGeographicLib  1.50.1
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  * https://geographiclib.sourceforge.io/
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://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="https://arxiv.org/abs/1102.1215v1">Geodesics
40  * on an ellipsoid of revolution</a>,
41  * Feb. 2011;
42  * preprint
43  * <a href="https://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 EquatorialRadius 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.
83  * @exception GeographicErr if \e a or (1 &minus; \e f ) \e a is not
84  * positive.
85  **********************************************************************/
86  Geocentric(double a, double f);
87 
88  /**
89  * A default constructor which assumes WGS84.
90  **********************************************************************/
92 
93  /**
94  * A constructor that is initialized from an unmanaged
95  * GeographicLib::Geocentric. For internal use only.
96  * @param[in] g An existing GeographicLib::Geocentric.
97  **********************************************************************/
99 
100  /**
101  * The destructor calls the finalizer.
102  **********************************************************************/
104  { this->!Geocentric(); }
105 
106  /**
107  * Convert from geodetic to geocentric coordinates.
108  *
109  * @param[in] lat latitude of point (degrees).
110  * @param[in] lon longitude of point (degrees).
111  * @param[in] h height of point above the ellipsoid (meters).
112  * @param[out] X geocentric coordinate (meters).
113  * @param[out] Y geocentric coordinate (meters).
114  * @param[out] Z geocentric coordinate (meters).
115  *
116  * \e lat should be in the range [&minus;90&deg;, 90&deg;].
117  **********************************************************************/
118  void Forward(double lat, double lon, double h,
119  [System::Runtime::InteropServices::Out] double% X,
120  [System::Runtime::InteropServices::Out] double% Y,
121  [System::Runtime::InteropServices::Out] double% Z);
122 
123  /**
124  * Convert from geodetic to geocentric coordinates and return rotation
125  * matrix.
126  *
127  * @param[in] lat latitude of point (degrees).
128  * @param[in] lon longitude of point (degrees).
129  * @param[in] h height of point above the ellipsoid (meters).
130  * @param[out] X geocentric coordinate (meters).
131  * @param[out] Y geocentric coordinate (meters).
132  * @param[out] Z geocentric coordinate (meters).
133  * @param[out] M a 3 &times; 3 rotation matrix.
134  *
135  * Let \e v be a unit vector located at (\e lat, \e lon, \e h). We can
136  * express \e v as \e column vectors in one of two ways
137  * - in east, north, up coordinates (where the components are relative to a
138  * local coordinate system at (\e lat, \e lon, \e h)); call this
139  * representation \e v1.
140  * - in geocentric \e X, \e Y, \e Z coordinates; call this representation
141  * \e v0.
142  * .
143  * Then we have \e v0 = \e M &sdot; \e v1.
144  **********************************************************************/
145  void Forward(double lat, double lon, double h,
146  [System::Runtime::InteropServices::Out] double% X,
147  [System::Runtime::InteropServices::Out] double% Y,
148  [System::Runtime::InteropServices::Out] double% Z,
149  [System::Runtime::InteropServices::Out] array<double,2>^% M);
150 
151  /**
152  * Convert from geocentric to geodetic to coordinates.
153  *
154  * @param[in] X geocentric coordinate (meters).
155  * @param[in] Y geocentric coordinate (meters).
156  * @param[in] Z geocentric coordinate (meters).
157  * @param[out] lat latitude of point (degrees).
158  * @param[out] lon longitude of point (degrees).
159  * @param[out] h height of point above the ellipsoid (meters).
160  *
161  * In general there are multiple solutions and the result which maximizes
162  * \e h is returned. If there are still multiple solutions with different
163  * latitudes (applies only if \e Z = 0), then the solution with \e lat > 0
164  * is returned. If there are still multiple solutions with different
165  * longitudes (applies only if \e X = \e Y = 0) then \e lon = 0 is
166  * returned. The value of \e h returned satisfies \e h &ge; &minus; \e a
167  * (1 &minus; <i>e</i><sup>2</sup>) / sqrt(1 &minus; <i>e</i><sup>2</sup>
168  * sin<sup>2</sup>\e lat). The value of \e lon returned is in the range
169  * [&minus;180&deg;, 180&deg;).
170  **********************************************************************/
171  void Reverse(double X, double Y, double Z,
172  [System::Runtime::InteropServices::Out] double% lat,
173  [System::Runtime::InteropServices::Out] double% lon,
174  [System::Runtime::InteropServices::Out] double% h);
175 
176  /**
177  * Convert from geocentric to geodetic to coordinates.
178  *
179  * @param[in] X geocentric coordinate (meters).
180  * @param[in] Y geocentric coordinate (meters).
181  * @param[in] Z geocentric coordinate (meters).
182  * @param[out] lat latitude of point (degrees).
183  * @param[out] lon longitude of point (degrees).
184  * @param[out] h height of point above the ellipsoid (meters).
185  * @param[out] M a 3 &times; 3 rotation matrix.
186  *
187  * Let \e v be a unit vector located at (\e lat, \e lon, \e h). We can
188  * express \e v as \e column vectors in one of two ways
189  * - in east, north, up coordinates (where the components are relative to a
190  * local coordinate system at (\e lat, \e lon, \e h)); call this
191  * representation \e v1.
192  * - in geocentric \e X, \e Y, \e Z coordinates; call this representation
193  * \e v0.
194  * .
195  * Then we have \e v1 = \e M<sup>T</sup> &sdot; \e v0, where \e
196  * M<sup>T</sup> is the transpose of \e M.
197  **********************************************************************/
198  void Reverse(double X, double Y, double Z,
199  [System::Runtime::InteropServices::Out] double% lat,
200  [System::Runtime::InteropServices::Out] double% lon,
201  [System::Runtime::InteropServices::Out] double% h,
202  [System::Runtime::InteropServices::Out] array<double,2>^% M);
203 
204  /** \name Inspector functions
205  **********************************************************************/
206  ///@{
207  /**
208  * @return a pointer to the unmanaged GeographicLib::Geocentric.
209  **********************************************************************/
210  System::IntPtr^ GetUnmanaged();
211 
212  /**
213  * @return \e a the equatorial radius of the ellipsoid (meters). This is
214  * the value used in the constructor.
215  **********************************************************************/
216  property double EquatorialRadius { double get(); }
217 
218  /**
219  * @return \e f the flattening of the ellipsoid. This is the
220  * value used in the constructor.
221  **********************************************************************/
222  property double Flattening { double get(); }
223  ///@}
224  };
225 } // namespace NETGeographicLib
NETGeographicLib::Geocentric
.NET wrapper for GeographicLib::Geocentric.
Definition: Geocentric.h:69
NETGeographicLib::Geocentric::GetUnmanaged
System::IntPtr ^ GetUnmanaged()
NETGeographicLib::Geocentric::Flattening
double Flattening
Definition: Geocentric.h:222
NETGeographicLib::Geocentric::Reverse
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::Runtime::InteropServices::Out] array< double, 2 >^% M)
GeographicLib::Geocentric
NETGeographicLib::Geocentric::Geocentric
Geocentric()
NETGeographicLib::Geocentric::Forward
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, [System::Runtime::InteropServices::Out] array< double, 2 >^% M)
NETGeographicLib::Geocentric::Geocentric
Geocentric(double a, double f)
NETGeographicLib::Geocentric::Geocentric
Geocentric(const GeographicLib::Geocentric &g)
NETGeographicLib::Geocentric::~Geocentric
~Geocentric()
Definition: Geocentric.h:103
NETGeographicLib::Geocentric::EquatorialRadius
double EquatorialRadius
Definition: Geocentric.h:216
NETGeographicLib::Geocentric::Forward
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)
NETGeographicLib
Definition: Accumulator.h:14
NETGeographicLib::Geocentric::Reverse
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)