Transverse Mercator projection. More...

#include <TransverseMercator.hpp>

Public Member Functions
void	Forward (real lon0, real lat, real lon, real &x, real &y) const

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) const

void	Reverse (real lon0, real x, real y, real &lat, real &lon, real &gamma, real &k) const

	TransverseMercator (real a, real f, real k0)

Inspector functions
Math::real	MajorRadius () const

Math::real	Flattening () const

Math::real	CentralScale () const

Static Public Member Functions
static const TransverseMercator &	UTM ()

Private Types
typedef Math::real	real

Private Attributes
real	_a

real	_a1

real	_alp [maxpow_+1]

real	_b1

real	_bet [maxpow_+1]

real	_c

real	_e2

real	_e2m

real	_es

real	_f

real	_k0

real	_n

Static Private Attributes
static const int	maxpow_ = GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER

static const int	numit_ = 5

Friends
class	Ellipsoid

Detailed Description

Transverse Mercator projection.

This uses Krüger's method which evaluates the projection and its inverse in terms of a series. See

L. Krüger, Konforme Abbildung des Erdellipsoids in der Ebene (Conformal mapping of the ellipsoidal earth to the plane), Royal Prussian Geodetic Institute, New Series 52, 172 pp. (1912).
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.

Krüger's method has been extended from 4th to 6th order. The maximum error is 5 nm (5 nanometers), ground distance, for all positions within 35 degrees of the central meridian. The error in the convergence is 2 × 10⁻¹⁵" and the relative error in the scale is 6 × 10⁻¹²%%. See Sec. 4 of arXiv:1002.1417 for details. The speed penalty in going to 6th order is only about 1%.

There's a singularity in the projection at φ = 0°, λ − λ₀ = ±(1 − e)90° (≈ ±82.6° for the WGS84 ellipsoid), where e is the eccentricity. Beyond this point, the series ceases to converge and the results from this method will be garbage. To be on the safe side, don't use this method if the angular distance from the central meridian exceeds (1 − 2e)90° (≈ 75° for the WGS84 ellipsoid)

TransverseMercatorExact is an alternative implementation of the projection using exact formulas which yield accurate (to 8 nm) results over the entire ellipsoid.

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 TransverseMercator::Forward and TransverseMercator::Reverse functions. The latitude of origin is taken to be the equator. There is no provision in this class for specifying a false easting or false northing or a different latitude of origin. However these are can be simply included by the calling function. For example, the UTMUPS class applies the false easting and false northing for the UTM projections. A more complicated example is the British National Grid (EPSG:7405) which requires the use of a latitude of origin. This is implemented by the GeographicLib::OSGB class.

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 TransverseMercator.cpp for more information on the implementation.

See transversemercator for a discussion of this projection.

Example of use:

// Example of using the GeographicLib::TransverseMercator class
 
#include <iostream>
#include <iomanip>
#include <exception>
#include <GeographicLib/TransverseMercator.hpp>
 
using namespace std;
using namespace GeographicLib;
 
// Define a UTM projection for an arbitrary ellipsoid
class UTMalt {
private:
  TransverseMercator _tm;       // The projection
  double _lon0;                 // Central longitude
  double _falseeasting, _falsenorthing;
public:
  UTMalt(double a,              // equatorial radius
         double f,              // flattening
         int zone,              // the UTM zone + hemisphere
         bool northp)
    : _tm(a, f, Constants::UTM_k0())
    , _lon0(6 * zone - 183)
    , _falseeasting(5e5)
    , _falsenorthing(northp ? 0 : 100e5) {
    if (!(zone >= 1 && zone <= 60))
      throw GeographicErr("zone not in [1,60]");
  }
  void Forward(double lat, double lon, double& x, double& y) {
    _tm.Forward(_lon0, lat, lon, x, y);
    x += _falseeasting;
    y += _falsenorthing;
  }
  void Reverse(double x, double y, double& lat, double& lon) {
    x -= _falseeasting;
    y -= _falsenorthing;
    _tm.Reverse(_lon0, x, y, lat, lon);
  }
};
 
