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, northing)` locations. See also Karney's utility TransverseMercatorProj.

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

Copyright (C) Charles Karney (2008-2022) 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.08.24

Classes
| ETMError Exact Transverse Mercator (ETM) parse, projection or other Etm issue or ExactTransverseMercator conversion failure.
| 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`.

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='', strict=True, 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='', strict=True, 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`). `strict` - Restrict `lat` to UTM ranges (`bool`). `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: `ETMError` - 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.