GeographicLib  1.37
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;
48  void IntReverse(real x, real y, real z, real& lat, real& lon, real& h,
49  real M[dim2_]) const;
50  void MatrixMultiply(real M[dim2_]) const;
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())
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  : _earth(earth)
80  { Reset(real(0), real(0), real(0)); }
81 
82  /**
83  * Reset the origin.
84  *
85  * @param[in] lat0 latitude at origin (degrees).
86  * @param[in] lon0 longitude at origin (degrees).
87  * @param[in] h0 height above ellipsoid at origin (meters); default 0.
88  *
89  * \e lat0 should be in the range [&minus;90&deg;, 90&deg;]; \e
90  * lon0 should be in the range [&minus;540&deg;, 540&deg;).
91  **********************************************************************/
92  void Reset(real lat0, real lon0, real h0 = 0);
93 
94  /**
95  * Convert from geodetic to local cartesian coordinates.
96  *
97  * @param[in] lat latitude of point (degrees).
98  * @param[in] lon longitude of point (degrees).
99  * @param[in] h height of point above the ellipsoid (meters).
100  * @param[out] x local cartesian coordinate (meters).
101  * @param[out] y local cartesian coordinate (meters).
102  * @param[out] z local cartesian coordinate (meters).
103  *
104  * \e lat should be in the range [&minus;90&deg;, 90&deg;]; \e lon
105  * should be in the range [&minus;540&deg;, 540&deg;).
106  **********************************************************************/
107  void Forward(real lat, real lon, real h, real& x, real& y, real& z)
108  const {
109  IntForward(lat, lon, h, x, y, z, NULL);
110  }
111 
112  /**
113  * Convert from geodetic to local cartesian coordinates and return rotation
114  * matrix.
115  *
116  * @param[in] lat latitude of point (degrees).
117  * @param[in] lon longitude of point (degrees).
118  * @param[in] h height of point above the ellipsoid (meters).
119  * @param[out] x local cartesian coordinate (meters).
120  * @param[out] y local cartesian coordinate (meters).
121  * @param[out] z local cartesian coordinate (meters).
122  * @param[out] M if the length of the vector is 9, fill with the rotation
123  * matrix in row-major order.
124  *
125  * \e lat should be in the range [&minus;90&deg;, 90&deg;]; \e lon
126  * should be in the range [&minus;540&deg;, 540&deg;).
127  *
128  * Let \e v be a unit vector located at (\e lat, \e lon, \e h). We can
129  * express \e v as \e column vectors in one of two ways
130  * - in east, north, up coordinates (where the components are relative to a
131  * local coordinate system at (\e lat, \e lon, \e h)); call this
132  * representation \e v1.
133  * - in \e x, \e y, \e z coordinates (where the components are relative to
134  * the local coordinate system at (\e lat0, \e lon0, \e h0)); call this
135  * representation \e v0.
136  * .
137  * Then we have \e v0 = \e M &sdot; \e v1.
138  **********************************************************************/
139  void Forward(real lat, real lon, real h, real& x, real& y, real& z,
140  std::vector<real>& M)
141  const {
142  if (M.end() == M.begin() + dim2_) {
143  real t[dim2_];
144  IntForward(lat, lon, h, x, y, z, t);
145  std::copy(t, t + dim2_, M.begin());
146  } else
147  IntForward(lat, lon, h, x, y, z, NULL);
148  }
149 
150  /**
151  * Convert from local cartesian to geodetic coordinates.
152  *
153  * @param[in] x local cartesian coordinate (meters).
154  * @param[in] y local cartesian coordinate (meters).
155  * @param[in] z local cartesian coordinate (meters).
156  * @param[out] lat latitude of point (degrees).
157  * @param[out] lon longitude of point (degrees).
158  * @param[out] h height of point above the ellipsoid (meters).
159  *
160  * The value of \e lon returned is in the range [&minus;180&deg;,
161  * 180&deg;).
162  **********************************************************************/
163  void Reverse(real x, real y, real z, real& lat, real& lon, real& h)
164  const {
165  IntReverse(x, y, z, lat, lon, h, NULL);
166  }
167 
168  /**
169  * Convert from local cartesian to geodetic coordinates and return rotation
170  * matrix.
171  *
172  * @param[in] x local cartesian coordinate (meters).
173  * @param[in] y local cartesian coordinate (meters).
174  * @param[in] z local cartesian coordinate (meters).
175  * @param[out] lat latitude of point (degrees).
176  * @param[out] lon longitude of point (degrees).
177  * @param[out] h height of point above the ellipsoid (meters).
178  * @param[out] M if the length of the vector is 9, fill with the rotation
179  * matrix in row-major order.
180  *
181  * Let \e v be a unit vector located at (\e lat, \e lon, \e h). We can
182  * express \e v as \e column vectors in one of two ways
183  * - in east, north, up coordinates (where the components are relative to a
184  * local coordinate system at (\e lat, \e lon, \e h)); call this
185  * representation \e v1.
186  * - in \e x, \e y, \e z coordinates (where the components are relative to
187  * the local coordinate system at (\e lat0, \e lon0, \e h0)); call this
188  * representation \e v0.
189  * .
190  * Then we have \e v1 = <i>M</i><sup>T</sup> &sdot; \e v0, where
191  * <i>M</i><sup>T</sup> is the transpose of \e M.
192  **********************************************************************/
193  void Reverse(real x, real y, real z, real& lat, real& lon, real& h,
194  std::vector<real>& M)
195  const {
196  if (M.end() == M.begin() + dim2_) {
197  real t[dim2_];
198  IntReverse(x, y, z, lat, lon, h, t);
199  std::copy(t, t + dim2_, M.begin());
200  } else
201  IntReverse(x, y, z, lat, lon, h, NULL);
202  }
203 
204  /** \name Inspector functions
205  **********************************************************************/
206  ///@{
207  /**
208  * @return latitude of the origin (degrees).
209  **********************************************************************/
210  Math::real LatitudeOrigin() const { return _lat0; }
211 
212  /**
213  * @return longitude of the origin (degrees).
214  **********************************************************************/
215  Math::real LongitudeOrigin() const { return _lon0; }
216 
217  /**
218  * @return height of the origin (meters).
219  **********************************************************************/
220  Math::real HeightOrigin() const { return _h0; }
221 
222  /**
223  * @return \e a the equatorial radius of the ellipsoid (meters). This is
224  * the value of \e a inherited from the Geocentric object used in the
225  * constructor.
226  **********************************************************************/
227  Math::real MajorRadius() const { return _earth.MajorRadius(); }
228 
229  /**
230  * @return \e f the flattening of the ellipsoid. This is the value
231  * inherited from the Geocentric object used in the constructor.
232  **********************************************************************/
233  Math::real Flattening() const { return _earth.Flattening(); }
234  ///@}
235 
236  /// \cond SKIP
237  /**
238  * <b>DEPRECATED</b>
239  * @return \e r the inverse flattening of the ellipsoid.
240  **********************************************************************/
241  Math::real InverseFlattening() const
242  { return _earth.InverseFlattening(); }
243  /// \endcond
244  };
245 
246 } // namespace GeographicLib
247 
248 #endif // GEOGRAPHICLIB_LOCALCARTESIAN_HPP
LocalCartesian(real lat0, real lon0, real h0=0, const Geocentric &earth=Geocentric::WGS84())
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:70
GeographicLib::Math::real real
Definition: GeodSolve.cpp:40
Math::real Flattening() const
Geocentric coordinates
Definition: Geocentric.hpp:67
void Reverse(real x, real y, real z, real &lat, real &lon, real &h) const
static const Geocentric & WGS84()
Definition: Geocentric.cpp:31
Math::real LongitudeOrigin() const
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
Math::real Flattening() const
Definition: Geocentric.hpp:259
LocalCartesian(const Geocentric &earth=Geocentric::WGS84())
Math::real MajorRadius() const
Math::real MajorRadius() const
Definition: Geocentric.hpp:252
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.
void Forward(real lat, real lon, real h, real &x, real &y, real &z) const
Math::real LatitudeOrigin() const
void Reverse(real x, real y, real z, real &lat, real &lon, real &h, std::vector< real > &M) const