GeographicLib: GeographicLib::TransverseMercatorExact Class Reference

GeographicLib 2.5.2

Loading...
Searching...
No Matches
GeographicLib::TransverseMercatorExact Class Reference

An exact implementation of the transverse Mercator projection. More...

`#include <GeographicLib/TransverseMercatorExact.hpp>`

## Public Member Functions
| TransverseMercatorExact (real a, real f, real k0, bool extendp=false)
void | Forward (real lon0, real lat, real lon, real &x, real &y, real &gamma, real &k) const
void | Reverse (real lon0, real x, real y, real &lat, real &lon, real &gamma, real &k) const
void | Forward (real lon0, real lat, real lon, real &x, real &y) const
void | Reverse (real lon0, real x, real y, real &lat, real &lon) const
Inspector functions
Math::real | EquatorialRadius () const
Math::real | Flattening () const
Math::real | CentralScale () const

## Static Public Member Functions
static const TransverseMercatorExact & | UTM ()

## Friends
class | TransverseMercator

## Detailed Description

An exact implementation of the transverse Mercator projection.

Implementation of the Transverse Mercator Projection given in

- L. P. Lee, Conformal Projections Based On Jacobian Elliptic Functions, Part V of Conformal Projections Based on Elliptic Functions, (B. V. Gutsell, Toronto, 1976), 128pp., ISBN: 0919870163 (also appeared as: Monograph 16, Suppl. No. 1 to Canadian Cartographer, Vol 13); borrow from archive.org.
- C. F. F. Karney, Transverse Mercator with an accuracy of a few nanometers, J. Geodesy 85(8), 475–485 (Aug. 2011); preprint arXiv:1002.1417.

Lee gives the correct results for forward and reverse transformations subject to the branch cut rules (see the description of the extendp argument to the constructor). The maximum error is about 8 nm (8 nanometers), ground distance, for the forward and reverse transformations. The error in the convergence is 2 × 10−15", the relative error in the scale is 7 × 10−12%%. See Sec. 3 of arXiv:1002.1417 for details. The method is "exact" in the sense that the errors are close to the round-off limit and that no changes are needed in the algorithms for them to be used with reals of a higher precision. Thus the errors using long double (with a 64-bit fraction) are about 2000 times smaller than using double (with a 53-bit fraction).

This algorithm is about 4.5 times slower than the 6th-order Krüger method, TransverseMercator, taking about 11 us for a combined forward and reverse projection on a 2.66 GHz Intel machine (g++, version 4.3.0, -O3).

The ellipsoid parameters and the central scale are set in the constructor. The central meridian (which is a trivial shift of the longitude) is specified as the lon0 argument of the TransverseMercatorExact::Forward and TransverseMercatorExact::Reverse functions. The latitude of origin is taken to be the equator. See the documentation on TransverseMercator for how to include a false easting, false northing, or a latitude of origin.

See tm-grid.kmz, for an illustration of the transverse Mercator grid in Google Earth.

This class also returns the meridian convergence gamma and scale k. The meridian convergence is the bearing of grid north (the y axis) measured clockwise from true north.

See TransverseMercatorExact.cpp for more information on the implementation.

See Transverse Mercator projection for a discussion of this projection.

Example of use:

// Example of using the GeographicLib::TransverseMercatorExact class
#include <iostream>
#include <iomanip>
#include <exception>
#include <GeographicLib/TransverseMercatorExact.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
TransverseMercatorExact proj(Constants::WGS84_a(), Constants::WGS84_f(),
Constants::UTM_k0());
// Alternatively:
// const TransverseMercatorExact& proj = TransverseMercatorExact::UTM();
double lon0 = -75; // Central meridian for UTM zone 18
{
// Sample forward calculation
double lat = 40.3, lon = -74.7; // Princeton, NJ
double x, y;
proj.Forward(lon0, lat, lon, x, y);
cout << x << " " << y << "\n";
}
{
// Sample reverse calculation
double x = 25e3, y = 4461e3;
double lat, lon;
proj.Reverse(lon0, x, y, lat, lon);
cout << lat << " " << lon << "\n";
}
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition CartConvert.cpp:28
TransverseMercatorExact.hpp
Header for GeographicLib::TransverseMercatorExact class.
GeographicLib::Constants::UTM_k0
static T UTM_k0()
Definition Constants.hpp:199
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition Constants.hpp:141
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition Constants.hpp:135
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

