Coverage for pygeodesy/cartesianBase.py: 92%

332 statements  

« prev     ^ index     » next       coverage.py v7.2.2, created at 2024-06-27 20:21 -0400

1 

2# -*- coding: utf-8 -*- 

3 

4u'''(INTERNAL) Private C{CartesianBase} class for elliposiodal, spherical and N-/vectorial 

5C{Cartesian}s and public functions L{rtp2xyz}, L{rtp2xyz_}, L{xyz2rtp} and L{xyz2rtp_}. 

6 

7After I{(C) Chris Veness 2011-2015} published under the same MIT Licence**, see 

8U{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''' 

12 

13# from pygeodesy.basics import _xinstanceof # from .datums 

14from pygeodesy.constants import EPS, EPS0, INT0, PI2, _isfinite, isnear0, \ 

15 _0_0, _1_0, _N_1_0, _2_0, _4_0, _6_0 

16from pygeodesy.datums import Datum, _earth_ellipsoid, _spherical_datum, \ 

17 Transform, _WGS84, _xinstanceof 

18# from pygeodesy.ecef import EcefKarney # _MODS 

19from pygeodesy.errors import _IsnotError, _TypeError, _ValueError, _xattr, \ 

20 _xdatum, _xkwds, _xkwds_get, _xkwds_pop2 

21from pygeodesy.fmath import cbrt, hypot, hypot_, hypot2, fabs, sqrt # hypot 

22# from pygeodesy.formy import _hartzell # _MODS 

23from pygeodesy.fsums import fsumf_, Fmt 

24from pygeodesy.interns import _COMMASPACE_, _datum_, _no_, _phi_ 

25from pygeodesy.interns import _ellipsoidal_, _spherical_ # PYCHOK used! 

26from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS 

27from pygeodesy.named import _name2__, _Pass 

28from pygeodesy.namedTuples import LatLon4Tuple, _NamedTupleTo , Vector3Tuple, \ 

29 Vector4Tuple, Bearing2Tuple # PYCHOK .sphericalBase 

30# from pygeodesy.nvectorBase import _N_vector # _MODS 

31from pygeodesy.props import deprecated_method, Property, Property_RO, \ 

32 property_doc_, property_RO, _update_all 

33# from pygeodesy,resections import cassini, collins5, pierlot, pierlotx, \ 

34# tienstra7 # _MODS 

35# from pygeodesy.streprs import Fmt # from .fsums 

36# from pygeodesy.triaxials import Triaxial_ # _MODS 

37from pygeodesy.units import Degrees, Height, _heigHt, _isMeter, Meter, Radians 

38from pygeodesy.utily import acos1, sincos2d, sincos2_, atan2, degrees, radians 

39from pygeodesy.vector3d import Vector3d, _xyzhdlln4 

40# from pygeodesy.vector3dBase import _xyz3 # _MODS 

41# from pygeodesy import ltp # _MODS 

42 

43# from math import atan2, degrees, fabs, radians, sqrt # from .fmath, .utily 

44 

45__all__ = _ALL_LAZY.cartesianBase 

46__version__ = '24.06.11' 

47 

48_r_ = 'r' 

49_theta_ = 'theta' 

50 

51 

52class CartesianBase(Vector3d): 

53 '''(INTERNAL) Base class for ellipsoidal and spherical C{Cartesian}. 

54 ''' 

55 _datum = None # L{Datum}, to be overriden 

56 _height = None # height (L{Height}), set or approximated 

57 

58 def __init__(self, x_xyz, y=None, z=None, datum=None, **ll_name): 

59 '''New C{Cartesian...}. 

60 

61 @arg x_xyz: Cartesian X coordinate (C{scalar}) or a C{Cartesian}, 

62 L{Ecef9Tuple}, L{Vector3Tuple} or L{Vector4Tuple}. 

63 @kwarg y: Cartesian Y coordinate (C{scalar}), ignored if B{C{x_xyz}} 

64 is not C{scalar}, otherwise same units as B{C{x_xyz}}. 

65 @kwarg z: Cartesian Z coordinate (C{scalar}), like B{C{y}}. 

66 @kwarg datum: Optional datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2} 

67 or L{a_f2Tuple}). 

68 @kwarg ll_name: Optional C{B{name}=NN} (C{str}) and optional, original 

69 latlon C{B{ll}=None} (C{LatLon}). 

70 

71 @raise TypeError: Non-scalar B{C{x_xyz}}, B{C{y}} or B{C{z}} coordinate 

72 or B{C{x_xyz}} not a C{Cartesian}, L{Ecef9Tuple}, 

73 L{Vector3Tuple} or L{Vector4Tuple} or B{C{datum}} is 

74 not a L{Datum}. 

75 ''' 

76 h, d, ll, n = _xyzhdlln4(x_xyz, None, datum, **ll_name) 

77 Vector3d.__init__(self, x_xyz, y=y, z=z, ll=ll, name=n) 

78 if h is not None: 

79 self._height = Height(h) 

80 if d is not None: 

81 self.datum = d 

82 

83# def __matmul__(self, other): # PYCHOK Python 3.5+ 

84# '''Return C{NotImplemented} for C{c_ = c @ datum} and C{c_ = c @ transform}. 

85# ''' 

86# return NotImplemented if isinstance(other, (Datum, Transform)) else \ 

87# _NotImplemented(self, other) 

88 

89 def cassini(self, pointB, pointC, alpha, beta, useZ=False): 

90 '''3-Point resection between this and 2 other points using U{Cassini 

91 <https://NL.WikiPedia.org/wiki/Achterwaartse_insnijding>}'s method. 

92 

93 @arg pointB: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, 

94 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}). 

95 @arg pointC: Center point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, 

96 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}). 

97 @arg alpha: Angle subtended by triangle side C{b} from B{C{pointA}} to 

98 B{C{pointC}} (C{degrees}, non-negative). 

99 @arg beta: Angle subtended by triangle side C{a} from B{C{pointB}} to 

100 B{C{pointC}} (C{degrees}, non-negative). 

101 @kwarg useZ: If C{True}, use and interpolate the Z component, otherwise 

102 force C{z=INT0} (C{bool}). 

103 

104 @note: Typically, B{C{pointC}} is between this and B{C{pointB}}. 

105 

106 @return: The survey point, an instance of this (sub-)class. 

107 

108 @raise ResectionError: Near-coincident, -colinear or -concyclic points 

109 or negative or invalid B{C{alpha}} or B{C{beta}}. 

110 

111 @raise TypeError: Invalid B{C{pointA}}, B{C{pointB}} or B{C{pointM}}. 

112 

113 @see: Function L{pygeodesy.cassini} for references and more details. 

114 ''' 

