Coverage for pygeodesy/heights.py: 95%

315 statements  

« prev     ^ index     » next       coverage.py v7.6.1, created at 2025-01-06 12:20 -0500

1 

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

3 

4u'''Height interpolations at C{LatLon} points from known C{knots}. 

5 

6Classes L{HeightCubic}, L{HeightIDWcosineLaw}, L{HeightIDWdistanceTo}, 

7L{HeightIDWequirectangular}, L{HeightIDWeuclidean}, L{HeightIDWflatLocal}, 

8L{HeightIDWflatPolar}, L{HeightIDWhaversine}, L{HeightIDWhubeny}, 

9L{HeightIDWkarney}, L{HeightIDWthomas}, L{HeightIDWvincentys}, L{HeightLinear}, 

10L{HeightLSQBiSpline} and L{HeightSmoothBiSpline} to interpolate the height of 

11C{LatLon} locations or separate lat-/longitudes from a set of C{LatLon} points 

12with I{known heights}. 

13 

14Typical usage 

15============= 

16 

171. Get or create a set of C{LatLon} points with I{known heights}, called 

18C{knots}. The C{knots} do not need to be ordered in any particular way. 

19 

20C{>>> ...} 

21 

222. Select one of the C{Height} classes for height interpolation 

23 

24C{>>> from pygeodesy import HeightCubic # or other Height... as HeightXyz} 

25 

263. Instantiate a height interpolator with the C{knots} and use keyword 

27arguments to select different interpolation options 

28 

29C{>>> hinterpolator = HeightXyz(knots, **options)} 

30 

314. Get the interpolated height of C{LatLon} location(s) with 

32 

33C{>>> ll = LatLon(1, 2, ...)} 

34 

35C{>>> h = hinterpolator(ll)} 

36 

37or 

38 

39C{>>> h0, h1, h2, ... = hinterpolator(ll0, ll1, ll2, ...)} 

40 

41or a list, tuple, generator, etc. of C{LatLon}s 

42 

43C{>>> hs = hinterpolator(lls)} 

44 

455. For separate lat- and longitudes invoke the C{height} method as 

46 

47C{>>> h = hinterpolator.height(lat, lon)} 

48 

49or as 2 lists, 2 tuples, etc. 

50 

51C{>>> hs = hinterpolator.height(lats, lons)} 

52 

53or for several positionals use the C{height_} method 

54 

55C{>>> h1, h2, ... = hinterpolator.height_(lat1, lon1, lat2, lon2, ...)} 

56 

57@note: Classes L{HeightCubic} and L{HeightLinear} require package U{numpy 

58 <https://PyPI.org/project/numpy>}, classes L{HeightLSQBiSpline} and 

59 L{HeightSmoothBiSpline} require package U{scipy<https://SciPy.org>}. 

60 Classes L{HeightIDWkarney} and L{HeightIDWdistanceTo} -if used with 

61 L{ellipsoidalKarney.LatLon} points- require I{Karney}'s U{geographiclib 

62 <https://PyPI.org/project/geographiclib>} to be installed. 

63 

64@note: Errors from C{scipy} are raised as L{SciPyError}s. Warnings issued 

65 by C{scipy} can be thrown as L{SciPyWarning} exceptions, provided 

66 Python C{warnings} are filtered accordingly, see L{SciPyWarning}. 

67 

68@see: U{SciPy<https://docs.SciPy.org/doc/scipy/reference/interpolate.html>} 

69 Interpolation. 

70''' 

71# make sure int/int division yields float quotient, see .basics 

72from __future__ import division as _; del _ # PYCHOK semicolon 

73 

74from pygeodesy.basics import isscalar, len2, map1, min2, _xnumpy, _xscipy 

75from pygeodesy.constants import EPS, PI, PI_2, PI2, _0_0, _90_0, _180_0 

76from pygeodesy.datums import _ellipsoidal_datum, _WGS84 

77from pygeodesy.errors import _AssertionError, LenError, PointsError, \ 

78 _SciPyIssue, _xattr, _xkwds, _xkwds_get, _xkwds_item2 

79# from pygeodesy.fmath import fidw # _MODS 

80# from pygeodesy.formy import cosineLaw, cosineLawAL, cosineLawFAL, equirectangular4, \ 

81# euclidean, flatLocal, flatPolar, haversine, thomas, \ 

82# vincentys # _MODS.into 

83# from pygeodesy.internals import _version2 # _MODS 

84from pygeodesy.interns import NN, _COMMASPACE_, _insufficient_, _NOTEQUAL_, \ 

85 _PLUS_, _scipy_, _SPACE_, _STAR_ 

86from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS, _FOR_DOCS 

87from pygeodesy.named import _name2__, _Named 

88from pygeodesy.points import _distanceTo, LatLon_, Fmt, radians, _Wrap 

89from pygeodesy.props import Property_RO, property_RO, property_ROver 

90# from pygeodesy.streprs import Fmt # from .points 

91from pygeodesy.units import _isDegrees, Float_, Int_ 

92# from pygeodesy.utily import _Wrap # from .points 

93 

94# from math import radians # from .points 

95 

96__all__ = _ALL_LAZY.heights 

97__version__ = '24.12.31' 

98 

99_error_ = 'error' 

100_formy = _MODS.into(formy=__name__) 

101_linear_ = 'linear' 

102_llis_ = 'llis' 

103 

104 

105class HeightError(PointsError): 

106 '''Height interpolator C{Height...} or interpolation issue. 

107 ''' 

108 pass 

109 

110 

111def _alist(ais): 

112 # return list of floats, not numpy.float64s 

113 return list(map(float, ais)) 

114 

115 

116def _ascalar(ais): # in .geoids 

117 # return single float, not numpy.float64 

118 ais = list(ais) # np.array, etc. to list 

119 if len(ais) != 1: 

120 n = Fmt.PAREN(len=repr(ais)) 

121 t = _SPACE_(len(ais), _NOTEQUAL_, 1) 

122 raise _AssertionError(n, txt=t) 

123 return float(ais[0]) # remove np.<type> 

