Coverage for pygeodesy/cartesianBase.py: 95%
202 statements
« prev ^ index » next coverage.py v7.2.2, created at 2023-04-02 08:40 -0400
« prev ^ index » next coverage.py v7.2.2, created at 2023-04-02 08:40 -0400
2# -*- coding: utf-8 -*-
4u'''(INTERNAL) Private base classes for elliposiodal, spherical and N-/vectorial
5C{Cartesian}s.
7After I{(C) Chris Veness 2011-2015} published under the same MIT Licence**,
8see U{https://www.Movable-Type.co.UK/scripts/latlong.html},
9U{https://www.Movable-Type.co.UK/scripts/latlong-vectors.html} and
10U{https://www.Movable-Type.co.UK/scripts/geodesy/docs/latlon-ellipsoidal.js.html}..
11'''
13# from pygeodesy.basics import _xinstanceof # from .datums
14from pygeodesy.constants import EPS0, isnear0, _1_0, _N_1_0, _2_0, _4_0, _6_0
15from pygeodesy.datums import Datum, _spherical_datum, _WGS84, _xinstanceof
16from pygeodesy.errors import _IsnotError, _ValueError, _xdatum, _xkwds
17from pygeodesy.fmath import cbrt, hypot_, hypot2, sqrt # hypot
18from pygeodesy.fsums import Fmt, fsum_
19from pygeodesy.interns import NN, _COMMASPACE_, _height_, _not_
20from pygeodesy.interns import _ellipsoidal_, _spherical_ # PYCHOK used!
21from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS
22from pygeodesy.namedTuples import Bearing2Tuple, Height, LatLon4Tuple, Vector4Tuple, \
23 Vector3Tuple # PYCHOK .ellipsoidal-, .sphericalBase
24from pygeodesy.props import deprecated_method, Property, Property_RO, \
25 property_doc_, _update_all
26# from pygeodesy.resections impoty cassini, collins5, pierlot, tienstra7
27# from pygeodesy.streprs import Fmt # from .fsums
28# from pygeodesy.units import Height # from .namedTuples
29from pygeodesy.vector3d import Vector3d, _xyzhdn3
31# from math import sqrt # from .fmath
33__all__ = _ALL_LAZY.cartesianBase
34__version__ = '22.11.03'
37class CartesianBase(Vector3d):
38 '''(INTERNAL) Base class for ellipsoidal and spherical C{Cartesian}.
39 '''
40 _datum = None # L{Datum}, to be overriden
41 _height = None # height (L{Height}), set or approximated
43 def __init__(self, x_xyz, y=None, z=None, datum=None, ll=None, name=NN):
44 '''New C{Cartesian...}.
46 @arg x_xyz: Cartesian X coordinate (C{scalar}) or a C{Cartesian},
47 L{Ecef9Tuple}, L{Vector3Tuple} or L{Vector4Tuple}.
48 @kwarg y: Cartesian Y coordinate (C{scalar}), ignored if B{C{x_xyz}}
49 is not C{scalar}, otherwise same units as B{C{x_xyz}}.
50 @kwarg z: Cartesian Z coordinate (C{scalar}), ignored if B{C{x_xyz}}
51 is not C{scalar}, otherwise same units as B{C{x_xyz}}.
52 @kwarg datum: Optional datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2}
53 or L{a_f2Tuple}).
54 @kwarg ll: Optional, original latlon (C{LatLon}).
55 @kwarg name: Optional name (C{str}).
57 @raise TypeError: Non-scalar B{C{x_xyz}}, B{C{y}} or B{C{z}}
58 coordinate or B{C{x_xyz}} not an L{Ecef9Tuple},
59 L{Vector3Tuple} or L{Vector4Tuple}.
60 '''
61 h, d, n = _xyzhdn3(x_xyz, None, datum, ll)
62 Vector3d.__init__(self, x_xyz, y=y, z=z, ll=ll, name=name or n)
63 if h is not None:
64 self._height = Height(h)
65 if d is not None:
66 self.datum = d
68# def __matmul__(self, other): # PYCHOK Python 3.5+
69# '''Return C{NotImplemented} for C{c_ = c @ datum} and C{c_ = c @ transform}.
70# '''
71# return NotImplemented if isinstance(other, (Datum, Transform)) else \
72# _NotImplemented(self, other)
74 def cassini(self, pointB, pointC, alpha, beta, useZ=False):
75 '''3-Point resection between this and 2 other points using U{Cassini
76 <https://NL.WikiPedia.org/wiki/Achterwaartse_insnijding>}'s method.
78 @arg pointB: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple},
79 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}).
80 @arg pointC: Center point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple},
81 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}).
82 @arg alpha: Angle subtended by triangle side C{b} from B{C{pointA}} to
83 B{C{pointC}} (C{degrees}, non-negative).
84 @arg beta: Angle subtended by triangle side C{a} from B{C{pointB}} to
85 B{C{pointC}} (C{degrees}, non-negative).
86 @kwarg useZ: If C{True}, use and interpolate the Z component, otherwise
87 force C{z=INT0} (C{bool}).
89 @note: Typically, B{C{pointC}} is between this and B{C{pointB}}.
91 @return: The survey point, an instance of this (sub-)class.
93 @raise ResectionError: Near-coincident, -colinear or -concyclic points
94 or negative or invalid B{C{alpha}} or B{C{beta}}.
96 @raise TypeError: Invalid B{C{pointA}}, B{C{pointB}} or B{C{pointM}}.
98 @see: U{Three Point Resection Problem<https://Dokumen.tips/documents/
99 three-point-resection-problem-introduction-kaestner-burkhardt-method.html>}
100 and function L{pygeodesy.cassini}.
101 '''
102 return _MODS.resections.cassini(self, pointB, pointC, alpha, beta,
103 useZ=useZ, datum=self.datum)
105 @deprecated_method
106 def collins(self, pointB, pointC, alpha, beta, useZ=False):
107 '''DEPRECATED, use method L{collins5}.'''
108 return self.collins5(pointB, pointC, alpha, beta, useZ=useZ)
110 def collins5(self, pointB, pointC, alpha, beta, useZ=False):
111 '''3-Point resection between this and 2 other points using U{Collins<https://Dokumen.tips/
112 documents/three-point-resection-problem-introduction-kaestner-burkhardt-method.html>}' method.
114 @arg pointB: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple},
115 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}).
116 @arg pointC: Center point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple},
117 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}).
118 @arg alpha: Angle subtended by triangle side C{b} from B{C{pointA}} to
119 B{C{pointC}} (C{degrees}, non-negative).
120 @arg beta: Angle subtended by triangle side C{a} from B{C{pointB}} to
121 B{C{pointC}} (C{degrees}, non-negative).
122 @kwarg useZ: If C{True}, use and interpolate the Z component, otherwise
123 force C{z=INT0} (C{bool}).
125 @note: Typically, B{C{pointC}} is between this and B{C{pointB}}.
127 @return: L{Collins5Tuple}C{(pointP, pointH, a, b, c)} with survey C{pointP},
128 auxiliary C{pointH}, each an instance of this (sub-)class and
129 triangle sides C{a}, C{b} and C{c}.
131 @raise ResectionError: Near-coincident, -colinear or -concyclic points
132 or negative or invalid B{C{alpha}} or B{C{beta}}.
134 @raise TypeError: Invalid B{C{pointB}} or B{C{pointM}}.
136 @see: U{Collins' methode<https://NL.WikiPedia.org/wiki/Achterwaartse_insnijding>}
137 and function L{pygeodesy.collins5}.
138 '''
139 return _MODS.resections.collins5(self, pointB, pointC, alpha, beta,
140 useZ=useZ, datum=self.datum)
142 @property_doc_(''' this cartesian's datum (L{Datum}).''')
143 def datum(self):
144 '''Get this cartesian's datum (L{Datum}).
145 '''
146 return self._datum
148 @datum.setter # PYCHOK setter!
149 def datum(self, datum):
150 '''Set this cartesian's C{datum} I{without conversion}
151 (L{Datum}), ellipsoidal or spherical.
153 @raise TypeError: The B{C{datum}} is not a L{Datum}.
154 '''
155 d = _spherical_datum(datum, name=self.name)
156 if self._datum: # is not None
157 if self._datum.isEllipsoidal and not d.isEllipsoidal:
158 raise _IsnotError(_ellipsoidal_, datum=datum)
159 elif self._datum.isSpherical and not d.isSpherical:
160 raise _IsnotError(_spherical_, datum=datum)
161 if self._datum != d:
162 _update_all(self)
163 self._datum = d
165 def destinationXyz(self, delta, Cartesian=None, **Cartesian_kwds):
166 '''Calculate the destination using a I{local} delta from this cartesian.
168 @arg delta: Local delta to the destination (L{XyzLocal}, L{Enu},
169 L{Ned} or L{Local9Tuple}).
170 @kwarg Cartesian: Optional (geocentric) class to return the
171 destination or C{None}.
172 @kwarg Cartesian_kwds: Optional, additional B{C{Cartesian}} keyword
173 arguments, ignored if C{B{Cartesian} is None}.
175 @return: Destination as a C{B{Cartesian}(x, y, z, **B{Cartesian_kwds})}
176 instance or if C{B{Cartesian} is None}, an L{Ecef9Tuple}C{(x, y,
177 z, lat, lon, height, C, M, datum)} with C{M=None} always.
179 @raise TypeError: Invalid B{C{delta}}, B{C{Cartesian}} or
180 B{C{Cartesian_kwds}}.
181 '''
182 if Cartesian is None:
183 r = self._ltp._local2ecef(delta, nine=True)
184 else:
185 r = self._ltp._local2ecef(delta, nine=False)
186 r = Cartesian(*r, **_xkwds(Cartesian_kwds, datum=self.datum))
187 return r._xnamed(r) if self.name else r
189 @Property_RO
190 def Ecef(self):
191 '''Get the ECEF I{class} (L{EcefKarney}), I{lazily}.
192 '''
193 return _MODS.ecef.EcefKarney # default
195 @Property_RO
196 def _ecef9(self):
197 '''(INTERNAL) Helper for L{toEcef}, L{toLocal} and L{toLtp} (L{Ecef9Tuple}).
198 '''
199 return self.Ecef(self.datum, name=self.name).reverse(self, M=True)
201 def hartzell(self, los=None, earth=None):
202 '''Compute the intersection of a Line-Of-Sight (los) from this certesian
203 Point-Of-View (pov) with this cartesian's ellipsoid surface.
205 @kwarg los: Line-Of-Sight, I{direction} to earth (L{Vector3d}) or
206 C{None} to point to the ellipsoid's center.
207 @kwarg earth: The earth model (L{Datum}, L{Ellipsoid}, L{Ellipsoid2},
208 L{a_f2Tuple} or C{scalar} radius in C{meter}) overriding
209 this cartesian's C{datum} ellipsoid.
211 @return: The ellipsoid intersection (C{Cartesian}).
213 @raise IntersectionError: Null C{pov} or B{C{los}} vector, this C{pov}
214 is inside the ellipsoid or B{C{los}} points
215 outside the ellipsoid or in an opposite direction.
217 @raise TypeError: Invalid B{C{los}} or no B{C{datum}}.
219 @see: Function C{hartzell} for further details.
220 '''
221 return _MODS.formy.hartzell(self, los=los, earth=earth or self.datum)
223 @Property
224 def height(self):
225 '''Get the height (C{meter}).
226 '''
227 return self._height4.h if self._height is None else self._height
229 @height.setter # PYCHOK setter!
230 def height(self, height):
231 '''Set the height (C{meter}).
233 @raise TypeError: Invalid B{C{height}} C{type}.
235 @raise ValueError: Invalid B{C{height}}.
236 '''
237 h = Height(height)
238 if self._height != h:
239 _update_all(self)
240 self._height = h
242 @Property_RO
243 def _height4(self):
244 '''(INTERNAL) Get this C{height4}-tuple.
245 '''
246 try:
247 r = self.datum.ellipsoid.height4(self, normal=True)
248 except (AttributeError, ValueError): # no datum, null cartesian,
249 r = Vector4Tuple(self.x, self.y, self.z, 0, name=self.height4.__name__)
250 return r
252 def height4(self, earth=None, normal=True, Cartesian=None, **Cartesian_kwds):
253 '''Compute the height of this cartesian above or below and the projection
254 on this datum's ellipsoid surface.
256 @kwarg earth: A datum, ellipsoid, triaxial ellipsoid or earth radius
257 I{overriding} this datum (L{Datum}, L{Ellipsoid},
258 L{Ellipsoid2}, L{a_f2Tuple}, L{Triaxial}, L{Triaxial_},
259 L{JacobiConformal} or C{meter}, conventionally).
260 @kwarg normal: If C{True} the projection is the nearest point on the
261 ellipsoid's surface, otherwise the intersection of the
262 radial line to the center and the ellipsoid's surface.
263 @kwarg Cartesian: Optional class to return the height and projection
264 (C{Cartesian}) or C{None}.
265 @kwarg Cartesian_kwds: Optional, additional B{C{Cartesian}} keyword
266 arguments, ignored if C{B{Cartesian} is None}.
268 @note: Use keyword argument C{height=0} to override C{B{Cartesian}.height}
269 to {0} or any other C{scalar}, conventionally in C{meter}.
271 @return: An instance of B{C{Cartesian}} or if C{B{Cartesian} is None}, a
272 L{Vector4Tuple}C{(x, y, z, h)} with the I{projection} C{x}, C{y}
273 and C{z} coordinates and height C{h} in C{meter}, conventionally.
275 @raise TriaxialError: No convergence in triaxial root finding.
277 @raise TypeError: Invalid B{C{earth}}.
279 @see: L{Ellipsoid.height4} and L{Triaxial_.height4} for more information.
280 '''
281 d = self.datum if earth is None else earth
282 if normal and d == self.datum:
283 r = self._height4
284 elif isinstance(d, _MODS.triaxials.Triaxial_):
285 r = d.height4(self, normal=normal)
286 else:
287 r = _spherical_datum(d).ellipsoid.height4(self, normal=normal)
288 if Cartesian is not None:
289 kwds = Cartesian_kwds.copy()
290 h = kwds.pop(_height_, None)
291 r = Cartesian(r, **kwds)
292 if h is not None:
293 r.height = Height(height=h)
294 return r
296 @Property_RO
297 def isEllipsoidal(self):
298 '''Check whether this cartesian is ellipsoidal (C{bool} or C{None} if unknown).
299 '''
300 return self.datum.isEllipsoidal if self._datum else None
302 @Property_RO
303 def isSpherical(self):
304 '''Check whether this cartesian is spherical (C{bool} or C{None} if unknown).
305 '''
306 return self.datum.isSpherical if self._datum else None
308 @Property_RO
309 def latlon(self):
310 '''Get this cartesian's (geodetic) lat- and longitude in C{degrees} (L{LatLon2Tuple}C{(lat, lon)}).
311 '''
312 return self.toEcef().latlon
314 @Property_RO
315 def latlonheight(self):
316 '''Get this cartesian's (geodetic) lat-, longitude in C{degrees} with height (L{LatLon3Tuple}C{(lat, lon, height)}).
317 '''
318 return self.toEcef().latlonheight
320 @Property_RO
321 def latlonheightdatum(self):
322 '''Get this cartesian's (geodetic) lat-, longitude in C{degrees} with height and datum (L{LatLon4Tuple}C{(lat, lon, height, datum)}).
323 '''
324 return self.toEcef().latlonheightdatum
326 @Property_RO
327 def _ltp(self):
328 '''(INTERNAL) Cache for L{toLtp}.
329 '''
330 return _MODS.ltp.Ltp(self._ecef9, ecef=self.Ecef(self.datum), name=self.name)
332 @Property_RO
333 def _N_vector(self):
334 '''(INTERNAL) Get the (C{nvectorBase._N_vector_}).
335 '''
336 x, y, z, h = self._n_xyzh4(self.datum)
337 return _MODS.nvectorBase._N_vector_(x, y, z, h=h, name=self.name)
339 def _n_xyzh4(self, datum):
340 '''(INTERNAL) Get the n-vector components as L{Vector4Tuple}.
341 '''
342 def _ErrorEPS0(x):
343 return _ValueError(origin=self, txt=Fmt.PARENTSPACED(EPS0=x))
345 _xinstanceof(Datum, datum=datum)
346 # <https://www.Movable-Type.co.UK/scripts/geodesy/docs/
347 # latlon-nvector-ellipsoidal.js.html#line309>,
348 # <https://GitHub.com/pbrod/nvector>/src/nvector/core.py>
349 # _equation23 and <https://www.NavLab.net/nvector>
350 E = datum.ellipsoid
351 x, y, z = self.xyz
353 # Kenneth Gade eqn 23
354 p = hypot2(x, y) * E.a2_
355 q = (z**2 * E.e21) * E.a2_
356 r = fsum_(p, q, -E.e4) / _6_0
357 s = (p * q * E.e4) / (_4_0 * r**3)
358 t = cbrt(fsum_(_1_0, s, sqrt(s * (_2_0 + s))))
359 if isnear0(t):
360 raise _ErrorEPS0(t)
362 u = r * fsum_(_1_0, t, _1_0 / t)
363 v = sqrt(u**2 + E.e4 * q)
364 t = v * _2_0
365 if t < EPS0: # isnear0
366 raise _ErrorEPS0(t)
367 w = E.e2 * fsum_(u, v, -q) / t
369 k = sqrt(fsum_(u, v, w**2)) - w
370 if isnear0(k):
371 raise _ErrorEPS0(k)
372 t = k + E.e2
373 if isnear0(t):
374 raise _ErrorEPS0(t)
375 e = k / t
376# d = e * hypot(x, y)
378# tmp = 1 / hypot(d, z) == 1 / hypot(e * hypot(x, y), z)
379 t = hypot_(x * e, y * e, z) # == 1 / tmp
380 if t < EPS0: # isnear0
381 raise _ErrorEPS0(t)
382 h = fsum_(k, E.e2, _N_1_0) / k * t
383 s = e / t # == e * tmp
384 return Vector4Tuple(x * s, y * s, z / t, h, name=self.name)
386 @Property_RO
387 def philam(self):
388 '''Get this cartesian's (geodetic) lat- and longitude in C{radians} (L{PhiLam2Tuple}C{(phi, lam)}).
389 '''
390 return self.toEcef().philam
392 @Property_RO
393 def philamheight(self):
394 '''Get this cartesian's (geodetic) lat-, longitude in C{radians} with height (L{PhiLam3Tuple}C{(phi, lam, height)}).
395 '''
396 return self.toEcef().philamheight
398 @Property_RO
399 def philamheightdatum(self):
400 '''Get this cartesian's (geodetic) lat-, longitude in C{radians} with height and datum (L{PhiLam4Tuple}C{(phi, lam, height, datum)}).
401 '''
402 return self.toEcef().philamheightdatum
404 def pierlot(self, point2, point3, alpha12, alpha23, useZ=False):
405 '''3-Point resection between this and two other points using U{Pierlot
406 <http://www.Telecom.ULg.ac.Be/triangulation>}'s method C{ToTal}.
408 @arg point2: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple},
409 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}).
410 @arg point3: Third point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple},
411 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}).
412 @arg alpha12: Angle subtended from this point to B{C{point2}} (C{degrees}).
413 @arg alpha23: Angle subtended from B{C{point2}} to B{C{point3}} (C{degrees}).
414 @kwarg useZ: If C{True}, interpolate the Z component, otherwise use C{z=INT0}
415 (C{bool}).
417 @note: This point, B{C{point2}} and B{C{point3}} are ordered counter-clockwise.
419 @return: The survey (or robot) point, an instance of this (sub-)class.
421 @raise ResectionError: Near-coincident, -colinear or -concyclic points
422 or invalid B{C{alpha12}} or B{C{alpha23}}.
424 @raise TypeError: Invalid B{C{point2}} or B{C{point3}}.
426 @see: U{V. Pierlot, M. Van Droogenbroeck, "A New Three Object Triangulation
427 Algorithm for Mobile Robot Positioning"<https://ORBi.ULiege.Be/
428 bitstream/2268/157469/1/Pierlot2014ANewThree.pdf>}, U{18 Triangulation
429 Algorithms for 2D Positioning (also known as the Resection Problem)
430 <http://www.Telecom.ULg.ac.Be/triangulation>} and functions
431 L{pygeodesy.pierlot}.
432 '''
433 return _MODS.resections.pierlot(self, point2, point3, alpha12, alpha23,
434 useZ=useZ, datum=self.datum)
436 @deprecated_method
437 def tienstra(self, pointB, pointC, alpha, beta=None, gamma=None, useZ=False):
438 '''DEPRECATED, use method L{tienstra7}.'''
439 return self.tienstra7(pointB, pointC, alpha, beta=beta, gamma=gamma, useZ=useZ)
441 def tienstra7(self, pointB, pointC, alpha, beta=None, gamma=None, useZ=False):
442 '''3-Point resection between this and two other points using U{Tienstra
443 <https://WikiPedia.org/wiki/Tienstra_formula>}'s formula.
445 @arg pointB: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, C{Vector4Tuple} or
446 C{Vector2Tuple} if C{B{useZ}=False}).
447 @arg pointC: Third point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, C{Vector4Tuple} or
448 C{Vector2Tuple} if C{B{useZ}=False}).
449 @arg alpha: Angle subtended by triangle side C{a} from B{C{pointB}} to B{C{pointC}} (C{degrees},
450 non-negative).
451 @kwarg beta: Angle subtended by triangle side C{b} from this to B{C{pointC}} (C{degrees},
452 non-negative) or C{None} if C{B{gamma} is not None}.
453 @kwarg gamma: Angle subtended by triangle side C{c} from this to B{C{pointB}} (C{degrees},
454 non-negative) or C{None} if C{B{beta} is not None}.
455 @kwarg useZ: If C{True}, use and interpolate the Z component, otherwise force C{z=INT0}
456 (C{bool}).
458 @note: This point, B{C{pointB}} and B{C{pointC}} are ordered clockwise.
460 @return: L{Tienstra7Tuple}C{(pointP, A, B, C, a, b, c)} with survey C{pointP},
461 an instance of this (sub-)class and triangle angle C{A} at this point,
462 C{B} at B{C{pointB}} and C{C} at B{C{pointC}} in C{degrees} and
463 triangle sides C{a}, C{b} and C{c}.
465 @raise ResectionError: Near-coincident, -colinear or -concyclic points or sum of
466 B{C{alpha}}, B{C{beta}} and B{C{gamma}} not C{360} or
467 negative B{C{alpha}}, B{C{beta}} or B{C{gamma}}.
469 @raise TypeError: Invalid B{C{pointB}} or B{C{pointC}}.
471 @see: U{3-Point Resection Solver<http://MesaMike.org/geocache/GC1B0Q9/tienstra/>},
472 U{V. Pierlot, M. Van Droogenbroeck, "A New Three Object Triangulation..."
473 <http://www.Telecom.ULg.ac.Be/publi/publications/pierlot/Pierlot2014ANewThree/>},
474 U{18 Triangulation Algorithms...<http://www.Telecom.ULg.ac.Be/triangulation/>}
475 and function L{pygeodesy.tienstra7}.
476 '''
477 return _MODS.resections.tienstra7(self, pointB, pointC, alpha, beta, gamma,
478 useZ=useZ, datum=self.datum)
480 @deprecated_method
481 def to2ab(self): # PYCHOK no cover
482 '''DEPRECATED, use property C{philam}.
484 @return: A L{PhiLam2Tuple}C{(phi, lam)}.
485 '''
486 return self.philam
488 @deprecated_method
489 def to2ll(self): # PYCHOK no cover
490 '''DEPRECATED, use property C{latlon}.
492 @return: A L{LatLon2Tuple}C{(lat, lon)}.
493 '''
494 return self.latlon
496 @deprecated_method
497 def to3llh(self, datum=None): # PYCHOK no cover
498 '''DEPRECATED, use property L{latlonheightdatum} or L{latlonheight}.
500 @return: A L{LatLon4Tuple}C{(lat, lon, height, datum)}.
502 @note: This method returns a B{C{-4Tuple}} I{and not a} C{-3Tuple}
503 as its name may suggest.
504 '''
505 t = self.toLatLon(datum=datum, LatLon=None)
506 return LatLon4Tuple(t.lat, t.lon, t.height, t.datum, name=self.name)
508# def _to3LLh(self, datum, LL, **pairs): # OBSOLETE
509# '''(INTERNAL) Helper for C{subclass.toLatLon} and C{.to3llh}.
510# '''
511# r = self.to3llh(datum) # LatLon3Tuple
512# if LL is not None:
513# r = LL(r.lat, r.lon, height=r.height, datum=datum, name=self.name)
514# for n, v in pairs.items():
515# setattr(r, n, v)
516# return r
518 def toDatum(self, datum2, datum=None):
519 '''Convert this cartesian from one datum to an other.
521 @arg datum2: Datum to convert I{to} (L{Datum}).
522 @kwarg datum: Datum to convert I{from} (L{Datum}).
524 @return: The converted point (C{Cartesian}).
526 @raise TypeError: B{C{datum2}} or B{C{datum}}
527 invalid.
528 '''
529 _xinstanceof(Datum, datum2=datum2)
531 c = self if datum in (None, self.datum) else \
532 self.toDatum(datum)
534 i, d = False, c.datum
535 if d == datum2:
536 return c.copy() if c is self else c
538 elif d == _WGS84:
539 d = datum2 # convert from WGS84 to datum2
541 elif datum2 == _WGS84:
542 i = True # convert to WGS84 by inverse transformation
544 else: # neither datum2 nor c.datum is WGS84, invert to WGS84 first
545 c = c.toTransform(d.transform, inverse=True, datum=_WGS84)
546 d = datum2
548 return c.toTransform(d.transform, inverse=i, datum=datum2)
550 convertDatum = toDatum # for backward compatibility
552 def toEcef(self):
553 '''Convert this cartesian to I{geodetic} (lat-/longitude) coordinates.
555 @return: An L{Ecef9Tuple}C{(x, y, z, lat, lon, height,
556 C, M, datum)} with C{C} and C{M} if available.
558 @raise EcefError: A C{.datum} or an ECEF issue.
559 '''
560 return self._ecef9
562 def toLatLon(self, datum=None, height=None, LatLon=None, **LatLon_kwds): # see .ecef.Ecef9Tuple.toDatum
563 '''Convert this cartesian to a geodetic (lat-/longitude) point.
565 @kwarg datum: Optional datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2}
566 or L{a_f2Tuple}).
567 @kwarg height: Optional height, overriding the converted height
568 (C{meter}), iff B{C{LatLon}} is not C{None}.
569 @kwarg LatLon: Optional class to return the geodetic point
570 (C{LatLon}) or C{None}.
571 @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword
572 arguments, ignored if C{B{LatLon} is None}.
574 @return: The geodetic point (B{C{LatLon}}) or if B{C{LatLon}}
575 is C{None}, an L{Ecef9Tuple}C{(x, y, z, lat, lon,
576 height, C, M, datum)} with C{C} and C{M} if available.
578 @raise TypeError: Invalid B{C{datum}} or B{C{LatLon_kwds}}.
579 '''
580 d = _spherical_datum(datum or self.datum, name=self.name)
581 if d == self.datum:
582 r = self.toEcef()
583 else:
584 c = self.toDatum(d)
585 r = c.Ecef(d, name=self.name).reverse(c, M=LatLon is None)
587 if LatLon: # class or .classof
588 h = r.height if height is None else Height(height)
589 r = LatLon(r.lat, r.lon, datum=r.datum, height=h,
590 **_xkwds(LatLon_kwds, name=r.name))
591 _xdatum(r.datum, d)
592 return r
594 def toLocal(self, Xyz=None, ltp=None, **Xyz_kwds):
595 '''Convert this I{geocentric} cartesian to I{local} C{X}, C{Y} and C{Z}.
597 @kwarg Xyz: Optional class to return C{X}, C{Y} and C{Z}
598 (L{XyzLocal}, L{Enu}, L{Ned}) or C{None}.
599 @kwarg ltp: The I{local tangent plane} (LTP) to use,
600 overriding this cartesian's LTP (L{Ltp}).
601 @kwarg Xyz_kwds: Optional, additional B{C{Xyz}} keyword
602 arguments, ignored if C{B{Xyz} is None}.
604 @return: An B{C{Xyz}} instance or if C{B{Xyz} is None},
605 a L{Local9Tuple}C{(x, y, z, lat, lon, height,
606 ltp, ecef, M)} with C{M=None} always.
608 @raise TypeError: Invalid B{C{ltp}}.
609 '''
610 p = _MODS.ltp._xLtp(ltp, self._ltp)
611 return p._ecef2local(self._ecef9, Xyz, Xyz_kwds)
613 def toLtp(self, Ecef=None):
614 '''Return the I{local tangent plane} (LTP) for this cartesian.
616 @kwarg Ecef: Optional ECEF I{class} (L{EcefKarney}, ...
617 L{EcefYou}), overriding this cartesian's C{Ecef}.
618 '''
619 return self._ltp if Ecef in (None, self.Ecef) else _MODS.ltp.Ltp(
620 self._ecef9, ecef=Ecef(self.datum), name=self.name)
622 def toNvector(self, Nvector=None, datum=None, **Nvector_kwds):
623 '''Convert this cartesian to C{n-vector} components.
625 @kwarg Nvector: Optional class to return the C{n-vector}
626 components (C{Nvector}) or C{None}.
627 @kwarg datum: Optional datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2}
628 or L{a_f2Tuple}) overriding this cartesian's datum.
629 @kwarg Nvector_kwds: Optional, additional B{C{Nvector}} keyword
630 arguments, ignored if C{B{Nvector} is None}.
632 @return: The C{unit, n-vector} components (B{C{Nvector}}) or a
633 L{Vector4Tuple}C{(x, y, z, h)} if B{C{Nvector}} is C{None}.
635 @raise TypeError: Invalid B{C{datum}}.
637 @raise ValueError: The B{C{Cartesian}} at origin.
639 @example:
641 >>> c = Cartesian(3980581, 97, 4966825)
642 >>> n = c.toNvector() # (x=0.622818, y=0.00002, z=0.782367, h=0.242887)
643 '''
644 d = _spherical_datum(datum or self.datum, name=self.name)
645 r = self._N_vector.xyzh if self.datum == d else self._n_xyzh4(d)
647 if Nvector is not None:
648 kwds = _xkwds(Nvector_kwds, h=r.h, datum=d)
649 r = self._xnamed(Nvector(r.x, r.y, r.z, **kwds))
650 return r
652 def toStr(self, prec=3, fmt=Fmt.SQUARE, sep=_COMMASPACE_): # PYCHOK expected
653 '''Return the string representation of this cartesian.
655 @kwarg prec: Number of (decimal) digits, unstripped (C{int}).
656 @kwarg fmt: Enclosing backets format (string).
657 @kwarg sep: Separator to join (string).
659 @return: Cartesian represented as "[x, y, z]" (string).
660 '''
661 return Vector3d.toStr(self, prec=prec, fmt=fmt, sep=sep)
663 def toTransform(self, transform, inverse=False, datum=None):
664 '''Return a new cartesian by applying a Helmert transform
665 to this cartesian.
667 @arg transform: Transform to apply (L{Transform}).
668 @kwarg inverse: Apply the inverse of the Helmert
669 transform (C{bool}).
670 @kwarg datum: Datum for the transformed cartesian (L{Datum}),
671 overriding this cartesian's datum.
673 @return: The transformed cartesian (C{Cartesian}).
675 @raise Valuerror: If C{B{inverse}=True} and B{C{datum}}
676 is not L{Datums}C{.WGS84}.
677 '''
678 d = datum or self.datum
679 if inverse and d != _WGS84:
680 raise _ValueError(inverse=inverse, datum=d,
681 txt=_not_(_WGS84.name))
683 xyz = transform.transform(*self.xyz, inverse=inverse)
684 return self.classof(xyz, datum=d)
686 def toVector(self, Vector=None, **Vector_kwds):
687 '''Return this cartesian's components as vector.
689 @kwarg Vector: Optional class to return the C{n-vector}
690 components (L{Vector3d}) or C{None}.
691 @kwarg Vector_kwds: Optional, additional B{C{Vector}} keyword
692 arguments, ignored if C{B{Vector} is None}.
694 @return: A B{C{Vector}} or a L{Vector3Tuple}C{(x, y, z)} if
695 B{C{Vector}} is C{None}.
697 @raise TypeError: Invalid B{C{Vector}} or B{C{Vector_kwds}}.
698 '''
699 return self.xyz if Vector is None else self._xnamed(
700 Vector(self.x, self.y, self.z, **Vector_kwds))
703__all__ += _ALL_DOCS(CartesianBase)
705# **) MIT License
706#
707# Copyright (C) 2016-2023 -- mrJean1 at Gmail -- All Rights Reserved.
708#
709# Permission is hereby granted, free of charge, to any person obtaining a
710# copy of this software and associated documentation files (the "Software"),
711# to deal in the Software without restriction, including without limitation
712# the rights to use, copy, modify, merge, publish, distribute, sublicense,
713# and/or sell copies of the Software, and to permit persons to whom the
714# Software is furnished to do so, subject to the following conditions:
715#
716# The above copyright notice and this permission notice shall be included
717# in all copies or substantial portions of the Software.
718#
719# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
720# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
721# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
722# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
723# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
724# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
725# OTHER DEALINGS IN THE SOFTWARE.