Coverage for pygeodesy/heights.py: 95%
315 statements
« prev ^ index » next coverage.py v7.6.1, created at 2025-05-29 12:40 -0400
« prev ^ index » next coverage.py v7.6.1, created at 2025-05-29 12:40 -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 _ # noqa: E702 ;
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
92# from math import radians # from .points
94__all__ = _ALL_LAZY.heights
95__version__ = '25.05.26'
97_error_ = 'error'
98_formy = _MODS.into(formy=__name__)
99_linear_ = 'linear'
100_llis_ = 'llis'
103class HeightError(PointsError):
104 '''Height interpolator C{Height...} or interpolation issue.
105 '''
106 pass
109def _alist(ais):
110 # return list of floats, not numpy.float64s
111 return list(map(float, ais))
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>
124def _atuple(ais):
125 # return tuple of floats, not numpy.float64s
126 return tuple(map(float, ais))
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))
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
147 if n < m:
148 raise _InsufficientError(m, Error=Error, llis=n)
149 return _as, llis
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)
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
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)
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
185 _LLiC = LatLon_ # ._height class
186 _np_sp = None # (numpy, scipy)
187 _wrap = None # wrap knots and llis
189 def __call__(self, *llis, **wrap): # PYCHOK no cover
190 '''Interpolate the height for one or several locations. I{Must be overloaded}.
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.
196 @return: A single interpolated height (C{float}) or a list or tuple of
197 interpolated heights (each C{float}).
199 @raise HeightError: Insufficient number of B{C{llis}} or an invalid B{C{lli}}.
201 @raise SciPyError: A C{scipy} issue.
203 @raise SciPyWarning: A C{scipy} warning as exception.
204 '''
205 self._notOverloaded(callername='__call__', *llis, **wrap)
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
220 @property_RO
221 def datum(self):
222 '''Get the C{datum} setting or the default (L{Datum}).
223 '''
224 return self._datum
226 def height(self, lats, lons, **wrap): # PYCHOK no cover
227 '''I{Must be overloaded}.'''
228 self._notOverloaded(lats, lons, **wrap)
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})}.
234 @arg latlons: Alternating lat-/longitude pairs (each C{degrees}),
235 all positional.
237 @see: Method C{height} for further details.
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))
244 @property_RO
245 def kmin(self):
246 '''Get the minimum number of knots (C{int}).
247 '''
248 return self._kmin
250 @property_RO
251 def wrap(self):
252 '''Get the C{wrap} setting (C{bool}) or C{None}.
253 '''
254 return self._wrap
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'}
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
274 def _ev(self, *args): # PYCHOK no cover
275 '''(INTERNAL) I{Must be overloaded}.'''
276 self._notOverloaded(*args)
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)
285 def _ev2d(self, x, y): # PYCHOK no cover
286 '''(INTERNAL) I{Must be overloaded}.'''
287 self._notOverloaded(x, y)
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])])
302 def height(self, lats, lons, **wrap):
303 '''Interpolate the height for one or several lat-/longitudes.
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.
311 @return: A single interpolated height (C{float}) or a list of interpolated
312 heights (each C{float}).
314 @raise HeightError: Insufficient or unequal number of B{C{lats}} and B{C{lons}}.
316 @raise SciPyError: A C{scipy} issue.
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)
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])
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)
339 def _bisplev(x, y):
340 return spi.bisplev(x, y, r) # .T
342 self._ev2d = _bisplev
344 except Exception as x:
345 raise _SciPyIssue(x, self._ev_name)
347 def _kxky(self, kind):
348 return Int_(kind=kind, low=1, high=5, Error=self._Error)
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
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
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
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
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)
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)
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
407 def __init__(self, knots, **name_wrap):
408 '''New L{HeightCubic} interpolator.
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}).
415 @raise HeightError: Insufficient number of B{C{knots}} or invalid B{C{knot}}.
417 @raise ImportError: Package C{numpy} or C{scipy} not found or not installed.
419 @raise SciPyError: A C{scipy} issue.
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)
426 def __call__(self, *llis, **wrap):
427 '''Interpolate the height for one or several locations.
429 @see: L{Here<_HeightBase.__call__>} for further details.
430 '''
431 return self._evalls(llis, **wrap)
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)
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
448 def __init__(self, knots, **name_wrap):
449 '''New L{HeightLinear} interpolator.
451 @see: L{Here<HeightCubic.__init__>} for all details.
452 '''
453 HeightCubic.__init__(self, knots, **name_wrap)
455 if _FOR_DOCS:
456 __call__ = HeightCubic.__call__
457 height = HeightCubic.height
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
467 def __init__(self, knots, weight=None, low=1e-4, **name_wrap):
468 '''New L{HeightLSQBiSpline} interpolator.
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}).
479 @raise HeightError: Insufficient number of B{C{knots}} or an invalid
480 B{C{knot}}, B{C{weight}} or B{C{eps}}.
482 @raise LenError: Unequal number of B{C{knots}} and B{C{weight}}s.
484 @raise ImportError: Package C{numpy} or C{scipy} not found or not
485 installed.
487 @raise SciPyError: A C{scipy} issue.
489 @raise SciPyWarning: A C{scipy} warning as exception.
490 '''
491 np = self.numpy
492 spi = self.scipy_interpolate
494 xs, ys, hs = self._xyhs3(knots, **name_wrap)
495 n = len(hs)
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)
520 def __call__(self, *llis, **wrap):
521 '''Interpolate the height for one or several locations.
523 @see: L{Here<_HeightBase.__call__>} for further details.
524 '''
525 return self._evalls(llis, **wrap)
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
535 def __init__(self, knots, s=4, **name_wrap):
536 '''New L{HeightSmoothBiSpline} interpolator.
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}).
545 @raise HeightError: Insufficient number of B{C{knots}} or an invalid
546 B{C{knot}} or B{C{s}}.
548 @raise ImportError: Package C{numpy} or C{scipy} not found or not
549 installed.
551 @raise SciPyError: A C{scipy} issue.
553 @raise SciPyWarning: A C{scipy} warning as exception.
554 '''
555 spi = self.scipy_interpolate
557 s = Float_(smoothing=s, Error=HeightError, low=4)
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)
566 def __call__(self, *llis, **wrap):
567 '''Interpolate the height for one or several locations.
569 @see: L{Here<_HeightBase.__call__>} for further details.
570 '''
571 return self._evalls(llis, **wrap)
574class _HeightIDW(_HeightNamed):
575 '''(INTERNAL) Base class for U{Inverse Distance Weighting
576 <https://WikiPedia.org/wiki/Inverse_distance_weighting>} (IDW) height
577 interpolators.
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
590 def __init__(self, knots, beta=2, **name__kwds):
591 '''New C{_HeightIDW*} interpolator.
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}.
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
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 {}
612 def __call__(self, *llis, **wrap):
613 '''Interpolate the height for one or several locations.
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}).
619 @return: A single interpolated height (C{float}) or a list
620 or tuple of interpolated heights (C{float}s).
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)
635 _as, llis = _as_llis2(llis)
636 return _as(map(self._hIDW, *zip(*_xy2(**wrap))))
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)
644 @property
645 def beta(self):
646 '''Get the inverse distance power (C{int}).
647 '''
648 return self._beta
650 @beta.setter # PYCHOK setter!
651 def beta(self, beta):
652 '''Set the inverse distance power (C{int} 1, 2, or 3).
654 @raise HeightError: Invalid B{C{beta}}.
655 '''
656 self._beta = Int_(beta=beta, Error=HeightError, low=1, high=3)
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)
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)
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)
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)
694 def height(self, lats, lons, **wrap):
695 '''Interpolate the height for one or several lat-/longitudes.
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}}.
703 @return: A single interpolated height (C{float}) or a list of
704 interpolated heights (each C{float}).
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)
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)
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)
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)
734 @property_RO
735 def knots(self):
736 '''Get the B{C{knots}} (C{list} or C{tuple}).
737 '''
738 return self._knots
740 @property_RO
741 def kwds(self):
742 '''Get the optional keyword arguments (C{dict}).
743 '''
744 return self._kwds
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)
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)
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)
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)
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}.
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.
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}.
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
790 if _FOR_DOCS:
791 __call__ = _HeightIDW.__call__
792 height = _HeightIDW.height
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.
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}.
807 @see: L{Here<_HeightIDW.__init__>} for further details.
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)
820 def _distances(self, x, y):
821 '''(INTERNAL) Yield distances to C{(x, y)}.
822 '''
823 kwds, ll = self._kwds, self._LLiC(y, x)
825 def _To(k):
826 return k.distanceTo(ll, **kwds)
828 return self._distancesTo(_To)
830 if _FOR_DOCS:
831 __call__ = _HeightIDW.__call__
832 height = _HeightIDW.height
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.
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}.
847 @see: L{Here<_HeightIDW.__init__>} for further details.
848 '''
849 _HeightIDW.__init__(self, knots, beta=beta, **name__adjust_limit_wrap)
851 def _distances(self, x, y):
852 '''(INTERNAL) Yield distances to C{(x, y)}.
853 '''
854 _f, kwds = _formy.equirectangular4, self._kwds
856 def _To(k):
857 return _f(y, x, k.lat, k.lon, **kwds).distance2
859 return self._distancesTo(_To)
861 if _FOR_DOCS:
862 __call__ = _HeightIDW.__call__
863 height = _HeightIDW.height
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.
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}.
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
883 if _FOR_DOCS:
884 __call__ = _HeightIDW.__call__
885 height = _HeightIDW.height
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.
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}.
903 @raise TypeError: Invalid B{C{datum}}.
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
911 if _FOR_DOCS:
912 __call__ = _HeightIDW.__call__
913 height = _HeightIDW.height
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.
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}.
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
934 if _FOR_DOCS:
935 __call__ = _HeightIDW.__call__
936 height = _HeightIDW.height
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.
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}.
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
956 if _FOR_DOCS:
957 __call__ = _HeightIDW.__call__
958 height = _HeightIDW.height
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_}.
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.
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}.
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
980 if _FOR_DOCS:
981 __call__ = _HeightIDW.__call__
982 height = _HeightIDW.height
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
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.
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}.
1010 @raise ImportError: Package U{geographiclib
1011 <https://PyPI.org/project/geographiclib>} missing.
1013 @raise TypeError: Invalid B{C{datum}}.
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
1021 if _FOR_DOCS:
1022 __call__ = _HeightIDW.__call__
1023 height = _HeightIDW.height
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.
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}.
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
1043 if _FOR_DOCS:
1044 __call__ = _HeightIDW.__call__
1045 height = _HeightIDW.height
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_}.
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.
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}.
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
1067 if _FOR_DOCS:
1068 __call__ = _HeightIDW.__call__
1069 height = _HeightIDW.height
1072__all__ += _ALL_DOCS(_HeightBase, _HeightIDW, _HeightNamed)
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.