Coverage for pygeodesy/geodsolve.py: 94%

78 statements  

« prev     ^ index     » next       coverage.py v7.2.2, created at 2023-08-12 12:31 -0400

1 

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

3 

4u'''Wrapper to invoke I{Karney}'s U{GeodSolve 

5<https://GeographicLib.SourceForge.io/C++/doc/GeodSolve.1.html>} utility 

6as an (exact) geodesic, but intended I{for testing purposes only}. 

7 

8Set env variable C{PYGEODESY_GEODSOLVE} to the (fully qualified) path 

9of the C{GeodSolve} executable. 

10''' 

11 

12# from pygeodesy.basics import _xinstanceof # from .karney 

13from pygeodesy.interns import NN, _a12_, _azi1_, _azi2_, \ 

14 _lat1_, _lat2_, _lon1_, _lon2_, _m12_, \ 

15 _M12_, _M21_, _s12_, _S12_, _UNDER_ 

16from pygeodesy.interns import _UNUSED_, _not_ # PYCHOK used! 

17from pygeodesy.karney import _Azi, Caps, _Deg, GeodesicError, _GTuple, \ 

18 _Pass, _Lat, _Lon, _M, _M2, _sincos2d, \ 

19 _xinstanceof 

20from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS, \ 

21 _getenv, printf 

22from pygeodesy.namedTuples import Destination3Tuple, Distance3Tuple 

23from pygeodesy.props import Property, Property_RO 

24from pygeodesy.solveBase import _SolveBase, _SolveLineBase, wrap360 

25# from pygeodesy.utily import wrap360 # from .solveBase 

26 

27__all__ = _ALL_LAZY.geodsolve 

28__version__ = '23.08.04' 

29 

30_PYGEODESY_GEODSOLVE_ = 'PYGEODESY_GEODSOLVE' # PYCHOK used! 

31 

32 

33class GeodSolve12Tuple(_GTuple): 

34 '''12-Tuple C{(lat1, lon1, azi1, lat2, lon2, azi2, s12, a12, m12, M12, M21, S12)} with 

35 angles C{lat1}, C{lon1}, C{azi1}, C{lat2}, C{lon2} and C{azi2} and arc C{a12} all in 

36 C{degrees}, initial C{azi1} and final C{azi2} forward azimuths, distance C{s12} and 

37 reduced length C{m12} in C{meter}, area C{S12} in C{meter} I{squared} and geodesic 

38 scale factors C{M12} and C{M21}, both C{scalar}, see U{GeodSolve 

39 <https://GeographicLib.SourceForge.io/C++/doc/GeodSolve.1.html>}. 

40 ''' 

41 # from GeodSolve --help option -f ... lat1 lon1 azi1 lat2 lon2 azi2 s12 a12 m12 M12 M21 S12 

42 _Names_ = (_lat1_, _lon1_, _azi1_, _lat2_, _lon2_, _azi2_, _s12_, _a12_, _m12_, _M12_, _M21_, _S12_) 

43 _Units_ = (_Lat, _Lon, _Azi, _Lat, _Lon, _Azi, _M, _Deg, _Pass, _Pass, _Pass, _M2) 

44 

45 

46class _GeodesicSolveBase(_SolveBase): 

47 '''(INTERNAL) Base class for L{GeodesicSolve} and L{GeodesicLineSolve}. 

48 ''' 

49 _Error = GeodesicError 

50 _Names_Direct = \ 

51 _Names_Inverse = GeodSolve12Tuple._Names_ 

52 _Solve_name = 'GeodSolve' 

53 _Solve_path = _getenv(_PYGEODESY_GEODSOLVE_, _PYGEODESY_GEODSOLVE_) 

54 

55 @Property_RO 

56 def _b_option(self): 

57 return ('-b',) if self.reverse2 else () 

58 

59 @Property_RO 

60 def _cmdBasic(self): 

61 '''(INTERNAL) Get the basic C{GeodSolve} cmd (C{tuple}). 

62 ''' 