115 return _MODS.resections.cassini(self, pointB, pointC, alpha, beta, 

116 useZ=useZ, datum=self.datum) 

117 

118 @deprecated_method 

119 def collins(self, pointB, pointC, alpha, beta, useZ=False): 

120 '''DEPRECATED, use method L{collins5}.''' 

121 return self.collins5(pointB, pointC, alpha, beta, useZ=useZ) 

122 

123 def collins5(self, pointB, pointC, alpha, beta, useZ=False): 

124 '''3-Point resection between this and 2 other points using U{Collins<https://Dokumen.tips/ 

125 documents/three-point-resection-problem-introduction-kaestner-burkhardt-method.html>}' method. 

126 

127 @arg pointB: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, 

128 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}). 

129 @arg pointC: Center point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, 

130 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}). 

131 @arg alpha: Angle subtended by triangle side C{b} from B{C{pointA}} to 

132 B{C{pointC}} (C{degrees}, non-negative). 

133 @arg beta: Angle subtended by triangle side C{a} from B{C{pointB}} to 

134 B{C{pointC}} (C{degrees}, non-negative). 

135 @kwarg useZ: If C{True}, use and interpolate the Z component, otherwise 

136 force C{z=INT0} (C{bool}). 

137 

138 @note: Typically, B{C{pointC}} is between this and B{C{pointB}}. 

139 

140 @return: L{Collins5Tuple}C{(pointP, pointH, a, b, c)} with survey C{pointP}, 

141 auxiliary C{pointH}, each an instance of this (sub-)class and 

142 triangle sides C{a}, C{b} and C{c}. 

143 

144 @raise ResectionError: Near-coincident, -colinear or -concyclic points 

145 or negative or invalid B{C{alpha}} or B{C{beta}}. 

146 

147 @raise TypeError: Invalid B{C{pointB}} or B{C{pointM}}. 

148 

149 @see: Function L{pygeodesy.collins5} for references and more details. 

150 ''' 

151 return _MODS.resections.collins5(self, pointB, pointC, alpha, beta, 

152 useZ=useZ, datum=self.datum) 

153 

154 @deprecated_method 

155 def convertDatum(self, datum2, **datum): 

156 '''DEPRECATED, use method L{toDatum}.''' 

157 return self.toDatum(datum2, **datum) 

158 

159 @property_doc_(''' this cartesian's datum (L{Datum}).''') 

160 def datum(self): 

161 '''Get this cartesian's datum (L{Datum}). 

162 ''' 

163 return self._datum 

164 

165 @datum.setter # PYCHOK setter! 

166 def datum(self, datum): 

167 '''Set this cartesian's C{datum} I{without conversion} 

168 (L{Datum}), ellipsoidal or spherical. 

169 

170 @raise TypeError: The B{C{datum}} is not a L{Datum}. 

171 ''' 

172 d = _spherical_datum(datum, name=self.name) 

173 if self._datum: # is not None 

174 if d.isEllipsoidal and not self._datum.isEllipsoidal: 

175 raise _IsnotError(_ellipsoidal_, datum=datum) 

176 elif d.isSpherical and not self._datum.isSpherical: 

177 raise _IsnotError(_spherical_, datum=datum) 

178 if self._datum != d: 

179 _update_all(self) 

180 self._datum = d 

181 

182 def destinationXyz(self, delta, Cartesian=None, **name_Cartesian_kwds): 

183 '''Calculate the destination using a I{local} delta from this cartesian. 

184 

185 @arg delta: Local delta to the destination (L{XyzLocal}, L{Enu}, L{Ned} 

186 or L{Local9Tuple}). 

187 @kwarg Cartesian: Optional (geocentric) class to return the destination 

188 or C{None}. 

189 @kwarg name_Cartesian_kwds: Optional C{B{name}=NN} (C{str}) and optional, 

190 additional B{C{Cartesian}} keyword arguments, ignored if 

191 C{B{Cartesian} is None}. 

192 

193 @return: Destination as a C{B{Cartesian}(x, y, z, **B{Cartesian_kwds})} 

194 instance or if C{B{Cartesian} is None}, an L{Ecef9Tuple}C{(x, y, 

195 z, lat, lon, height, C, M, datum)} with C{M=None} always. 

196 

197 @raise TypeError: Invalid B{C{delta}}, B{C{Cartesian}} or B{C{Cartesian_kwds}} 

198 item or C{datum} missing or incompatible. 

199 ''' 

200 n, kwds = _name2__(name_Cartesian_kwds, _or_nameof=self) 

201 if Cartesian is None: 

202 r = self._Ltp._local2ecef(delta, nine=True) 

203 else: 

204 d = self.datum 

205 if not d: 

206 raise _TypeError(delta=delta, txt=_no_(_datum_)) 

207 t = _xkwds_get(kwds, datum=d) 

208 if _xattr(t, ellipsoid=None) != d.ellipsoid: 

209 raise _TypeError(datum=t, txt=str(d)) 

210 c = self._Ltp._local2ecef(delta, nine=False) 

211 r = Cartesian(*c, **kwds) 

212 return r.renamed(n) if n else r 

213 

214 @property_RO 

215 def Ecef(self): 

216 '''Get the ECEF I{class} (L{EcefKarney}), I{once}. 

217 ''' 

218 CartesianBase.Ecef = E = _MODS.ecef.EcefKarney # overwrite property_RO 

219 return E 

220 

221 @Property_RO 

222 def _ecef9(self): 

223 '''(INTERNAL) Helper for L{toEcef}, L{toLocal} and L{toLtp} (L{Ecef9Tuple}). 

224 ''' 

225 return self.Ecef(self.datum, name=self.name).reverse(self, M=True) 

226 

227 @property_RO 

228 def ellipsoidalCartesian(self): 

229 '''Get the C{Cartesian type} iff ellipsoidal, overloaded in L{CartesianEllipsoidalBase}. 

230 ''' 

231 return False 

232 

233 def hartzell(self, los=False, earth=None): 

234 '''Compute the intersection of a Line-Of-Sight from this cartesian Point-Of-View 

235 (pov) and this cartesian's ellipsoid surface. 

236 

237 @kwarg los: Line-Of-Sight, I{direction} to the ellipsoid (L{Los}, L{Vector3d}), 

238 C{True} for the I{normal, plumb} onto the surface or I{False} or 

239 C{None} to point to the center of the ellipsoid. 

240 @kwarg earth: The earth model (L{Datum}, L{Ellipsoid}, L{Ellipsoid2}, L{a_f2Tuple} 

241 or C{scalar} radius in C{meter}), overriding this cartesian's 

242 C{datum} ellipsoid. 

243 

244 @return: The intersection (C{Cartesian}) with C{.height} set to the distance to 

245 this C{pov}. 

246 

247 @raise IntersectionError: Null or bad C{pov} or B{C{los}}, this C{pov} is inside 

248 the ellipsoid or B{C{los}} points outside or away from 

249 the ellipsoid. 

250 

251 @raise TypeError: Invalid B{C{los}} or invalid or undefined B{C{earth}} or C{datum}. 

252 

253 @see: Function L{hartzell<pygeodesy.formy.hartzell>} for further details. 

254 ''' 