124 

125 

126def _atuple(ais): 

127 # return tuple of floats, not numpy.float64s 

128 return tuple(map(float, ais)) 

129 

130 

131def _as_llis2(llis, m=1, Error=HeightError): # in .geoids 

132 # determine return type and convert lli C{LatLon}s to list 

133 if not isinstance(llis, tuple): # llis are *args 

134 n = Fmt.PAREN(type_=_STAR_(NN, _llis_)) 

135 raise _AssertionError(n, txt=repr(llis)) 

136 

137 n = len(llis) 

138 if n == 1: # convert single lli to 1-item list 

139 llis = llis[0] 

140 try: 

141 n, llis = len2(llis) 

142 _as = _alist # return list of interpolated heights 

143 except TypeError: # single lli 

144 n, llis = 1, [llis] 

145 _as = _ascalar # return single interpolated heights 

146 else: # of 0, 2 or more llis 

147 _as = _atuple # return tuple of interpolated heights 

148 

149 if n < m: 

150 raise _InsufficientError(m, Error=Error, llis=n) 

151 return _as, llis 

152 

153 

154def _InsufficientError(need, Error=HeightError, **name_value): # PYCHOK no cover 

155 # create an insufficient Error instance 

156 t = _COMMASPACE_(_insufficient_, str(need) + _PLUS_) 

157 return Error(txt=t, **name_value) 

158 

159 

160def _orderedup(ts, lo=EPS, hi=PI2-EPS): 

161 # clip, order and remove duplicates 

162 return sorted(set(max(lo, min(hi, t)) for t in ts)) # list 

163 

164 

165def _xyhs(wrap=False, _lat=_90_0, _lon=_180_0, **name_lls): 

166 # map (lat, lon, h) to (x, y, h) in radians, offset 

167 # x as 0 <= lon <= PI2 and y as 0 <= lat <= PI 

168 name, lls = _xkwds_item2(name_lls) 

169 _w, _r = _Wrap._latlonop(wrap), radians 

170 try: 

171 for i, ll in enumerate(lls): 

172 y, x = _w(ll.lat, ll.lon) 

173 yield max(_0_0, _r(x + _lon)), \ 

174 max(_0_0, _r(y + _lat)), ll.height 

175 except Exception as x: 

176 i = Fmt.INDEX(name, i) 

177 raise HeightError(i, ll, cause=x) 

178 

179 

180class _HeightNamed(_Named): # in .geoids 

181 '''(INTERNAL) Interpolator base class. 

182 ''' 

183 _datum = _WGS84 # default 

184 _Error = HeightError 

185 _kmin = 2 # min number of knots 

186 

187 _LLiC = LatLon_ # ._height class 

188 _np_sp = None # (numpy, scipy) 

189 _wrap = None # wrap knots and llis 

190 

191 def __call__(self, *llis, **wrap): # PYCHOK no cover 

192 '''Interpolate the height for one or several locations. I{Must be overloaded}. 

193 

194 @arg llis: One or more locations (each C{LatLon}), all positional. 

195 @kwarg wrap: If C{B{wrap}=True} to wrap or I{normalize} all B{C{llis}} 

196 locations (C{bool}), overriding the B{C{knots}}' setting. 

197 

198 @return: A single interpolated height (C{float}) or a list or tuple of 

199 interpolated heights (each C{float}). 

200 

201 @raise HeightError: Insufficient number of B{C{llis}} or an invalid B{C{lli}}. 

202 

203 @raise SciPyError: A C{scipy} issue. 

204 

205 @raise SciPyWarning: A C{scipy} warning as exception. 

206 ''' 

207 self._notOverloaded(callername='__call__', *llis, **wrap) 

208 

209 def _as_lls(self, lats, lons): # in .geoids 

210 LLiC, d = self._LLiC, self.datum 

211 if _isDegrees(lats) and _isDegrees(lons): 

212 llis = LLiC(lats, lons, datum=d) 

213 else: 

214 n, lats = len2(lats) 

215 m, lons = len2(lons) 

216 if n != m: # format a LenError, but raise self._Error 

217 e = LenError(self.__class__, lats=n, lons=m, txt=None) 

218 raise self._Error(str(e)) 

219 llis = [LLiC(*t, datum=d) for t in zip(lats, lons)] 

220 return llis 

221 

222 @property_RO 

223 def datum(self): 

224 '''Get the C{datum} setting or the default (L{Datum}). 

225 ''' 

226 return self._datum 

227 

228 def height(self, lats, lons, **wrap): # PYCHOK no cover 

229 '''I{Must be overloaded}.''' 

230 self._notOverloaded(lats, lons, **wrap) 

231 

232 def height_(self, *latlons, **wrap): 

233 '''Interpolate the height for each M{(latlons[i], latlons[i+1]) pair 

234 for i in range(0, len(latlons), B{2})}. 

235 

236 @arg latlons: Alternating lat-/longitude pairs (each C{degrees}), 

237 all positional. 

238 

239 @see: Method C{height} for further details. 

240 

241 @return: A tuple of interpolated heights (each C{float}). 

242 ''' 

243 lls = self._as_lls(latlons[0::2], latlons[1::2]) 

244 return tuple(self(lls, **wrap)) 

245 

246 @property_RO 

247 def kmin(self): 

248 '''Get the minimum number of knots (C{int}). 

249 ''' 

250 return self._kmin 

251 

252 @property_RO 

253 def wrap(self): 

254 '''Get the C{wrap} setting (C{bool}) or C{None}. 

255 ''' 

256 return self._wrap 

257 

258 

259class _HeightBase(_HeightNamed): # in .geoids 

260 '''(INTERNAL) Interpolator base class. 

261 ''' 

262 _k2interp2d = {-1: _linear_, # in .geoids._GeoidBase.__init__ 

263 -2: _linear_, # for backward compatibility 

264 -3: 'cubic', 

265 -5: 'quintic'} 

266 

267 def _as_xyllis4(self, llis, **wrap): 

268 # convert lli C{LatLon}s to tuples or C{NumPy} arrays of 

