NETGeographicLib 1.52
Loading...
Searching...
No Matches
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
13namespace 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
.NET wrapper for GeographicLib::Geocentric.
Definition: Geocentric.h:69
Geocentric(double a, double f)
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)
Geocentric(const GeographicLib::Geocentric &g)
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)
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)
System::IntPtr ^ GetUnmanaged()
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)