int main() {
  try {
    UTMalt tm(6378388, 1/297.0, 30, true); // International ellipsoid, zone 30n
    {
      // Sample forward calculation
      double lat = 40.4, lon = -3.7; // Madrid
      double x, y;
      tm.Forward(lat, lon, x, y);
      cout << fixed << setprecision(0) << x << " " << y << "\n";
    }
    {
      // Sample reverse calculation
      double x = 441e3, y = 4472e3;
      double lat, lon;
      tm.Reverse(x, y, lat, lon);
      cout << fixed << setprecision(5) << 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 93 of file TransverseMercator.hpp.

Member Typedef Documentation

◆ real

typedef Math::real GeographicLib::TransverseMercator::real

private

Definition at line 95 of file TransverseMercator.hpp.

Constructor & Destructor Documentation

◆ TransverseMercator()

GeographicLib::TransverseMercator::TransverseMercator	(	real	a,
		real	f,
		real	k0
	)

Constructor for a ellipsoid with

Parameters

[in]	a	equatorial radius (meters).
[in]	f	flattening of ellipsoid. Setting f = 0 gives a sphere. Negative f gives a prolate ellipsoid.
[in]	k0	central scale factor.

Exceptions

GeographicErr if a, (1 − f) a, or k0 is not positive.

Definition at line 45 of file src/TransverseMercator.cpp.

Member Function Documentation

◆ CentralScale()

Math::real GeographicLib::TransverseMercator::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 187 of file TransverseMercator.hpp.

◆ Flattening()

Math::real GeographicLib::TransverseMercator::Flattening ( ) const

inline

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

Definition at line 181 of file TransverseMercator.hpp.

◆ Forward() [1/2]

void GeographicLib::TransverseMercator::Forward	(	real	lon0,
		real	lat,
		real	lon,
		real &	x,
		real &	y
	)		const

inline

TransverseMercator::Forward without returning the convergence and scale.

Definition at line 153 of file TransverseMercator.hpp.

◆ Forward() [2/2]

void GeographicLib::TransverseMercator::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 350 of file src/TransverseMercator.cpp.

◆ MajorRadius()

Math::real GeographicLib::TransverseMercator::MajorRadius ( ) const

inline

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

Definition at line 175 of file TransverseMercator.hpp.

◆ Reverse() [1/2]

void GeographicLib::TransverseMercator::Reverse	(	real	lon0,
		real	x,
		real	y,
		real &	lat,
		real &	lon
	)		const

inline

TransverseMercator::Reverse without returning the convergence and scale.

Definition at line 162 of file TransverseMercator.hpp.

◆ Reverse() [2/2]

void GeographicLib::TransverseMercator::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 516 of file src/TransverseMercator.cpp.

◆ UTM()

const TransverseMercator & GeographicLib::TransverseMercator::UTM ( )

static

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

Definition at line 277 of file src/TransverseMercator.cpp.

Friends And Related Function Documentation

◆ Ellipsoid

friend class Ellipsoid

friend

Definition at line 101 of file TransverseMercator.hpp.

Member Data Documentation

◆ _a

real GeographicLib::TransverseMercator::_a

private

Definition at line 98 of file TransverseMercator.hpp.

◆ _a1

real GeographicLib::TransverseMercator::_a1

private

Definition at line 100 of file TransverseMercator.hpp.

◆ _alp

real GeographicLib::TransverseMercator::_alp[maxpow_+1]

private

Definition at line 100 of file TransverseMercator.hpp.

◆ _b1

real GeographicLib::TransverseMercator::_b1

private

Definition at line 100 of file TransverseMercator.hpp.

◆ _bet

real GeographicLib::TransverseMercator::_bet[maxpow_+1]

private

Definition at line 100 of file TransverseMercator.hpp.

◆ _c

real GeographicLib::TransverseMercator::_c

private

Definition at line 98 of file TransverseMercator.hpp.

◆ _e2

real GeographicLib::TransverseMercator::_e2

private

Definition at line 98 of file TransverseMercator.hpp.

◆ _e2m

real GeographicLib::TransverseMercator::_e2m

private

Definition at line 98 of file TransverseMercator.hpp.

◆ _es

real GeographicLib::TransverseMercator::_es

private

Definition at line 98 of file TransverseMercator.hpp.

◆ _f

real GeographicLib::TransverseMercator::_f

private

Definition at line 98 of file TransverseMercator.hpp.

◆ _k0

real GeographicLib::TransverseMercator::_k0

private

Definition at line 98 of file TransverseMercator.hpp.

◆ _n

real GeographicLib::TransverseMercator::_n

private

Definition at line 98 of file TransverseMercator.hpp.

◆ maxpow_

const int GeographicLib::TransverseMercator::maxpow_ = GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER

staticprivate

Definition at line 96 of file TransverseMercator.hpp.

◆ numit_

const int GeographicLib::TransverseMercator::numit_ = 5

staticprivate

Definition at line 97 of file TransverseMercator.hpp.

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

Public Member Functions

Static Public Member Functions

Private Types

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ real

Constructor & Destructor Documentation

◆ TransverseMercator()

Member Function Documentation

◆ CentralScale()

◆ Flattening()

◆ Forward() [1/2]

◆ Forward() [2/2]

◆ MajorRadius()

◆ Reverse() [1/2]

◆ Reverse() [2/2]

◆ UTM()

Friends And Related Function Documentation

◆ Ellipsoid

Member Data Documentation

◆ _a

◆ _a1

◆ _alp

◆ _b1

◆ _bet

◆ _c

◆ _e2

◆ _e2m

◆ _es

◆ _f

◆ _k0

◆ _n

◆ maxpow_

◆ numit_