269 # C{SciPy} sphericals and determine the return type 

270 atype = self.numpy.array 

271 wrap = _xkwds(wrap, wrap=self._wrap) 

272 _as, llis = _as_llis2(llis) 

273 xis, yis, _ = zip(*_xyhs(llis=llis, **wrap)) # PYCHOK yield 

274 return _as, atype(xis), atype(yis), llis 

275 

276 def _ev(self, *args): # PYCHOK no cover 

277 '''(INTERNAL) I{Must be overloaded}.''' 

278 self._notOverloaded(*args) 

279 

280 def _evalls(self, llis, **wrap): # XXX single arg, not *args 

281 _as, xis, yis, _ = self._as_xyllis4(llis, **wrap) 

282 try: # SciPy .ev signature: y first, then x! 

283 return _as(self._ev(yis, xis)) 

284 except Exception as x: 

285 raise _SciPyIssue(x, self._ev_name) 

286 

287 def _ev2d(self, x, y): # PYCHOK no cover 

288 '''(INTERNAL) I{Must be overloaded}.''' 

289 self._notOverloaded(x, y) 

290 

291 @property_RO 

292 def _ev_name(self): 

293 '''(INTERNAL) Get the name of the C{.ev} method. 

294 ''' 

295 _ev = str(self._ev) 

296 if _scipy_ not in _ev: 

297 _ev = str(self._ev2d) 

298 # '<scipy.interpolate._interpolate.interp2d object at ...> 

299 # '<function _HeightBase._interp2d.<locals>._bisplev at ...> 

300 # '<bound method BivariateSpline.ev of ... object at ...> 

301 _ev = _ev[1:].split(None, 4) 

302 return Fmt.PAREN(_ev['sfb'.index(_ev[0][0])]) 

303 

304 def height(self, lats, lons, **wrap): 

305 '''Interpolate the height for one or several lat-/longitudes. 

306 

307 @arg lats: Latitude or latitudes (each C{degrees}). 

308 @arg lons: Longitude or longitudes (each C{degrees}). 

309 @kwarg wrap: Kewyord argument C{B{wrap}=False} (C{bool}). Use C{True} to 

310 wrap or I{normalize} all B{C{lats}} and B{C{lons}} locationts, 

311 overriding the B{C{knots}}' setting. 

312 

313 @return: A single interpolated height (C{float}) or a list of interpolated 

314 heights (each C{float}). 

315 

316 @raise HeightError: Insufficient or unequal number of B{C{lats}} and B{C{lons}}. 

317 

318 @raise SciPyError: A C{scipy} issue. 

319 

320 @raise SciPyWarning: A C{scipy} warning as exception. 

321 ''' 

322 lls = self._as_lls(lats, lons) # dup of _HeightIDW.height 

323 return self(lls, **wrap) # __call__(ll) or __call__(lls) 

324 

325 def _interp2d(self, xs, ys, hs, kind=-3): 

326 '''Create a C{scipy.interpolate.interp2d} or C{-.bisplrep/-ev} 

327 interpolator before, respectively since C{SciPy} version 1.14. 

328 ''' 

329 try: 

330 spi = self.scipy_interpolate 

331 if self._scipy_version() < (1, 14) and kind in self._k2interp2d: 

332 # SciPy.interpolate.interp2d kind 'linear', 'cubic' or 'quintic' 

333 # DEPRECATED since scipy 1.10, removed altogether in 1.14 

334 self._ev2d = spi.interp2d(xs, ys, hs, kind=self._k2interp2d[kind]) 

335 

336 else: # <https://scipy.GitHub.io/devdocs/tutorial/interpolate/interp_transition_guide.html> 

337 k = self._kxky(abs(kind)) 

338 # spi.RectBivariateSpline needs strictly ordered xs and ys 

339 r = spi.bisplrep(xs, ys, hs.T, kx=k, ky=k) 

340 

341 def _bisplev(x, y): 

342 return spi.bisplev(x, y, r) # .T 

343 

344 self._ev2d = _bisplev 

345 

346 except Exception as x: 

347 raise _SciPyIssue(x, self._ev_name) 

348 

349 def _kxky(self, kind): 

350 return Int_(kind=kind, low=1, high=5, Error=self._Error) 

351 

352 def _np_sp2(self, throwarnings=False): # PYCHOK no cover 

353 '''(INTERNAL) Import C{numpy} and C{scipy}, once. 

354 ''' 

355 # raise SciPyWarnings, but not if 

356 # scipy has already been imported 

357 if throwarnings: # PYCHOK no cover 

358 import sys 

359 if _scipy_ not in sys.modules: 

360 import warnings 

361 warnings.filterwarnings(_error_) 

362 return self.numpy, self.scipy 

363 

364 @property_ROver 

365 def numpy(self): 

366 '''Get the C{numpy} module or C{None}. 

367 ''' 

368 return _xnumpy(self.__class__, 1, 9) # overwrite property_ROver 

369 

370 @property_ROver 

371 def scipy(self): 

372 '''Get the C{scipy} module or C{None}. 

373 ''' 

374 return _xscipy(self.__class__, 1, 2) # overwrite property_ROver 

375 

376 @property_ROver 

377 def scipy_interpolate(self): 

378 '''Get the C{scipy.interpolate} module or C{None}. 

379 ''' 

380 _ = self.scipy 

381 import scipy.interpolate as spi # scipy 1.2.2 

382 return spi # overwrite property_ROver 

383 

384 def _scipy_version(self, **n): 

385 '''Get the C{scipy} version as 2- or 3-tuple C{(major, minor, micro)}. 

386 ''' 

387 return _MODS.internals._version2(self.scipy.version.version, **n) 

388 

389 def _xyhs3(self, knots, wrap=False, **name): 

390 # convert knot C{LatLon}s to tuples or C{NumPy} arrays and C{SciPy} sphericals 

391 xs, ys, hs = zip(*_xyhs(knots=knots, wrap=wrap)) # PYCHOK yield 

392 n = len(hs) 

393 if n < self.kmin: 

