Coverage for pygeodesy/gars.py: 97%

143 statements  

« prev     ^ index     » next       coverage.py v7.6.1, created at 2025-01-10 16:55 -0500

1 

2# -*- coding: utf-8 -*- 

3 

4u'''I{Global Area Reference System} (GARS) en-/decoding. 

5 

6Class L{Garef} and several functions to encode, decode and inspect 

7GARS references. 

8 

9Transcoded from I{Charles Karney}'s C++ class U{GARS 

10<https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1GARS.html>}. 

11 

12@see: U{Global Area Reference System 

13 <https://WikiPedia.org/wiki/Global_Area_Reference_System>} and U{NGA 

14 (GARS)<https://Earth-Info.NGA.mil/GandG/coordsys/grids/gars.html>}. 

15''' 

16 

17# from pygeodesy.basics import isstr # from .named 

18from pygeodesy.constants import _off90, _1_over, _0_5, \ 

19 _1_0 # PYCHOK used! 

20from pygeodesy.errors import _ValueError, _xkwds, _xStrError 

21from pygeodesy.interns import NN, _0to9_, _AtoZnoIO_, _COMMA_, \ 

22 _INV_, _SPACE_ 

23from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY 

24from pygeodesy.named import _name__, Fmt, isstr, Property_RO 

25from pygeodesy.namedTuples import LatLon2Tuple, LatLonPrec3Tuple 

26# from pygeodesy.props import Property_RO # from .named 

27# from pygeodesy.streprs import Fmt # from .named 

28from pygeodesy.units import Int_, Lat, Lon, Precision_, Scalar_, Str 

29 

30from math import floor 

31 

32__all__ = _ALL_LAZY.gars 

33__version__ = '24.08.13' 

34 

35_Digits = _0to9_ 

36_LatLen = 2 

37_LatOrig = -90 

38_Letters = _AtoZnoIO_ 

39_LonLen = 3 

40_LonOrig = -180 

41_MaxPrec = 2 

42 

43_MinLen = _LonLen + _LatLen 

44_MaxLen = _MinLen + _MaxPrec 

45 

46_M1 = _M2 = 2 

47_M3 = 3 

48_M4 = _M1 * _M2 * _M3 

49 

50_LatOrig_M4 = _LatOrig * _M4 

51_LatOrig_M1 = _LatOrig * _M1 

52_LonOrig_M4 = _LonOrig * _M4 

53_LonOrig_M1_1 = _LonOrig * _M1 - 1 

54 

55_Resolutions = _1_over(_M1), _1_over(_M1 * _M2), _1_over(_M4) 

56 

57 

58def _2divmod2(ll, _Orig_M4): 

59 x = int(floor(ll * _M4)) - _Orig_M4 

60 i = (x * _M1) // _M4 

61 x -= i * _M4 // _M1 

62 return i, x 

63 

64 

65def _2fll(lat, lon, *unused): 

66 '''(INTERNAL) Convert lat, lon. 

67 ''' 

68 # lat, lon = parseDMS2(lat, lon) 

69 return (Lat(lat, Error=GARSError), 

70 Lon(lon, Error=GARSError)) 

71 

72 

73# def _2Garef(garef): 

74# '''(INTERNAL) Check or create a L{Garef} instance. 

75# ''' 

76# if not isinstance(garef, Garef): 

77# try: 

78# garef = Garef(garef) 

79# except (TypeError, ValueError): 

80# raise _xStrError(Garef, Str, garef=garef) 

81# return garef 

82 

83 

84def _2garstr2(garef): 

85 '''(INTERNAL) Check a garef string. 

86 ''' 

87 try: 

88 n, garstr = len(garef), garef.upper() 

89 if n < _MinLen or n > _MaxLen \ 

90 or garstr.startswith(_INV_) \ 

91 or not garstr.isalnum(): 

92 raise ValueError() 

93 return garstr, _2Precision(n - _MinLen) 

94 

95 except (AttributeError, TypeError, ValueError) as x: 

96 raise GARSError(Garef.__name__, garef, cause=x) 

97 

98 

99def _2Precision(precision): 

100 '''(INTERNAL) Return a L{Precision_} instance. 

101 ''' 

102 return Precision_(precision, Error=GARSError, low=0, high=_MaxPrec) 

103 

104 

105class GARSError(_ValueError): 

106 '''Global Area Reference System (GARS) encode, decode or other L{Garef} issue. 

107 ''' 

108 pass 

109 

110 

111class Garef(Str): 

112 '''Garef class, a named C{str}. 

113 ''' 

114 # no str.__init__ in Python 3 

115 def __new__(cls, lat_gll, lon=None, precision=1, **name): 

