Coverage for pygeodesy/heights.py: 95%

315 statements  

« prev     ^ index     » next       coverage.py v7.6.1, created at 2025-05-29 12:40 -0400

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 _ # noqa: E702 ; 

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 import formy as _formy # _MODS.into 

81# from pygeodesy.internals import _version2 # _MODS 

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

83 _PLUS_, _scipy_, _SPACE_, _STAR_ 

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

85from pygeodesy.named import _name2__, _Named 

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

87from pygeodesy.props import Property_RO, property_RO, property_ROver 

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

89from pygeodesy.units import _isDegrees, Float_, Int_ 

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

91 

92# from math import radians # from .points 

93 

94__all__ = _ALL_LAZY.heights 

95__version__ = '25.05.26' 

96 

97_error_ = 'error' 

98_formy = _MODS.into(formy=__name__) 

99_linear_ = 'linear' 

100_llis_ = 'llis' 

101 

102 

103class HeightError(PointsError): 

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

105 ''' 

106 pass 

107 

108 

109def _alist(ais): 

110 # return list of floats, not numpy.float64s 

111 return list(map(float, ais)) 

112 

113 

114def _ascalar(ais): # in .geoids 

115 # return single float, not numpy.float64 

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

117 if len(ais) != 1: 

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

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

120 raise _AssertionError(n, txt=t) 

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

122 

123 

124def _atuple(ais): 

125 # return tuple of floats, not numpy.float64s 

126 return tuple(map(float, ais)) 

127 

128 

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

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

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

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

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

134 

135 n = len(llis) 

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

137 llis = llis[0] 

138 try: 

139 n, llis = len2(llis) 

140 _as = _alist # return list of interpolated heights 

141 except TypeError: # single lli 

142 n, llis = 1, [llis] 

143 _as = _ascalar # return single interpolated heights 

144 else: # of 0, 2 or more llis 

145 _as = _atuple # return tuple of interpolated heights 

146 

147 if n < m: 

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

149 return _as, llis 

150 

151 

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

153 # create an insufficient Error instance 

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

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

156 

157 

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

159 # clip, order and remove duplicates 

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

161 

162 

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

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

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

166 name, lls = _xkwds_item2(name_lls) 

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

168 try: 

169 for i, ll in enumerate(lls): 

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

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

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

173 except Exception as x: 

174 i = Fmt.INDEX(name, i) 

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

176 

177 

178class _HeightNamed(_Named): # in .geoids 

179 '''(INTERNAL) Interpolator base class. 

180 ''' 

181 _datum = _WGS84 # default 

182 _Error = HeightError 

183 _kmin = 2 # min number of knots 

184 

185 _LLiC = LatLon_ # ._height class 

186 _np_sp = None # (numpy, scipy) 

187 _wrap = None # wrap knots and llis 

188 

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

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

191 

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

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

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

195 

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

197 interpolated heights (each C{float}). 

198 

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

200 

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

202 

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

204 ''' 

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

206 

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

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

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

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

211 else: 

212 n, lats = len2(lats) 

213 m, lons = len2(lons) 

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

215 e = LenError(type(self), lats=n, lons=m, txt=None) 

216 raise self._Error(str(e)) 

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

218 return llis 

219 

220 @property_RO 

221 def datum(self): 

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

223 ''' 

224 return self._datum 

225 

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

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

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

229 

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

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

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

233 

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

235 all positional. 

236 

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

238 

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

240 ''' 

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

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

243 

244 @property_RO 

245 def kmin(self): 

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

247 ''' 

248 return self._kmin 

249 

250 @property_RO 

251 def wrap(self): 

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

253 ''' 

254 return self._wrap 

255 

256 

257class _HeightBase(_HeightNamed): # in .geoids 

258 '''(INTERNAL) Interpolator base class. 

259 ''' 

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

261 -2: _linear_, # for backward compatibility 

262 -3: 'cubic', 

263 -5: 'quintic'} 

264 

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

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

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

268 atype = self.numpy.array 

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

270 _as, llis = _as_llis2(llis) 

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

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

273 

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

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

276 self._notOverloaded(*args) 

277 

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

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

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

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

282 except Exception as x: 

283 raise _SciPyIssue(x, self._ev_name) 

284 

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

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

287 self._notOverloaded(x, y) 

288 

289 @property_RO 

290 def _ev_name(self): 

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

292 ''' 

293 _ev = str(self._ev) 

294 if _scipy_ not in _ev: 

295 _ev = str(self._ev2d) 

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

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

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

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

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

301 

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

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

304 

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

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

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

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

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

310 

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

312 heights (each C{float}). 

313 

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

315 

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

317 

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

319 ''' 

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

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

322 

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

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

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