394 raise _InsufficientError(self.kmin, knots=n) 

395 if name: 

396 self.name = name 

397 return map1(self.numpy.array, xs, ys, hs) 

398 

399 

400class HeightCubic(_HeightBase): 

401 '''Height interpolator based on C{SciPy} U{interp2d<https://docs.SciPy.org/ 

402 doc/scipy/reference/generated/scipy.interpolate.interp2d.html>} 

403 C{kind='cubic'} or U{bisplrep/-ev<https://docs.SciPy.org/doc/scipy/ 

404 reference/generated/scipy.interpolate.interp2d.html>} C{kx=ky=3}. 

405 ''' 

406 _kind = -3 

407 _kmin = 16 

408 

409 def __init__(self, knots, **name_wrap): 

410 '''New L{HeightCubic} interpolator. 

411 

412 @arg knots: The points with known height (C{LatLon}s). 

413 @kwarg name_wrap: Optional C{B{name}=NN} for this height interpolator (C{str}) 

414 and keyword argument C{b{wrap}=False} to wrap or I{normalize} all 

415 B{C{knots}} and B{C{llis}} locations iff C{True} (C{bool}). 

416 

417 @raise HeightError: Insufficient number of B{C{knots}} or invalid B{C{knot}}. 

418 

419 @raise ImportError: Package C{numpy} or C{scipy} not found or not installed. 

420 

421 @raise SciPyError: A C{scipy} issue. 

422 

423 @raise SciPyWarning: A C{scipy} warning as exception. 

424 ''' 

425 xs_yx_hs = self._xyhs3(knots, **name_wrap) 

426 self._interp2d(*xs_yx_hs, kind=self._kind) 

427 

428 def __call__(self, *llis, **wrap): 

429 '''Interpolate the height for one or several locations. 

430 

431 @see: L{Here<_HeightBase.__call__>} for further details. 

432 ''' 

433 return self._evalls(llis, **wrap) 

434 

435 def _ev(self, yis, xis): # PYCHOK overwritten with .RectBivariateSpline.ev 

436 # to make SciPy .interp2d single (x, y) signature 

437 # match SciPy .ev signature(ys, xs), flipped multiples 

438 return map(self._ev2d, xis, yis) 

439 

440 

441class HeightLinear(HeightCubic): 

442 '''Height interpolator based on C{SciPy} U{interp2d<https://docs.SciPy.org/ 

443 doc/scipy/reference/generated/scipy.interpolate.interp2d.html>} 

444 C{kind='linear'} or U{bisplrep/-ev<https://docs.SciPy.org/doc/scipy/ 

445 reference/generated/scipy.interpolate.interp2d.html>} C{kx=ky=1}. 

446 ''' 

447 _kind = -1 

448 _kmin = 2 

449 

450 def __init__(self, knots, **name_wrap): 

451 '''New L{HeightLinear} interpolator. 

452 

453 @see: L{Here<HeightCubic.__init__>} for all details. 

454 ''' 

455 HeightCubic.__init__(self, knots, **name_wrap) 

456 

457 if _FOR_DOCS: 

458 __call__ = HeightCubic.__call__ 

459 height = HeightCubic.height 

460 

461 

462class HeightLSQBiSpline(_HeightBase): 

463 '''Height interpolator using C{SciPy} U{LSQSphereBivariateSpline 

464 <https://docs.SciPy.org/doc/scipy/reference/generated/scipy. 

465 interpolate.LSQSphereBivariateSpline.html>}. 

466 ''' 

467 _kmin = 16 # k = 3, always 

468 

469 def __init__(self, knots, weight=None, low=1e-4, **name_wrap): 

470 '''New L{HeightLSQBiSpline} interpolator. 

471 

472 @arg knots: The points with known height (C{LatLon}s). 

473 @kwarg weight: Optional weight or weights for each B{C{knot}} 

474 (C{scalar} or C{scalar}s). 

475 @kwarg low: Optional lower bound for I{ordered knots} (C{radians}). 

476 @kwarg name_wrap: Optional C{B{name}=NN} for this height interpolator 

477 (C{str}) and keyword argument C{b{wrap}=False} to wrap or 

478 I{normalize} all B{C{knots}} and B{C{llis}} locations iff 

479 C{True} (C{bool}). 

480 

481 @raise HeightError: Insufficient number of B{C{knots}} or an invalid 

482 B{C{knot}}, B{C{weight}} or B{C{eps}}. 

483 

484 @raise LenError: Unequal number of B{C{knots}} and B{C{weight}}s. 

485 

486 @raise ImportError: Package C{numpy} or C{scipy} not found or not 

487 installed. 

488 

489 @raise SciPyError: A C{scipy} issue. 

490 

491 @raise SciPyWarning: A C{scipy} warning as exception. 

492 ''' 

493 np = self.numpy 

494 spi = self.scipy_interpolate 

495 

496 xs, ys, hs = self._xyhs3(knots, **name_wrap) 

497 n = len(hs) 

498 

499 w = weight 

500 if isscalar(w): 

501 w = float(w) 

502 if w <= 0: 

503 raise HeightError(weight=w) 

504 w = (w,) * n 

505 elif w is not None: 

506 m, w = len2(w) 

507 if m != n: 

508 raise LenError(HeightLSQBiSpline, weight=m, knots=n) 

509 m, i = min2(*map(float, w)) 

510 if m <= 0: # PYCHOK no cover 

511 raise HeightError(Fmt.INDEX(weight=i), m) 

512 try: 

513 if not EPS < low < (PI_2 - EPS): # 1e-4 like SciPy example 

514 raise HeightError(low=low) 

515 ps = np.array(_orderedup(xs, low, PI2 - low)) 

516 ts = np.array(_orderedup(ys, low, PI - low)) 

517 self._ev = spi.LSQSphereBivariateSpline(ys, xs, hs, 

518 ts, ps, eps=EPS, w=w).ev 

519 except Exception as x: 

520 raise _SciPyIssue(x, self._ev_name) 

521 

522 def __call__(self, *llis, **wrap): 

