Coverage for pygeodesy/ellipsoidalNvector.py: 96%
133 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'''Ellipsoidal, C{N-vector}-based geodesy.
6Ellipsoidal classes geodetic L{LatLon}, geocentric (ECEF) L{Cartesian}
7and C{Nvector} and DEPRECATED L{Ned} and functions L{meanOf}, L{sumOf}
8and DEPRECATED L{toNed}.
10Pure Python implementation of n-vector-based geodetic (lat-/longitude)
11methods by I{(C) Chris Veness 2011-2024} published under the same MIT
12Licence**, see U{Vector-based geodesy
13<https://www.Movable-Type.co.UK/scripts/latlong-vectors.html>}.
15These classes and functions work with: (a) geodetic lat-/longitude points on
16the earth's surface and (b) 3-D vectors used as n-vectors representing points
17on the earth's surface or vectors normal to the plane of a great circle.
19See also I{Kenneth Gade} U{'A Non-singular Horizontal Position Representation'
20<https://www.NavLab.net/Publications/A_Nonsingular_Horizontal_Position_Representation.pdf>},
21The Journal of Navigation (2010), vol 63, nr 3, pp 395-417.
22'''
23# make sure int/int division yields float quotient, see .basics
24from __future__ import division as _; del _ # PYCHOK semicolon
26from pygeodesy.basics import issubclassof, map2, _xinstanceof, _xsubclassof
27from pygeodesy.datums import _earth_ellipsoid, _ellipsoidal_datum, _WGS84
28# from pygeodesy.dms import F_D, toDMS # _MODS
29from pygeodesy.ellipsoidalBase import CartesianEllipsoidalBase, \
30 _nearestOn, LatLonEllipsoidalBase, \
31 _TOL_M, _Wrap
32from pygeodesy.errors import _xkwds, _xkwds_pop2
33# from pygeodesy.fmath import fdot # from .nvectorBase
34from pygeodesy.interns import _Nv00_, _COMMASPACE_, _pole_ # PYCHOK used!
35from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS, _ALL_OTHER
36# from pygeodesy.ltp import Ltp # _MODS
37from pygeodesy.ltpTuples import Aer as _Aer, Ned as _Ned, Ned4Tuple, \
38 sincos2d_, _xnamed
39# from pygeodesy.named import _xnamed # from .ltpTuples
40from pygeodesy.nvectorBase import LatLonNvectorBase, NorthPole, NvectorBase, \
41 sumOf as _sumOf, fabs, fdot
42from pygeodesy.props import deprecated_class, deprecated_function, \
43 deprecated_method, Property_RO, property_RO
44from pygeodesy.streprs import Fmt, fstr, _xzipairs
45from pygeodesy.units import Bearing, Distance, Height, Scalar
46# from pygeodesy.utily import sincos2d_, _Wrap # from .ltpTuples, .ellipsoidalBase
48# from math import fabs # from .nvectorBase
50__all__ = _ALL_LAZY.ellipsoidalNvector
51__version__ = '24.10.19'
54class Ned(_Ned):
55 '''DEPRECATED on 2024.02.04, use class L{pygeodesy.Ned}.'''
57 def __init__(self, north, east, down, **name):
58 deprecated_class(self.__class__)
59 _Ned.__init__(self, north, east, down, **name)
61 @deprecated_method # PYCHOK expected
62 def toRepr(self, prec=None, fmt=Fmt.SQUARE, sep=_COMMASPACE_, **unused):
63 '''DEPRECATED, use class L{pygeodesy.Ned}.
65 @kwarg prec: Number of (decimal) digits, unstripped (C{int}).
66 @kwarg fmt: Enclosing backets format (C{str}).
67 @kwarg sep: Separator between NEDs (C{str}).
69 @return: This Ned as "[L:f, B:degrees360, E:degrees90]" (C{str})
70 with length or slantrange C{L}, bearing or azimuth C{B}
71 and elevation C{E}.
72 '''
73 m = _MODS.dms
74 t = (fstr(self.slantrange, prec=prec),
75 m.toDMS(self.azimuth, form=m.F_D, prec=prec, ddd=0),
76 m.toDMS(self.elevation, form=m.F_D, prec=prec, ddd=0))
77 return _xzipairs('LBE', t, sep=sep, fmt=fmt)
80class Cartesian(CartesianEllipsoidalBase):
81 '''Extended to convert geocentric, L{Cartesian} points to
82 C{Nvector} and n-vector-based, geodetic L{LatLon}.
83 '''
84 @property_RO
85 def Ecef(self):
86 '''Get the ECEF I{class} (L{EcefVeness}), I{once}.
87 '''
88 return _Ecef()
90 def toLatLon(self, **LatLon_and_kwds): # PYCHOK LatLon=LatLon, datum=None
91 '''Convert this cartesian to an C{Nvector}-based geodetic point.
93 @kwarg LatLon_and_kwds: Optional L{LatLon}, B{C{datum}} and other
94 keyword arguments. Use C{B{LatLon}=...} to
95 override this L{LatLon} class or specify
96 C{B{LatLon} is None}.
98 @return: The geodetic point (L{LatLon}) or if C{B{LatLon} is None},
99 an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)}
100 with C{C} and C{M} if available.
102 @raise TypeError: Invalid B{C{LatLon_and_kwds}}.
103 '''
104 kwds = _xkwds(LatLon_and_kwds, LatLon=LatLon, datum=self.datum)
105 return CartesianEllipsoidalBase.toLatLon(self, **kwds)
107 def toNvector(self, **Nvector_and_kwds): # PYCHOK Datums.WGS84
108 '''Convert this cartesian to C{Nvector} components, I{including height}.
110 @kwarg Nvector_and_kwds: Optional C{Nvector}, B{C{datum}} and other
111 keyword arguments. Use C{B{Nvector}=...} to
112 override this C{Nvector} class or specify
113 C{B{Nvector} is None}.
115 @return: The C{n-vector} components (C{Nvector}) or if C{B{Nvector}
116 is None}, a L{Vector4Tuple}C{(x, y, z, h)}.
118 @raise TypeError: Invalid B{C{Nvector_and_kwds}}.
119 '''
120 kwds = _xkwds(Nvector_and_kwds, Nvector=Nvector, datum=self.datum)
121 return CartesianEllipsoidalBase.toNvector(self, **kwds)
124class LatLon(LatLonNvectorBase, LatLonEllipsoidalBase):
125 '''An n-vector-based, ellipsoidal L{LatLon} point.
126 '''
127 _Nv = None # cached toNvector (C{Nvector})
129 def _update(self, updated, *attrs, **setters): # PYCHOK args
130 '''(INTERNAL) Zap cached attributes if updated.
131 '''
132 if updated:
133 LatLonNvectorBase._update(self, updated, _Nv=self._Nv) # special case
134 LatLonEllipsoidalBase._update(self, updated, *attrs, **setters)
136# def crossTrackDistanceTo(self, start, end, radius=R_M):
137# '''Return the (signed) distance from this point to the great
138# circle defined by a start point and an end point or bearing.
139#
140# @arg start: Start point of great circle line (L{LatLon}).
141# @arg end: End point of great circle line (L{LatLon}) or
142# initial bearing (compass C{degrees360}) at the
143# start point.
144# @kwarg radius: Mean earth radius (C{meter}).
145#
146# @return: Distance to great circle, negative if to left or
147# positive if to right of line (C{meter}, same units
148# as B{C{radius}}).
149#
150# @raise TypeError: If B{C{start}} or B{C{end}} point is not L{LatLon}.
151# '''
152# self.others(start=start)
153#
154# if _isDegrees(end): # gc from point and bearing
155# gc = start.greatCircle(end)
156# else: # gc by two points
157# gc = start.toNvector().cross(end.toNvector())
158#
159# # (signed) angle between point and gc normal vector
160# v = self.toNvector()
161# a = gc.angleTo(v, vSign=v.cross(gc))
162# a = _copysign(PI_2, a) - a
163# return a * float(radius)
165 def deltaTo(self, other, wrap=False, **Ned_and_kwds):
166 '''Calculate the local delta from this to an other point.
168 @note: This is a linear delta, I{unrelated} to a geodesic on the
169 ellipsoid.
171 @arg other: The other point (L{LatLon}).
172 @kwarg wrap: If C{True}, wrap or I{normalize} the B{C{other}}
173 point (C{bool}).
174 @kwarg Ned_and_kwds: Optional C{B{Ned}=L{Ned} class and B{name}=NN}
175 to return delta and other B{C{Ned}} keyword arguments.
177 @return: Delta from this to the other point (B{C{Ned}}).
179 @raise TypeError: The B{C{other}} point is not L{LatLon} or B{C{Ned}}
180 is not an L{Ned4Tuple<pygeodesy.Ned4Tuple>} nor an
181 L{Ned<pygeodesy.Ned>} nor a DEPRECATED L{Ned}.
183 @raise ValueError: If ellipsoids are incompatible.
184 '''
185 self.ellipsoids(other) # throws TypeError and ValueError
187 p = self.others(other)
188 if wrap:
189 p = _Wrap.point(p)
190 # get delta in cartesian frame
191 dc = p.toCartesian().minus(self.toCartesian())
192 # rotate dc to get delta in n-vector reference
193 # frame using the rotation matrix row vectors
194 ned_ = map2(dc.dot, self._rotation3)
196 N, kwds = _xkwds_pop2(Ned_and_kwds, Ned=Ned)
197 if issubclassof(N, Ned4Tuple):
198 ned_ += _MODS.ltp.Ltp(self, ecef=self.Ecef(self.datum)),
199 else:
200 _xsubclassof(_Ned, Ned4Tuple, Ned=N)
201 return N(*ned_, **_xkwds(kwds, name=self.name))
203# def destination(self, distance, bearing, radius=R_M, height=None):
204# '''Return the destination point after traveling from this
205# point the given distance on the given initial bearing.
206#
207# @arg distance: Distance traveled (C{meter}, same units as
208# given earth B{C{radius}}).
209# @arg bearing: Initial bearing (compass C{degrees360}).
210# @kwarg radius: Mean earth radius (C{meter}).
211# @kwarg height: Optional height at destination point,
212# overriding default (C{meter}, same units
213# as B{C{radius}}).
214#
215# @return: Destination point (L{LatLon}).
216# '''
217# r = _m2radians(distance, radius) # angular distance in radians
218# # great circle by starting from this point on given bearing
219# gc = self.greatCircle(bearing)
220#
221# v1 = self.toNvector()
222# x = v1.times(cos(r)) # component of v2 parallel to v1
223# y = gc.cross(v1).times(sin(r)) # component of v2 perpendicular to v1
224#
225# v2 = x.plus(y).unit()
226# return v2.toLatLon(height=self._heigHt(height))
228 def destinationNed(self, delta):
229 '''Calculate the destination point using the supplied NED delta
230 from this point.
232 @arg delta: Delta from this to the other point in the local
233 tangent plane (LTP) of this point (L{Ned}).
235 @return: Destination point (L{LatLon}).
237 @raise TypeError: If B{C{delta}} is not an L{Ned<pygeodesy.Ned>}
238 or a DEPRECATED L{Ned}.
239 '''
240 _xinstanceof(_Ned, delta=delta)
242 nv, ev, dv = self._rotation3
243 # convert NED delta to standard coordinate frame of n-vector
244 dn = delta.ned[:3] # XXX Ned4Tuple.to3Tuple
245 # rotate dn to get delta in cartesian (ECEF) coordinate
246 # reference frame using the rotation matrix column vectors
247 dc = Cartesian(fdot(dn, nv.x, ev.x, dv.x),
248 fdot(dn, nv.y, ev.y, dv.y),
249 fdot(dn, nv.z, ev.z, dv.z))
251 # apply (cartesian) delta to this Cartesian to obtain destination as cartesian
252 v = self.toCartesian().plus(dc)
253 return v.toLatLon(datum=self.datum, LatLon=self.classof) # Cartesian(v.x, v.y, v.z).toLatLon(...)
255 def distanceTo(self, other, radius=None, wrap=False):
256 '''I{Approximate} the distance from this to an other point.
258 @arg other: The other point (L{LatLon}).
259 @kwarg radius: Mean earth radius, ellipsoid or datum (C{meter},
260 L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or
261 L{a_f2Tuple}), overriding the mean radius C{R1}
262 of this point's datum..
263 @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the
264 B{C{other}} and angular distance (C{bool}).
266 @return: Distance (C{meter}, same units as B{C{radius}}).
268 @raise TypeError: The B{C{other}} point is not L{LatLon}.
270 @raise ValueError: Invalid B{C{radius}}.
271 '''
272 p = self.others(other)
273 if wrap:
274 p = _Wrap.point(p)
275 a = self._N_vector.angleTo(p._N_vector, wrap=wrap)
276 E = self.datum.ellipsoid if radius is None else _earth_ellipsoid(radius)
277 return fabs(a) * E.R1 # see .utily.radians2m
279 @property_RO
280 def Ecef(self):
281 '''Get the ECEF I{class} (L{EcefVeness}), I{once}.
282 '''
283 return _Ecef()
285 @deprecated_method
286 def equals(self, other, eps=None): # PYCHOK no cover
287 '''DEPRECATED, use method L{isequalTo}.
288 '''
289 return self.isequalTo(other, eps=eps)
291 def isequalTo(self, other, eps=None):
292 '''Compare this point with an other point.
294 @arg other: The other point (L{LatLon}).
295 @kwarg eps: Optional margin (C{float}).
297 @return: C{True} if points are identical, including
298 datum, I{ignoring height}, C{False} otherwise.
300 @raise TypeError: The B{C{other}} point is not L{LatLon}.
302 @raise ValueError: Invalid B{C{eps}}.
304 @see: Method C{isequalTo3} to include I{height}.
305 '''
306 return self.datum == self.others(other).datum and \
307 _MODS.formy._isequalTo(self, other, eps=eps)
309# def greatCircle(self, bearing):
310# '''Return the great circle heading on the given bearing
311# from this point.
312#
313# Direction of vector is such that initial bearing vector
314# b = c × p, where p is representing this point.
315#
316# @arg bearing: Bearing from this point (compass C{degrees360}).
317#
318# @return: N-vector representing great circle (C{Nvector}).
319# '''
320# a, b, _ = self.philamheight
321# t = radians(bearing)
322#
323# sa, ca, sb, cb, st, ct = sincos2_(a, b, t)
324# return self._xnamed(Nvector(sb * ct - sa * cb * st,
325# -cb * ct - sa * sb * st,
326# ca * st)
328# def initialBearingTo(self, other, wrap=False):
329# '''Return the initial bearing (forward azimuth) from
330# this to an other point.
331#
332# @arg other: The other point (L{LatLon}).
333# @kwarg wrap: If C{True}, wrap or I{normalize}
334# and unroll the B{C{other}} (C{bool}).
335#
336# @return: Initial bearing (compass C{degrees360}).
337#
338# @raise TypeError: The B{C{other}} point is not L{LatLon}.
339# '''
340# p = self.others(other)
341# if wrap:
342# p = _Wrap.point(p)
343# v1 = self.toNvector()
344#
345# gc1 = v1.cross(p.toNvector()) # gc through v1 & v2
346# gc2 = v1.cross(_NP3) # gc through v1 & North pole
347#
348# # bearing is (signed) angle between gc1 & gc2
349# return degrees360(gc1.angleTo(gc2, vSign=v1))
351 def intermediateTo(self, other, fraction, height=None, wrap=False):
352 '''Return the point at given fraction between this and
353 an other point.
355 @arg other: The other point (L{LatLon}).
356 @arg fraction: Fraction between both points (C{scalar},
357 0.0 at this to 1.0 at the other point.
358 @kwarg height: Optional height, overriding the fractional
359 height (C{meter}).
360 @kwarg wrap: If C{True}, wrap or I{normalize} the
361 B{C{other}} point (C{bool}).
363 @return: Intermediate point (L{LatLon}).
365 @raise TypeError: The B{C{other}} point is not L{LatLon}.
366 '''
367 p = self.others(other)
368 if wrap:
369 p = _Wrap.point(p)
370 f = Scalar(fraction=fraction)
371 h = self._havg(other, f=f, h=height)
372 i = self.toNvector().intermediateTo(p.toNvector(), f)
373 return i.toLatLon(height=h, LatLon=self.classof) # Nvector(i.x, i.y, i.z).toLatLon(...)
375 @Property_RO
376 def _rotation3(self):
377 '''(INTERNAL) Get the rotation matrix from n-vector coordinate frame axes.
378 '''
379 nv = self.toNvector() # local (n-vector) coordinate frame
381 dv = nv.negate() # down, opposite to n-vector
382 ev = NorthPole.cross(nv, raiser=_pole_).unit() # east, pointing perpendicular to the plane
383 nv = ev.cross(dv) # north, by right hand rule
384 return nv, ev, dv # matrix rows
386 def toCartesian(self, **Cartesian_and_kwds): # PYCHOK Cartesian=Cartesian, datum=None
387 '''Convert this point to an C{Nvector}-based geodetic point.
389 @kwarg Cartesian_and_kwds: Optional L{Cartesian}, B{C{datum}} and other
390 keyword arguments. Use C{B{Cartesian}=...}
391 to override this L{Cartesian} class or specify
392 C{B{Cartesian}=None}.
394 @return: The geodetic point (L{Cartesian}) or if C{B{Cartesian} is None},
395 an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)} with
396 C{C} and C{M} if available.
398 @raise TypeError: Invalid B{C{Cartesian}} or other B{C{Cartesian_and_kwds}}.
399 '''
400 kwds = _xkwds(Cartesian_and_kwds, Cartesian=Cartesian, datum=self.datum)
401 return LatLonEllipsoidalBase.toCartesian(self, **kwds)
403 def toNvector(self, **Nvector_and_kwds): # PYCHOK signature
404 '''Convert this point to C{Nvector} components, I{including height}.
406 @kwarg Nvector_and_kwds: Optional C{Nvector}, B{C{datum}} and other
407 keyword arguments. Use C{B{Nvector}=...}
408 to override this C{Nvector} class or specify
409 C{B{Nvector}=None}.
411 @return: The C{n-vector} components (C{Nvector}) or if B{C{Nvector}}
412 is set to C{None}, a L{Vector4Tuple}C{(x, y, z, h)}.
414 @raise TypeError: Invalid B{C{Nvector}} or other B{C{Nvector_and_kwds}}.
415 '''
416 kwds = _xkwds(Nvector_and_kwds, Nvector=Nvector, datum=self.datum)
417 return LatLonNvectorBase.toNvector(self, **kwds)
420_Nv00 = LatLon(0, 0, name=_Nv00_) # reference instance (L{LatLon})
423class Nvector(NvectorBase):
424 '''An n-vector is a position representation using a (unit) vector
425 normal to the earth ellipsoid. Unlike lat-/longitude points,
426 n-vectors have no singularities or discontinuities.
428 For many applications, n-vectors are more convenient to work
429 with than other position representations like lat-/longitude,
430 earth-centred earth-fixed (ECEF) vectors, UTM coordinates, etc.
432 Note commonality with L{pygeodesy.sphericalNvector.Nvector}.
433 '''
434 _datum = _WGS84 # default datum (L{Datum})
436 def __init__(self, x_xyz, y=None, z=None, h=0, datum=None, ll=None, **name):
437 '''New n-vector normal to the earth's surface.
439 @arg x_xyz: X component of vector (C{scalar}) or (3-D) vector
440 (C{Nvector}, L{Vector3d}, L{Vector3Tuple} or
441 L{Vector4Tuple}).
442 @kwarg y: Y component of vector (C{scalar}), ignored if B{C{x_xyz}}
443 is not C{scalar}, otherwise same units as B{C{x_xyz}}.
444 @kwarg z: Z component of vector (C{scalar}), ignored if B{C{x_xyz}}
445 is not C{scalar}, otherwise same units as B{C{x_xyz}}.
446 @kwarg h: Optional height above model surface (C{meter}).
447 @kwarg datum: Optional datum this n-vector is defined in
448 (L{Datum}, L{Ellipsoid}, L{Ellipsoid2} or
449 L{a_f2Tuple}).
450 @kwarg ll: Optional, original latlon (C{LatLon}).
451 @kwarg name: Optional C{B{name}=NN} (C{str}).
453 @raise TypeError: If B{C{datum}} is not a L{Datum}.
454 '''
455 NvectorBase.__init__(self, x_xyz, y=y, z=z, h=h, ll=ll, **name)
456 if datum not in (None, self._datum):
457 self._datum = _ellipsoidal_datum(datum, **name)
459 @Property_RO
460 def datum(self):
461 '''Get this n-vector's datum (L{Datum}).
462 '''
463 return self._datum
465 @property_RO
466 def ellipsoidalNvector(self):
467 '''Get this C{Nvector}'s ellipsoidal class.
468 '''
469 return type(self)
471 def toCartesian(self, **Cartesian_and_kwds): # PYCHOK Cartesian=Cartesian
472 '''Convert this n-vector to C{Nvector}-based cartesian (ECEF) coordinates.
474 @kwarg Cartesian_and_kwds: Optional L{Cartesian}, B{C{h}}, B{C{datum}} and
475 other keyword arguments. Use C{B{Cartesian}=...}
476 to override this L{Cartesian} class or specify
477 C{B{Cartesian} is None}.
479 @return: The cartesian point (L{Cartesian}) or if C{B{Cartesian} is None},
480 an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)} with
481 C{C} and C{M} if available.
483 @raise TypeError: Invalid B{C{Cartesian_and_kwds}}.
484 '''
485 kwds = _xkwds(Cartesian_and_kwds, h=self.h, Cartesian=Cartesian,
486 datum=self.datum)
487 return NvectorBase.toCartesian(self, **kwds) # class or .classof
489 def toLatLon(self, **LatLon_and_kwds): # PYCHOK height=None, LatLon=LatLon
490 '''Convert this n-vector to an C{Nvector}-based geodetic point.
492 @kwarg LatLon_and_kwds: Optional L{LatLon}, B{C{height}}, B{C{datum}}
493 and other keyword arguments. Use C{B{LatLon}=...}
494 to override this L{LatLon} class or specify
495 C{B{LatLon} is None}.
497 @return: The geodetic point (L{LatLon}) or if C{B{LatLon} is None},
498 an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)}
499 with C{C} and C{M} if available.
501 @raise TypeError: Invalid B{C{LatLon_and_kwds}}.
502 '''
503 kwds = _xkwds(LatLon_and_kwds, height=self.h, datum=self.datum, LatLon=LatLon)
504 return NvectorBase.toLatLon(self, **kwds) # class or .classof
506 def unit(self, ll=None):
507 '''Normalize this vector to unit length.
509 @kwarg ll: Optional, original latlon (C{LatLon}).
511 @return: Normalised vector (C{Nvector}).
512 '''
513 u = NvectorBase.unit(self, ll=ll)
514 if u.datum != self.datum:
515 u._update(False, datum=self.datum)
516 return u
519def _Ecef():
520 # return the Ecef class and overwrite property_RO
521 Cartesian.Ecef = LatLon.Ecef = E = _MODS.ecef.EcefVeness
522 return E
525def meanOf(points, datum=_WGS84, height=None, wrap=False,
526 **LatLon_and_kwds):
527 '''Compute the geographic mean of several points.
529 @arg points: Points to be averaged (L{LatLon}[]).
530 @kwarg datum: Optional datum to use (L{Datum}).
531 @kwarg height: Optional height at mean point, overriding the mean
532 height (C{meter}).
533 @kwarg wrap: If C{True}, wrap or I{normalize} B{C{points}} (C{bool}).
534 @kwarg LatLon_and_kwds: Optional B{C{LatLon}} class to return the mean
535 points (or C{None}) and additional B{C{LatLon}} keyword
536 arguments, ignored if C{B{LatLon} is None}.
538 @return: Geographic mean point and height (B{C{LatLon}}) or if C{B{LatLon}
539 is None}, an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M,
540 datum)} with C{C} and C{M} if available.
542 @raise ValueError: Insufficient number of B{C{points}}.
543 '''
544 Ps = _Nv00.PointsIter(points, wrap=wrap)
545 n = sumOf(p._N_vector for p in Ps.iterate(closed=False))
546 return n.toLatLon(**_xkwds(LatLon_and_kwds, height=height, datum=datum,
547 LatLon=LatLon, name__=meanOf))
550def nearestOn(point, point1, point2, within=True, height=None, wrap=False,
551 equidistant=None, tol=_TOL_M, LatLon=LatLon, **LatLon_kwds):
552 '''I{Iteratively} locate the closest point on the geodesic between
553 two other (ellipsoidal) points.
555 @arg point: Reference point (C{LatLon}).
556 @arg point1: Start point of the geodesic (C{LatLon}).
557 @arg point2: End point of the geodesic (C{LatLon}).
558 @kwarg within: If C{True}, return the closest point I{between}
559 B{C{point1}} and B{C{point2}}, otherwise the
560 closest point elsewhere on the geodesic (C{bool}).
561 @kwarg height: Optional height for the closest point (C{meter},
562 conventionally) or C{None} or C{False} for the
563 interpolated height. If C{False}, the closest
564 takes the heights of the points into account.
565 @kwarg wrap: If C{True}, wrap or I{normalize} and unroll I{only}
566 B{C{point1}} and B{C{point2}} (C{bool}).
567 @kwarg equidistant: An azimuthal equidistant projection (I{class}
568 or function L{pygeodesy.equidistant}) or C{None}
569 for the preferred C{B{point}.Equidistant}.
570 @kwarg tol: Convergence tolerance (C{meter}).
571 @kwarg LatLon: Optional class to return the closest point
572 (L{LatLon}) or C{None}.
573 @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword
574 arguments, ignored if C{B{LatLon} is None}.
576 @return: Closest point, a B{C{LatLon}} instance or if C{B{LatLon}
577 is None}, a L{LatLon4Tuple}C{(lat, lon, height, datum)}.
579 @raise ImportError: Package U{geographiclib
580 <https://PyPI.org/project/geographiclib>}
581 not installed or not found.
583 @raise TypeError: Invalid or non-ellipsoidal B{C{point}}, B{C{point1}}
584 or B{C{point2}} or invalid B{C{equidistant}}.
586 @raise ValueError: No convergence for the B{C{tol}}.
588 @see: U{The B{ellipsoidal} case<https://GIS.StackExchange.com/questions/48937/
589 calculating-intersection-of-two-circles>} and U{Karney's paper
590 <https://ArXiv.org/pdf/1102.1215.pdf>}, pp 20-21, section B{14. MARITIME
591 BOUNDARIES} for more details about the iteration algorithm.
592 '''
593 return _nearestOn(point, point1, point2, within=within, height=height, wrap=wrap,
594 equidistant=equidistant, tol=tol, LatLon=LatLon, **LatLon_kwds)
597def sumOf(nvectors, Vector=Nvector, h=None, **Vector_kwds):
598 '''Return the vectorial sum of two or more n-vectors.
600 @arg nvectors: Vectors to be added (C{Nvector}[]).
601 @kwarg Vector: Optional class for the vectorial sum (C{Nvector}).
602 @kwarg h: Optional height, overriding the mean height (C{meter}).
603 @kwarg Vector_kwds: Optional, additional B{C{Vector}} keyword
604 arguments, ignored if C{B{Vector} is None}.
606 @return: Vectorial sum (B{C{Vector}}).
608 @raise VectorError: No B{C{nvectors}}.
609 '''
610 return _sumOf(nvectors, Vector=Vector, h=h, **Vector_kwds)
613@deprecated_function
614def toNed(distance, bearing, elevation, Ned=Ned, **name):
615 '''DEPRECATED, use L{pygeodesy.Aer}C{(bearing, elevation,
616 distance).xyzLocal.toNed(B{Ned}, name=B{name})} or
617 L{XyzLocal}C{(pygeodesy.Aer(bearing, elevation,
618 distance)).toNed(B{Ned}, name=B{name})}.
620 Create an NED vector from distance, bearing and elevation
621 (in local coordinate system).
623 @arg distance: NED vector length (C{meter}).
624 @arg bearing: NED vector bearing (compass C{degrees360}).
625 @arg elevation: NED vector elevation from local coordinate
626 frame horizontal (C{degrees}).
627 @kwarg Ned: Optional class to return the NED (C{Ned}) or
628 C{None}.
629 @kwarg name: Optional C{B{name}=NN} (C{str}).
631 @return: An NED vector equivalent to this B{C{distance}},
632 B{C{bearing}} and B{C{elevation}} (DEPRECATED L{Ned})
633 or a DEPRECATED L{Ned3Tuple}C{(north, east, down)}
634 if C{B{Ned} is None}.
636 @raise ValueError: Invalid B{C{distance}}, B{C{bearing}}
637 or B{C{elevation}}.
638 '''
639 if True: # use new Aer class
640 n, e, d, _ = _Aer(bearing, elevation, distance).xyz4
641 else: # DEPRECATED
642 d = Distance(distance)
644 sb, cb, se, ce = sincos2d_(Bearing(bearing),
645 Height(elevation=elevation))
646 n = cb * d * ce
647 e = sb * d * ce
648 d *= se
650 r = _MODS.deprecated.classes.Ned3Tuple(n, e, -d) if Ned is None else \
651 Ned(n, e, -d)
652 return _xnamed(r, name)
655__all__ += _ALL_OTHER(Cartesian, LatLon, Ned, Nvector, # classes
656 meanOf, sumOf, toNed)
658# **) MIT License
659#
660# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
661#
662# Permission is hereby granted, free of charge, to any person obtaining a
663# copy of this software and associated documentation files (the "Software"),
664# to deal in the Software without restriction, including without limitation
665# the rights to use, copy, modify, merge, publish, distribute, sublicense,
666# and/or sell copies of the Software, and to permit persons to whom the
667# Software is furnished to do so, subject to the following conditions:
668#
669# The above copyright notice and this permission notice shall be included
670# in all copies or substantial portions of the Software.
671#
672# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
673# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
674# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
675# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
676# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
677# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
678# OTHER DEALINGS IN THE SOFTWARE.