TransverseMercatorProj is a command-line utility providing access to the functionality of TransverseMercator and TransverseMercatorExact.

Definition at line 85 of file TransverseMercatorExact.hpp.

## Constructor & Destructor Documentation

## ◆ TransverseMercatorExact()

GeographicLib::TransverseMercatorExact::TransverseMercatorExact | ( | real | a,
|  | real | f,
|  | real | k0,
|  | bool | extendp = false )

Constructor for an ellipsoid with

Parameters

  [in] | a | equatorial radius (meters).
  [in] | f | flattening of ellipsoid.
  [in] | k0 | central scale factor.
  [in] | extendp | if true, use extended domain (default false).

Exceptions

  GeographicErr | if a, f, or k0 is not positive.

The transverse Mercator projection has a branch point singularity at lat = 0 and lon − lon0 = 90 (1 − e) or (for TransverseMercatorExact::UTM) x = 18381 km, y = 0m. The extendp argument governs where the branch cut is placed. With extendp = false, the "standard" convention is followed, namely the cut is placed along x > 18381 km, y = 0m. Forward can be called with any lat and lon then produces the transformation shown in Lee, Fig 46. Reverse analytically continues this in the ± x direction. As a consequence, Reverse may map multiple points to the same geographic location; for example, for TransverseMercatorExact::UTM, x = 22051449.037349 m, y = −7131237.022729 m and x = 29735142.378357 m, y = 4235043.607933 m both map to lat = −2°, lon = 88°.

With extendp = true, the branch cut is moved to the lower left quadrant. The various symmetries of the transverse Mercator projection can be used to explore the projection on any sheet. In this mode the domains of lat, lon, x, and y are restricted to

- the union of
  - lat in [0, 90] and lon − lon0 in [0, 90]
  - lat in (-90, 0] and lon − lon0 in [90 (1 − e), 90]
- the union of
  - x/(k0 a) in [0, ∞) and y/(k0 a) in [0, E(e2)]
  - x/(k0 a) in [K(1 − e2) − E(1 − e2), ∞) and y/(k0 a) in (−∞, 0]

See Sec. 5 of arXiv:1002.1417 for a full discussion of the treatment of the branch cut.

The method will work for all ellipsoids used in terrestrial geodesy. The method cannot be applied directly to the case of a sphere (f = 0) because some the constants characterizing this method diverge in that limit, and in practice, f should be larger than about numeric_limits<real>::epsilon(). However, TransverseMercator treats the sphere exactly.

Definition at line 50 of file TransverseMercatorExact.cpp.

## Member Function Documentation

## ◆ Forward() [1/2]

void GeographicLib::TransverseMercatorExact::Forward | ( | real | lon0,
|  | real | lat,
|  | real | lon,
|  | real & | x,
|  | real & | y,
|  | real & | gamma,
|  | real & | k ) const

Forward projection, from geographic to transverse Mercator.

Parameters

  [in] | lon0 | central meridian of the projection (degrees).
  [in] | lat | latitude of point (degrees).
  [in] | lon | longitude of point (degrees).
  [out] | x | easting of point (meters).
  [out] | y | northing of point (meters).
  [out] | gamma | meridian convergence at point (degrees).
  [out] | k | scale of projection at point.

No false easting or northing is added. lat should be in the range [−90°, 90°].

Definition at line 353 of file TransverseMercatorExact.cpp.