255 return _MODS.formy._hartzell(self, los, earth) 

256 

257 @Property 

258 def height(self): 

259 '''Get the height (C{meter}). 

260 ''' 

261 return self._height4.h if self._height is None else self._height 

262 

263 @height.setter # PYCHOK setter! 

264 def height(self, height): 

265 '''Set the height (C{meter}). 

266 

267 @raise TypeError: Invalid B{C{height}} C{type}. 

268 

269 @raise ValueError: Invalid B{C{height}}. 

270 ''' 

271 h = Height(height) 

272 if self._height != h: 

273 _update_all(self) 

274 self._height = h 

275 

276 def _height2C(self, r, Cartesian=None, datum=None, height=INT0, **kwds): 

277 '''(INTERNAL) Helper for methods C{.height3} and C{.height4}. 

278 ''' 

279 if Cartesian is not None: 

280 r = Cartesian(r, **kwds) 

281 if datum is not None: 

282 r.datum = datum 

283 if height is not None: 

284 r.height = height # Height(height) 

285 return r 

286 

287 def height3(self, earth=None, height=None, **Cartesian_and_kwds): 

288 '''Compute the cartesian at a height above or below this certesian's ellipsoid. 

289 

290 @kwarg earth: A datum, ellipsoid, triaxial ellipsoid or earth radius, 

291 I{overriding} this cartesian's datum (L{Datum}, L{Ellipsoid}, 

292 L{Ellipsoid2}, L{a_f2Tuple} or C{meter}, conventionally). 

293 @kwarg height: The height (C{meter}, conventionally), overriding this 

294 cartesian's height. 

295 @kwarg Cartesian_and_kwds: Optional C{B{Cartesian}=None} class to return 

296 the cartesian I{at height} and additional B{C{Cartesian}} 

297 keyword arguments. 

298 

299 @return: An instance of B{C{Cartesian}} or if C{B{Cartesian} is None}, 

300 a L{Vector3Tuple}C{(x, y, z)} with the C{x}, C{y} and C{z} 

301 coordinates I{at height} in C{meter}, conventionally. 

302 

303 @note: This cartesian's coordinates are returned if B{C{earth}} and this 

304 datum or B{C{heigth}} and/or this height are C{None} or undefined. 

305 

306 @note: Include keyword argument C{B{datum}=None} if class B{C{Cartesian}} 

307 does not accept a B{C{datum}} keyword agument. 

308 

309 @raise TriaxialError: No convergence in triaxial root finding. 

310 

311 @raise TypeError: Invalid or undefined B{C{earth}} or C{datum}. 

312 ''' 

313 n = self.height3.__name__ 

314 d = self.datum if earth is None else _spherical_datum(earth, name=n) 

315 c, h = self, _heigHt(self, height) 

316 if h and d: 

317 R, r = self.Roc2(earth=d) 

318 if R > EPS0: 

319 R = (R + h) / R 

320 r = ((r + h) / r) if r > EPS0 else _1_0 

321 c = c.times_(R, R, r) 

322 

323 r = Vector3Tuple(c.x, c.y, c.z, name=n) 

324 if Cartesian_and_kwds: 

325 r = self._height2C(r, **_xkwds(Cartesian_and_kwds, datum=d)) 

326 return r 

327 

328 @Property_RO 

329 def _height4(self): 

330 '''(INTERNAL) Get this C{height4}-tuple. 

331 ''' 

332 try: 

333 r = self.datum.ellipsoid.height4(self, normal=True) 

334 except (AttributeError, ValueError): # no datum, null cartesian, 

335 r = Vector4Tuple(self.x, self.y, self.z, 0, name__=self.height4) 

336 return r 

337 

338 def height4(self, earth=None, normal=True, **Cartesian_and_kwds): 

339 '''Compute the projection of this point on and the height above or below 

340 this datum's ellipsoid surface. 

341 

342 @kwarg earth: A datum, ellipsoid, triaxial ellipsoid or earth radius, 

343 I{overriding} this datum (L{Datum}, L{Ellipsoid}, 

344 L{Ellipsoid2}, L{a_f2Tuple}, L{Triaxial}, L{Triaxial_}, 

345 L{JacobiConformal} or C{meter}, conventionally). 

346 @kwarg normal: If C{True} the projection is the nearest point on the 

347 ellipsoid's surface, otherwise the intersection of the 

348 radial line to the ellipsoid's center and the surface. 

349 @kwarg Cartesian_and_kwds: Optional C{B{Cartesian}=None} class to return 

350 the I{projection} and additional B{C{Cartesian}} keyword 

351 arguments. 

352 

353 @return: An instance of B{C{Cartesian}} or if C{B{Cartesian} is None}, a 

354 L{Vector4Tuple}C{(x, y, z, h)} with the I{projection} C{x}, C{y} 

355 and C{z} coordinates and height C{h} in C{meter}, conventionally. 

356 

357 @note: Include keyword argument C{B{datum}=None} if class B{C{Cartesian}} 

358 does not accept a B{C{datum}} keyword agument. 

359 

360 @raise TriaxialError: No convergence in triaxial root finding. 

361 

362 @raise TypeError: Invalid or undefined B{C{earth}} or C{datum}. 

363 

364 @see: Methods L{Ellipsoid.height4} and L{Triaxial_.height4} for more information. 

365 ''' 

366 n = self.height4.__name__ 

367 d = self.datum if earth is None else earth 

368 if normal and d is self.datum: 

369 r = self._height4 

370 elif isinstance(d, _MODS.triaxials.Triaxial_): 

371 r = d.height4(self, normal=normal) 

372 try: 

373 d = d.toEllipsoid(name=n) 

374 except (TypeError, ValueError): # TriaxialError 

375 d = None 

376 else: 

377 r = _earth_ellipsoid(d).height4(self, normal=normal) 

378 

379 if Cartesian_and_kwds: 

380 if d and not isinstance(d, Datum): 

381 d = _spherical_datum(d, name=n) 

382 r = self._height2C(r, **_xkwds(Cartesian_and_kwds, datum=d)) 

383 return r 

384 

385 @Property_RO 

386 def isEllipsoidal(self): 

387 '''Check whether this cartesian is ellipsoidal (C{bool} or C{None} if unknown). 

388 ''' 

389 return _xattr(self.datum, isEllipsoidal=None) 