63 return (self.GeodSolve,) + self._b_option \ 

64 + self._e_option \ 

65 + self._E_option \ 

66 + self._p_option \ 

67 + self._u_option + ('-f',) 

68 

69 @Property_RO 

70 def _E_option(self): 

71 return ('-E',) if self.Exact else () 

72 

73 @Property 

74 def GeodSolve(self): 

75 '''Get the U{GeodSolve<https://GeographicLib.SourceForge.io/C++/doc/GeodSolve.1.html>} 

76 executable (C{filename}). 

77 ''' 

78 return self._Solve_path 

79 

80 @GeodSolve.setter # PYCHOK setter! 

81 def GeodSolve(self, path): 

82 '''Set the U{GeodSolve<https://GeographicLib.SourceForge.io/C++/doc/GeodSolve.1.html>} 

83 executable (C{filename}), the (fully qualified) path to the C{GeodSolve} executable. 

84 

85 @raise GeodesicError: Invalid B{C{path}}, B{C{path}} doesn't exist or 

86 isn't the C{GeodSolve} executable. 

87 ''' 

88 self._setSolve(path) 

89 

90 def toStr(self, **prec_sep): # PYCHOK signature 

91 '''Return this C{GeodesicSolve} as string. 

92 

93 @kwarg prec_sep: Keyword argumens C{B{prec}=6} and C{B{sep}=', '} 

94 for the C{float} C{prec}ision, number of decimal digits 

95 (0..9) and the C{sep}arator string to join. Trailing 

96 zero decimals are stripped for B{C{prec}} values of 

97 1 and above, but kept for negative B{C{prec}} values. 

98 

99 @return: GeodesicSolve items (C{str}). 

100 ''' 

101 return _SolveBase._toStr(self, GeodSolve=self.GeodSolve, **prec_sep) 

102 

103 @Property_RO 

104 def _u_option(self): 

105 return ('-u',) if self.unroll else () 

106 

107 

108class GeodesicSolve(_GeodesicSolveBase): 

109 '''Wrapper to invoke I{Karney}'s U{GeodSolve<https://GeographicLib.SourceForge.io/C++/doc/GeodSolve.1.html>} 

110 as an C{Exact} version of I{Karney}'s Python class U{Geodesic<https://GeographicLib.SourceForge.io/C++/doc/ 

111 python/code.html#geographiclib.geodesic.Geodesic>}. 

112 

113 @note: Use property C{GeodSolve} or env variable C{PYGEODESY_GEODSOLVE} to specify the (fully 

114 qualified) path to the C{GeodSolve} executable. 

115 

116 @note: This C{geodesic} is intended I{for testing purposes only}, it invokes the C{GeodSolve} 

117 executable for I{every} method call. 

118 ''' 

119 

120 def Area(self, polyline=False, name=NN): 

121 '''Set up a L{GeodesicAreaExact} to compute area and 

122 perimeter of a polygon. 

123 

124 @kwarg polyline: If C{True} perimeter only, otherwise 

125 area and perimeter (C{bool}). 

126 @kwarg name: Optional name (C{str}). 

127 

128 @return: A L{GeodesicAreaExact} instance. 

129 

130 @note: The B{C{debug}} setting is passed as C{verbose} 

131 to the returned L{GeodesicAreaExact} instance. 

132 ''' 

133 gaX = _MODS.geodesicx.GeodesicAreaExact(self, polyline=polyline, 

134 name=name or self.name) 

135 if self.verbose or self.debug: # PYCHOK no cover 

136 gaX.verbose = True 

137 return gaX 

138 

139 Polygon = Area # for C{geographiclib} compatibility 

140 

141 def Direct3(self, lat1, lon1, azi1, s12): # PYCHOK outmask 

142 '''Return the destination lat, lon and reverse azimuth 

143 (final bearing) in C{degrees}. 

144 

145 @return: L{Destination3Tuple}C{(lat, lon, final)}. 

146 ''' 

147 r = self._GDictDirect(lat1, lon1, azi1, False, s12, floats=False) 

