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 and use `"python[3] -m pygeodesy.etm ..."` to compare the results, see usage `"python[3] -m pygeodesy.etm -h"`.

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

Copyright (C) Charles Karney (2008-2024) 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: 25.04.14

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 Pure Python version of Karney's C++ class TransverseMercatorExact, a numerically exact transverse Mercator projection, abbreviated 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, strict=True, zone=None, **name_cmoff) Convert a geodetic lat-/longitude 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=NN` (`str`). Returns: The UTM coordinate (`Etm`) or if `Etm is None`, a UtmUps5Tuple`(zone, hemipole, easting, northing, band)` with `hemipole` is the hemisphere `'N'|'S'`. Raises: `ETMError` - Invalid `strUTM`. `TypeError` - Invalid or near-spherical `datum`.

### toEtm8 (latlon, lon=None, datum=None, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, strict=True, zone=None, **name_cmoff) |
Convert a geodetic lat-/longitude to an ETM coordinate. Arguments: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` instance. `lon` - Optional longitude (`degrees`), required if `latlon` is `degrees`, ignored otherwise. `datum` - Optional datum for the 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`). `strict` - Restrict `lat` to UTM ranges (`bool`). `zone` - Optional UTM zone to enforce (`int` or `str`). `name_cmoff` - Optional `Etm` `name=NN` (`str`) and DEPRECATED keyword argument `cmoff=True` to offset the longitude from the zone's central meridian (`bool`), use `falsed` instead. Returns: The ETM coordinate as `Etm` or if `Etm is None` or not `falsed`, a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, gamma, scale)`. The `hemipole` is the `'N'|'S'` hemisphere. Raises: `ETMError` - No convergence transforming to ETM easting 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 rangerrors is `True`. `TypeError` - Invalid or near-spherical `datum` or `latlon` not ellipsoidal. `ValueError` - The `lon` value is missing or `latlon` is invalid.