390 

391 @Property_RO 

392 def isSpherical(self): 

393 '''Check whether this cartesian is spherical (C{bool} or C{None} if unknown). 

394 ''' 

395 return _xattr(self.datum, isSpherical=None) 

396 

397 @Property_RO 

398 def latlon(self): 

399 '''Get this cartesian's (geodetic) lat- and longitude in C{degrees} (L{LatLon2Tuple}C{(lat, lon)}). 

400 ''' 

401 return self.toEcef().latlon 

402 

403 @Property_RO 

404 def latlonheight(self): 

405 '''Get this cartesian's (geodetic) lat-, longitude in C{degrees} with height (L{LatLon3Tuple}C{(lat, lon, height)}). 

406 ''' 

407 return self.toEcef().latlonheight 

408 

409 @Property_RO 

410 def latlonheightdatum(self): 

411 '''Get this cartesian's (geodetic) lat-, longitude in C{degrees} with height and datum (L{LatLon4Tuple}C{(lat, lon, height, datum)}). 

412 ''' 

413 return self.toEcef().latlonheightdatum 

414 

415 @Property_RO 

416 def _Ltp(self): 

417 '''(INTERNAL) Cache for L{toLtp}. 

418 ''' 

419 return _MODS.ltp.Ltp(self._ecef9, ecef=self.Ecef(self.datum), name=self.name) 

420 

421 @Property_RO 

422 def _N_vector(self): 

423 '''(INTERNAL) Get the (C{nvectorBase._N_vector_}). 

424 ''' 

425 _N = _MODS.nvectorBase._N_vector_ 

426 x, y, z, h = self._n_xyzh4(self.datum) 

427 return _N(x, y, z, h=h, name=self.name) 

428 

429 def _n_xyzh4(self, datum): 

430 '''(INTERNAL) Get the n-vector components as L{Vector4Tuple}. 

431 ''' 

432 def _ErrorEPS0(x): 

433 return _ValueError(origin=self, txt=Fmt.PARENSPACED(EPS0=x)) 

434 

435 _xinstanceof(Datum, datum=datum) 

436 # <https://www.Movable-Type.co.UK/scripts/geodesy/docs/ 

437 # latlon-nvector-ellipsoidal.js.html#line309>, 

438 # <https://GitHub.com/pbrod/nvector>/src/nvector/core.py> 

439 # _equation23 and <https://www.NavLab.net/nvector> 

440 E = datum.ellipsoid 

441 x, y, z = self.xyz 

442 

443 # Kenneth Gade eqn 23 

444 p = hypot2(x, y) * E.a2_ 

445 q = z**2 * E.e21 * E.a2_ 

446 r = fsumf_(p, q, -E.e4) / _6_0 

447 s = (p * q * E.e4) / (_4_0 * r**3) 

448 t = cbrt(fsumf_(_1_0, s, sqrt(s * (_2_0 + s)))) 

449 if isnear0(t): 

450 raise _ErrorEPS0(t) 

451 u = fsumf_(_1_0, t, _1_0 / t) * r 

452 v = sqrt(u**2 + E.e4 * q) 

453 t = v * _2_0 

454 if t < EPS0: # isnear0 

455 raise _ErrorEPS0(t) 

456 w = fsumf_(u, v, -q) * E.e2 / t 

457 k = sqrt(fsumf_(u, v, w**2)) - w 

458 if isnear0(k): 

459 raise _ErrorEPS0(k) 

460 t = k + E.e2 

461 if isnear0(t): 

462 raise _ErrorEPS0(t) 

463 e = k / t 

464# d = e * hypot(x, y) 

465# tmp = 1 / hypot(d, z) == 1 / hypot(e * hypot(x, y), z) 

466 t = hypot_(x * e, y * e, z) # == 1 / tmp 

467 if t < EPS0: # isnear0 

468 raise _ErrorEPS0(t) 

469 h = fsumf_(k, E.e2, _N_1_0) / k * t 

470 s = e / t # == e * tmp 

471 return Vector4Tuple(x * s, y * s, z / t, h, name=self.name) 

472 

473 @Property_RO 

474 def philam(self): 

475 '''Get this cartesian's (geodetic) lat- and longitude in C{radians} (L{PhiLam2Tuple}C{(phi, lam)}). 

476 ''' 

477 return self.toEcef().philam 

478 

479 @Property_RO 

480 def philamheight(self): 

481 '''Get this cartesian's (geodetic) lat-, longitude in C{radians} with height (L{PhiLam3Tuple}C{(phi, lam, height)}). 

482 ''' 

483 return self.toEcef().philamheight 

484 

485 @Property_RO 

486 def philamheightdatum(self): 

487 '''Get this cartesian's (geodetic) lat-, longitude in C{radians} with height and datum (L{PhiLam4Tuple}C{(phi, lam, height, datum)}). 

488 ''' 

489 return self.toEcef().philamheightdatum 

490 

491 def pierlot(self, point2, point3, alpha12, alpha23, useZ=False, eps=EPS): 

492 '''3-Point resection between this and two other points using U{Pierlot 

493 <http://www.Telecom.ULg.ac.Be/triangulation>}'s method C{ToTal} with 

494 I{approximate} limits for the (pseudo-)singularities. 

495 

496 @arg point2: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, 

497 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}). 

498 @arg point3: Third point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, 

499 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}). 

500 @arg alpha12: Angle subtended from this point to B{C{point2}} or 

501 B{C{alpha2 - alpha}} (C{degrees}). 

502 @arg alpha23: Angle subtended from B{C{point2}} to B{C{point3}} or 

503 B{C{alpha3 - alpha2}} (C{degrees}). 

504 @kwarg useZ: If C{True}, interpolate the Z component, otherwise use C{z=INT0} 

505 (C{bool}). 

506 @kwarg eps: Tolerance for C{cot} (pseudo-)singularities (C{float}). 

507 

508 @note: This point, B{C{point2}} and B{C{point3}} are ordered counter-clockwise. 

509 

510 @return: The survey (or robot) point, an instance of this (sub-)class. 

511 

512 @raise ResectionError: Near-coincident, -colinear or -concyclic points 

513 or invalid B{C{alpha12}} or B{C{alpha23}}. 

514 

515 @raise TypeError: Invalid B{C{point2}} or B{C{point3}}. 

516 

517 @see: Function L{pygeodesy.pierlot} for references and more details. 

518 ''' 

519 return _MODS.resections.pierlot(self, point2, point3, alpha12, alpha23, 

520 useZ=useZ, eps=eps, datum=self.datum) 

521 

522 def pierlotx(self, point2, point3, alpha1, alpha2, alpha3, useZ=False): 

