GeographicLib 2.3

Public Member Functions | Static Public Member Functions | List of all members
GeographicLib::TransverseMercator Class Reference

Transverse Mercator projection. More...

`#include <GeographicLib/TransverseMercator.hpp>`

## Public Member Functions
| TransverseMercator (real a, real f, real k0, bool exact=false, 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
bool | Exact () const

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

## 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−15" and the relative error in the scale is 6 × 10−12%%. 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°, λ − λ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. This formulation is accessible in this class by calling the constructor with exact = true.

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 Transverse Mercator projection 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;
}
}
main
int main(int argc, const char *const argv[])
Definition: CartConvert.cpp:29
TransverseMercator.hpp
Header for GeographicLib::TransverseMercator class.
GeographicLib::TransverseMercator::TransverseMercator
TransverseMercator(real a, real f, real k0, bool exact=false, bool extendp=false)
Definition: TransverseMercator.cpp:49
GeographicLib::TransverseMercator::Reverse
void Reverse(real lon0, real x, real y, real &lat, real &lon, real &gamma, real &k) const
Definition: TransverseMercator.cpp:528
GeographicLib::TransverseMercator::Forward
void Forward(real lon0, real lat, real lon, real &x, real &y, real &gamma, real &k) const
Definition: TransverseMercator.cpp:360
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812

TransverseMercatorProj is a command-line utility providing access to the functionality of this class.

Definition at line 94 of file TransverseMercator.hpp.

## Constructor & Destructor Documentation

## ◆ TransverseMercator()

GeographicLib::TransverseMercator::TransverseMercator | ( | real | a,
|  | real | f,
|  | real | k0,
|  | bool | exact = `false`,
|  | bool | extendp = `false`
| ) |  |

Constructor for an 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.
  [in] | exact | if true use exact formulation in terms of elliptic functions instead of series expansions (default false).
  [in] | extendp | use extended domain (default false); should only be used if exact = true;

Exceptions

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

With exact = true, this class delegates the calculations to the TransverseMercatorExact classes which compute the projection in terms of elliptic functions.

Definition at line 49 of file TransverseMercator.cpp.

References GeographicLib::Math::polyval(), and GeographicLib::Math::sq().

## Member Function Documentation

## ◆ Forward() [1/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 360 of file TransverseMercator.cpp.

References GeographicLib::Math::AngDiff(), GeographicLib::Math::AngNormalize(), GeographicLib::Math::atan2d(), GeographicLib::TransverseMercatorExact::Forward(), GeographicLib::Math::hd, GeographicLib::Math::LatFix(), GeographicLib::Math::pi(), GeographicLib::Math::qd, GeographicLib::Math::sincosd(), GeographicLib::Math::sq(), and GeographicLib::Math::taupf().

Referenced by GeographicLib::UTMUPS::Forward(), GeographicLib::OSGB::Forward(), and main().

## ◆ Reverse() [1/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 528 of file TransverseMercator.cpp.

References GeographicLib::Math::AngNormalize(), GeographicLib::Math::atan2d(), GeographicLib::Math::atand(), GeographicLib::Math::hd, GeographicLib::Math::pi(), GeographicLib::Math::qd, GeographicLib::TransverseMercatorExact::Reverse(), GeographicLib::Math::sq(), and GeographicLib::Math::tauf().

Referenced by main(), GeographicLib::UTMUPS::Reverse(), and GeographicLib::OSGB::Reverse().

## ◆ Forward() [2/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 165 of file TransverseMercator.hpp.

## ◆ Reverse() [2/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 174 of file TransverseMercator.hpp.

## ◆ EquatorialRadius()

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

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

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 193 of file TransverseMercator.hpp.

## ◆ 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 199 of file TransverseMercator.hpp.

## ◆ Exact()

bool GeographicLib::TransverseMercator::Exact | ( |  | ) | const
| inline

Returns
  exact whether the exact formulation is used. This is the value used in the constructor.

Definition at line 205 of file TransverseMercator.hpp.

## ◆ 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 287 of file TransverseMercator.cpp.

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

Referenced by GeographicLib::UTMUPS::Forward(), and GeographicLib::UTMUPS::Reverse().

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

- TransverseMercator.hpp
- TransverseMercator.cpp