Public Member Functions | Static Public Member Functions | Private Types | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
GeographicLib::TransverseMercatorExact Class Reference

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

#include <TransverseMercatorExact.hpp>

Public Member Functions

void Forward (real lon0, real lat, real lon, real &x, real &y, 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, real &gamma, real &k) const
 
void Reverse (real lon0, real x, real y, real &lat, real &lon) const
 
 TransverseMercatorExact (real a, real f, real k0, bool extendp=false)
 
Inspector functions
Math::real MajorRadius () const
 
Math::real Flattening () const
 
Math::real CentralScale () const
 

Static Public Member Functions

static const TransverseMercatorExactUTM ()
 

Private Types

typedef Math::real real
 

Private Member Functions

void dwdsigma (real u, real snu, real cnu, real dnu, real v, real snv, real cnv, real dnv, real &du, real &dv) const
 
void dwdzeta (real u, real snu, real cnu, real dnu, real v, real snv, real cnv, real dnv, real &du, real &dv) const
 
void Scale (real tau, real lam, real snu, real cnu, real dnu, real snv, real cnv, real dnv, real &gamma, real &k) const
 
void sigma (real u, real snu, real cnu, real dnu, real v, real snv, real cnv, real dnv, real &xi, real &eta) const
 
void sigmainv (real xi, real eta, real &u, real &v) const
 
bool sigmainv0 (real xi, real eta, real &u, real &v) const
 
void zeta (real u, real snu, real cnu, real dnu, real v, real snv, real cnv, real dnv, real &taup, real &lam) const
 
void zetainv (real taup, real lam, real &u, real &v) const
 
bool zetainv0 (real psi, real lam, real &u, real &v) const
 

Private Attributes

real _a
 
real _e
 
EllipticFunction _Eu
 
EllipticFunction _Ev
 
bool _extendp
 
real _f
 
real _k0
 
real _mu
 
real _mv
 
real taytol_
 
real tol2_
 
real tol_
 

Static Private Attributes

static const int numit_ = 10
 

Detailed Description

An exact implementation of the transverse Mercator projection.

Implementation of the Transverse Mercator Projection given in

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 transversemercator for a discussion of this projection.

Example of use:

// Example of using the GeographicLib::TransverseMercatorExact class
#include <iostream>
#include <iomanip>
#include <exception>
using namespace std;
using namespace GeographicLib;
int main() {
try {
// 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;
}
}

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

Definition at line 83 of file TransverseMercatorExact.hpp.

Member Typedef Documentation

◆ real

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 a ellipsoid with

Parameters
[in]aequatorial radius (meters).
[in]fflattening of ellipsoid.
[in]k0central scale factor.
[in]extendpuse extended domain.
Exceptions
GeographicErrif a, f, or k0 is not positive.

The transverse Mercator projection has a branch point singularity at lat = 0 and lonlon0 = 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 lonlon0 in [0, 90]
    • lat in (-90, 0] and lonlon0 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 53 of file src/TransverseMercatorExact.cpp.

Member Function Documentation

◆ 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 245 of file TransverseMercatorExact.hpp.

◆ dwdsigma()

void GeographicLib::TransverseMercatorExact::dwdsigma ( real  u,
real  snu,
real  cnu,
real  dnu,
real  v,
real  snv,
real  cnv,
real  dnv,
real du,
real dv 
) const
private

Definition at line 229 of file src/TransverseMercatorExact.cpp.

◆ dwdzeta()

void GeographicLib::TransverseMercatorExact::dwdzeta ( real  u,
real  snu,
real  cnu,
real  dnu,
real  v,
real  snv,
real  cnv,
real  dnv,
real du,
real dv 
) const
private

Definition at line 109 of file src/TransverseMercatorExact.cpp.

◆ 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 239 of file TransverseMercatorExact.hpp.

◆ 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]lon0central meridian of the projection (degrees).
[in]latlatitude of point (degrees).
[in]lonlongitude of point (degrees).
[out]xeasting of point (meters).
[out]ynorthing of point (meters).
[out]gammameridian convergence at point (degrees).
[out]kscale of projection at point.

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

Definition at line 348 of file src/TransverseMercatorExact.cpp.

◆ 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 210 of file TransverseMercatorExact.hpp.

◆ MajorRadius()

Math::real GeographicLib::TransverseMercatorExact::MajorRadius ( ) const
inline
Returns
a the equatorial radius of the ellipsoid (meters). This is the value used in the constructor.

