Coverage for pygeodesy/heights.py: 95%
315 statements
« prev ^ index » next coverage.py v7.6.1, created at 2025-04-09 11:05 -0400
« prev ^ index » next coverage.py v7.6.1, created at 2025-04-09 11:05 -0400
2# -*- coding: utf-8 -*-
4u'''Height interpolations at C{LatLon} points from known C{knots}.
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}.
14Typical usage
15=============
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.
20C{>>> ...}
222. Select one of the C{Height} classes for height interpolation
24C{>>> from pygeodesy import HeightCubic # or other Height... as HeightXyz}
263. Instantiate a height interpolator with the C{knots} and use keyword
27arguments to select different interpolation options
29C{>>> hinterpolator = HeightXyz(knots, **options)}
314. Get the interpolated height of C{LatLon} location(s) with
33C{>>> ll = LatLon(1, 2, ...)}
35C{>>> h = hinterpolator(ll)}
37or
39C{>>> h0, h1, h2, ... = hinterpolator(ll0, ll1, ll2, ...)}
41or a list, tuple, generator, etc. of C{LatLon}s
43C{>>> hs = hinterpolator(lls)}
455. For separate lat- and longitudes invoke the C{height} method as
47C{>>> h = hinterpolator.height(lat, lon)}
49or as 2 lists, 2 tuples, etc.
51C{>>> hs = hinterpolator.height(lats, lons)}
53or for several positionals use the C{height_} method
55C{>>> h1, h2, ... = hinterpolator.height_(lat1, lon1, lat2, lon2, ...)}
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.
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}.
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
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
94# from math import radians # from .points
96__all__ = _ALL_LAZY.heights
97__version__ = '24.12.31'
99_error_ = 'error'
100_formy = _MODS.into(formy=__name__)
101_linear_ = 'linear'
102_llis_ = 'llis'
105class HeightError(PointsError):
106 '''Height interpolator C{Height...} or interpolation issue.
107 '''
108 pass
111def _alist(ais):
112 # return list of floats, not numpy.float64s
113 return list(map(float, ais))
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>
126def _atuple(ais):
127 # return tuple of floats, not numpy.float64s
128 return tuple(map(float, ais))
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))
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
149 if n < m:
150 raise _InsufficientError(m, Error=Error, llis=n)
151 return _as, llis
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)
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
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)
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
187 _LLiC = LatLon_ # ._height class
188 _np_sp = None # (numpy, scipy)
189 _wrap = None # wrap knots and llis
191 def __call__(self, *llis, **wrap): # PYCHOK no cover
192 '''Interpolate the height for one or several locations. I{Must be overloaded}.
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.
198 @return: A single interpolated height (C{float}) or a list or tuple of
199 interpolated heights (each C{float}).
201 @raise HeightError: Insufficient number of B{C{llis}} or an invalid B{C{lli}}.
203 @raise SciPyError: A C{scipy} issue.
205 @raise SciPyWarning: A C{scipy} warning as exception.
206 '''
207 self._notOverloaded(callername='__call__', *llis, **wrap)
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
222 @property_RO
223 def datum(self):
224 '''Get the C{datum} setting or the default (L{Datum}).
225 '''
226 return self._datum
228 def height(self, lats, lons, **wrap): # PYCHOK no cover
229 '''I{Must be overloaded}.'''
230 self._notOverloaded(lats, lons, **wrap)
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})}.
236 @arg latlons: Alternating lat-/longitude pairs (each C{degrees}),
237 all positional.
239 @see: Method C{height} for further details.
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))
246 @property_RO
247 def kmin(self):
248 '''Get the minimum number of knots (C{int}).
249 '''
250 return self._kmin
252 @property_RO
253 def wrap(self):
254 '''Get the C{wrap} setting (C{bool}) or C{None}.
255 '''
256 return self._wrap
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'}
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
276 def _ev(self, *args): # PYCHOK no cover
277 '''(INTERNAL) I{Must be overloaded}.'''
278 self._notOverloaded(*args)
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)
287 def _ev2d(self, x, y): # PYCHOK no cover
288 '''(INTERNAL) I{Must be overloaded}.'''
289 self._notOverloaded(x, y)
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])])
304 def height(self, lats, lons, **wrap):
305 '''Interpolate the height for one or several lat-/longitudes.
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.
313 @return: A single interpolated height (C{float}) or a list of interpolated
314 heights (each C{float}).
316 @raise HeightError: Insufficient or unequal number of B{C{lats}} and B{C{lons}}.
318 @raise SciPyError: A C{scipy} issue.
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)
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])
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)
341 def _bisplev(x, y):
342 return spi.bisplev(x, y, r) # .T
344 self._ev2d = _bisplev
346 except Exception as x:
347 raise _SciPyIssue(x, self._ev_name)
349 def _kxky(self, kind):
350 return Int_(kind=kind, low=1, high=5, Error=self._Error)
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
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
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
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
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)
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)
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
409 def __init__(self, knots, **name_wrap):
410 '''New L{HeightCubic} interpolator.
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}).
417 @raise HeightError: Insufficient number of B{C{knots}} or invalid B{C{knot}}.
419 @raise ImportError: Package C{numpy} or C{scipy} not found or not installed.
421 @raise SciPyError: A C{scipy} issue.
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)
428 def __call__(self, *llis, **wrap):
429 '''Interpolate the height for one or several locations.
431 @see: L{Here<_HeightBase.__call__>} for further details.
432 '''
433 return self._evalls(llis, **wrap)
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)
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
450 def __init__(self, knots, **name_wrap):
451 '''New L{HeightLinear} interpolator.
453 @see: L{Here<HeightCubic.__init__>} for all details.
454 '''
455 HeightCubic.__init__(self, knots, **name_wrap)
457 if _FOR_DOCS:
458 __call__ = HeightCubic.__call__
459 height = HeightCubic.height
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
469 def __init__(self, knots, weight=None, low=1e-4, **name_wrap):
470 '''New L{HeightLSQBiSpline} interpolator.
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}).
481 @raise HeightError: Insufficient number of B{C{knots}} or an invalid
482 B{C{knot}}, B{C{weight}} or B{C{eps}}.
484 @raise LenError: Unequal number of B{C{knots}} and B{C{weight}}s.
486 @raise ImportError: Package C{numpy} or C{scipy} not found or not
487 installed.
489 @raise SciPyError: A C{scipy} issue.
491 @raise SciPyWarning: A C{scipy} warning as exception.
492 '''
493 np = self.numpy
494 spi = self.scipy_interpolate
496 xs, ys, hs = self._xyhs3(knots, **name_wrap)
497 n = len(hs)
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)
522 def __call__(self, *llis, **wrap):
523 '''Interpolate the height for one or several locations.
525 @see: L{Here<_HeightBase.__call__>} for further details.
526 '''
527 return self._evalls(llis, **wrap)
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
537 def __init__(self, knots, s=4, **name_wrap):
538 '''New L{HeightSmoothBiSpline} interpolator.
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}).
547 @raise HeightError: Insufficient number of B{C{knots}} or an invalid
548 B{C{knot}} or B{C{s}}.
550 @raise ImportError: Package C{numpy} or C{scipy} not found or not
551 installed.
553 @raise SciPyError: A C{scipy} issue.
555 @raise SciPyWarning: A C{scipy} warning as exception.
556 '''
557 spi = self.scipy_interpolate
559 s = Float_(smoothing=s, Error=HeightError, low=4)
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)
568 def __call__(self, *llis, **wrap):
569 '''Interpolate the height for one or several locations.
571 @see: L{Here<_HeightBase.__call__>} for further details.
572 '''
573 return self._evalls(llis, **wrap)
576class _HeightIDW(_HeightNamed):
577 '''(INTERNAL) Base class for U{Inverse Distance Weighting
578 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) height
579 interpolators.
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
592 def __init__(self, knots, beta=2, **name__kwds):
593 '''New C{_HeightIDW*} interpolator.
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}.
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
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 {}
614 def __call__(self, *llis, **wrap):
615 '''Interpolate the height for one or several locations.
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}).
621 @return: A single interpolated height (C{float}) or a list
622 or tuple of interpolated heights (C{float}s).
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)
637 _as, llis = _as_llis2(llis)
638 return _as(map(self._hIDW, *zip(*_xy2(**wrap))))
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)
646 @property
647 def beta(self):
648 '''Get the inverse distance power (C{int}).
649 '''
650 return self._beta
652 @beta.setter # PYCHOK setter!
653 def beta(self, beta):
654 '''Set the inverse distance power (C{int} 1, 2, or 3).
656 @raise HeightError: Invalid B{C{beta}}.
657 '''
658 self._beta = Int_(beta=beta, Error=HeightError, low=1, high=3)
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)
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)
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)
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)
696 def height(self, lats, lons, **wrap):
697 '''Interpolate the height for one or several lat-/longitudes.
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}}.
705 @return: A single interpolated height (C{float}) or a list of
706 interpolated heights (each C{float}).
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)
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)
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)
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)
736 @property_RO
737 def knots(self):
738 '''Get the B{C{knots}} (C{list} or C{tuple}).
739 '''
740 return self._knots
742 @property_RO
743 def kwds(self):
744 '''Get the optional keyword arguments (C{dict}).
745 '''
746 return self._kwds
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)
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)
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)
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)
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}.
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.
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}.
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
792 if _FOR_DOCS:
793 __call__ = _HeightIDW.__call__
794 height = _HeightIDW.height
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.
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}.
809 @see: L{Here<_HeightIDW.__init__>} for further details.
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)
822 def _distances(self, x, y):
823 '''(INTERNAL) Yield distances to C{(x, y)}.
824 '''
825 kwds, ll = self._kwds, self._LLiC(y, x)
827 def _To(k):
828 return k.distanceTo(ll, **kwds)
830 return self._distancesTo(_To)
832 if _FOR_DOCS:
833 __call__ = _HeightIDW.__call__
834 height = _HeightIDW.height
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.
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}.
849 @see: L{Here<_HeightIDW.__init__>} for further details.
850 '''
851 _HeightIDW.__init__(self, knots, beta=beta, **name__adjust_limit_wrap)
853 def _distances(self, x, y):
854 '''(INTERNAL) Yield distances to C{(x, y)}.
855 '''
856 _f, kwds = _formy.equirectangular4, self._kwds
858 def _To(k):
859 return _f(y, x, k.lat, k.lon, **kwds).distance2
861 return self._distancesTo(_To)
863 if _FOR_DOCS:
864 __call__ = _HeightIDW.__call__
865 height = _HeightIDW.height
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.
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}.
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
885 if _FOR_DOCS:
886 __call__ = _HeightIDW.__call__
887 height = _HeightIDW.height
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.
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}.
905 @raise TypeError: Invalid B{C{datum}}.
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
913 if _FOR_DOCS:
914 __call__ = _HeightIDW.__call__
915 height = _HeightIDW.height
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.
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}.
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
936 if _FOR_DOCS:
937 __call__ = _HeightIDW.__call__
938 height = _HeightIDW.height
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.
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}.
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
958 if _FOR_DOCS:
959 __call__ = _HeightIDW.__call__
960 height = _HeightIDW.height
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_}.
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.
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}.
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
982 if _FOR_DOCS:
983 __call__ = _HeightIDW.__call__
984 height = _HeightIDW.height
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
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.
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}.
1012 @raise ImportError: Package U{geographiclib
1013 <https://PyPI.org/project/geographiclib>} missing.
1015 @raise TypeError: Invalid B{C{datum}}.
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
1023 if _FOR_DOCS:
1024 __call__ = _HeightIDW.__call__
1025 height = _HeightIDW.height
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.
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}.
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
1045 if _FOR_DOCS:
1046 __call__ = _HeightIDW.__call__
1047 height = _HeightIDW.height
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_}.
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.
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}.
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
1069 if _FOR_DOCS:
1070 __call__ = _HeightIDW.__call__
1071 height = _HeightIDW.height
1074__all__ += _ALL_DOCS(_HeightBase, _HeightIDW, _HeightNamed)
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.