116 '''New L{Garef} from an other L{Garef} instance or garef C{str} 

117 or from a lat- and longitude. 

118 

119 @arg lat_gll: Latitude (C{degrees90}), a garef (L{Garef}, 

120 C{str}) or a location (C{LatLon}, C{LatLon*Tuple}). 

121 @kwarg lon: Logitude (C{degrees180)}, required if B{C{lat_gll}} 

122 is C{degrees90}, ignored otherwise. 

123 @kwarg precision: The desired garef resolution and length (C{int} 

124 0..2), see L{encode<pygeodesy.gars.encode>}. 

125 @kwarg name: Optional C{B{name}=NN} (C{str}). 

126 

127 @return: New L{Garef}. 

128 

129 @raise GARSError: INValid B{C{lat_gll}}. 

130 

131 @raise RangeError: Invalid B{C{lat_gll}} or B{C{lon}}. 

132 

133 @raise TypeError: Invalid B{C{lat_gll}} or B{C{lon}}. 

134 ''' 

135 if lon is None: 

136 if isinstance(lat_gll, Garef): 

137 g, ll, p = str(lat_gll), lat_gll.latlon, lat_gll.precision 

138 elif isstr(lat_gll): 

139 ll = lat_gll.replace(_COMMA_, _SPACE_).split() 

140 if len(ll) > 1: 

141 g, ll, p = _encode3(ll[0], ll[1], precision) 

142 else: 

143 g, ll = lat_gll.upper(), None 

144 _, p = _2garstr2(g) # validate 

145 else: # assume LatLon 

146 try: 

147 g, ll, p = _encode3(lat_gll.lat, lat_gll.lon, precision) 

148 except AttributeError: 

149 raise _xStrError(Garef, gll=lat_gll, Error=GARSError) 

150 else: 

151 g, ll, p = _encode3(lat_gll, lon, precision) 

152 

153 self = Str.__new__(cls, g, name=_name__(name, _or_nameof=lat_gll)) 

154 self._latlon = ll 

155 self._precision = p 

156 return self 

157 

158 @Property_RO 

159 def decoded3(self): 

160 '''Get this garef's attributes (L{LatLonPrec3Tuple}). 

161 ''' 

162 lat, lon = self.latlon 

163 return LatLonPrec3Tuple(lat, lon, self.precision, name=self.name) 

164 

165 @Property_RO 

166 def _decoded3(self): 

167 '''(INTERNAL) Initial L{LatLonPrec3Tuple}. 

168 ''' 

169 return decode3(self) 

170 

171 @Property_RO 

172 def latlon(self): 

173 '''Get this garef's (center) lat- and longitude (L{LatLon2Tuple}). 

174 ''' 

175 lat, lon = self._latlon or self._decoded3[:2] 

176 return LatLon2Tuple(lat, lon, name=self.name) 

177 

178 @Property_RO 

179 def precision(self): 

180 '''Get this garef's precision (C{int}). 

181 ''' 

182 p = self._precision 

183 return self._decoded3.precision if p is None else p 

184 

185 def toLatLon(self, LatLon=None, **LatLon_kwds): 

186 '''Return (the center of) this garef cell as an instance 

187 of the supplied C{LatLon} class. 

188 

189 @kwarg LatLon: Class to use (C{LatLon} or C{None}). 

190 @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} 

191 keyword arguments. 

192 

193 @return: This garef location as B{C{LatLon}} or if 

194 C{B{LatLon} is None} as L{LatLonPrec3Tuple}. 

195 ''' 

196 return self.decoded3 if LatLon is None else LatLon( 

197 *self.latlon, **_xkwds(LatLon_kwds, name=self.name)) 

198 

199 

200def decode3(garef, center=True, **name): 

201 '''Decode a C{garef} to lat-, longitude and precision. 

202 

203 @arg garef: To be decoded (L{Garef} or C{str}). 

204 @kwarg center: If C{True}, use the garef's center, otherwise 

205 the south-west, lower-left corner (C{bool}). 

206 

207 @return: A L{LatLonPrec3Tuple}C{(lat, lon, precision)}. 

208 

209 @raise GARSError: Invalid B{C{garef}}, INValid, non-alphanumeric 

210 or bad length B{C{garef}}. 

211 ''' 

212 def _Error(i): 

213 return GARSError(garef=Fmt.SQUARE(repr(garef), i)) 

214 

215 def _ll(chars, g, i, j, lo, hi): 

216 ll, b = 0, len(chars) 

217 for i in range(i, j): 

218 d = chars.find(g[i]) 

219 if d < 0: 

220 raise _Error(i) 

221 ll = ll * b + d 

222 if ll < lo or ll > hi: 

223 raise _Error(j) 

224 return ll 

225 

226 def _ll2(lon, lat, g, i, m): 

227 d = _Digits.find(g[i]) 

228 if d < 1 or d > m * m: 

229 raise _Error(i) 

230 d, r = divmod(d - 1, m) 

231 lon = lon * m + r 

232 lat = lat * m + (m - 1 - d) 

233 return lon, lat 

234 

235 g, precision = _2garstr2(garef) 

236 

