Package pygeodesy :: Module etm
[frames] | no frames]

Module etm

A pure Python version of Karney's Exact Transverse Mercator (ETM) projection.

Classes Etm, ETMError and ExactTransverseMercator, transcoded from Karney's C++ class TransverseMercatorExact (abbreviated as TMExact below).

Class ExactTransverseMercator provides Exact Transverse Mercator projections while instances of class Etm represent ETM (easting, nothing) locations.

Following is a copy of Karney's TransverseMercatorExact.hpp file Header.

Copyright (C) Charles Karney (2008-2021) and licensed under the MIT/X11 License. For more information, see the GeographicLib documentation.

The method entails using the Thompson Transverse Mercator as an intermediate projection. The projections from the intermediate coordinates to phi, lam and x, y are given by elliptic functions. The inverse of these projections are found by Newton's method with a suitable starting guess.

The relevant section of L.P. Lee's paper Conformal Projections Based On Jacobian Elliptic Functions in part V, pp 67-101. The C++ implementation and notation closely follow Lee, with the following exceptions:

 Lee   here   Description

 x/a   xi     Northing (unit Earth)

 y/a   eta    Easting (unit Earth)

 s/a   sigma  xi + i * eta

 y     x      Easting

 x     y      Northing

 k     e      Eccentricity

 k^2   mu     Elliptic function parameter

 k'^2  mv     Elliptic function complementary parameter

 m     k      Scale

 zeta  zeta   Complex longitude = Mercator = chi in paper

 s     sigma  Complex GK = zeta in paper

Minor alterations have been made in some of Lee's expressions in an attempt to control round-off. For example, atanh(sin(phi)) is replaced by asinh(tan(phi)) which maintains accuracy near phi = pi/2. Such changes are noted in the code.


Version: 22.04.27

Classes
  EasNorExact4Tuple
4-Tuple (easting, northing, convergence, scale) in meter, meter, degrees and scalar.
  ETMError
Exact Transverse Mercator (ETM) parse, projection or other Etm issue.
  Etm
Exact Transverse Mercator (ETM) coordinate, a sub-class of Utm, a Universal Transverse Mercator (UTM) coordinate using the ExactTransverseMercator projection for highest accuracy.
  ExactTransverseMercator
A Python version of Karney's TransverseMercatorExact C++ class, a numerically exact transverse Mercator projection, here referred to as TMExact.
  LatLonExact4Tuple
4-Tuple (lat, lon, convergence, scale) in degrees180, degrees180, degrees and scalar.
Functions
 
parseETM5(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, name='')
Parse a string representing a UTM coordinate, consisting of "zone[band] hemisphere easting northing".
 
toEtm8(latlon, lon=None, datum=None, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, name='', zone=None, **cmoff)
Convert a lat-/longitude point to an ETM coordinate.
Variables
  __all__ = _ALL_LAZY.etm
Function Details

parseETM5 (strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, name='')

 

Parse a string representing a UTM coordinate, consisting of "zone[band] hemisphere easting northing".

Arguments:
  • strUTM - A UTM coordinate (str).
  • datum - Optional datum to use (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • Etm - Optional class to return the UTM coordinate (Etm) or None.
  • falsed - Both easting and northing are falsed (bool).
  • name - Optional Etm name (str).
Returns:
The UTM coordinate (Etm) or if Etm is None, a UtmUps5Tuple(zone, hemipole, easting, northing, band). The hemipole is the hemisphere 'N'|'S'.
Raises:
  • ETMError - Invalid strUTM.
  • TypeError - Invalid or near-spherical datum.

Example:

>>> u = parseETM5('31 N 448251 5411932')
>>> u.toRepr()  # [Z:31, H:N, E:448251, N:5411932]
>>> u = parseETM5('31 N 448251.8 5411932.7')
>>> u.toStr()  # 31 N 448252 5411933

toEtm8 (latlon, lon=None, datum=None, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, name='', zone=None, **cmoff)

 

Convert a lat-/longitude point to an ETM coordinate.

Arguments:
  • latlon - Latitude (degrees) or an (ellipsoidal) geodetic LatLon point.
  • lon - Optional longitude (degrees) or None.
  • datum - Optional datum for this ETM coordinate, overriding latlon's datum (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • Etm - Optional class to return the ETM coordinate (Etm) or None.
  • falsed - False both easting and northing (bool).
  • name - Optional Utm name (str).
  • zone - Optional UTM zone to enforce (int or str).
  • cmoff - DEPRECATED, use falsed. Offset longitude from the zone's central meridian (bool).
Returns:
The ETM coordinate (Etm) or a UtmUps8Tuple(zone, hemipole, easting, northing, band, datum, convergence, scale) if Etm is None or not falsed. The hemipole is the 'N'|'S' hemisphere.
Raises:
  • EllipticError - No convergence transforming to ETM east- and northing.
  • ETMError - Invalid zone or near-spherical or incompatible datum or ellipsoid.
  • RangeError - If lat outside the valid UTM bands or if lat or lon outside the valid range and pygeodesy.rangerrors set to True.
  • TypeError - Invalid or near-spherical datum or latlon not ellipsoidal.
  • ValueError - The lon value is missing or latlon is invalid.