523 '''3-Point resection between this and two other points using U{Pierlot 

524 <http://www.Telecom.ULg.ac.Be/publi/publications/pierlot/Pierlot2014ANewThree>}'s 

525 method C{ToTal} with I{exact} limits for the (pseudo-)singularities. 

526 

527 @arg point2: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, 

528 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}). 

529 @arg point3: Third point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, 

530 C{Vector4Tuple} or C{Vector2Tuple} if C{B{useZ}=False}). 

531 @arg alpha1: Angle at B{C{point1}} (C{degrees}). 

532 @arg alpha2: Angle at B{C{point2}} (C{degrees}). 

533 @arg alpha3: Angle at B{C{point3}} (C{degrees}). 

534 @kwarg useZ: If C{True}, interpolate the survey point's Z component, 

535 otherwise use C{z=INT0} (C{bool}). 

536 

537 @return: The survey (or robot) point, an instance of this (sub-)class. 

538 

539 @raise ResectionError: Near-coincident, -colinear or -concyclic points or 

540 invalid B{C{alpha1}}, B{C{alpha2}} or B{C{alpha3}}. 

541 

542 @raise TypeError: Invalid B{C{point2}} or B{C{point3}}. 

543 

544 @see: Function L{pygeodesy.pierlotx} for references and more details. 

545 ''' 

546 return _MODS.resections.pierlotx(self, point2, point3, alpha1, alpha2, alpha3, 

547 useZ=useZ, datum=self.datum) 

548 

549 def Roc2(self, earth=None): 

550 '''Compute this cartesian's I{normal} and I{pseudo, z-based} radius of curvature. 

551 

552 @kwarg earth: A datum, ellipsoid, triaxial ellipsoid or earth radius, 

553 I{overriding} this cartesian's datum (L{Datum}, L{Ellipsoid}, 

554 L{Ellipsoid2}, L{a_f2Tuple} or C{meter}, conventionally). 

555 

556 @return: 2-Tuple C{(R, r)} with the I{normal} and I{pseudo, z-based} radius of 

557 curvature C{R} respectively C{r}, both in C{meter} conventionally. 

558 

559 @raise TypeError: Invalid or undefined B{C{earth}} or C{datum}. 

560 ''' 

561 r = z = fabs( self.z) 

562 R, _0 = hypot(self.x, self.y), EPS0 

563 if R < _0: # polar 

564 R = z 

565 elif z > _0: # non-equatorial 

566 d = self.datum if earth is None else _spherical_datum(earth) 

567 e = self.toLatLon(datum=d, height=0, LatLon=None) # Ecef9Tuple 

568 M = e.M # EcefMatrix 

569 sa, ca = map(fabs, (M._2_2_, M._2_1_) if M else sincos2d(e.lat)) 

570 if ca < _0: # polar 

571 R = z 

572 else: # prime-vertical, normal roc R 

573 R = R / ca # /= chokes PyChecker 

574 r = R if sa < _0 else (r / sa) # non-/equatorial 

575 return R, r 

576 

577 @property_RO 

578 def sphericalCartesian(self): 

579 '''Get the C{Cartesian type} iff spherical, overloaded in L{CartesianSphericalBase}. 

580 ''' 

581 return False 

582 

583 @deprecated_method 

584 def tienstra(self, pointB, pointC, alpha, beta=None, gamma=None, useZ=False): 

585 '''DEPRECATED, use method L{tienstra7}.''' 

586 return self.tienstra7(pointB, pointC, alpha, beta=beta, gamma=gamma, useZ=useZ) 

587 

588 def tienstra7(self, pointB, pointC, alpha, beta=None, gamma=None, useZ=False): 

589 '''3-Point resection between this and two other points using U{Tienstra 

590 <https://WikiPedia.org/wiki/Tienstra_formula>}'s formula. 

591 

592 @arg pointB: Second point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, C{Vector4Tuple} or 

593 C{Vector2Tuple} if C{B{useZ}=False}). 

594 @arg pointC: Third point (C{Cartesian}, L{Vector3d}, C{Vector3Tuple}, C{Vector4Tuple} or 

595 C{Vector2Tuple} if C{B{useZ}=False}). 

596 @arg alpha: Angle subtended by triangle side C{a} from B{C{pointB}} to B{C{pointC}} (C{degrees}, 

597 non-negative). 

598 @kwarg beta: Angle subtended by triangle side C{b} from this to B{C{pointC}} (C{degrees}, 

599 non-negative) or C{None} if C{B{gamma} is not None}. 

600 @kwarg gamma: Angle subtended by triangle side C{c} from this to B{C{pointB}} (C{degrees}, 

601 non-negative) or C{None} if C{B{beta} is not None}. 

602 @kwarg useZ: If C{True}, use and interpolate the Z component, otherwise force C{z=INT0} 

603 (C{bool}). 

604 

605 @note: This point, B{C{pointB}} and B{C{pointC}} are ordered clockwise. 

606 

607 @return: L{Tienstra7Tuple}C{(pointP, A, B, C, a, b, c)} with survey C{pointP}, 

608 an instance of this (sub-)class and triangle angle C{A} at this point, 

609 C{B} at B{C{pointB}} and C{C} at B{C{pointC}} in C{degrees} and 

610 triangle sides C{a}, C{b} and C{c}. 

611 

612 @raise ResectionError: Near-coincident, -colinear or -concyclic points or sum of 

613 B{C{alpha}}, B{C{beta}} and B{C{gamma}} not C{360} or 

614 negative B{C{alpha}}, B{C{beta}} or B{C{gamma}}. 

615 

616 @raise TypeError: Invalid B{C{pointB}} or B{C{pointC}}. 

617 

618 @see: Function L{pygeodesy.tienstra7} for references and more details. 

619 ''' 

620 return _MODS.resections.tienstra7(self, pointB, pointC, alpha, beta, gamma, 

621 useZ=useZ, datum=self.datum) 

622 

623 @deprecated_method 

624 def to2ab(self): # PYCHOK no cover 

625 '''DEPRECATED, use property C{philam}. 

626 

627 @return: A L{PhiLam2Tuple}C{(phi, lam)}. 

628 ''' 

629 return self.philam 

630 

631 @deprecated_method 

632 def to2ll(self): # PYCHOK no cover 

633 '''DEPRECATED, use property C{latlon}. 

634 

635 @return: A L{LatLon2Tuple}C{(lat, lon)}. 

636 ''' 

637 return self.latlon 

638 

639 @deprecated_method 

640 def to3llh(self, datum=None): # PYCHOK no cover 

641 '''DEPRECATED, use property L{latlonheight} or L{latlonheightdatum}. 

642 

643 @return: A L{LatLon4Tuple}C{(lat, lon, height, datum)}. 

644 

645 @note: This method returns a B{C{-4Tuple}} I{and not a} C{-3Tuple} 

646 as its name may suggest. 

647 ''' 