326 ''' 

327 try: 

328 spi = self.scipy_interpolate 

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

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

331 # DEPRECATED since scipy 1.10, removed altogether in 1.14 

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

333 

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

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

336 # spi.RectBivariateSpline needs strictly ordered xs and ys 

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

338 

339 def _bisplev(x, y): 

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

341 

342 self._ev2d = _bisplev 

343 

344 except Exception as x: 

345 raise _SciPyIssue(x, self._ev_name) 

346 

347 def _kxky(self, kind): 

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

349 

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

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

352 ''' 

353 # raise SciPyWarnings, but not if 

354 # scipy has already been imported 

355 if throwarnings: # PYCHOK no cover 

356 import sys 

357 if _scipy_ not in sys.modules: 

358 import warnings 

359 warnings.filterwarnings(_error_) 

360 return self.numpy, self.scipy 

361 

362 @property_ROver 

363 def numpy(self): 

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

365 ''' 

366 return _xnumpy(type(self), 1, 9) # overwrite property_ROver 

367 

368 @property_ROver 

369 def scipy(self): 

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

371 ''' 

372 return _xscipy(type(self), 1, 2) # overwrite property_ROver 

373 

374 @property_ROver 

375 def scipy_interpolate(self): 

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

377 ''' 

378 _ = self.scipy 

379 import scipy.interpolate as spi # scipy 1.2.2 

380 return spi # overwrite property_ROver 

381 

382 def _scipy_version(self, **n): 

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

384 ''' 

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

386 

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

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

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

390 n = len(hs) 

391 if n < self.kmin: 

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

393 if name: 

394 self.name = name 

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

396 

397 

398class HeightCubic(_HeightBase): 

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

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

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

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

403 ''' 

404 _kind = -3 

405 _kmin = 16 

406 

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

408 '''New L{HeightCubic} interpolator. 

409 

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

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

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

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

414 

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

416 

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

418 

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

420 

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

422 ''' 

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

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

425 

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

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

428 

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

430 ''' 

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

432 

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

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

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

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

437 

438 

439class HeightLinear(HeightCubic): 

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

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

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

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

444 ''' 

445 _kind = -1 

446 _kmin = 2 

447 

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

449 '''New L{HeightLinear} interpolator. 

450 

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

452 ''' 

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

454 

455 if _FOR_DOCS: 

456 __call__ = HeightCubic.__call__ 

457 height = HeightCubic.height 

458 

459 

460class HeightLSQBiSpline(_HeightBase): 

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

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

463 interpolate.LSQSphereBivariateSpline.html>}. 

464 ''' 

465 _kmin = 16 # k = 3, always 

466 

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

468 '''New L{HeightLSQBiSpline} interpolator. 

469 

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

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

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

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

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

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

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

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

478 

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

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

481 

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

483 

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

485 installed. 

486 

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

488 

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

490 ''' 

491 np = self.numpy 

492 spi = self.scipy_interpolate 

493 

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

495 n = len(hs) 

496 

497 w = weight 

498 if isscalar(w): 

499 w = float(w) 

500 if w <= 0: 

501 raise HeightError(weight=w) 

502 w = (w,) * n 

503 elif w is not None: 

504 m, w = len2(w) 

505 if m != n: 

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

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

508 if m <= 0: # PYCHOK no cover 

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

510 try: 

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

512 raise HeightError(low=low) 

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

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

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

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

517 except Exception as x: 

518 raise _SciPyIssue(x, self._ev_name) 

519 

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

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

522 

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

524 ''' 

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

526 

527 

528class HeightSmoothBiSpline(_HeightBase): 

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

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

531 interpolate.SmoothSphereBivariateSpline.html>}. 

532 ''' 

533 _kmin = 16 # k = 3, always 

534 

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

536 '''New L{HeightSmoothBiSpline} interpolator. 

537 

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

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

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

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

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

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

544 

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

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

547 

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

549 installed. 

550 

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

552 

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

554 ''' 

555 spi = self.scipy_interpolate 

556 

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

558 

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

560 try: 

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

562 eps=EPS, s=s).ev 

563 except Exception as x: 

564 raise _SciPyIssue(x, self._ev_name) 

565 

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

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

568 

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

570 ''' 

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

572 

573 

574class _HeightIDW(_HeightNamed): 

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

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

577 interpolators. 

578 

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

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

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

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

583 classes. 

584 ''' 

585 _beta = 0 # fidw inverse power 

586 _func = None # formy function 

587 _knots = () # knots list or tuple 

588 _kwds = {} # func_ options 

589 

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

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

592 

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

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

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

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

597 retrievable with property C{kwds}. 

598 

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

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

