GeographicLib 1.52
Loading...
Searching...
No Matches
TransverseMercatorExact.hpp
Go to the documentation of this file.
1/**
2 * \file TransverseMercatorExact.hpp
3 * \brief Header for GeographicLib::TransverseMercatorExact class
4 *
5 * Copyright (c) Charles Karney (2008-2020) <charles@karney.com> and licensed
6 * under the MIT/X11 License. For more information, see
7 * https://geographiclib.sourceforge.io/
8 **********************************************************************/
9
10#if !defined(GEOGRAPHICLIB_TRANSVERSEMERCATOREXACT_HPP)
11#define GEOGRAPHICLIB_TRANSVERSEMERCATOREXACT_HPP 1
12
15
16namespace GeographicLib {
17
18 /**
19 * \brief An exact implementation of the transverse Mercator projection
20 *
21 * Implementation of the Transverse Mercator Projection given in
22 * - L. P. Lee,
23 * <a href="https://doi.org/10.3138/X687-1574-4325-WM62"> Conformal
24 * Projections Based On Jacobian Elliptic Functions</a>, Part V of
25 * Conformal Projections Based on Elliptic Functions,
26 * (B. V. Gutsell, Toronto, 1976), 128pp.,
27 * ISBN: 0919870163
28 * (also appeared as:
29 * Monograph 16, Suppl. No. 1 to Canadian Cartographer, Vol 13).
30 * - C. F. F. Karney,
31 * <a href="https://doi.org/10.1007/s00190-011-0445-3">
32 * Transverse Mercator with an accuracy of a few nanometers,</a>
33 * J. Geodesy 85(8), 475--485 (Aug. 2011);
34 * preprint
35 * <a href="https://arxiv.org/abs/1002.1417">arXiv:1002.1417</a>.
36 *
37 * Lee gives the correct results for forward and reverse transformations
38 * subject to the branch cut rules (see the description of the \e extendp
39 * argument to the constructor). The maximum error is about 8 nm (8
40 * nanometers), ground distance, for the forward and reverse transformations.
41 * The error in the convergence is 2 &times; 10<sup>&minus;15</sup>&quot;,
42 * the relative error in the scale is 7 &times; 10<sup>&minus;12</sup>%%.
43 * See Sec. 3 of
44 * <a href="https://arxiv.org/abs/1002.1417">arXiv:1002.1417</a> for details.
45 * The method is "exact" in the sense that the errors are close to the
46 * round-off limit and that no changes are needed in the algorithms for them
47 * to be used with reals of a higher precision. Thus the errors using long
48 * double (with a 64-bit fraction) are about 2000 times smaller than using
49 * double (with a 53-bit fraction).
50 *
51 * This algorithm is about 4.5 times slower than the 6th-order Kr&uuml;ger
52 * method, TransverseMercator, taking about 11 us for a combined forward and
53 * reverse projection on a 2.66 GHz Intel machine (g++, version 4.3.0, -O3).
54 *
55 * The ellipsoid parameters and the central scale are set in the constructor.
56 * The central meridian (which is a trivial shift of the longitude) is
57 * specified as the \e lon0 argument of the TransverseMercatorExact::Forward
58 * and TransverseMercatorExact::Reverse functions. The latitude of origin is
59 * taken to be the equator. See the documentation on TransverseMercator for
60 * how to include a false easting, false northing, or a latitude of origin.
61 *
62 * See <a href="https://geographiclib.sourceforge.io/tm-grid.kmz"
63 * type="application/vnd.google-earth.kmz"> tm-grid.kmz</a>, for an
64 * illustration of the transverse Mercator grid in Google Earth.
65 *
66 * This class also returns the meridian convergence \e gamma and scale \e k.
67 * The meridian convergence is the bearing of grid north (the \e y axis)
68 * measured clockwise from true north.
69 *
70 * See TransverseMercatorExact.cpp for more information on the
71 * implementation.
72 *
73 * See \ref transversemercator for a discussion of this projection.
74 *
75 * Example of use:
76 * \include example-TransverseMercatorExact.cpp
77 *
78 * <a href="TransverseMercatorProj.1.html">TransverseMercatorProj</a> is a
79 * command-line utility providing access to the functionality of
80 * TransverseMercator and TransverseMercatorExact.
81 **********************************************************************/
82
84 private:
85 typedef Math::real real;
86 static const int numit_ = 10;
87 real tol_, tol2_, taytol_;
88 real _a, _f, _k0, _mu, _mv, _e;
89 bool _extendp;
90 EllipticFunction _Eu, _Ev;
91
92 void zeta(real u, real snu, real cnu, real dnu,
93 real v, real snv, real cnv, real dnv,
94 real& taup, real& lam) const;
95
96 void dwdzeta(real u, real snu, real cnu, real dnu,
97 real v, real snv, real cnv, real dnv,
98 real& du, real& dv) const;
99
100 bool zetainv0(real psi, real lam, real& u, real& v) const;
101 void zetainv(real taup, real lam, real& u, real& v) const;
102
103 void sigma(real u, real snu, real cnu, real dnu,
104 real v, real snv, real cnv, real dnv,
105 real& xi, real& eta) const;
106
107 void dwdsigma(real u, real snu, real cnu, real dnu,
108 real v, real snv, real cnv, real dnv,
109 real& du, real& dv) const;
110
111 bool sigmainv0(real xi, real eta, real& u, real& v) const;
112 void sigmainv(real xi, real eta, real& u, real& v) const;
113
114 void Scale(real tau, real lam,
115 real snu, real cnu, real dnu,
116 real snv, real cnv, real dnv,
117 real& gamma, real& k) const;
118
119 public:
120
121 /**
122 * Constructor for a ellipsoid with
123 *
124 * @param[in] a equatorial radius (meters).
125 * @param[in] f flattening of ellipsoid.
126 * @param[in] k0 central scale factor.
127 * @param[in] extendp use extended domain.
128 * @exception GeographicErr if \e a, \e f, or \e k0 is not positive.
129 *
130 * The transverse Mercator projection has a branch point singularity at \e
131 * lat = 0 and \e lon &minus; \e lon0 = 90 (1 &minus; \e e) or (for
132 * TransverseMercatorExact::UTM) x = 18381 km, y = 0m. The \e extendp
133 * argument governs where the branch cut is placed. With \e extendp =
134 * false, the "standard" convention is followed, namely the cut is placed
135 * along \e x > 18381 km, \e y = 0m. Forward can be called with any \e lat
136 * and \e lon then produces the transformation shown in Lee, Fig 46.
137 * Reverse analytically continues this in the &plusmn; \e x direction. As
138 * a consequence, Reverse may map multiple points to the same geographic
139 * location; for example, for TransverseMercatorExact::UTM, \e x =
140 * 22051449.037349 m, \e y = &minus;7131237.022729 m and \e x =
141 * 29735142.378357 m, \e y = 4235043.607933 m both map to \e lat =
142 * &minus;2&deg;, \e lon = 88&deg;.
143 *
144 * With \e extendp = true, the branch cut is moved to the lower left
145 * quadrant. The various symmetries of the transverse Mercator projection
146 * can be used to explore the projection on any sheet. In this mode the
147 * domains of \e lat, \e lon, \e x, and \e y are restricted to
148 * - the union of
149 * - \e lat in [0, 90] and \e lon &minus; \e lon0 in [0, 90]
150 * - \e lat in (-90, 0] and \e lon &minus; \e lon0 in [90 (1 &minus; \e
151 e), 90]
152 * - the union of
153 * - <i>x</i>/(\e k0 \e a) in [0, &infin;) and
154 * <i>y</i>/(\e k0 \e a) in [0, E(<i>e</i><sup>2</sup>)]
155 * - <i>x</i>/(\e k0 \e a) in [K(1 &minus; <i>e</i><sup>2</sup>) &minus;
156 * E(1 &minus; <i>e</i><sup>2</sup>), &infin;) and <i>y</i>/(\e k0 \e
157 * a) in (&minus;&infin;, 0]
158 * .
159 * See Sec. 5 of
160 * <a href="https://arxiv.org/abs/1002.1417">arXiv:1002.1417</a> for a full
161 * discussion of the treatment of the branch cut.
162 *
163 * The method will work for all ellipsoids used in terrestrial geodesy.
164 * The method cannot be applied directly to the case of a sphere (\e f = 0)
165 * because some the constants characterizing this method diverge in that
166 * limit, and in practice, \e f should be larger than about
167 * numeric_limits<real>::epsilon(). However, TransverseMercator treats the
168 * sphere exactly.
169 **********************************************************************/
170 TransverseMercatorExact(real a, real f, real k0, bool extendp = false);
171
172 /**
173 * Forward projection, from geographic to transverse Mercator.
174 *
175 * @param[in] lon0 central meridian of the projection (degrees).
176 * @param[in] lat latitude of point (degrees).
177 * @param[in] lon longitude of point (degrees).
178 * @param[out] x easting of point (meters).
179 * @param[out] y northing of point (meters).
180 * @param[out] gamma meridian convergence at point (degrees).
181 * @param[out] k scale of projection at point.
182 *
183 * No false easting or northing is added. \e lat should be in the range
184 * [&minus;90&deg;, 90&deg;].
185 **********************************************************************/
186 void Forward(real lon0, real lat, real lon,
187 real& x, real& y, real& gamma, real& k) const;
188
189 /**
190 * Reverse projection, from transverse Mercator to geographic.
191 *
192 * @param[in] lon0 central meridian of the projection (degrees).
193 * @param[in] x easting of point (meters).
194 * @param[in] y northing of point (meters).
195 * @param[out] lat latitude of point (degrees).
196 * @param[out] lon longitude of point (degrees).
197 * @param[out] gamma meridian convergence at point (degrees).
198 * @param[out] k scale of projection at point.
199 *
200 * No false easting or northing is added. The value of \e lon returned is
201 * in the range [&minus;180&deg;, 180&deg;].
202 **********************************************************************/
203 void Reverse(real lon0, real x, real y,
204 real& lat, real& lon, real& gamma, real& k) const;
205
206 /**
207 * TransverseMercatorExact::Forward without returning the convergence and
208 * scale.
209 **********************************************************************/
210 void Forward(real lon0, real lat, real lon,
211 real& x, real& y) const {
212 real gamma, k;
213 Forward(lon0, lat, lon, x, y, gamma, k);
214 }
215
216 /**
217 * TransverseMercatorExact::Reverse without returning the convergence and
218 * scale.
219 **********************************************************************/
220 void Reverse(real lon0, real x, real y,
221 real& lat, real& lon) const {
222 real gamma, k;
223 Reverse(lon0, x, y, lat, lon, gamma, k);
224 }
225
226 /** \name Inspector functions
227 **********************************************************************/
228 ///@{
229 /**
230 * @return \e a the equatorial radius of the ellipsoid (meters). This is
231 * the value used in the constructor.
232 **********************************************************************/
233 Math::real EquatorialRadius() const { return _a; }
234
235 /**
236 * @return \e f the flattening of the ellipsoid. This is the value used in
237 * the constructor.
238 **********************************************************************/
239 Math::real Flattening() const { return _f; }
240
241 /**
242 * @return \e k0 central scale for the projection. This is the value of \e
243 * k0 used in the constructor and is the scale on the central meridian.
244 **********************************************************************/
245 Math::real CentralScale() const { return _k0; }
246
247 /**
248 * \deprecated An old name for EquatorialRadius().
249 **********************************************************************/
250 GEOGRAPHICLIB_DEPRECATED("Use EquatorialRadius()")
251 Math::real MajorRadius() const { return EquatorialRadius(); }
252 ///@}
253
254 /**
255 * A global instantiation of TransverseMercatorExact with the WGS84
256 * ellipsoid and the UTM scale factor. However, unlike UTM, no false
257 * easting or northing is added.
258 **********************************************************************/
259 static const TransverseMercatorExact& UTM();
260 };
261
262} // namespace GeographicLib
263
264#endif // GEOGRAPHICLIB_TRANSVERSEMERCATOREXACT_HPP
Header for GeographicLib::Constants class.
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:66
#define GEOGRAPHICLIB_DEPRECATED(msg)
Definition: Constants.hpp:81
Header for GeographicLib::EllipticFunction class.
GeographicLib::Math::real real
Definition: GeodSolve.cpp:31
Elliptic integrals and functions.
Mathematical functions needed by GeographicLib.
Definition: Math.hpp:76
An exact implementation of the transverse Mercator projection.
void Reverse(real lon0, real x, real y, real &lat, real &lon) const
void Forward(real lon0, real lat, real lon, real &x, real &y) const
Namespace for GeographicLib.
Definition: Accumulator.cpp:12