148 return Destination3Tuple(float(r.lat2), float(r.lon2), wrap360(r.azi2), 

149 iteration=r._iteration) 

150 

151 def Inverse3(self, lat1, lon1, lat2, lon2): # PYCHOK outmask 

152 '''Return the distance in C{meter} and the forward and 

153 reverse azimuths (initial and final bearing) in C{degrees}. 

154 

155 @return: L{Distance3Tuple}C{(distance, initial, final)}. 

156 ''' 

157 r = self._GDictInverse(lat1, lon1, lat2, lon2, floats=False) 

158 return Distance3Tuple(float(r.s12), wrap360(r.azi1), wrap360(r.azi2), 

159 iteration=r._iteration) 

160 

161 def Line(self, lat1, lon1, azi1, caps=Caps.ALL): 

162 '''Set up a L{GeodesicLineSolve} to compute several points 

163 on a single geodesic. 

164 

165 @arg lat1: Latitude of the first point (C{degrees}). 

166 @arg lon1: Longitude of the first point (C{degrees}). 

167 @arg azi1: Azimuth at the first point (compass C{degrees}). 

168 @kwarg caps: Bit-or'ed combination of L{Caps} values specifying 

169 the capabilities the L{GeodesicLineSolve} instance 

170 should possess, always C{Caps.ALL}. 

171 

172 @return: A L{GeodesicLineSolve} instance. 

173 

174 @note: If the point is at a pole, the azimuth is defined by keeping 

175 B{C{lon1}} fixed, writing C{B{lat1} = ±(90 − ε)}, and taking 

176 the limit C{ε → 0+}. 

177 

178 @see: C++ U{GeodesicExact.Line 

179 <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1GeodesicExact.html>} 

180 and Python U{Geodesic.Line<https://GeographicLib.SourceForge.io/Python/doc/code.html>}. 

181 ''' 

182 return GeodesicLineSolve(self, lat1, lon1, azi1, caps=caps, name=self.name) 

183 

184 

185class GeodesicLineSolve(_GeodesicSolveBase, _SolveLineBase): 

186 '''Wrapper to invoke I{Karney}'s U{GeodSolve<https://GeographicLib.SourceForge.io/C++/doc/GeodSolve.1.html>} 

187 as an C{Exact} version of I{Karney}'s Python class U{GeodesicLine<https://GeographicLib.SourceForge.io/C++/doc/ 

188 python/code.html#geographiclib.geodesicline.GeodesicLine>}. 

189 

190 @note: Use property C{GeodSolve} or env variable C{PYGEODESY_GEODSOLVE} to specify the (fully 

191 qualified) path to the C{GeodSolve} executable. 

192 

193 @note: This C{geodesic} is intended I{for testing purposes only}, it invokes the C{GeodSolve} 

194 executable for I{every} method call. 

195 ''' 

196 

197 def __init__(self, geodesic, lat1, lon1, azi1, caps=Caps.ALL, name=NN): 

198 '''New L{GeodesicLineSolve} instance, allowing points to be found along 

199 a geodesic starting at C{(B{lat1}, B{lon1})} with azimuth B{C{azi1}}. 

200 

201 @arg geodesic: The geodesic to use (L{GeodesicSolve}). 

202 @arg lat1: Latitude of the first point (C{degrees}). 

203 @arg lon1: Longitude of the first point (C{degrees}). 

204 @arg azi1: Azimuth at the first points (compass C{degrees}). 

205 @kwarg caps: Bit-or'ed combination of L{Caps} values specifying 

206 the capabilities the L{GeodesicLineSolve} instance 

207 should possess, always C{Caps.ALL}. Use C{Caps.LINE_OFF} 

208 if updates to the B{C{geodesic}} should I{not} be 

209 reflected in this L{GeodesicLineSolve} instance. 

210 @kwarg name: Optional name (C{str}). 

211 

212 @raise GeodesicError: Invalid path for the C{GeodSolve} executable or 

213 or isn't the C{GeodSolve} executable, see 

214 property C{geodesic.GeodSolve}. 

215 

216 @raise TypeError: Invalid B{C{geodesic}}. 

217 ''' 