601 ''' 

602 name, kwds = _name2__(**name__kwds) 

603 if name: 

604 self.name = name 

605 

606 n, self._knots = len2(knots) 

607 if n < self.kmin: 

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

609 self.beta = beta 

610 self._kwds = kwds or {} 

611 

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

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

614 

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

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

617 locations (C{bool}). 

618 

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

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

621 

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

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

624 issue. 

625 ''' 

626 def _xy2(wrap=False): 

627 _w = _Wrap._latlonop(wrap) 

628 try: # like _xyhs above, but degrees 

629 for i, ll in enumerate(llis): 

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

631 except Exception as x: 

632 i = Fmt.INDEX(llis=i) 

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

634 

635 _as, llis = _as_llis2(llis) 

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

637 

638 @property_RO 

639 def adjust(self): 

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

641 ''' 

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

643 

644 @property 

645 def beta(self): 

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

647 ''' 

648 return self._beta 

649 

650 @beta.setter # PYCHOK setter! 

651 def beta(self, beta): 

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

653 

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

655 ''' 

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

657 

658 @property_RO 

659 def datum(self): 

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

661 ''' 

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

663 

664 def _datum_setter(self, datum): 

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

666 ''' 

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

668 if d and d is not self._datum: 

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

670 

671 def _distances(self, x, y): 

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

673 ''' 

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

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

676 self._notOverloaded(distance_function=_f) 

677 try: 

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

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

680 except Exception as x: 

681 i = Fmt.INDEX(knots=i) 

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

683 

684 def _distancesTo(self, _To): 

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

686 ''' 

687 try: 

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

689 yield _To(k) 

690 except Exception as x: 

691 i = Fmt.INDEX(knots=i) 

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

693 

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

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

696 

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

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

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

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

701 and B{C{lons}}. 

702 

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

704 interpolated heights (each C{float}). 

705 

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

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

708 ''' 

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

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

711 

712 @Property_RO 

713 def _heights(self): 

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

715 ''' 

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

717 

718 def _hIDW(self, x, y): 

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

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

721 ''' 

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

723 try: 

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

725 except (TypeError, ValueError) as e: 

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

727 

728 @property_RO 

729 def hypot(self): 

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

731 ''' 

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

733 

734 @property_RO 

735 def knots(self): 

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

737 ''' 

738 return self._knots 

739 

740 @property_RO 

741 def kwds(self): 

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

743 ''' 

744 return self._kwds 

745 

746 @property_RO 

747 def limit(self): 

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

749 ''' 

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

751 

752 @property_RO 

753 def radius(self): 

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

755 ''' 

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

757 

758 @property_RO 

759 def scaled(self): 

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

761 ''' 

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

763 

764 @property_RO 

765 def wrap(self): 

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

767 ''' 

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

769 

770 

771class HeightIDWcosineLaw(_HeightIDW): 

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

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

774 and function L{pygeodesy.cosineLaw}. 

775 

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

777 ''' 

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

779 '''New L{HeightIDWcosineLaw} interpolator. 

780 

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

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

783 arguments for function L{pygeodesy.cosineLaw}. 

784 

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

786 ''' 

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

788 self._func = _formy.cosineLaw 

789 

790 if _FOR_DOCS: 

791 __call__ = _HeightIDW.__call__ 

792 height = _HeightIDW.height 

793 

794 

795class HeightIDWdistanceTo(_HeightIDW): 

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

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

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

799 ''' 

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

801 '''New L{HeightIDWdistanceTo} interpolator. 

802 

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

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

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

806 

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

808 

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

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

811 checked}. 

812 ''' 

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

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

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

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

817 self._datum = ks0.datum 

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

819 

820 def _distances(self, x, y): 

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

822 ''' 

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

824 

825 def _To(k): 

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

827 

828 return self._distancesTo(_To) 

829 

830 if _FOR_DOCS: 

831 __call__ = _HeightIDW.__call__ 

832 height = _HeightIDW.height 

833 

834 

835class HeightIDWequirectangular(_HeightIDW): 

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

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

838 and function L{pygeodesy.equirectangular4}. 

839 ''' 

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

841 '''New L{HeightIDWequirectangular} interpolator. 

842 

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

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

845 for function L{pygeodesy.equirectangular4}. 

846 

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

848 ''' 

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

850 

851 def _distances(self, x, y): 

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

853 ''' 

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

855 

856 def _To(k): 

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

858 

859 return self._distancesTo(_To) 

860 

861 if _FOR_DOCS: 

862 __call__ = _HeightIDW.__call__ 

863 height = _HeightIDW.height 

864 

865 

866class HeightIDWeuclidean(_HeightIDW): 

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

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

869 and function L{pygeodesy.euclidean_}. 

870 ''' 

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

872 '''New L{HeightIDWeuclidean} interpolator. 