523 '''Interpolate the height for one or several locations. 

524 

525 @see: L{Here<_HeightBase.__call__>} for further details. 

526 ''' 

527 return self._evalls(llis, **wrap) 

528 

529 

530class HeightSmoothBiSpline(_HeightBase): 

531 '''Height interpolator using C{SciPy} U{SmoothSphereBivariateSpline 

532 <https://docs.SciPy.org/doc/scipy/reference/generated/scipy. 

533 interpolate.SmoothSphereBivariateSpline.html>}. 

534 ''' 

535 _kmin = 16 # k = 3, always 

536 

537 def __init__(self, knots, s=4, **name_wrap): 

538 '''New L{HeightSmoothBiSpline} interpolator. 

539 

540 @arg knots: The points with known height (C{LatLon}s). 

541 @kwarg s: The spline smoothing factor (C{scalar}), default C{4}. 

542 @kwarg name_wrap: Optional C{B{name}=NN} for this height interpolator 

543 (C{str}) and keyword argument C{b{wrap}=False} to wrap or 

544 I{normalize} all B{C{knots}} and B{C{llis}} locations iff 

545 C{True} (C{bool}). 

546 

547 @raise HeightError: Insufficient number of B{C{knots}} or an invalid 

548 B{C{knot}} or B{C{s}}. 

549 

550 @raise ImportError: Package C{numpy} or C{scipy} not found or not 

551 installed. 

552 

553 @raise SciPyError: A C{scipy} issue. 

554 

555 @raise SciPyWarning: A C{scipy} warning as exception. 

556 ''' 

557 spi = self.scipy_interpolate 

558 

559 s = Float_(smoothing=s, Error=HeightError, low=4) 

560 

561 xs, ys, hs = self._xyhs3(knots, **name_wrap) 

562 try: 

563 self._ev = spi.SmoothSphereBivariateSpline(ys, xs, hs, 

564 eps=EPS, s=s).ev 

565 except Exception as x: 

566 raise _SciPyIssue(x, self._ev_name) 

567 

568 def __call__(self, *llis, **wrap): 

569 '''Interpolate the height for one or several locations. 

570 

571 @see: L{Here<_HeightBase.__call__>} for further details. 

572 ''' 

573 return self._evalls(llis, **wrap) 

574 

575 

576class _HeightIDW(_HeightNamed): 

577 '''(INTERNAL) Base class for U{Inverse Distance Weighting 

578 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) height 

579 interpolators. 

580 

581 @see: U{IDW<https://www.Geo.FU-Berlin.DE/en/v/soga/Geodata-analysis/ 

582 geostatistics/Inverse-Distance-Weighting/index.html>}, 

583 U{SHEPARD_INTERP_2D<https://People.SC.FSU.edu/~jburkardt/c_src/ 

584 shepard_interp_2d/shepard_interp_2d.html>} and other C{_HeightIDW*} 

585 classes. 

586 ''' 

587 _beta = 0 # fidw inverse power 

588 _func = None # formy function 

589 _knots = () # knots list or tuple 

590 _kwds = {} # func_ options 

591 

592 def __init__(self, knots, beta=2, **name__kwds): 

593 '''New C{_HeightIDW*} interpolator. 

594 

595 @arg knots: The points with known height (C{LatLon}s). 

596 @kwarg beta: Inverse distance power (C{int} 1, 2, or 3). 

597 @kwarg name__kwds: Optional C{B{name}=NN} for this height interpolator 

598 (C{str}) and any keyword arguments for the distance function, 

599 retrievable with property C{kwds}. 

600 

601 @raise HeightError: Insufficient number of B{C{knots}} or an invalid 

602 B{C{knot}} or B{C{beta}}. 

603 ''' 

604 name, kwds = _name2__(**name__kwds) 

605 if name: 

606 self.name = name 

607 

608 n, self._knots = len2(knots) 

609 if n < self.kmin: 

610 raise _InsufficientError(self.kmin, knots=n) 

611 self.beta = beta 

612 self._kwds = kwds or {} 

613 

614 def __call__(self, *llis, **wrap): 

615 '''Interpolate the height for one or several locations. 

616 

617 @arg llis: One or more locations (C{LatLon}s), all positional. 

618 @kwarg wrap: If C{True}, wrap or I{normalize} all B{C{llis}} 

619 locations (C{bool}). 

620 

621 @return: A single interpolated height (C{float}) or a list 

622 or tuple of interpolated heights (C{float}s). 

623 

624 @raise HeightError: Insufficient number of B{C{llis}}, an 

625 invalid B{C{lli}} or L{pygeodesy.fidw} 

626 issue. 

627 ''' 

628 def _xy2(wrap=False): 

629 _w = _Wrap._latlonop(wrap) 

630 try: # like _xyhs above, but degrees 

631 for i, ll in enumerate(llis): 

632 yield _w(ll.lon, ll.lat) 

633 except Exception as x: 

634 i = Fmt.INDEX(llis=i) 

635 raise HeightError(i, ll, cause=x) 

636 

637 _as, llis = _as_llis2(llis) 

638 return _as(map(self._hIDW, *zip(*_xy2(**wrap)))) 

639 

640 @property_RO 

641 def adjust(self): 

642 '''Get the C{adjust} setting (C{bool}) or C{None}. 

643 ''' 

644 return _xkwds_get(self._kwds, adjust=None) 

645 

646 @property 

647 def beta(self): 

648 '''Get the inverse distance power (C{int}). 

649 ''' 

650 return self._beta 

651 

652 @beta.setter # PYCHOK setter! 

653 def beta(self, beta): 

654 '''Set the inverse distance power (C{int} 1, 2, or 3). 

655 

656 @raise HeightError: Invalid B{C{beta}}. 

657 ''' 

658 self._beta = Int_(beta=beta, Error=HeightError, low=1, high=3) 

659 

660 @property_RO 

661 def datum(self): 

662 '''Get the C{datum} setting or the default (L{Datum}). 

663 ''' 

664 return _xkwds_get(self._kwds, datum=self._datum) 