218 _xinstanceof(GeodesicSolve, geodesic=geodesic) 

219 if (caps & Caps.LINE_OFF): # copy to avoid updates 

220 geodesic = geodesic.copy(deep=False, name=NN(_UNDER_, geodesic.name)) 

221 _SolveLineBase.__init__(self, geodesic, lat1, lon1, caps, name, azi1=azi1) 

222 try: 

223 self.GeodSolve = geodesic.GeodSolve # geodesic or copy of geodesic 

224 except GeodesicError: 

225 pass 

226 

227 def ArcPosition(self, a12, outmask=_UNUSED_): # PYCHOK unused 

228 '''Find the position on the line given B{C{a12}}. 

229 

230 @arg a12: Spherical arc length from the first point to the 

231 second point (C{degrees}). 

232 

233 @return: A C{GDict} with 12 items C{lat1, lon1, azi1, lat2, lon2, 

234 azi2, m12, a12, s12, M12, M21, S12}. 

235 ''' 

236 return self._GDictInvoke(self._cmdArc, True, self._Names_Direct, a12) 

237 

238 @Property_RO 

239 def azi1(self): 

240 '''Get the azimuth at the first point (compass C{degrees}). 

241 ''' 

242 return self._lla1.azi1 

243 

244 azi12 = azi1 # like RhumbLineSolve 

245 

246 @Property_RO 

247 def azi1_sincos2(self): 

248 '''Get the sine and cosine of the first point's azimuth (2-tuple C{(sin, cos)}). 

249 ''' 

250 return _sincos2d(self.azi1) 

251 

252 azi12_sincos2 = azi1_sincos2 

253 

254 @Property_RO 

255 def _cmdArc(self): 

256 '''(INTERNAL) Get the C{GeodSolve} I{-a -L} cmd (C{tuple}). 

257 ''' 

258 return self._cmdDistance + ('-a',) 

259 

260 def Position(self, s12, outmask=_UNUSED_): # PYCHOK unused 

261 '''Find the position on the line given B{C{s12}}. 

262 

263 @arg s12: Distance from the first point to the second (C{meter}). 

264 

265 @return: A C{GDict} with 12 items C{lat1, lon1, azi1, lat2, lon2, 

266 azi2, m12, a12, s12, M12, M21, S12}, possibly C{a12=NAN}. 

267 ''' 

268 return self._GDictInvoke(self._cmdDistance, True, self._Names_Direct, s12) 

269 

270 def toStr(self, **prec_sep): # PYCHOK signature 

271 '''Return this C{GeodesicLineSolve} as string. 

272 

273 @kwarg prec_sep: Keyword argumens C{B{prec}=6} and C{B{sep}=', '} 

274 for the C{float} C{prec}ision, number of decimal digits 

275 (0..9) and the C{sep}arator string to join. Trailing 

276 zero decimals are stripped for B{C{prec}} values of 

277 1 and above, but kept for negative B{C{prec}} values. 

278 

279 @return: GeodesicLineSolve items (C{str}). 

280 ''' 

281 return _SolveLineBase._toStr(self, azi1=self.azi1, geodesic=self._solve, 

282 GeodSolve=self.GeodSolve, **prec_sep) 

283 

284 

285__all__ += _ALL_DOCS(_GeodesicSolveBase) 

286 

287if __name__ == '__main__': 

288 

289 from sys import argv 

290 

291 gS = GeodesicSolve(name='Test') 

292 gS.verbose = '--verbose' in argv # or '-v' in argv 

293 

294 if gS.GeodSolve in (_PYGEODESY_GEODSOLVE_, None): # not set 

295 gS.GeodSolve = '/opt/local/bin/GeodSolve' # '/opt/local/Cellar/geographiclib/1.51/bin/GeodSolve' # HomeBrew 

296 printf('version: %s', gS.version) 

297 