648 t = self.toLatLon(datum=datum, LatLon=None) 

649 return LatLon4Tuple(t.lat, t.lon, t.height, t.datum, name=self.name) 

650 

651# def _to3LLh(self, datum, LL, **pairs): # OBSOLETE 

652# '''(INTERNAL) Helper for C{subclass.toLatLon} and C{.to3llh}. 

653# ''' 

654# r = self.to3llh(datum) # LatLon3Tuple 

655# if LL is not None: 

656# r = LL(r.lat, r.lon, height=r.height, datum=datum, name=self.name) 

657# for n, v in pairs.items(): 

658# setattr(r, n, v) 

659# return r 

660 

661 def toDatum(self, datum2, datum=None): 

662 '''Convert this cartesian from one datum to an other. 

663 

664 @arg datum2: Datum to convert I{to} (L{Datum}). 

665 @kwarg datum: Datum to convert I{from} (L{Datum}). 

666 

667 @return: The converted point (C{Cartesian}). 

668 

669 @raise TypeError: B{C{datum2}} or B{C{datum}} 

670 invalid. 

671 ''' 

672 _xinstanceof(Datum, datum2=datum2) 

673 

674 c = self if datum in (None, self.datum) else \ 

675 self.toDatum(datum) 

676 

677 i, d = False, c.datum 

678 if d == datum2: 

679 return c.copy() if c is self else c 

680 

681 elif d is None or (d.transform.isunity and 

682 datum2.transform.isunity): 

683 return c.dup(datum=datum2) 

684 

685 elif d == _WGS84: 

686 d = datum2 # convert from WGS84 to datum2 

687 

688 elif datum2 == _WGS84: 

689 i = True # convert to WGS84 by inverse transformation 

690 

691 else: # neither datum2 nor c.datum is WGS84, invert to WGS84 first 

692 c = c.toTransform(d.transform, inverse=True, datum=_WGS84) 

693 d = datum2 

694 

695 return c.toTransform(d.transform, inverse=i, datum=datum2) 

696 

697 def toEcef(self): 

698 '''Convert this cartesian to I{geodetic} (lat-/longitude) coordinates. 

699 

700 @return: An L{Ecef9Tuple}C{(x, y, z, lat, lon, height, 

701 C, M, datum)} with C{C} and C{M} if available. 

702 

703 @raise EcefError: A C{.datum} or an ECEF issue. 

704 ''' 

705 return self._ecef9 

706 

707 def toLatLon(self, datum=None, height=None, LatLon=None, **LatLon_kwds): # see .ecef.Ecef9Tuple.toDatum 

708 '''Convert this cartesian to a I{geodetic} (lat-/longitude) point. 

709 

710 @kwarg datum: Optional datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2} 

711 or L{a_f2Tuple}). 

712 @kwarg height: Optional height, overriding the converted height 

713 (C{meter}), only if C{B{LatLon} is not None}. 

714 @kwarg LatLon: Optional class to return the geodetic point 

715 (C{LatLon}) or C{None}. 

716 @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword 

717 arguments, ignored if C{B{LatLon} is None}. 

718 

719 @return: The geodetic point (B{C{LatLon}}) or if C{B{LatLon} 

720 is None}, an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, 

721 C, M, datum)} with C{C} and C{M} if available. 

722 

723 @raise TypeError: Invalid B{C{datum}} or B{C{LatLon_kwds}}. 

724 ''' 

725 d = _spherical_datum(datum or self.datum, name=self.name) 

726 if d == self.datum: 

727 r = self.toEcef() 

728 else: 

729 c = self.toDatum(d) 

730 r = c.Ecef(d, name=self.name).reverse(c, M=LatLon is None) 

731 

732 if LatLon: # class or .classof 

733 h = _heigHt(r, height) 

734 r = LatLon(r.lat, r.lon, datum=r.datum, height=h, 

735 **_xkwds(LatLon_kwds, name=r.name)) 

736 _xdatum(r.datum, d) 

737 return r 

738 

739 def toLocal(self, Xyz=None, ltp=None, **Xyz_kwds): 

740 '''Convert this I{geocentric} cartesian to I{local} C{X}, C{Y} and C{Z}. 

741 

742 @kwarg Xyz: Optional class to return C{X}, C{Y} and C{Z} (L{XyzLocal}, 

743 L{Enu}, L{Ned}) or C{None}. 

744 @kwarg ltp: The I{local tangent plane} (LTP) to use, overriding this 

745 cartesian's LTP (L{Ltp}). 

746 @kwarg Xyz_kwds: Optional, additional B{C{Xyz}} keyword arguments, 

747 ignored if C{B{Xyz} is None}. 

748 

749 @return: An B{C{Xyz}} instance or a L{Local9Tuple}C{(x, y, z, lat, lon, 

750 height, ltp, ecef, M)} if C{B{Xyz} is None} (with C{M=None}). 

751 

752 @raise TypeError: Invalid B{C{ltp}}. 

753 ''' 

754 return _MODS.ltp._toLocal(self, ltp, Xyz, Xyz_kwds) # self._ecef9 

755 

756 def toLtp(self, Ecef=None, **name): 

757 '''Return the I{local tangent plane} (LTP) for this cartesian. 

758 

759 @kwarg Ecef: Optional ECEF I{class} (L{EcefKarney}, ... 

760 L{EcefYou}), overriding this cartesian's C{Ecef}. 

761 @kwarg name: Optional C{B{name}=NN} (C{str}). 

762 ''' 

763 return _MODS.ltp._toLtp(self, Ecef, self._ecef9, name) # self._Ltp 

764 

765 def toNvector(self, Nvector=None, datum=None, **name_Nvector_kwds): 

766 '''Convert this cartesian to C{n-vector} components, I{including height}. 

767 

768 @kwarg Nvector: Optional class to return the C{n-vector} components 

769 (C{Nvector}) or C{None}. 

770 @kwarg datum: Optional datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2} 

771 or L{a_f2Tuple}) overriding this cartesian's datum. 

772 @kwarg name_Nvector_kwds: Optional C{B{name}=NN} (C{str}) and optional, 

773 additional B{C{Nvector}} keyword arguments, ignored if 

774 C{B{Nvector} is None}. 

775 

776 @return: An B{C{Nvector}} or a L{Vector4Tuple}C{(x, y, z, h)} if 

777 C{B{Nvector} is None}. 

778 

779 @raise TypeError: Invalid B{C{Nvector}}, B{C{datum}} or 

780 B{C{name_Nvector_kwds}} item. 

781 

782 @raise ValueError: B{C{Cartesian}} at origin. 

783 ''' 