665 

666 def _datum_setter(self, datum): 

667 '''(INTERNAL) Set the default C{datum}. 

668 ''' 

669 d = datum or _xattr(self._knots[0], datum=None) 

670 if d and d is not self._datum: 

671 self._datum = _ellipsoidal_datum(d, name=self.name) 

672 

673 def _distances(self, x, y): 

674 '''(INTERNAL) Yield distances to C{(x, y)}. 

675 ''' 

676 _f, kwds = self._func, self._kwds 

677 if not callable(_f): # PYCHOK no cover 

678 self._notOverloaded(distance_function=_f) 

679 try: 

680 for i, k in enumerate(self._knots): 

681 yield _f(y, x, k.lat, k.lon, **kwds) 

682 except Exception as x: 

683 i = Fmt.INDEX(knots=i) 

684 raise HeightError(i, k, cause=x) 

685 

686 def _distancesTo(self, _To): 

687 '''(INTERNAL) Yield distances C{_To}. 

688 ''' 

689 try: 

690 for i, k in enumerate(self._knots): 

691 yield _To(k) 

692 except Exception as x: 

693 i = Fmt.INDEX(knots=i) 

694 raise HeightError(i, k, cause=x) 

695 

696 def height(self, lats, lons, **wrap): 

697 '''Interpolate the height for one or several lat-/longitudes. 

698 

699 @arg lats: Latitude or latitudes (each C{degrees}). 

700 @arg lons: Longitude or longitudes (each C{degrees}). 

701 @kwarg wrap: Keyword argument C{B{wrap}=False} (C{bool}). Use 

702 C{B{wrap}=True} to wrap or I{normalize} all B{C{lats}} 

703 and B{C{lons}}. 

704 

705 @return: A single interpolated height (C{float}) or a list of 

706 interpolated heights (each C{float}). 

707 

708 @raise HeightError: Insufficient or unequal number of B{C{lats}} 

709 and B{C{lons}} or a L{pygeodesy.fidw} issue. 

710 ''' 

711 lls = self._as_lls(lats, lons) # dup of _HeightBase.height 

712 return self(lls, **wrap) # __call__(ll) or __call__(lls) 

713 

714 @Property_RO 

715 def _heights(self): 

716 '''(INTERNAL) Get the knots' heights. 

717 ''' 

718 return tuple(_xattr(k, height=0) for k in self.knots) 

719 

720 def _hIDW(self, x, y): 

721 '''(INTERNAL) Return the IDW-interpolated height at 

722 location (x, y), both C{degrees} or C{radians}. 

723 ''' 

724 ds, hs = self._distances(x, y), self._heights 

725 try: 

726 return _MODS.fmath.fidw(hs, ds, beta=self.beta) 

727 except (TypeError, ValueError) as e: 

728 raise HeightError(x=x, y=y, cause=e) 

729 

730 @property_RO 

731 def hypot(self): 

732 '''Get the C{hypot} setting (C{callable}) or C{None}. 

733 ''' 

734 return _xkwds_get(self._kwds, hypot=None) 

735 

736 @property_RO 

737 def knots(self): 

738 '''Get the B{C{knots}} (C{list} or C{tuple}). 

739 ''' 

740 return self._knots 

741 

742 @property_RO 

743 def kwds(self): 

744 '''Get the optional keyword arguments (C{dict}). 

745 ''' 

746 return self._kwds 

747 

748 @property_RO 

749 def limit(self): 

750 '''Get the C{limit} setting (C{degrees}) or C{None}. 

751 ''' 

752 return _xkwds_get(self._kwds, limit=None) 

753 

754 @property_RO 

755 def radius(self): 

756 '''Get the C{radius} setting (C{bool}) or C{None}. 

757 ''' 

758 return _xkwds_get(self._kwds, radius=None) 

759 

760 @property_RO 

761 def scaled(self): 

762 '''Get the C{scaled} setting (C{bool}) or C{None}. 

763 ''' 

764 return _xkwds_get(self._kwds, scaled=None) 

765 

766 @property_RO 

767 def wrap(self): 

768 '''Get the C{wrap} setting or the default (C{bool}) or C{None}. 

769 ''' 

770 return _xkwds_get(self._kwds, wrap=self._wrap) 

771 

772 

773class HeightIDWcosineLaw(_HeightIDW): 

774 '''Height interpolator using U{Inverse Distance Weighting 

775 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

776 and function L{pygeodesy.cosineLaw}. 

777 

778 @note: See note at function L{pygeodesy.vincentys_}. 

779 ''' 

780 def __init__(self, knots, beta=2, **name__corr_earth_datum_radius_wrap): 

781 '''New L{HeightIDWcosineLaw} interpolator. 

782 

783 @kwarg name__corr_earth_datum_radius_wrap: Optional C{B{name}=NN} 

784 for this height interpolator (C{str}) and any keyword 

785 arguments for function L{pygeodesy.cosineLaw}. 

786 

787 @see: L{Here<_HeightIDW.__init__>} for further details. 

788 ''' 

789 _HeightIDW.__init__(self, knots, beta=beta, **name__corr_earth_datum_radius_wrap) 

790 self._func = _formy.cosineLaw 

791 

792 if _FOR_DOCS: 

793 __call__ = _HeightIDW.__call__ 

794 height = _HeightIDW.height 

795 

796 

797class HeightIDWdistanceTo(_HeightIDW): 

798 '''Height interpolator using U{Inverse Distance Weighting 

799 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

800 and the points' C{LatLon.distanceTo} method. 

801 ''' 

802 def __init__(self, knots, beta=2, **name__distanceTo_kwds): 

803 '''New L{HeightIDWdistanceTo} interpolator. 

804 

805 @kwarg name__distanceTo_kwds: Optional C{B{name}=NN} for this 

806 height interpolator (C{str}) and keyword arguments 

807 for B{C{knots}}' method C{LatLon.distanceTo}. 

808 

809 @see: L{Here<_HeightIDW.__init__>} for further details. 

810 

811 @note: All B{C{points}} I{must} be instances of the same 

812 ellipsoidal or spherical C{LatLon} class, I{not 

813 checked}. 

814 ''' 