Definition at line 233 of file TransverseMercatorExact.hpp.

◆ 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]lon0central meridian of the projection (degrees).
[in]xeasting of point (meters).
[in]ynorthing of point (meters).
[out]latlatitude of point (degrees).
[out]lonlongitude of point (degrees).
[out]gammameridian convergence at point (degrees).
[out]kscale 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 408 of file src/TransverseMercatorExact.cpp.

◆ 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 220 of file TransverseMercatorExact.hpp.

◆ Scale()

void GeographicLib::TransverseMercatorExact::Scale ( real  tau,
real  lam,
real  snu,
real  cnu,
real  dnu,
real  snv,
real  cnv,
real  dnv,
real gamma,
real k 
) const
private

Definition at line 322 of file src/TransverseMercatorExact.cpp.

◆ sigma()

void GeographicLib::TransverseMercatorExact::sigma ( real  u,
real  snu,
real  cnu,
real  dnu,
real  v,
real  snv,
real  cnv,
real  dnv,
real xi,
real eta 
) const
private

Definition at line 219 of file src/TransverseMercatorExact.cpp.

◆ sigmainv()

void GeographicLib::TransverseMercatorExact::sigmainv ( real  xi,
real  eta,
real u,
real v 
) const
private

Definition at line 295 of file src/TransverseMercatorExact.cpp.

◆ sigmainv0()

bool GeographicLib::TransverseMercatorExact::sigmainv0 ( real  xi,
real  eta,
real u,
real v 
) const
private

Definition at line 245 of file src/TransverseMercatorExact.cpp.

◆ 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 78 of file src/TransverseMercatorExact.cpp.

◆ zeta()

void GeographicLib::TransverseMercatorExact::zeta ( real  u,
real  snu,
real  cnu,
real  dnu,
real  v,
real  snv,
real  cnv,
real  dnv,
real taup,
real lam 
) const
private

Definition at line 85 of file src/TransverseMercatorExact.cpp.

◆ zetainv()

void GeographicLib::TransverseMercatorExact::zetainv ( real  taup,
real  lam,
real u,
real v 
) const
private

Definition at line 187 of file src/TransverseMercatorExact.cpp.

◆ zetainv0()

bool GeographicLib::TransverseMercatorExact::zetainv0 ( real  psi,
real  lam,
real u,
real v 
) const
private

Definition at line 122 of file src/TransverseMercatorExact.cpp.

Member Data Documentation

◆ _a

real GeographicLib::TransverseMercatorExact::_a
private

Definition at line 88 of file TransverseMercatorExact.hpp.

◆ _e

real GeographicLib::TransverseMercatorExact::_e
private

Definition at line 88 of file TransverseMercatorExact.hpp.

◆ _Eu

EllipticFunction GeographicLib::TransverseMercatorExact::_Eu
private

Definition at line 90 of file TransverseMercatorExact.hpp.

◆ _Ev

EllipticFunction GeographicLib::TransverseMercatorExact::_Ev
private

Definition at line 90 of file TransverseMercatorExact.hpp.

◆ _extendp

bool GeographicLib::TransverseMercatorExact::_extendp
private

Definition at line 89 of file TransverseMercatorExact.hpp.

◆ _f

real GeographicLib::TransverseMercatorExact::_f
private

Definition at line 88 of file TransverseMercatorExact.hpp.

◆ _k0

real GeographicLib::TransverseMercatorExact::_k0
private

Definition at line 88 of file TransverseMercatorExact.hpp.

◆ _mu

real GeographicLib::TransverseMercatorExact::_mu
private

Definition at line 88 of file TransverseMercatorExact.hpp.

◆ _mv

real GeographicLib::TransverseMercatorExact::_mv
private

Definition at line 88 of file TransverseMercatorExact.hpp.

◆ numit_

const int GeographicLib::TransverseMercatorExact::numit_ = 10
staticprivate

Definition at line 86 of file TransverseMercatorExact.hpp.

◆ taytol_

real GeographicLib::TransverseMercatorExact::taytol_
private

Definition at line 87 of file TransverseMercatorExact.hpp.

◆ tol2_

real GeographicLib::TransverseMercatorExact::tol2_
private

Definition at line 87 of file TransverseMercatorExact.hpp.

◆ tol_

real GeographicLib::TransverseMercatorExact::tol_
private

Definition at line 87 of file TransverseMercatorExact.hpp.


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


gtsam
Author(s):
autogenerated on Tue Jul 4 2023 02:46:12