784 r, d = self._N_vector.xyzh, self.datum 

785 if datum is not None: 

786 d = _spherical_datum(datum, name=self.name) 

787 if d != self.datum: 

788 r = self._n_xyzh4(d) 

789 

790 if Nvector is None: 

791 n, _ = _name2__(name_Nvector_kwds, _or_nameof=self) 

792 if n: 

793 r = r.dup(name=n) 

794 else: 

795 kwds = _xkwds(name_Nvector_kwds, h=r.h, datum=d) 

796 r = Nvector(r.x, r.y, r.z, **self._name1__(kwds)) 

797 return r 

798 

799 def toRtp(self): 

800 '''Convert this cartesian to I{spherical, polar} coordinates. 

801 

802 @return: L{RadiusThetaPhi3Tuple}C{(r, theta, phi)} with C{theta} 

803 and C{phi}, both in L{Degrees}. 

804 

805 @see: Function L{xyz2rtp_} and class L{RadiusThetaPhi3Tuple}. 

806 ''' 

807 return _rtp3(self.toRtp, Degrees, self, name=self.name) 

808 

809 def toStr(self, prec=3, fmt=Fmt.SQUARE, sep=_COMMASPACE_): # PYCHOK expected 

810 '''Return the string representation of this cartesian. 

811 

812 @kwarg prec: Number of (decimal) digits, unstripped (C{int}). 

813 @kwarg fmt: Enclosing backets format (C{letter}). 

814 @kwarg sep: Separator to join (C{str}). 

815 

816 @return: Cartesian represented as "[x, y, z]" (C{str}). 

817 ''' 

818 return Vector3d.toStr(self, prec=prec, fmt=fmt, sep=sep) 

819 

820 def toTransform(self, transform, inverse=False, datum=None): 

821 '''Apply a Helmert transform to this cartesian. 

822 

823 @arg transform: Transform to apply (L{Transform} or L{TransformXform}). 

824 @kwarg inverse: Apply the inverse of the C{B{transform}} (C{bool}). 

825 @kwarg datum: Datum for the transformed cartesian (L{Datum}), overriding 

826 this cartesian's datum but I{not} taken it into account. 

827 

828 @return: A transformed cartesian (C{Cartesian}) or a copy of this 

829 cartesian if C{B{transform}.isunity}. 

830 

831 @raise TypeError: Invalid B{C{transform}}. 

832 ''' 

833 _xinstanceof(Transform, transform=transform) 

834 if transform.isunity: 

835 c = self.dup(datum=datum or self.datum) 

836 else: 

837 # if inverse and d != _WGS84: 

838 # raise _ValueError(inverse=inverse, datum=d, 

839 # txt_not_=_WGS84.name) 

840 xyz = transform.transform(*self.xyz, inverse=inverse) 

841 c = self.dup(xyz=xyz, datum=datum or self.datum) 

842 return c 

843 

844 def toVector(self, Vector=None, **Vector_kwds): 

845 '''Return this cartesian's I{geocentric} components as vector. 

846 

847 @kwarg Vector: Optional class to return the I{geocentric} 

848 components (L{Vector3d}) or C{None}. 

849 @kwarg Vector_kwds: Optional, additional B{C{Vector}} keyword 

850 arguments, ignored if C{B{Vector} is None}. 

851 

852 @return: A B{C{Vector}} or a L{Vector3Tuple}C{(x, y, z)} if 

853 C{B{Vector} is None}. 

854 

855 @raise TypeError: Invalid B{C{Vector}} or B{C{Vector_kwds}}. 

856 ''' 

857 return self.xyz if Vector is None else Vector( 

858 self.x, self.y, self.z, **self._name1__(Vector_kwds)) 

859 

860 

861class RadiusThetaPhi3Tuple(_NamedTupleTo): 

862 '''3-Tuple C{(r, theta, phi)} with radial distance C{r} in C{meter}, inclination 

863 C{theta} (with respect to the positive z-axis) and azimuthal angle C{phi} in 

864 L{Degrees} I{or} L{Radians} representing a U{spherical, polar position 

865 <https://WikiPedia.org/wiki/Spherical_coordinate_system>}. 

866 ''' 

867 _Names_ = (_r_, _theta_, _phi_) 

868 _Units_ = ( Meter, _Pass, _Pass) 

869 

870 def toCartesian(self, **name_Cartesian_and_kwds): 

871 '''Convert this L{RadiusThetaPhi3Tuple} to a cartesian C{(x, y, z)} vector. 

872 

873 @kwarg name_Cartesian_and_kwds: Optional C{B{name}=NN}, overriding this 

874 name and optional class C{B{Cartesian}=None} and additional 

875 C{B{Cartesian}} keyword arguments. 

876 

877 @return: A C{B{Cartesian}(x, y, z)} instance or if no C{B{Cartesian}} keyword 

878 argument is given, a L{Vector3Tuple}C{(x, y, z)} with C{x}, C{y} 

879 and C{z} in the same units as radius C{r}, C{meter} conventionally. 

880 

881 @see: Function L{rtp2xyz_}. 

882 ''' 

883 r, t, p = self 

884 t, p, _ = _NamedTupleTo._Radians3(self, t, p) 

885 return rtp2xyz_(r, t, p, **name_Cartesian_and_kwds) 

886 

887 def toDegrees(self, **name): 

888 '''Convert this L{RadiusThetaPhi3Tuple}'s angles to L{Degrees}. 

889 

890 @kwarg name: Optional C{B{name}=NN} (C{str}), overriding this name. 

891 

892 @return: L{RadiusThetaPhi3Tuple}C{(r, theta, phi)} with C{theta} 

893 and C{phi} both in L{Degrees}. 

894 ''' 

895 return self._toX3U(_NamedTupleTo._Degrees3, Degrees, name) 

896 

897 def toRadians(self, **name): 

898 '''Convert this L{RadiusThetaPhi3Tuple}'s angles to L{Radians}. 

899 

900 @kwarg name: Optional C{B{name}=NN} (C{str}), overriding this name. 

901 

902 @return: L{RadiusThetaPhi3Tuple}C{(r, theta, phi)} with C{theta} 

903 and C{phi} both in L{Radians}. 

904 ''' 

905 return self._toX3U(_NamedTupleTo._Radians3, Radians, name) 

906 

907 def _toU(self, U): 

908 M = RadiusThetaPhi3Tuple._Units_[0] # Meter 

909 return self.reUnit(M, U, U).toUnits() 

910 

911 def _toX3U(self, _X3, U, name): 

912 r, t, p = self 

913 t, p, s = _X3(self, t, p) 

914 if s is None or name: 

915 n = self._name__(name) 

916 s = self.classof(r, t, p, name=n)._toU(U) 

