Coverage for pygeodesy/mgrs.py : 98%

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 -*-
L{MGRSError} and functions L{parseMGRS} and L{toMgrs}.
Pure Python implementation of MGRS / UTM conversion functions using an ellipsoidal earth model, transcribed 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>}.
@newfield example: Example, Examples '''
_xinstanceof, _xzipairs _easting_, _northing_, _SPACE_, \ _SQUARE_, _zone_, _0_0
# 100 km grid square column (‘e’) letters repeat every third zone # 100 km grid square row (‘n’) letters repeat every other zone
# split an MGRS string "12ABC1235..." into 3 parts
'''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. '''
band=NN, datum=Datums.WGS84, 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° latitudinal band (C{str}), C..X covering 80°S..84°N. @kwarg datum: Optional this reference's datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2} or L{a_f2Tuple}). @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 latitudinal band (C{str, 'A'|'B'..'Y'|'Z'}). '''
'''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 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)
'''Return a string representation of this MGRS grid reference.
@kwarg prec: Optional number of digits (C{int}), 4:km, 10:m. @kwarg fmt: Optional enclosing backets format (C{str}). @kwarg sep: Optional 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: Optional 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}.
@return: The UTM coordinate (L{Utm}) or a L{UtmUps5Tuple}C{(zone, hemipole, easting, northing, band)} if B{C{Utm}} is C{None}.
@example:
>>> m = Mgrs('31U', 'DQ', 448251, 11932) >>> u = m.toUtm() # 31 N 448251 5411932 >>> u = m.toUtm(None) # 31 N 448251 5411932 U ''' # 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=self.datum)
'''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: A 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 (B{L{Mgrs}}) or an L{Mgrs4Tuple}C{(zone, digraph, easting, northing)} if B{C{Mgrs}} is C{None}.
@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
Mgrs(z, EN, e, n, datum=datum)
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 B{C{Mgrs=None}}.
@return: The MGRS grid reference (B{L{Mgrs}}) or an L{Mgrs6Tuple}C{(zone, digraph, easting, northing, band, datum)} if B{L{Mgrs}} is C{None}.
@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-2020 -- 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. |