GeographicLib  1.35
LocalCartesian.hpp
Go to the documentation of this file.
1 /**
2  * \file LocalCartesian.hpp
3  * \brief Header for GeographicLib::LocalCartesian class
4  *
5  * Copyright (c) Charles Karney (2008-2011) <charles@karney.com> and licensed
6  * under the MIT/X11 License. For more information, see
7  * http://geographiclib.sourceforge.net/
8  **********************************************************************/
9 
10 #if !defined(GEOGRAPHICLIB_LOCALCARTESIAN_HPP)
11 #define GEOGRAPHICLIB_LOCALCARTESIAN_HPP 1
12 
15 
16 namespace GeographicLib {
17 
18  /**
19  * \brief Local cartesian coordinates
20  *
21  * Convert between geodetic coordinates latitude = \e lat, longitude = \e
22  * lon, height = \e h (measured vertically from the surface of the ellipsoid)
23  * to local cartesian coordinates (\e x, \e y, \e z). The origin of local
24  * cartesian coordinate system is at \e lat = \e lat0, \e lon = \e lon0, \e h
25  * = \e h0. The \e z axis is normal to the ellipsoid; the \e y axis points
26  * due north. The plane \e z = - \e h0 is tangent to the ellipsoid.
27  *
28  * The conversions all take place via geocentric coordinates using a
29  * Geocentric object (by default Geocentric::WGS84).
30  *
31  * Example of use:
32  * \include example-LocalCartesian.cpp
33  *
34  * <a href="CartConvert.1.html">CartConvert</a> is a command-line utility
35  * providing access to the functionality of Geocentric and LocalCartesian.
36  **********************************************************************/
37 
39  private:
40  typedef Math::real real;
41  static const size_t dim_ = 3;
42  static const size_t dim2_ = dim_ * dim_;
43  Geocentric _earth;
44  real _lat0, _lon0, _h0;
45  real _x0, _y0, _z0, _r[dim2_];
46  void IntForward(real lat, real lon, real h, real& x, real& y, real& z,
47  real M[dim2_]) const throw();
48  void IntReverse(real x, real y, real z, real& lat, real& lon, real& h,
49  real M[dim2_]) const throw();
50  void MatrixMultiply(real M[dim2_]) const throw();
51  public:
52 
53  /**
54  * Constructor setting the origin.
55  *
56  * @param[in] lat0 latitude at origin (degrees).
57  * @param[in] lon0 longitude at origin (degrees).
58  * @param[in] h0 height above ellipsoid at origin (meters); default 0.
59  * @param[in] earth Geocentric object for the transformation; default
60  * Geocentric::WGS84.
61  *
62  * \e lat0 should be in the range [&minus;90&deg;, 90&deg;]; \e
63  * lon0 should be in the range [&minus;540&deg;, 540&deg;).
64  **********************************************************************/
65  LocalCartesian(real lat0, real lon0, real h0 = 0,
66  const Geocentric& earth = Geocentric::WGS84) throw()
67  : _earth(earth)
68  { Reset(lat0, lon0, h0); }
69 
70  /**
71  * Default constructor.
72  *
73  * @param[in] earth Geocentric object for the transformation; default
74  * Geocentric::WGS84.
75  *
76  * Sets \e lat0 = 0, \e lon0 = 0, \e h0 = 0.
77  **********************************************************************/
78  explicit LocalCartesian(const Geocentric& earth = Geocentric::WGS84)
79  throw()
80  : _earth(earth)
81  { Reset(real(0), real(0), real(0)); }
82 
83  /**
84  * Reset the origin.
85  *
86  * @param[in] lat0 latitude at origin (degrees).
87  * @param[in] lon0 longitude at origin (degrees).
88  * @param[in] h0 height above ellipsoid at origin (meters); default 0.
89  *
90  * \e lat0 should be in the range [&minus;90&deg;, 90&deg;]; \e
91  * lon0 should be in the range [&minus;540&deg;, 540&deg;).
92  **********************************************************************/
93  void Reset(real lat0, real lon0, real h0 = 0) throw();
94 
95  /**
96  * Convert from geodetic to local cartesian coordinates.
97  *
98  * @param[in] lat latitude of point (degrees).
99  * @param[in] lon longitude of point (degrees).
100  * @param[in] h height of point above the ellipsoid (meters).
101  * @param[out] x local cartesian coordinate (meters).
102  * @param[out] y local cartesian coordinate (meters).
103  * @param[out] z local cartesian coordinate (meters).
104  *
105  * \e lat should be in the range [&minus;90&deg;, 90&deg;]; \e lon
106  * should be in the range [&minus;540&deg;, 540&deg;).
107  **********************************************************************/
108  void Forward(real lat, real lon, real h, real& x, real& y, real& z)
109  const throw() {
110  IntForward(lat, lon, h, x, y, z, NULL);
111  }
112 
113  /**
114  * Convert from geodetic to local cartesian coordinates and return rotation
115  * matrix.
116  *
117  * @param[in] lat latitude of point (degrees).
118  * @param[in] lon longitude of point (degrees).
119  * @param[in] h height of point above the ellipsoid (meters).
120  * @param[out] x local cartesian coordinate (meters).
121  * @param[out] y local cartesian coordinate (meters).
122  * @param[out] z local cartesian coordinate (meters).
123  * @param[out] M if the length of the vector is 9, fill with the rotation
124  * matrix in row-major order.
125  *
126  * \e lat should be in the range [&minus;90&deg;, 90&deg;]; \e lon
127  * should be in the range [&minus;540&deg;, 540&deg;).
128  *
129  * Let \e v be a unit vector located at (\e lat, \e lon, \e h). We can
130  * express \e v as \e column vectors in one of two ways
131  * - in east, north, up coordinates (where the components are relative to a
132  * local coordinate system at (\e lat, \e lon, \e h)); call this
133  * representation \e v1.
134  * - in \e x, \e y, \e z coordinates (where the components are relative to
135  * the local coordinate system at (\e lat0, \e lon0, \e h0)); call this
136  * representation \e v0.
137  * .
138  * Then we have \e v0 = \e M &sdot; \e v1.
139  **********************************************************************/
140  void Forward(real lat, real lon, real h, real& x, real& y, real& z,
141  std::vector<real>& M)
142  const throw() {
143  if (M.end() == M.begin() + dim2_) {
144  real t[dim2_];
145  IntForward(lat, lon, h, x, y, z, t);
146  copy(t, t + dim2_, M.begin());
147  } else
148  IntForward(lat, lon, h, x, y, z, NULL);
149  }
150 
151  /**
152  * Convert from local cartesian to geodetic coordinates.
153  *
154  * @param[in] x local cartesian coordinate (meters).
155  * @param[in] y local cartesian coordinate (meters).
156  * @param[in] z local cartesian 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  * The value of \e lon returned is in the range [&minus;180&deg;,
162  * 180&deg;).
163  **********************************************************************/
164  void Reverse(real x, real y, real z, real& lat, real& lon, real& h)
165  const throw() {
166  IntReverse(x, y, z, lat, lon, h, NULL);
167  }
168 
169  /**
170  * Convert from local cartesian to geodetic coordinates and return rotation
171  * matrix.
172  *
173  * @param[in] x local cartesian coordinate (meters).
174  * @param[in] y local cartesian coordinate (meters).
175  * @param[in] z local cartesian coordinate (meters).
176  * @param[out] lat latitude of point (degrees).
177  * @param[out] lon longitude of point (degrees).
178  * @param[out] h height of point above the ellipsoid (meters).
179  * @param[out] M if the length of the vector is 9, fill with the rotation
180  * matrix in row-major order.
181  *
182  * Let \e v be a unit vector located at (\e lat, \e lon, \e h). We can
183  * express \e v as \e column vectors in one of two ways
184  * - in east, north, up coordinates (where the components are relative to a
185  * local coordinate system at (\e lat, \e lon, \e h)); call this
186  * representation \e v1.
187  * - in \e x, \e y, \e z coordinates (where the components are relative to
188  * the local coordinate system at (\e lat0, \e lon0, \e h0)); call this
189  * representation \e v0.
190  * .
191  * Then we have \e v1 = \e M<sup>T</sup> &sdot; \e v0, where \e
192  * M<sup>T</sup> is the transpose of \e M.
193  **********************************************************************/
194  void Reverse(real x, real y, real z, real& lat, real& lon, real& h,
195  std::vector<real>& M)
196  const throw() {
197  if (M.end() == M.begin() + dim2_) {
198  real t[dim2_];
199  IntReverse(x, y, z, lat, lon, h, t);
200  copy(t, t + dim2_, M.begin());
201  } else
202  IntReverse(x, y, z, lat, lon, h, NULL);
203  }
204 
205  /** \name Inspector functions
206  **********************************************************************/
207  ///@{
208  /**
209  * @return latitude of the origin (degrees).
210  **********************************************************************/
211  Math::real LatitudeOrigin() const throw() { return _lat0; }
212 
213  /**
214  * @return longitude of the origin (degrees).
215  **********************************************************************/
216  Math::real LongitudeOrigin() const throw() { return _lon0; }
217 
218  /**
219  * @return height of the origin (meters).
220  **********************************************************************/
221  Math::real HeightOrigin() const throw() { return _h0; }
222 
223  /**
224  * @return \e a the equatorial radius of the ellipsoid (meters). This is
225  * the value of \e a inherited from the Geocentric object used in the
226  * constructor.
227  **********************************************************************/
228  Math::real MajorRadius() const throw() { return _earth.MajorRadius(); }
229 
230  /**
231  * @return \e f the flattening of the ellipsoid. This is the value
232  * inherited from the Geocentric object used in the constructor.
233  **********************************************************************/
234  Math::real Flattening() const throw() { return _earth.Flattening(); }
235  ///@}
236 
237  /// \cond SKIP
238  /**
239  * <b>DEPRECATED</b>
240  * @return \e r the inverse flattening of the ellipsoid.
241  **********************************************************************/
242  Math::real InverseFlattening() const throw()
243  { return _earth.InverseFlattening(); }
244  /// \endcond
245  };
246 
247 } // namespace GeographicLib
248 
249 #endif // GEOGRAPHICLIB_LOCALCARTESIAN_HPP
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:52
LocalCartesian(real lat0, real lon0, real h0=0, const Geocentric &earth=Geocentric::WGS84)
GeographicLib::Math::real real
Definition: GeodSolve.cpp:40
LocalCartesian(const Geocentric &earth=Geocentric::WGS84)
Math::real Flattening() const
Geocentric coordinates
Definition: Geocentric.hpp:61
void Reverse(real x, real y, real z, real &lat, real &lon, real &h) const
Math::real LongitudeOrigin() const
static const Geocentric WGS84
Definition: Geocentric.hpp:270
Math::real MajorRadius() const
Header for GeographicLib::Geocentric class.
Math::real HeightOrigin() const
Local cartesian coordinates.
void Forward(real lat, real lon, real h, real &x, real &y, real &z, std::vector< real > &M) const
Header for GeographicLib::Constants class.
Math::real LatitudeOrigin() const
void Reverse(real x, real y, real z, real &lat, real &lon, real &h, std::vector< real > &M) const