917 return s 

918 

919 

920def rtp2xyz(r_rtp, theta=0, phi=0, **name_Cartesian_and_kwds): 

921 '''Convert I{spherical, polar} C{(r, theta, phi)} to cartesian C{(x, y, z)} coordinates. 

922 

923 @arg theta: Inclination B{C{theta}} (C{degrees} with respect to the positive z-axis), 

924 required if C{B{r_rtp}} is C{scalar}, ignored otherwise. 

925 @arg phi: Azimuthal angle B{C{phi}} (C{degrees}), like B{C{theta}}. 

926 

927 @see: Function L{rtp2xyz_} for further details. 

928 ''' 

929 if isinstance(r_rtp, RadiusThetaPhi3Tuple): 

930 c = r_rtp.toCartesian(**name_Cartesian_and_kwds) 

931 else: 

932 c = rtp2xyz_(r_rtp, radians(theta), radians(phi), **name_Cartesian_and_kwds) 

933 return c 

934 

935 

936def rtp2xyz_(r_rtp, theta=0, phi=0, **name_Cartesian_and_kwds): 

937 '''Convert I{spherical, polar} C{(r, theta, phi)} to cartesian C{(x, y, z)} coordinates. 

938 

939 @arg r_rtp: Radial distance (C{scalar}, conventially C{meter}) or a previous 

940 L{RadiusThetaPhi3Tuple} instance. 

941 @arg theta: Inclination B{C{theta}} (C{radians} with respect to the positive z-axis), 

942 required if C{B{r_rtp}} is C{scalar}, ignored otherwise. 

943 @arg phi: Azimuthal angle B{C{phi}} (C{radians}), like B{C{theta}}. 

944 @kwarg name_Cartesian_and_kwds: Optional C{B{name}=NN} (C{str}), a C{B{Cartesian}=None} 

945 class to return the coordinates and optional, additional C{B{Cartesian}} 

946 keyword arguments. 

947 

948 @return: A C{B{Cartesian}(x, y, z)} instance or if no C{B{Cartesian}} keyword argument 

949 is given a L{Vector3Tuple}C{(x, y, z)}, with C{x}, C{y} and C{z} in the same 

950 units as radius C{r}, C{meter} conventionally. 

951 

952 @raise TypeError: Invalid B{C{r_rtp}}, B{C{theta}}, B{C{phi}} or 

953 B{C{name_Cartesian_and_kwds}} item. 

954 

955 @see: U{Physics convention<https://WikiPedia.org/wiki/Spherical_coordinate_system>} 

956 (ISO 80000-2:2019), class L{RadiusThetaPhi3Tuple} and functions L{rtp2xyz} 

957 and L{xyz2rtp}. 

958 ''' 

959 if isinstance(r_rtp, RadiusThetaPhi3Tuple): 

960 c = r_rtp.toCartesian(**name_Cartesian_and_kwds) 

961 elif _isMeter(r_rtp): 

962 r = r_rtp 

963 if r and _isfinite(r): 

964 s, z, y, x = sincos2_(theta, phi) 

965 s *= r 

966 z *= r 

967 y *= s 

968 x *= s 

969 else: 

970 x = y = z = r 

971 

972 n, kwds = _name2__(**name_Cartesian_and_kwds) 

973 C, kwds = _xkwds_pop2(kwds, Cartesian=None) 

974 c = Vector3Tuple(x, y, z, name=n) if C is None else \ 

975 C(x, y, z, name=n, **kwds) 

976 else: 

977 raise _TypeError(r_rtp=r_rtp, theta=theta, phi=phi) 

978 return c 

979 

980 

981def _rtp3(where, U, *x_y_z, **name): 

982 '''(INTERNAL) Helper for C{.toRtp}, C{xyz2rtp} and C{xyz2rtp_}. 

983 ''' 

984 x, y, z = _MODS.vector3dBase._xyz3(where, *x_y_z) 

985 r = hypot_(x, y, z) 

986 if r > 0: 

987 t = acos1(z / r) 

988 p = atan2(y, x) 

989 while p < 0: 

990 p += PI2 

991 if U is Degrees: 

992 t = degrees(t) 

993 p = degrees(p) 

994 else: 

995 t = p = _0_0 

996 return RadiusThetaPhi3Tuple(r, t, p, **name)._toU(U) 

997 

998 

999def xyz2rtp(x_xyz, y=0, z=0, **name): 

1000 '''Convert cartesian C{(x, y, z)} to I{spherical, polar} C{(r, theta, phi)} coordinates. 

1001 

1002 @return: L{RadiusThetaPhi3Tuple}C{(r, theta, phi)} with C{theta} and C{phi}, both 

1003 in L{Degrees}. 

1004 

1005 @see: Function L{xyz2rtp_} for further details. 

1006 ''' 

1007 return _rtp3(xyz2rtp, Degrees, x_xyz, y, z, **name) 

1008 

1009 

1010def xyz2rtp_(x_xyz, y=0, z=0, **name): 

1011 '''Convert cartesian C{(x, y, z)} to I{spherical, polar} C{(r, theta, phi)} coordinates. 

1012 

1013 @arg x_xyz: X component (C{scalar}) or a cartesian (C{Cartesian}, L{Ecef9Tuple}, 

1014 C{Nvector}, L{Vector3d}, L{Vector3Tuple}, L{Vector4Tuple} or a C{tuple} or 

1015 C{list} of 3+ C{scalar} items) if no C{y_z} specified. 

1016 @arg y: Y component (C{scalar}), required if C{B{x_xyz}} is C{scalar}, ignored otherwise. 

1017 @arg z: Z component (C{scalar}), like B{C{y}}. 

1018 @kwarg name: Optional C{B{name}=NN} (C{str}). 

1019 

1020 @return: L{RadiusThetaPhi3Tuple}C{(r, theta, phi)} with radial distance C{r} (C{meter}, 

1021 same units as C{x}, C{y} and C{z}), inclination C{theta} (with respect to the 

1022 positive z-axis) and azimuthal angle C{phi}, both in L{Radians}. 

1023 

1024 @see: U{Physics convention<https://WikiPedia.org/wiki/Spherical_coordinate_system>} 

1025 (ISO 80000-2:2019), class L{RadiusThetaPhi3Tuple} and function L{xyz2rtp}. 

1026 ''' 

1027 return _rtp3(xyz2rtp_, Radians, x_xyz, y, z, **name) 

1028 

1029 

1030__all__ += _ALL_DOCS(CartesianBase) 

1031 

1032# **) MIT License 

1033# 

1034# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved. 

1035# 

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

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

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

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

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

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

1042# 

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

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

1045# 

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

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

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

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

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

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

1052# OTHER DEALINGS IN THE SOFTWARE.