298 r = gS.Direct(40.6, -73.8, 51, 5.5e6) 

299 printf('Direct: %r', r, nl=1) 

300 printf('Direct3: %r', gS.Direct3(40.6, -73.8, 51, 5.5e6)) 

301 

302 printf('Inverse: %r', gS.Inverse( 40.6, -73.8, 51.6, -0.5), nl=1) 

303 printf('Inverse1: %r', gS.Inverse1(40.6, -73.8, 51.6, -0.5)) 

304 printf('Inverse3: %r', gS.Inverse3(40.6, -73.8, 51.6, -0.5)) 

305 

306 glS = GeodesicLineSolve(gS, 40.6, -73.8, 51, name='LineTest') 

307 p = glS.Position(5.5e6) 

308 printf('Position: %s %r', p == r, p, nl=1) 

309 p = glS.ArcPosition(49.475527) 

310 printf('ArcPosition: %s %r', p == r, p) 

311 

312# % python3 -m pygeodesy.geodsolve 

313 

314# version: /opt/local/bin/GeodSolve: GeographicLib version 1.51 

315 

316# version: /opt/local/bin/GeodSolve: GeographicLib version 1.51 

317 

318# Direct: GDict(M12=0.650911, M21=0.651229, S12=39735075134877.09375, a12=49.475527, azi1=51.0, azi2=107.189397, lat1=40.6, lat2=51.884565, lon1=-73.8, lon2=-1.141173, m12=4844148.703101, s12=5500000.0) 

319# Direct3: Destination3Tuple(lat=51.884565, lon=-1.141173, final=107.189397) 

320 

321# Inverse: GDict(M12=0.64473, M21=0.645046, S12=40041368848742.53125, a12=49.94131, azi1=51.198883, azi2=107.821777, lat1=40.6, lat2=51.6, lon1=-73.8, lon2=-0.5, m12=4877684.602706, s12=5551759.400319) 

322# Inverse1: 49.94131021789904 

323# Inverse3: Distance3Tuple(distance=5551759.400319, initial=51.198883, final=107.821777) 

324 

325# Position: True GDict(M12=0.650911, M21=0.651229, S12=39735075134877.09375, a12=49.475527, azi1=51.0, azi2=107.189397, lat1=40.6, lat2=51.884565, lon1=-73.8, lon2=-1.141173, m12=4844148.703101, s12=5500000.0) 

326# ArcPosition: False GDict(M12=0.650911, M21=0.651229, S12=39735074737272.734375, a12=49.475527, azi1=51.0, azi2=107.189397, lat1=40.6, lat2=51.884565, lon1=-73.8, lon2=-1.141174, m12=4844148.669561, s12=5499999.948497) 

327 

328 

329# % python3 -m pygeodesy.geodsolve --verbose 

330 

331# GeodesicSolve 'Test' 1: /opt/local/bin/GeodSolve --version (invoke) 

332# GeodesicSolve 'Test' 1: /opt/local/bin/GeodSolve: GeographicLib version 1.51 (0) 

333# version: /opt/local/bin/GeodSolve: GeographicLib version 1.51 

334# GeodesicSolve 'Test' 2: /opt/local/bin/GeodSolve -E -p 10 -f \ 40.600000000000001 -73.799999999999997 51.0 5500000.0 (Direct) 

335# GeodesicSolve 'Test' 2: lat1=40.600000000000001, lon1=-73.799999999999997, azi1=51.0, lat2=51.884564505606761, lon2=-1.141172861200829, azi2=107.189397162605886, s12=5500000.0, a12=49.475527463251467, m12=4844148.703101486, M12=0.65091056699808603, M21=0.65122865892196558, S12=39735075134877.094 (0) 

336 

337# Direct: GDict(M12=0.650911, M21=0.651229, S12=39735075134877.09375, a12=49.475527, azi1=51.0, azi2=107.189397, lat1=40.6, lat2=51.884565, lon1=-73.8, lon2=-1.141173, m12=4844148.703101, s12=5500000.0) 