873 

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

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

876 for function function L{pygeodesy.euclidean}. 

877 

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

879 ''' 

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

881 self._func = _formy.euclidean 

882 

883 if _FOR_DOCS: 

884 __call__ = _HeightIDW.__call__ 

885 height = _HeightIDW.height 

886 

887 

888class HeightIDWexact(_HeightIDW): 

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

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

891 and method L{GeodesicExact.Inverse}. 

892 ''' 

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

894 '''New L{HeightIDWexact} interpolator. 

895 

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

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

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

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

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

901 class L{geodesicx.GeodesicExact}. 

902 

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

904 

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

906 ''' 

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

908 self._datum_setter(datum) 

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

910 

911 if _FOR_DOCS: 

912 __call__ = _HeightIDW.__call__ 

913 height = _HeightIDW.height 

914 

915 

916class HeightIDWflatLocal(_HeightIDW): 

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

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

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

920 ''' 

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

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

923 

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

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

926 keyword arguments for L{pygeodesy.flatLocal}. 

927 

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

929 ''' 

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

931 **name__datum_hypot_scaled_wrap) 

932 self._func = _formy.flatLocal 

933 

934 if _FOR_DOCS: 

935 __call__ = _HeightIDW.__call__ 

936 height = _HeightIDW.height 

937 

938 

939class HeightIDWflatPolar(_HeightIDW): 

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

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

942 and function L{pygeodesy.flatPolar_}. 

943 ''' 

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

945 '''New L{HeightIDWflatPolar} interpolator. 

946 

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

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

949 arguments for function L{pygeodesy.flatPolar}. 

950 

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

952 ''' 

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

954 self._func = _formy.flatPolar 

955 

956 if _FOR_DOCS: 

957 __call__ = _HeightIDW.__call__ 

958 height = _HeightIDW.height 

959 

960 

961class HeightIDWhaversine(_HeightIDW): 

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

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

964 and function L{pygeodesy.haversine_}. 

965 

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

967 ''' 

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

969 '''New L{HeightIDWhaversine} interpolator. 

970 

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

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

973 arguments for function L{pygeodesy.haversine}. 

974 

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

976 ''' 

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

978 self._func = _formy.haversine 

979 

980 if _FOR_DOCS: 

981 __call__ = _HeightIDW.__call__ 

982 height = _HeightIDW.height 

983 

984 

985class HeightIDWhubeny(HeightIDWflatLocal): # for Karl Hubeny 

986 if _FOR_DOCS: 

987 __doc__ = HeightIDWflatLocal.__doc__ 

988 __init__ = HeightIDWflatLocal.__init__ 

989 __call__ = HeightIDWflatLocal.__call__ 

990 height = HeightIDWflatLocal.height 

991 

992 

993class HeightIDWkarney(_HeightIDW): 

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

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

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

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

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

999 ''' 

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

1001 '''New L{HeightIDWkarney} interpolator. 

1002 

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

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

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

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

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

1008 class L{geodesicw.Geodesic}. 

1009 

1010 @raise ImportError: Package U{geographiclib 

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

1012 

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

1014 

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

1016 ''' 

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

1018 self._datum_setter(datum) 

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

1020 

1021 if _FOR_DOCS: 

1022 __call__ = _HeightIDW.__call__ 

1023 height = _HeightIDW.height 

1024 

1025 

1026class HeightIDWthomas(_HeightIDW): 

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

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

1029 and function L{pygeodesy.thomas_}. 

1030 ''' 

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

1032 '''New L{HeightIDWthomas} interpolator. 

1033 

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

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

1036 arguments for function L{pygeodesy.thomas}. 

1037 

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

1039 ''' 

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

1041 self._func = _formy.thomas 

1042 

1043 if _FOR_DOCS: 

1044 __call__ = _HeightIDW.__call__ 

1045 height = _HeightIDW.height 

1046 

1047 

1048class HeightIDWvincentys(_HeightIDW): 

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

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

1051 and function L{pygeodesy.vincentys_}. 

1052 

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

1054 ''' 

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

1056 '''New L{HeightIDWvincentys} interpolator. 

1057 

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

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

1060 arguments for function L{pygeodesy.vincentys}. 

1061 

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

1063 ''' 

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

1065 self._func = _formy.vincentys 

1066 

1067 if _FOR_DOCS: 

1068 __call__ = _HeightIDW.__call__ 

1069 height = _HeightIDW.height 

1070 

1071 

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

1073 

1074# **) MIT License 

1075# 

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

1077# 

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

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

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

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

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

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

1084# 

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

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

1087# 

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

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

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

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

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

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

1094# OTHER DEALINGS IN THE SOFTWARE.