Coverage for pygeodesy/mgrs.py : 97%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# -*- coding: utf-8 -*-
Military Grid Reference System (MGRS/NATO) classes L{Mgrs} and L{MGRSError} and functions L{parseMGRS} and L{toMgrs}.
Pure Python implementation of MGRS / UTM conversion functions using an ellipsoidal earth model, transcoded from JavaScript originals by I{(C) Chris Veness 2014-2016} published under the same MIT Licence**, see U{MGRS<https://www.Movable-Type.co.UK/scripts/latlong-utm-mgrs.html>} and U{Module mgrs<https://www.Movable-Type.co.UK/scripts/geodesy/docs/module-mgrs.html>}.
The MGRS/NATO grid references provides geocoordinate references covering the entire globe, based on UTM projections.
MGRS references comprise a grid zone designation, a 100 km square identification, and an easting and northing (in metres).
Depending on requirements, some parts of the reference may be omitted (implied), and easting/northing may be given to varying resolution.
See also U{United States National Grid <https://www.FGDC.gov/standards/projects/FGDC-standards-projects/usng/fgdc_std_011_2001_usng.pdf>} and U{Military Grid Reference System<https://WikiPedia.org/wiki/Military_grid_reference_system>}. '''
_COMMASPACE_, _datum_, _easting_, \ _northing_, _SPACE_, _zone_, _0_5
# 100 km grid square column (‘e’) letters repeat every third zone # 100 km grid square row (‘n’) letters repeat every other zone
'''(INTERNAL) Lazily compiled regex-es. '''
'''Military Grid Reference System (MGRS) parse or other L{Mgrs} issue. '''
'''Military Grid Reference System (MGRS/NATO) references, with method to convert to UTM coordinates. '''
datum=_WGS84, resolution=0, name=NN): '''New L{Mgrs} Military grid reference.
@arg zone: 6° longitudinal zone (C{int}), 1..60 covering 180°W..180°E. @arg en100k: Two-letter EN digraph (C{str}), 100 km grid square. @arg easting: Easting (C{meter}), within 100 km grid square. @arg northing: Northing (C{meter}), within 100 km grid square. @kwarg band: Optional, 8° I{latitudinal} band (C{str}), 'C'|..|'X' covering 80°S..84°N (without 'I' and 'O'). @kwarg datum: Optional this reference's datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2} or L{a_f2Tuple}). @kwarg resolution: Optional resolution, cell size (C{meter}) or C{0}. @kwarg name: Optional name (C{str}).
@raise MGRSError: Invalid MGRS grid reference, B{C{zone}}, B{C{en100k}}, B{C{easting}}, B{C{northing}} or B{C{band}}.
@raise TypeError: Invalid B{C{datum}}.
@example:
>>> from pygeodesy import Mgrs >>> m = Mgrs('31U', 'DQ', 48251, 11932) # 31U DQ 48251 11932 ''' self.name = name
raise IndexError # caught below except IndexError: raise MGRSError(en100k=en100k)
self._datum = _ellipsoidal_datum(datum, name=name)
# check and convert grid letters to meter # get easting specified by e100k (note, +1 because # eastings start at 166e3 due to 500 km false origin) # similarly, get northing specified by n100k
'''Get the I{latitudinal} band (C{str, 'A'|'B'|..|'W'|'X'}). '''
'''Get the band latitude (C{degrees90} or C{None}). '''
'''Get the datum (L{Datum}). '''
'''Get the 2-character grid EN digraph (C{str}). '''
'''Gets the easting (C{meter}). '''
'''Get easting and northing (L{EasNor2Tuple}C{(easting, northing)}). ''' return EasNor2Tuple(self.easting, self.northing)
'''Get the northing (C{meter}). '''
'''Parse a string to a similar L{Mgrs} instance.
@arg strMGRS: The MGRS reference (C{str}), see function L{parseMGRS}. @kwarg name: Optional instance name (C{str}), overriding this name.
@return: The similar instance (L{Mgrs}).
@raise MGRSError: Invalid B{C{strMGRS}}. ''' name=name or self.name)
'''Get the resolution (C{meter}). '''
'''Set the resolution of this L{Mgrs} instance.
@arg resolution: Cell size (C{meter}, power of 10).
@raise MGRSError: Invalid B{C{resolution}}. ''' raise ValueError else: r = 0 except (ValueError, TypeError): raise MGRSError(resolution=resolution)
'''Convert this MGRS grid reference to a UTM coordinate.
@kwarg LatLon: Optional, ellipsoidal class to return the geodetic point (C{LatLon}) or C{None}. @kwarg center: Optionally, return the grid's center or lower left corner (C{bool}). @kwarg toLatLon_kwds: Optional, additional L{Utm.toLatLon} and B{C{LatLon}} keyword arguments.
@return: A B{C{LatLon}} instance or if C{B{LatLon} is None} a L{LatLonDatum5Tuple}C{(lat, lon, datum, convergence, scale)}.
@raise TypeError: If B{C{LatLon}} is not ellipsoidal.
@raise UTMError: Invalid meridional radius or H-value.
@see: Methods L{Mgrs.toUtm} and L{Utm.toLatLon}. '''
'''Return a string representation of this MGRS grid reference.
@kwarg prec: Number of digits (C{int}), 4:Km, 10:m. @kwarg fmt: Enclosing backets format (C{str}). @kwarg sep: Separator between name:values (C{str}).
@return: This Mgrs as "[Z:00B, G:EN, E:meter, N:meter]" (C{str}). '''
'''Return a string representation of this MGRS grid reference.
Note that MGRS grid references are truncated, not rounded (unlike UTM coordinates).
@kwarg prec: Number of digits (C{int}), 4:Km, 10:m. @kwarg sep: Optional separator to join (C{str}) or C{None} to return an unjoined C{tuple} of C{str}s.
@return: This Mgrs as "00B EN easting northing" (C{str}).
@raise ValueError: Invalid B{C{prec}}.
@example:
>>> m = Mgrs(31, 'DQ', 48251, 11932, band='U') >>> m.toStr() # '31U DQ 48251 11932' '''
'''Convert this MGRS grid reference to a UTM coordinate.
@kwarg Utm: Optional class to return the UTM coordinate (L{Utm}) or C{None}. @kwarg center: Optionally, center easting and northing by the resolution (C{bool}).
@return: A B{C{Utm}} instance or if C{B{Utm} is None} a L{UtmUps5Tuple}C{(zone, hemipole, easting, northing, band)}. ''' Error=MGRSError, name=r.name) else: band=r.band, datum=self.datum, name=r.name)
'''(INTERNAL) Cache for L{pygeodesy.toUtm}. ''' # get northing of the band bottom, extended to # include entirety of bottom-most 100 km square
# 100 km grid square row letters repeat every 2,000 km north; # add enough 2,000 km blocks to get into required band
Utm( z, h, e, n, band=B, datum=d, name=s))
'''Get the longitudal zone (C{int}, 1..60). '''
'''4-Tuple C{(zone, digraph, easting, northing)}, C{zone} and C{digraph} as C{str}, C{easting} and C{northing} in C{meter}. '''
'''Extend this L{Mgrs4Tuple} to a L{Mgrs6Tuple}.
@arg band: The band to add (C{str} or C{None}). @arg datum: The datum to add (L{Datum} or C{None}).
@return: An L{Mgrs6Tuple}C{(zone, digraph, easting, northing, band, datum)}. '''
'''6-Tuple C{(zone, digraph, easting, northing, band, datum)}, C{zone}, C{digraph} and C{band} as C{str}, C{easting} and C{northing} in C{meter} and C{datum} a L{Datum}. '''
'''Parse a string representing a MGRS grid reference, consisting of C{"zoneBand, grid, easting, northing"}.
@arg strMGRS: MGRS grid reference (C{str}). @kwarg datum: Optional datum to use (L{Datum}). @kwarg Mgrs: Optional class to return the MGRS grid reference (L{Mgrs}) or C{None}. @kwarg name: Optional B{C{Mgrs}} name (C{str}).
@return: The MGRS grid reference as B{C{Mgrs}} or if C{B{Mgrs} is None} as an L{Mgrs4Tuple}C{(zone, digraph, easting, northing)}.
@raise MGRSError: Invalid B{C{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 = mgrs.parseMGRS('42SXD0970538646') >>> str(m) # 42S XD 09705 38646 >>> m = mgrs.parseMGRS('42SXD9738') # Km >>> str(m) # 42S XD 97000 38000 ''' raise ValueError
# convert to meter if less than 5 digits
raise ValueError
r = Mgrs4Tuple(z, EN, e, n, name=name) else:
strMGRS=strMGRS, Error=MGRSError)
'''Convert a UTM coordinate to an MGRS grid reference.
@arg utm: A UTM coordinate (L{Utm} or L{Etm}). @kwarg Mgrs: Optional class to return the MGRS grid reference (L{Mgrs}) or C{None}. @kwarg name: Optional B{C{Mgrs}} name (C{str}). @kwarg Mgrs_kwds: Optional, additional B{C{Mgrs}} keyword arguments, ignored if C{B{Mgrs} is None}.
@return: The MGRS grid reference as B{C{Mgrs}} or if C{B{Mgrs} is None} as an L{Mgrs6Tuple}C{(zone, digraph, easting, northing, band, datum)}.
@raise TypeError: If B{C{utm}} is not L{Utm} nor L{Etm}.
@raise MGRSError: Invalid B{C{utm}}.
@example:
>>> u = Utm(31, 'N', 448251, 5411932) >>> m = u.toMgrs() # 31U DQ 48251 11932 '''
# truncate east-/northing to within 100 km grid square # XXX add rounding to nm precision?
# columns in zone 1 are A-H, zone 2 J-R, zone 3 S-Z, then # repeating every 3rd zone (note -1 because eastings start # at 166e3 due to 500km false origin) # rows in even zones are A-V, in odd zones are F-E _Ln100k[z % 2][int(N) % len(_Ln100k[0])])
else:
# **) MIT License # # Copyright (C) 2016-2022 -- mrJean1 at Gmail -- All Rights Reserved. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), # to deal in the Software without restriction, including without limitation # the rights to use, copy, modify, merge, publish, distribute, sublicense, # and/or sell copies of the Software, and to permit persons to whom the # Software is furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included # in all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR # OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR # OTHER DEALINGS IN THE SOFTWARE. |