338# GeodesicSolve 'Test' 3: /opt/local/bin/GeodSolve -E -p 10 -f \ 40.600000000000001 -73.799999999999997 51.0 5500000.0 (Direct3) 

339# GeodesicSolve 'Test' 3: lat1=40.600000000000001, lon1=-73.799999999999997, azi1=51.0, lat2=51.884564505606761, lon2=-1.141172861200829, azi2=107.189397162605886, s12=5500000.0, a12=49.475527463251467, m12=4844148.703101486, M12=0.65091056699808603, M21=0.65122865892196558, S12=39735075134877.094 (0) 

340# Direct3: Destination3Tuple(lat=51.884565, lon=-1.141173, final=107.189397) 

341# GeodesicSolve 'Test' 4: /opt/local/bin/GeodSolve -E -p 10 -f -i \ 40.600000000000001 -73.799999999999997 51.600000000000001 -0.5 (Inverse) 

342# GeodesicSolve 'Test' 4: lat1=40.600000000000001, lon1=-73.799999999999997, azi1=51.198882845579824, lat2=51.600000000000001, lon2=-0.5, azi2=107.821776735514248, s12=5551759.4003186841, a12=49.941310217899037, m12=4877684.6027061976, M12=0.64472969205948238, M21=0.64504567852134398, S12=40041368848742.531 (0) 

343 

344# Inverse: GDict(M12=0.64473, M21=0.645046, S12=40041368848742.53125, a12=49.94131, azi1=51.198883, azi2=107.821777, lat1=40.6, lat2=51.6, lon1=-73.8, lon2=-0.5, m12=4877684.602706, s12=5551759.400319) 

345# GeodesicSolve 'Test' 5: /opt/local/bin/GeodSolve -E -p 10 -f -i \ 40.600000000000001 -73.799999999999997 51.600000000000001 -0.5 (Inverse1) 

346# GeodesicSolve 'Test' 5: lat1=40.600000000000001, lon1=-73.799999999999997, azi1=51.198882845579824, lat2=51.600000000000001, lon2=-0.5, azi2=107.821776735514248, s12=5551759.4003186841, a12=49.941310217899037, m12=4877684.6027061976, M12=0.64472969205948238, M21=0.64504567852134398, S12=40041368848742.531 (0) 

347# Inverse1: 49.94131021789904 

348# GeodesicSolve 'Test' 6: /opt/local/bin/GeodSolve -E -p 10 -f -i \ 40.600000000000001 -73.799999999999997 51.600000000000001 -0.5 (Inverse3) 

349# GeodesicSolve 'Test' 6: lat1=40.600000000000001, lon1=-73.799999999999997, azi1=51.198882845579824, lat2=51.600000000000001, lon2=-0.5, azi2=107.821776735514248, s12=5551759.4003186841, a12=49.941310217899037, m12=4877684.6027061976, M12=0.64472969205948238, M21=0.64504567852134398, S12=40041368848742.531 (0) 

350# Inverse3: Distance3Tuple(distance=5551759.400319, initial=51.198883, final=107.821777) 

351 

352# Position: True GDict(M12=0.650911, M21=0.651229, S12=39735075134877.09375, a12=49.475527, azi1=51.0, azi2=107.189397, lat1=40.6, lat2=51.884565, lon1=-73.8, lon2=-1.141173, m12=4844148.703101, s12=5500000.0) 

353# ArcPosition: False GDict(M12=0.650911, M21=0.651229, S12=39735074737272.734375, a12=49.475527, azi1=51.0, azi2=107.189397, lat1=40.6, lat2=51.884565, lon1=-73.8, lon2=-1.141174, m12=4844148.669561, s12=5499999.948497) 

354 

355 

356# **) MIT License 

357# 

358# Copyright (C) 2016-2023 -- mrJean1 at Gmail -- All Rights Reserved. 

359# 

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

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

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

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

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

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

366# 

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

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

369# 

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

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

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

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

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

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

376# OTHER DEALINGS IN THE SOFTWARE.