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

# Module mgrs

Military Grid Reference System (MGRS/NATO) references.

Classes Mgrs, Mgrs4Tuple and Mgrs6Tuple and functions parseMGRS and toMgrs.

Pure Python implementation of MGRS, UTM and UPS conversions covering the entire ellipsoidal earth, transcoded from Chris Veness' JavaScript originals MGRS and Module mgrs and from Charles Karney's C++ class MGRS.

MGRS references comprise a grid zone designation (GZD), a 100 km grid (square) tile identification and an easting and northing (in `meter`). The GZD consists of a longitudinal zone (or column) number and latitudinal band (row) letter in the UTM region between 80°S and 84°N. Each zone (column) is 6° wide and each band (row) is 8° high, except top band 'X' is 12° tall. In UPS polar regions below 80°S and above 84°N the GZD contains only a single letter, `'A'` or `'B'` near the south and `'Y'` or `'Z'` around the north pole (for west respectively east longitudes).

See also the United States National Grid and Military Grid Reference System.

See module pygeodesy.ups for env variable `PYGEODESY_UPS_POLES` determining the UPS encoding at the south and north pole.

Set env variable `PYGEODESY_GEOCONVERT` to the (fully qualified) path of the `GeoConvert` executable to run this module as python[3] -m pygeodesy.mgrs and compare the MGRS results with those from Karney's utility GeoConvert.

Version: 22.09.24

Classes
| Mgrs Military Grid Reference System (MGRS/NATO) references, with method to convert to UTM coordinates.
| Mgrs4Tuple 4-Tuple `(zone, EN, easting, northing)`, `zone` and grid tile `EN` as `str`, `easting` and `northing` in `meter`.
| Mgrs6Tuple 6-Tuple `(zone, EN, easting, northing, band, datum)`, with `zone`, grid tile `EN` and `band` as `str`, `easting` and `northing` in `meter` and `datum` a Datum.

Functions
parseMGRS(strMGRS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, name='') Parse a string representing a MGRS grid reference, consisting of `"[zone]Band, EN, easting, northing"`. |
toMgrs(utmups, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, name='', **Mgrs_kwds) Convert a UTM or UPS coordinate to an MGRS grid reference. |

Variables
| __all__ = `_ALL_LAZY.mgrs`

Function Details

### parseMGRS (strMGRS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, name='') |
Parse a string representing a MGRS grid reference, consisting of `"[zone]Band, EN, easting, northing"`. Arguments: `strMGRS` - MGRS grid reference (`str`). `datum` - Optional datum to use (Datum). `Mgrs` - Optional class to return the MGRS grid reference (Mgrs) or `None`. `name` - Optional `Mgrs` name (`str`). Returns: The MGRS grid reference as `Mgrs` or if `Mgrs is None` as an Mgrs4Tuple`(zone, EN, easting, northing)`. Raises: `MGRSError` - Invalid `strMGRS`. Example:
    >>> m = parseMGRS('31U DQ 48251 11932')
    >>> str(m)  # '31U DQ 48251 11932'
    >>> m = parseMGRS('31UDQ4825111932')
    >>> repr(m)  # [Z:31U, G:DQ, E:48251, N:11932]
    >>> m = parseMGRS('42SXD0970538646')
    >>> str(m)  # '42S XD 09705 38646'
    >>> m = parseMGRS('42SXD9738')  # Km
    >>> str(m)  # '42S XD 97000 38000'
    >>> m = parseMGRS('YUB17770380')  # polar
    >>> str(m)  # 'Y UB 17770 03800'

### toMgrs (utmups, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, name='', **Mgrs_kwds) |
Convert a UTM or UPS coordinate to an MGRS grid reference. Arguments: `utmups` - A UTM or UPS coordinate (Utm, Etm or Ups). `Mgrs` - Optional class to return the MGRS grid reference (Mgrs) or `None`. `name` - Optional `Mgrs` name (`str`). `Mgrs_kwds` - Optional, additional `Mgrs` keyword arguments, ignored if `Mgrs is None`. Returns: The MGRS grid reference as `Mgrs` or if `Mgrs is None` as an Mgrs6Tuple`(zone, EN, easting, northing, band, datum)`. Raises: `MGRSError` - Invalid `utmups`. `TypeError` - If `utmups` is not Utm nor Etm nor Ups. Example:
    >>> u = Utm(31, 'N', 448251, 5411932)
    >>> m = u.toMgrs()  # 31U DQ 48251 11932