References GeographicLib::Math::AngDiff(), GeographicLib::Math::degree(), GeographicLib::Math::hd, GeographicLib::Math::LatFix(), GeographicLib::Math::qd, GeographicLib::Math::tand(), GeographicLib::Math::tauf(), and GeographicLib::Math::taupf().

Referenced by Forward().

## ◆ Reverse() [1/2]

void GeographicLib::TransverseMercatorExact::Reverse | ( | real | lon0,
|  | real | x,
|  | real | y,
|  | real & | lat,
|  | real & | lon,
|  | real & | gamma,
|  | real & | k ) const

Reverse projection, from transverse Mercator to geographic.

Parameters

  [in] | lon0 | central meridian of the projection (degrees).
  [in] | x | easting of point (meters).
  [in] | y | northing of point (meters).
  [out] | lat | latitude of point (degrees).
  [out] | lon | longitude of point (degrees).
  [out] | gamma | meridian convergence at point (degrees).
  [out] | k | scale of projection at point.

No false easting or northing is added. The value of lon returned is in the range [−180°, 180°].

Definition at line 413 of file TransverseMercatorExact.cpp.

References GeographicLib::Math::AngNormalize(), GeographicLib::Math::degree(), GeographicLib::Math::hd, GeographicLib::Math::qd, and GeographicLib::Math::tauf().

Referenced by Reverse().

## ◆ Forward() [2/2]

void GeographicLib::TransverseMercatorExact::Forward | ( | real | lon0,
|  | real | lat,
|  | real | lon,
|  | real & | x,
|  | real & | y ) const
| inline

TransverseMercatorExact::Forward without returning the convergence and scale.

Definition at line 214 of file TransverseMercatorExact.hpp.

References Forward().

## ◆ Reverse() [2/2]

void GeographicLib::TransverseMercatorExact::Reverse | ( | real | lon0,
|  | real | x,
|  | real | y,
|  | real & | lat,
|  | real & | lon ) const
| inline

TransverseMercatorExact::Reverse without returning the convergence and scale.

Definition at line 224 of file TransverseMercatorExact.hpp.

References Reverse().

## ◆ EquatorialRadius()

Math::real GeographicLib::TransverseMercatorExact::EquatorialRadius | ( |  | ) | const
| inline

Returns
  a the equatorial radius of the ellipsoid (meters). This is the value used in the constructor.

Definition at line 237 of file TransverseMercatorExact.hpp.

## ◆ Flattening()

Math::real GeographicLib::TransverseMercatorExact::Flattening | ( |  | ) | const
| inline

Returns
  f the flattening of the ellipsoid. This is the value used in the constructor.

Definition at line 243 of file TransverseMercatorExact.hpp.

## ◆ CentralScale()

Math::real GeographicLib::TransverseMercatorExact::CentralScale | ( |  | ) | const
| inline

Returns
  k0 central scale for the projection. This is the value of k0 used in the constructor and is the scale on the central meridian.

Definition at line 249 of file TransverseMercatorExact.hpp.

## ◆ UTM()

const TransverseMercatorExact & GeographicLib::TransverseMercatorExact::UTM | ( |  | ) |
| static

A global instantiation of TransverseMercatorExact with the WGS84 ellipsoid and the UTM scale factor. However, unlike UTM, no false easting or northing is added.

Definition at line 75 of file TransverseMercatorExact.cpp.

References GeographicLib::Constants::UTM_k0(), GeographicLib::Constants::WGS84_a(), and GeographicLib::Constants::WGS84_f().

## Friends And Related Symbol Documentation

## ◆ TransverseMercator

friend class TransverseMercator
| friend

Definition at line 88 of file TransverseMercatorExact.hpp.

References TransverseMercator.

Referenced by TransverseMercator.

The documentation for this class was generated from the following files:

- TransverseMercatorExact.hpp
- TransverseMercatorExact.cpp