815 _HeightIDW.__init__(self, knots, beta=beta, **name__distanceTo_kwds) 

816 ks0 = _distanceTo(HeightError, knots=self._knots)[0] 

817 # use knots[0] class and datum to create compatible points 

818 # in ._as_lls instead of class LatLon_ and datum None 

819 self._datum = ks0.datum 

820 self._LLiC = ks0.classof # type(ks0) 

821 

822 def _distances(self, x, y): 

823 '''(INTERNAL) Yield distances to C{(x, y)}. 

824 ''' 

825 kwds, ll = self._kwds, self._LLiC(y, x) 

826 

827 def _To(k): 

828 return k.distanceTo(ll, **kwds) 

829 

830 return self._distancesTo(_To) 

831 

832 if _FOR_DOCS: 

833 __call__ = _HeightIDW.__call__ 

834 height = _HeightIDW.height 

835 

836 

837class HeightIDWequirectangular(_HeightIDW): 

838 '''Height interpolator using U{Inverse Distance Weighting 

839 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

840 and function L{pygeodesy.equirectangular4}. 

841 ''' 

842 def __init__(self, knots, beta=2, **name__adjust_limit_wrap): # XXX beta=1 

843 '''New L{HeightIDWequirectangular} interpolator. 

844 

845 @kwarg name__adjust_limit_wrap: Optional C{B{name}=NN} for this 

846 height interpolator (C{str}) and keyword arguments 

847 for function L{pygeodesy.equirectangular4}. 

848 

849 @see: L{Here<_HeightIDW.__init__>} for further details. 

850 ''' 

851 _HeightIDW.__init__(self, knots, beta=beta, **name__adjust_limit_wrap) 

852 

853 def _distances(self, x, y): 

854 '''(INTERNAL) Yield distances to C{(x, y)}. 

855 ''' 

856 _f, kwds = _formy.equirectangular4, self._kwds 

857 

858 def _To(k): 

859 return _f(y, x, k.lat, k.lon, **kwds).distance2 

860 

861 return self._distancesTo(_To) 

862 

863 if _FOR_DOCS: 

864 __call__ = _HeightIDW.__call__ 

865 height = _HeightIDW.height 

866 

867 

868class HeightIDWeuclidean(_HeightIDW): 

869 '''Height interpolator using U{Inverse Distance Weighting 

870 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

871 and function L{pygeodesy.euclidean_}. 

872 ''' 

873 def __init__(self, knots, beta=2, **name__adjust_radius_wrap): 

874 '''New L{HeightIDWeuclidean} interpolator. 

875 

876 @kwarg name__adjust_radius_wrap: Optional C{B{name}=NN} for this 

877 height interpolator (C{str}) and keyword arguments 

878 for function function L{pygeodesy.euclidean}. 

879 

880 @see: L{Here<_HeightIDW.__init__>} for further details. 

881 ''' 

882 _HeightIDW.__init__(self, knots, beta=beta, **name__adjust_radius_wrap) 

883 self._func = _formy.euclidean 

884 

885 if _FOR_DOCS: 

886 __call__ = _HeightIDW.__call__ 

887 height = _HeightIDW.height 

888 

889 

890class HeightIDWexact(_HeightIDW): 

891 '''Height interpolator using U{Inverse Distance Weighting 

892 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

893 and method L{GeodesicExact.Inverse}. 

894 ''' 

895 def __init__(self, knots, beta=2, datum=None, **name__wrap): 

896 '''New L{HeightIDWexact} interpolator. 

897 

898 @kwarg datum: Datum to override the default C{Datums.WGS84} and 

899 first B{C{knots}}' datum (L{Datum}, L{Ellipsoid}, 

900 L{Ellipsoid2} or L{a_f2Tuple}). 

901 @kwarg name__wrap: Optional C{B{name}=NN} for this height interpolator 

902 (C{str}) and a keyword argument for method C{Inverse1} of 

903 class L{geodesicx.GeodesicExact}. 

904 

905 @raise TypeError: Invalid B{C{datum}}. 

906 

907 @see: L{Here<_HeightIDW.__init__>} for further details. 

908 ''' 

909 _HeightIDW.__init__(self, knots, beta=beta, **name__wrap) 

910 self._datum_setter(datum) 

911 self._func = self.datum.ellipsoid.geodesicx.Inverse1 

912 

913 if _FOR_DOCS: 

914 __call__ = _HeightIDW.__call__ 

915 height = _HeightIDW.height 

916 

917 

918class HeightIDWflatLocal(_HeightIDW): 

919 '''Height interpolator using U{Inverse Distance Weighting 

920 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) and 

921 the function L{pygeodesy.flatLocal_}/L{pygeodesy.hubeny_}. 

922 ''' 

923 def __init__(self, knots, beta=2, **name__datum_hypot_scaled_wrap): 

924 '''New L{HeightIDWflatLocal}/L{HeightIDWhubeny} interpolator. 

925 

926 @kwarg name__datum_hypot_scaled_wrap: Optional C{B{name}=NN} 

927 for this height interpolator (C{str}) and any 

928 keyword arguments for L{pygeodesy.flatLocal}. 

929 

930 @see: L{HeightIDW<_HeightIDW.__init__>} for further details. 

931 ''' 

932 _HeightIDW.__init__(self, knots, beta=beta, 

933 **name__datum_hypot_scaled_wrap) 

934 self._func = _formy.flatLocal 

935 

936 if _FOR_DOCS: 

937 __call__ = _HeightIDW.__call__ 

938 height = _HeightIDW.height 

939 

940 

941class HeightIDWflatPolar(_HeightIDW): 

942 '''Height interpolator using U{Inverse Distance Weighting 

943 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

944 and function L{pygeodesy.flatPolar_}. 

945 ''' 

946 def __init__(self, knots, beta=2, **name__radius_wrap): 