237 lon = _ll(_Digits, g, 0, _LonLen, 1, 720) + _LonOrig_M1_1 

238 lat = _ll(_Letters, g, _LonLen, _MinLen, 0, 359) + _LatOrig_M1 

239 if precision > 0: 

240 lon, lat = _ll2(lon, lat, g, _MinLen, _M2) 

241 if precision > 1: 

242 lon, lat = _ll2(lon, lat, g, _MinLen + 1, _M3) 

243 

244 if center: # ll = (ll * 2 + 1) / 2 

245 lon += _0_5 

246 lat += _0_5 

247 

248 n = _name__(name, _or_nameof=garef) 

249 r = _Resolutions[precision] # == 1.0 / unit 

250 return LatLonPrec3Tuple(Lat(lat * r, Error=GARSError), 

251 Lon(lon * r, Error=GARSError), 

252 precision, name=n) 

253 

254 

255def encode(lat, lon, precision=1): 

256 '''Encode a lat-/longitude as a C{garef} of the given precision. 

257 

258 @arg lat: Latitude (C{degrees}). 

259 @arg lon: Longitude (C{degrees}). 

260 @kwarg precision: Optional, the desired C{garef} resolution 

261 and length (C{int} 0..2). 

262 

263 @return: The C{garef} (C{str}). 

264 

265 @raise RangeError: Invalid B{C{lat}} or B{C{lon}}. 

266 

267 @raise GARSError: Invalid B{C{precision}}. 

268 

269 @note: The C{garef} length is M{precision + 5} and the C{garef} 

270 resolution is B{30′} for B{C{precision}} 0, B{15′} for 1 

271 and B{5′} for 2, respectively. 

272 ''' 

273 g, _, _ = _encode3(lat, lon, precision) 

274 return g 

275 

276 

277def _encode3(lat, lon, precision): # MCCABE 14 

278 '''Return 3-tuple C{(garef, (lat, lon), p)}. 

279 ''' 

280 def _digit(x, y, m): 

281 return _Digits[m * (m - y - 1) + x + 1], 

282 

283 def _str(chars, x, n): 

284 s, b = [], len(chars) 

285 for i in range(n): 

286 x, i = divmod(x, b) 

287 s.append(chars[i]) 

288 return tuple(reversed(s)) 

289 

290 p = _2Precision(precision) 

291 

292 lat, lon = _2fll(lat, lon) 

293 

294 ix, x = _2divmod2( lon, _LonOrig_M4) 

295 iy, y = _2divmod2(_off90(lat), _LatOrig_M4) 

296 

297 g = _str(_Digits, ix + 1, _LonLen) + \ 

298 _str(_Letters, iy, _LatLen) 

299 if p > 0: 

300 ix, x = divmod(x, _M3) 

301 iy, y = divmod(y, _M3) 

302 g += _digit(ix, iy, _M2) 

303 if p > 1: 

304 g += _digit(x, y, _M3) 

305 

306 return NN.join(g), (lat, lon), p 

307 

308 

309def precision(res): 

310 '''Determine the L{Garef} precision to meet a required (geographic) 

311 resolution. 

312 

313 @arg res: The required resolution (C{degrees}). 

314 

315 @return: The L{Garef} precision (C{int} 0..2). 

316 

317 @raise ValueError: Invalid B{C{res}}. 

318 

319 @see: Function L{gars.encode} for more C{precision} details. 

320 ''' 

321 r = Scalar_(res=res) 

322 for p in range(_MaxPrec): 

323 if resolution(p) <= r: 

324 return p 

325 return _MaxPrec 

326 

327 

328def resolution(prec): 

329 '''Determine the (geographic) resolution of a given L{Garef} precision. 

330 

331 @arg prec: The given precision (C{int}). 

332 

333 @return: The (geographic) resolution (C{degrees}). 

334 

335 @raise GARSError: Invalid B{C{prec}}. 

336 

337 @see: Function L{gars.encode} for more C{precision} details. 

338 ''' 

339 p = Int_(prec=prec, Error=GARSError, low=-1, high=_MaxPrec + 1) 

340 return _Resolutions[max(0, min(p, _MaxPrec))] 

341 

342 

343__all__ += _ALL_DOCS(decode3, # functions 

344 encode, precision, resolution) 

345 

346# **) MIT License 

347# 

348# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved. 

349# 

350# Permission is hereby granted, free of charge, to any person obtaining a 

351# copy of this software and associated documentation files (the "Software"), 

352# to deal in the Software without restriction, including without limitation 

353# the rights to use, copy, modify, merge, publish, distribute, sublicense, 

354# and/or sell copies of the Software, and to permit persons to whom the 

355# Software is furnished to do so, subject to the following conditions: 

356# 

357# The above copyright notice and this permission notice shall be included 

358# in all copies or substantial portions of the Software. 

359# 

360# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 

361# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 

362# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 

363# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR 

364# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 

365# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 

366# OTHER DEALINGS IN THE SOFTWARE.