947 '''New L{HeightIDWflatPolar} interpolator. 

948 

949 @kwarg name__radius_wrap: Optional C{B{name}=NN} for this 

950 height interpolator (C{str}) and any keyword 

951 arguments for function L{pygeodesy.flatPolar}. 

952 

953 @see: L{Here<_HeightIDW.__init__>} for further details. 

954 ''' 

955 _HeightIDW.__init__(self, knots, beta=beta, **name__radius_wrap) 

956 self._func = _formy.flatPolar 

957 

958 if _FOR_DOCS: 

959 __call__ = _HeightIDW.__call__ 

960 height = _HeightIDW.height 

961 

962 

963class HeightIDWhaversine(_HeightIDW): 

964 '''Height interpolator using U{Inverse Distance Weighting 

965 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

966 and function L{pygeodesy.haversine_}. 

967 

968 @note: See note at function L{pygeodesy.vincentys_}. 

969 ''' 

970 def __init__(self, knots, beta=2, **name__radius_wrap): 

971 '''New L{HeightIDWhaversine} interpolator. 

972 

973 @kwarg name__radius_wrap: Optional C{B{name}=NN} for this 

974 height interpolator (C{str}) and any keyword 

975 arguments for function L{pygeodesy.haversine}. 

976 

977 @see: L{Here<_HeightIDW.__init__>} for further details. 

978 ''' 

979 _HeightIDW.__init__(self, knots, beta=beta, **name__radius_wrap) 

980 self._func = _formy.haversine 

981 

982 if _FOR_DOCS: 

983 __call__ = _HeightIDW.__call__ 

984 height = _HeightIDW.height 

985 

986 

987class HeightIDWhubeny(HeightIDWflatLocal): # for Karl Hubeny 

988 if _FOR_DOCS: 

989 __doc__ = HeightIDWflatLocal.__doc__ 

990 __init__ = HeightIDWflatLocal.__init__ 

991 __call__ = HeightIDWflatLocal.__call__ 

992 height = HeightIDWflatLocal.height 

993 

994 

995class HeightIDWkarney(_HeightIDW): 

996 '''Height interpolator using U{Inverse Distance Weighting 

997 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) and 

998 I{Karney}'s U{geographiclib<https://PyPI.org/project/geographiclib>} 

999 method U{geodesic.Geodesic.Inverse<https://GeographicLib.SourceForge.io/ 

1000 Python/doc/code.html#geographiclib.geodesic.Geodesic.Inverse>}. 

1001 ''' 

1002 def __init__(self, knots, beta=2, datum=None, **name__wrap): 

1003 '''New L{HeightIDWkarney} interpolator. 

1004 

1005 @kwarg datum: Datum to override the default C{Datums.WGS84} and 

1006 first B{C{knots}}' datum (L{Datum}, L{Ellipsoid}, 

1007 L{Ellipsoid2} or L{a_f2Tuple}). 

1008 @kwarg name__wrap: Optional C{B{name}=NN} for this height interpolator 

1009 (C{str}) and a keyword argument for method C{Inverse1} of 

1010 class L{geodesicw.Geodesic}. 

1011 

1012 @raise ImportError: Package U{geographiclib 

1013 <https://PyPI.org/project/geographiclib>} missing. 

1014 

1015 @raise TypeError: Invalid B{C{datum}}. 

1016 

1017 @see: L{Here<_HeightIDW.__init__>} for further details. 

1018 ''' 

1019 _HeightIDW.__init__(self, knots, beta=beta, **name__wrap) 

1020 self._datum_setter(datum) 

1021 self._func = self.datum.ellipsoid.geodesic.Inverse1 

1022 

1023 if _FOR_DOCS: 

1024 __call__ = _HeightIDW.__call__ 

1025 height = _HeightIDW.height 

1026 

1027 

1028class HeightIDWthomas(_HeightIDW): 

1029 '''Height interpolator using U{Inverse Distance Weighting 

1030 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

1031 and function L{pygeodesy.thomas_}. 

1032 ''' 

1033 def __init__(self, knots, beta=2, **name__datum_wrap): 

1034 '''New L{HeightIDWthomas} interpolator. 

1035 

1036 @kwarg name__datum_wrap: Optional C{B{name}=NN} for this 

1037 height interpolator (C{str}) and any keyword 

1038 arguments for function L{pygeodesy.thomas}. 

1039 

1040 @see: L{Here<_HeightIDW.__init__>} for further details. 

1041 ''' 

1042 _HeightIDW.__init__(self, knots, beta=beta, **name__datum_wrap) 

1043 self._func = _formy.thomas 

1044 

1045 if _FOR_DOCS: 

1046 __call__ = _HeightIDW.__call__ 

1047 height = _HeightIDW.height 

1048 

1049 

1050class HeightIDWvincentys(_HeightIDW): 

1051 '''Height interpolator using U{Inverse Distance Weighting 

1052 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) 

1053 and function L{pygeodesy.vincentys_}. 

1054 

1055 @note: See note at function L{pygeodesy.vincentys_}. 

1056 ''' 

1057 def __init__(self, knots, beta=2, **name__radius_wrap): 

1058 '''New L{HeightIDWvincentys} interpolator. 

1059 

1060 @kwarg name__radius_wrap: Optional C{B{name}=NN} for this 

1061 height interpolator (C{str}) and any keyword 

1062 arguments for function L{pygeodesy.vincentys}. 

1063 

1064 @see: L{Here<_HeightIDW.__init__>} for further details. 

1065 ''' 

1066 _HeightIDW.__init__(self, knots, beta=beta, **name__radius_wrap) 

1067 self._func = _formy.vincentys 

1068 

1069 if _FOR_DOCS: 

1070 __call__ = _HeightIDW.__call__ 

1071 height = _HeightIDW.height 

1072 

1073 

1074__all__ += _ALL_DOCS(_HeightBase, _HeightIDW, _HeightNamed) 

1075 

1076# **) MIT License 

1077# 

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

1079# 

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

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

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

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

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

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

1086# 

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

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

1089# 

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

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

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

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

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

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

1096# OTHER DEALINGS IN THE SOFTWARE.