Coverage for pygeodesy/ltpTuples.py: 96%

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

4u'''Named, I{Local Tangent Plane} (LTP) tuples.

6Local coordinate classes L{XyzLocal}, L{Enu}, L{Ned} and L{Aer} and

7local coordinate tuples L{Local9Tuple}, L{Xyz4Tuple}, L{Enu4Tuple},

8L{Ned4Tuple}, L{Aer4Tuple} and L{Footprint5Tuple}.

10@see: References in module L{ltp}.

11'''

13from pygeodesy.basics import issubclassof, typename

14from pygeodesy.constants import _0_0, _1_0, _90_0, _N_90_0

15# from pygeodesy.dms import F_D, toDMS # _MODS

16from pygeodesy.errors import _TypeError, _TypesError, _xattr, _xkwds, \

17 _xkwds_item2

18from pygeodesy.fmath import fdot_, hypot, hypot_

19# rom pygeodesy.internals import typename # from .basics

20from pygeodesy.interns import NN, _4_, _azimuth_, _center_, _COMMASPACE_, \

21 _ecef_, _elevation_, _height_, _lat_, _lon_, \

22 _ltp_, _M_, _name_, _up_, _x_, _xyz_, _y_, _z_

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

24# from pygeodesy.ltp Attitude # _MODS.into

25from pygeodesy.named import _name__, _name1__, _name2__, _NamedBase, \

26 _NamedTuple, _Pass, _xnamed

27from pygeodesy.namedTuples import LatLon2Tuple, PhiLam2Tuple, Vector3Tuple

28from pygeodesy.props import deprecated_method, deprecated_Property_RO, \

29 Property_RO, property_RO

30from pygeodesy.streprs import Fmt, fstr, strs, _xzipairs

31from pygeodesy.units import Azimuth, Bearing, Degrees, Degrees_, Height, \

32 _isDegrees, _isMeter, Lat, Lon, Meter, Meter_

33from pygeodesy.utily import atan2d, atan2b, sincos2_, sincos2d_, cos, radians

34from pygeodesy.vector3d import Vector3d

36# from math import cos, radians # from .utily

38__all__ = _ALL_LAZY.ltpTuples

39__version__ = '26.07.17'

41_aer_ = 'aer'

42_alt_ = 'alt'

43_down_ = 'down'

44_east_ = 'east'

45_enu_ = 'enu'

46_ned_ = 'ned'

47_north_ = 'north'

48_local_ = 'local'

49_ltp = _MODS.into(ltp=__name__)

50_roll_ = 'roll'

51_slantrange_ = 'slantrange'

52_tilt_ = 'tilt'

53_uvw_ = 'uvw'

54_yaw_ = 'yaw'

57class _AbcBase(_NamedBase):

58 '''(INTERNAL) Base class for classes C{Aer} and C{Ned}.

59 '''

60 _ltp = None # local tangent plane (C{Ltp}), origin

62 @Property_RO

63 def ltp(self):

64 '''Get the I{local tangent plane} (L{Ltp}).

65 '''

66 return self._ltp

68 def toAer(self, Aer=None, **name_Aer_kwds):

69 '''Get the I{local} I{Azimuth, Elevation, slant Range} (AER) components.

71 @kwarg Aer: Class to return AER (L{Aer}) or C{None}.

72 @kwarg name_Aer_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

73 additional B{L{Aer}} keyword arguments, ignored if C{B{Aer}

74 is None}.

76 @return: An B{C{Aer}} instance or an L{Aer4Tuple}C{(azimuth, elevation,

77 slantrange, ltp)} if C{B{Aer} is None}.

79 @raise TypeError: Invalid B{C{Aer}} or B{C{name_Aer_kwds}}.

80 '''

81 return self.xyz4._toXyz(Aer, name_Aer_kwds)

83 def toEnu(self, Enu=None, **name_Enu_kwds):

84 '''Get the I{local} I{East, North, Up} (ENU) components.

86 @kwarg Enu: Class to return ENU (L{Enu}) or C{None}.

87 @kwarg name_Enu_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

88 additional B{L{Enu}} keyword arguments, ignored if C{B{Enu}

89 is None}.

91 @return: An B{C{Enu}} instance or an L{Enu4Tuple}C{(east, north, up,

92 ltp)} if C{B{Enu} is None}.

94 @raise TypeError: Invalid B{C{Enu}} or B{C{name_Enu_kwds}}.

95 '''

96 return self.xyz4._toXyz(Enu, name_Enu_kwds)

98 def toNed(self, Ned=None, **name_Ned_kwds):

99 '''Get the I{local} I{North, East, Down} (NED) components.

100

101 @kwarg Ned: Class to return NED (L{Ned}) or C{None}.

102 @kwarg name_Ned_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

103 additional B{L{Ned}} keyword arguments, ignored if C{B{Ned}

104 is None}.

105

106 @return: An B{C{Ned}} instance or an L{Ned4Tuple}C{(north, east, down,

107 ltp)} if C{B{Ned} is None}.

108

109 @raise TypeError: Invalid B{C{Ned}} or B{C{name_Ned_kwds}}.

110 '''

111 return self.xyz4._toXyz(Ned, name_Ned_kwds)

112

113 def toXyz(self, Xyz=None, **name_Xyz_kwds):

114 '''Get the local I{X, Y, Z} (XYZ) components.

115

116 @kwarg Xyz: Class to return XYZ (L{XyzLocal}, L{Enu}, L{Ned}, L{Aer})

117 or C{None}.

118 @kwarg name_Xyz_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

119 additional B{C{Xyz}} keyword arguments, ignored if C{B{Xyz}

120 is None}.

121

122 @return: An B{C{Xyz}} instance or an L{Xyz4Tuple}C{(x, y, z, ltp)} if

123 C{B{Xyz} is None}.

124

125 @raise TypeError: Invalid B{C{Xyz}} or B{C{name_Xyz_kwds}}.

126 '''

127 return self.xyz4._toXyz(Xyz, name_Xyz_kwds)

128

129 @Property_RO

130 def xyz(self):

131 '''Get the I{local} C{(X, Y, Z)} coordinates (L{Vector3Tuple}C{(x, y, z)}).

132 '''

133 return Vector3Tuple(self.x, self.y, self.z, name=self.name) # like Ecef9Tuple.xyz, Local6tuple.xyz

134

135 @property_RO

136 def xyz3(self):

137 '''Get the I{local} C{(X, Y, Z)} coordinates as C{3-tuple}.

138 '''

139 return tuple(self.xyz)

140

141 @property_RO

142 def xyz4(self): # PYCHOK no cover

143 '''I{Must be overloaded}.'''

144 self._notOverloaded()

145

146 @Property_RO

147 def xyzLocal(self):

148 '''Get this AER or NED as an L{XyzLocal}.

149 '''

150 return XyzLocal(self.xyz4, name=self.name)

151

152

153class _Abc4Tuple(_NamedTuple):

154 '''(INTERNAL) Base class for C{Aer4Tuple}, C{Enu4Tuple},

155 C{Ned4Tuple} and C{Xyz4Tuple}.

156 '''

157 def _2Cls(self, Abc, Cls, Cls_kwds):

158 '''(INTERNAL) Convert 4-Tuple to C{Cls} instance.

159 '''

160 _isc = issubclassof

161 kwds = _name1__(Cls_kwds, _or_nameof=self)

162 if Cls is None:

163 n, _ = _name2__(Cls_kwds)

164 r = self.copy(name=n) if n else self

165 elif _isc(Cls, Abc):

166 r = Cls(*self, **kwds)

167 elif _isc(Cls, Aer):

168 r = self.xyzLocal.toAer(**_xkwds(kwds, Aer=Cls))

169 elif _isc(Cls, Enu): # PYCHOK no cover

170 r = self.xyzLocal.toEnu(**_xkwds(kwds, Enu=Cls))

171 elif _isc(Cls, Ned):

172 r = self.xyzLocal.toNed(**_xkwds(kwds, Ned=Cls))

173 elif _isc(Cls, XyzLocal): # PYCHOK no cover

174 r = self.xyzLocal.toXyz(**_xkwds(kwds, Xyz=Cls))

175 elif Cls is Local9Tuple: # PYCHOK no cover

176 r = self.xyzLocal.toLocal9Tuple(**kwds)

177 else: # PYCHOK no cover

178 n = typename(Abc)[:3]

179 raise _TypesError(n, Cls, Aer, Enu, Ned, XyzLocal)

180 return r

181

182 @property_RO

183 def xyzLocal(self): # PYCHOK no cover

184 '''I{Must be overloaded}.'''

185 self._notOverloaded()

186

187

188class Aer(_AbcBase):

189 '''Local C{Azimuth-Elevation-Range} (AER) in a I{local tangent plane}.

190 '''

191 _azimuth = _0_0 # bearing from North (C{degrees360})

192 _elevation = _0_0 # tilt, pitch from horizon (C{degrees}).

193# _ltp = None # local tangent plane (C{Ltp}), origin

194 _slantrange = _0_0 # distance (C{Meter})

195 _toStr = _aer_

196

197 def __init__(self, azimuth_aer, elevation=0, slantrange=0, ltp=None, **name):

198 '''New L{Aer}.

199

200 @arg azimuth_aer: Scalar azimuth, bearing from North (compass C{degrees})

201 or a previous I{local} instance (L{Aer}, L{Aer4Tuple},

202 L{Enu}, L{Enu4Tuple}, L{Local9Tuple}, L{Ned},

203 L{Ned4Tuple}, L{XyzLocal} or L{Xyz4Tuple}).

204 @kwarg elevation: Scalar angle I{above} the horizon, I{above} B{C{ltp}}

205 (C{degrees}, horizon is 0, zenith +90 and nadir -90),

206 only used with scalar B{C{azimuth_aer}}.

207 @kwarg slantrange: Scalar distance (C{meter}), only used with scalar

208 B{C{azimuth_aer}}.

209 @kwarg ltp: The I{local tangent plane}, (geodetic) origin (L{Ltp},

210 L{LocalCartesian}).

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

212

213 @raise TypeError: Invalid B{C{azimuth_aer}} or B{C{ltp}}.

214

215 @raise UnitError: Invalid B{C{azimuth_aer}}, B{C{elevation}} or

216 or B{C{slantrange}}.

217 '''

218 if _isDegrees(azimuth_aer):

219 aer = None

220 t = (Azimuth(azimuth_aer),

221 Degrees_(elevation=elevation, low=_N_90_0, high=_90_0),

222 Meter_(slantrange=slantrange), ltp)

223 else: # PYCHOK no cover

224 p = _xyzLocal(Aer, Aer4Tuple, Ned, azimuth_aer=azimuth_aer)

225 aer = p.toAer() if p else azimuth_aer

226 t = aer.aer4

227 self._azimuth, self._elevation, self._slantrange, _ = t

228 _init(self, aer, ltp, name)

229

230 @Property_RO

231 def aer4(self):

232 '''Get the C{(azimuth, elevation, slantrange, ltp)} components (L{Aer4Tuple}).

233 '''

234 return Aer4Tuple(self.azimuth, self.elevation, self.slantrange, self.ltp, name=self.name)

235

236 @Property_RO

237 def azimuth(self):

238 '''Get the Azimuth, bearing from North (C{degrees360}).

239 '''

240 return self._azimuth

241

242 @Property_RO

243 def down(self):

244 '''Get the Down component (C{meter}).

245 '''

246 return self.xyzLocal.down

247

248 @Property_RO

249 def east(self):

250 '''Get the East component (C{meter}).

251 '''

252 return self.xyzLocal.east

253

254 @Property_RO

255 def elevation(self):

256 '''Get the Elevation, tilt above horizon (C{degrees90}).

257 '''

258 return self._elevation

259

260 @Property_RO

261 def groundrange(self):

262 '''Get the I{ground range}, distance (C{meter}).

263 '''

264 return _er2gr(self._elevation, self._slantrange)

265

266 @Property_RO

267 def north(self):

268 '''Get the North component (C{meter}).

269 '''

270 return self.xyzLocal.north

271

272 @Property_RO

273 def slantrange(self):

274 '''Get the I{slant Range}, distance (C{meter}).

275 '''

276 return self._slantrange

277

278 def toRepr(self, prec=None, fmt=Fmt.SQUARE, sep=_COMMASPACE_, **unused): # PYCHOK expected

279 '''Return a string representation of this AER as azimuth

280 (bearing), elevation and slant range.

281

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

283 @kwarg fmt: Enclosing backets format (C{str}).

284 @kwarg sep: Optional separator between AERs (C{str}).

285

286 @return: This AER as "[A:degrees360, E:degrees90, R:meter]" (C{str}).

287 '''

288 m = _MODS.dms

289 t = (m.toDMS(self.azimuth, form=m.F_D, prec=prec, ddd=0),

290 m.toDMS(self.elevation, form=m.F_D, prec=prec, ddd=0),

291 fstr( self.slantrange, prec=3 if prec is None else prec))

292 return _xzipairs(self._toStr.upper(), t, sep=sep, fmt=fmt)

293

294 def toStr(self, **prec_fmt_sep): # PYCHOK expected

295 '''Return a string representation of this AER.

296

297 @kwarg prec_fmt_sep: Keyword arguments C{B{prec}=3} for the

298 number of (decimal) digits, unstripped

299 (C{int}), C{B{fmt}='[]'} the enclosing

300 backets format (C{str}) and separator

301 C{B{sep}=", "} to join (C{str}).

302

303 @return: This AER as "[degrees360, degrees90, meter]" (C{str}).

304 '''

305 _, t = _toStr2(self, **prec_fmt_sep)

306 return t

307

308 @Property_RO

309 def up(self):

310 '''Get the Up component (C{meter}).

311 '''

312 return self.xyzLocal.up

313

314 @Property_RO

315 def x(self):

316 '''Get the X component (C{meter}).

317 '''

318 return self.xyz4.x

319

320 @Property_RO

321 def xyz4(self):

322 '''Get the C{(x, y, z, ltp)} components (L{Xyz4Tuple}).

323 '''

324 sA, cA, sE, cE = sincos2d_(self._azimuth, self._elevation)

325 R = self._slantrange

326 r = cE * R # ground range

327 return Xyz4Tuple(sA * r, cA * r, sE * R, self.ltp, name=self.name)

328

329 @Property_RO

330 def y(self):

331 '''Get the Y component (C{meter}).

332 '''

333 return self.xyz4.y

334

335 @Property_RO

336 def z(self):

337 '''Get the Z component (C{meter}).

338 '''

339 return self.xyz4.z

340

341

342class Aer4Tuple(_Abc4Tuple):

343 '''4-Tuple C{(azimuth, elevation, slantrange, ltp)},

344 all in C{meter} except C{ltp}.

345 '''

346 _Names_ = (_azimuth_, _elevation_, _slantrange_, _ltp_)

347 _Units_ = ( Meter, Meter, Meter, _Pass)

348

349 def _toAer(self, Cls, Cls_kwds):

350 '''(INTERNAL) Return C{Cls(..., **Cls_kwds)} instance.

351 '''

352 return self._2Cls(Aer, Cls, Cls_kwds)

353

354 @Property_RO

355 def groundrange(self):

356 '''Get the I{ground range}, distance (C{meter}).

357 '''

358 return _er2gr(self.elevation, self.slantrange) # PYCHOK _Tuple

359

360 @Property_RO

361 def xyzLocal(self):

362 '''Get this L{Aer4Tuple} as an L{XyzLocal}.

363 '''

364 return Aer(self).xyzLocal

365

366

367class Attitude4Tuple(_NamedTuple):

368 '''4-Tuple C{(alt, tilt, yaw, roll)} with C{altitude} in (positive)

369 C{meter} and C{tilt}, C{yaw} and C{roll} in C{degrees} representing

370 the attitude of a plane or camera.

371 '''

372 _Names_ = (_alt_, _tilt_, _yaw_, _roll_)

373 _Units_ = ( Meter, Degrees, Bearing, Degrees)

374

375 @Property_RO

376 def atyr(self):

377 '''Return this attitude (L{Attitude4Tuple}).

378 '''

379 return self

380

381 @Property_RO

382 def tyr3d(self):

383 '''Get this attitude's (3-D) directional vector (L{Vector3d}).

384 '''

385 return _ltp.Attitude(self).tyr3d

386

387

388class Ned(_AbcBase):

389 '''Local C{North-Eeast-Down} (NED) location in a I{local tangent plane}.

390

391 @see: L{Enu} and L{Ltp}.

392 '''

393 _down = _0_0 # down, -XyzLocal.z (C{meter}).

394 _east = _0_0 # east, XyzLocal.y (C{meter}).

395# _ltp = None # local tangent plane (C{Ltp}), origin

396 _north = _0_0 # north, XyzLocal.x (C{meter})

397 _toStr = _ned_

398

399 def __init__(self, north_ned, east=0, down=0, ltp=None, **name):

400 '''New L{Ned} vector.

401

402 @arg north_ned: Scalar North component (C{meter}) or a previous

403 I{local} instance (L{Ned}, L{Ned4Tuple}, L{Aer},

404 L{Aer4Tuple}, L{Enu}, L{Enu4Tuple}, L{Local9Tuple},

405 L{XyzLocal} or L{Xyz4Tuple}).

406 @kwarg east: Scalar East component (C{meter}), only used with

407 scalar B{C{north_ned}}.

408 @kwarg down: Scalar Down component, normal to I{inside} surface

409 of the ellipsoid or sphere (C{meter}), only used with

410 scalar B{C{north_ned}}.

411 @kwarg ltp: The I{local tangent plane}, (geodetic) origin (L{Ltp},

412 L{LocalCartesian}).

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

414

415 @raise TypeError: Invalid B{C{north_ned}} or B{C{ltp}}.

416

417 @raise UnitError: Invalid B{C{north_ned}}, B{C{east}} or B{C{down}}.

418 '''

419 if _isMeter(north_ned):

420 ned = None

421 t = (Meter(north=north_ned or _0_0),

422 Meter(east=east or _0_0),

423 Meter(down=down or _0_0), ltp)

424 else: # PYCHOK no cover

425 p = _xyzLocal(Ned, Ned4Tuple, Aer, north_ned=north_ned)

426 ned = p.toNed() if p else north_ned

427 t = ned.ned4

428 self._north, self._east, self._down, _ = t

429 _init(self, ned, ltp, name)

430

431 @Property_RO

432 def aer4(self):

433 '''Get the C{(azimuth, elevation, slantrange, ltp)} components (L{Aer4Tuple}).

434 '''

435 return _xyz2aer4(self)

436

437 @Property_RO

438 def azimuth(self):

439 '''Get the Azimuth, bearing from North (C{degrees360}).

440 '''

441 return self.aer4.azimuth

442

443 @deprecated_Property_RO

444 def bearing(self):

445 '''DEPRECATED, use C{azimuth}.'''

446 return self.azimuth

447

448 @Property_RO

449 def down(self):

450 '''Get the Down component (C{meter}).

451 '''

452 return self._down

453

454 @Property_RO

455 def east(self):

456 '''Get the East component (C{meter}).

457 '''

458 return self._east

459

460 @Property_RO

461 def elevation(self):

462 '''Get the Elevation, tilt above horizon (C{degrees90}).

463 '''

464 return self.aer4.elevation # neg(degrees90(asin1(self.down / self.length))))

465

466 @Property_RO

467 def groundrange(self):

468 '''Get the I{ground range}, distance (C{meter}).

469 '''

470 return Meter(groundrange=hypot(self.north, self.east))

471

472 @deprecated_Property_RO

473 def length(self):

474 '''DEPRECATED, use C{slantrange}.'''

475 return self.slantrange

476

477 @deprecated_Property_RO

478 def ned(self):

479 '''DEPRECATED, use property C{ned4}.'''

480 return _MODS.deprecated.classes.Ned3Tuple(self.north, self.east, self.down, name=self.name)

481

482 @Property_RO

483 def ned4(self):

484 '''Get the C{(north, east, down, ltp)} components (L{Ned4Tuple}).

485 '''

486 return Ned4Tuple(self.north, self.east, self.down, self.ltp, name=self.name)

487

488 @Property_RO

489 def north(self):

490 '''Get the North component (C{meter}).

491 '''

492 return self._north

493

494 @Property_RO

495 def slantrange(self):

496 '''Get the I{slant Range}, distance (C{meter}).

497 '''

498 return self.aer4.slantrange

499

500 @deprecated_method

501 def to3ned(self): # PYCHOK no cover

502 '''DEPRECATED, use property L{ned4}.'''

503 return self.ned # XXX deprecated too

504

505 def toRepr(self, prec=None, fmt=Fmt.SQUARE, sep=_COMMASPACE_, **unused): # PYCHOK expected

506 '''Return a string representation of this NED.

507

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

509 @kwarg fmt: Enclosing backets format (C{str}).

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

511

512 @return: This NED as "[N:meter, E:meter, D:meter]" (C{str}).

513 '''

514 a, t = _toStr2(self, prec=prec, fmt=NN, sep=NN)

515 return _xzipairs(a.upper(), t, sep=sep, fmt=fmt)

516

517 def toStr(self, **prec_fmt_sep): # PYCHOK expected

518 '''Return a string representation of this NED.

519

520 @kwarg prec_fmt_sep: Keyword arguments C{B{prec}=3} for the

521 number of (decimal) digits, unstripped

522 (C{int}), C{B{fmt}='[]'} the enclosing

523 backets format (C{str}) and separator

524 C{B{sep}=", "} to join (C{str}).

525

526 @return: This NED as "[meter, meter, meter]" (C{str}).

527 '''

528 _, t = _toStr2(self, **prec_fmt_sep)

529 return t

530

531 @deprecated_method

532 def toVector3d(self):

533 '''DEPRECATED, use property L{xyz}.'''

534 return self.xyz

535

536 @Property_RO

537 def up(self):

538 '''Get the Up component (C{meter}).

539 '''

540 return Meter(up=-self._down) # negated

541

542 @Property_RO

543 def x(self):

544 '''Get the X component (C{meter}).

545 '''

546 return Meter(x=self._east) # 2nd arg, E

547

548 @Property_RO

549 def xyz4(self):

550 '''Get the C{(x, y, z, ltp)} components (L{Xyz4Tuple}).

551 '''

552 return Xyz4Tuple(self.x, self.y, self.z, self.ltp, name=self.name)

553

554 @Property_RO

555 def y(self):

556 '''Get the Y component (C{meter}).

557 '''

558 return Meter(y=self._north) # 1st arg N

559

560 @Property_RO

561 def z(self):

562 '''Get the Z component (C{meter}).

563 '''

564 return Meter(z=-self._down) # negated

565

566

567class Ned4Tuple(_Abc4Tuple):

568 '''4-Tuple C{(north, east, down, ltp)}, all in C{meter} except C{ltp}.

569 '''

570 _Names_ = (_north_, _east_, _down_, _ltp_)

571 _Units_ = ( Meter, Meter, Meter, _Pass)

572

573 def _toNed(self, Cls, Cls_kwds):

574 '''(INTERNAL) Return C{Cls(..., **Cls_kwds)} instance.

575 '''

576 return self._2Cls(Ned, Cls, Cls_kwds)

577

578 @Property_RO

579 def xyzLocal(self):

580 '''Get this L{Ned4Tuple} as an L{XyzLocal}.

581 '''

582 return Ned(self).xyzLocal

583

584

585class _Vector3d(Vector3d):

586

587 _toStr = _xyz_

588

589 def toRepr(self, prec=None, fmt=Fmt.SQUARE, sep=_COMMASPACE_, **unused): # PYCHOK expected

590 '''Return a string representation of this ENU/NED/XYZ.

591

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

593 @kwarg fmt: Enclosing backets format (C{str}).

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

595

596 @return: This XYZ/ENU as "[E:meter, N:meter, U:meter]",

597 "[N:meter, E:meter, D:meter]",

598 "[U:meter, V:meter, W:meter]" respectively

599 "[X:meter, Y:meter, Z:meter]" (C{str}).

600 '''

601 a, t = _toStr2(self, prec=prec, fmt=NN, sep=NN)

602 return _xzipairs(a.upper(), t, sep=sep, fmt=fmt)

603

604 def toStr(self, **prec_fmt_sep): # PYCHOK expected

605 '''Return a string representation of this XYZ.

606

607 @kwarg prec_fmt_sep: Keyword arguments C{B{prec}=3} for the

608 number of (decimal) digits, unstripped

609 (C{int}), C{B{fmt}='[]'} the enclosing

610 backets format (C{str}) and separator

611 C{B{sep}=", "} to join (C{str}).

612

613 @return: This XYZ as "[meter, meter, meter]" (C{str}).

614 '''

615 _, t = _toStr2(self, **prec_fmt_sep)

616 return t

617

618

619class XyzLocal(_Vector3d):

620 '''Local C{(x, y, z)} in a I{local tangent plane} (LTP),

621 also base class for local L{Enu}.

622 '''

623 _ltp = None # local tangent plane (C{Ltp}), origin

624

625 def __init__(self, x_xyz, y=0, z=0, ltp=None, **name):

626 '''New L{XyzLocal}.

627

628 @arg x_xyz: Scalar X component (C{meter}), C{positive east} or a

629 previous I{local} instance (L{XyzLocal}, L{Xyz4Tuple},

630 L{Aer}, L{Aer4Tuple}, L{Enu}, L{Enu4Tuple},

631 L{Local9Tuple}, L{Ned} or L{Ned4Tuple}).

632 @kwarg y: Scalar Y component (C{meter}), only used with scalar

633 B{C{x_xyz}}, C{positive north}.

634 @kwarg z: Scalar Z component, normal C{positive up} from the

635 surface of the ellipsoid or sphere (C{meter}), only

636 used with scalar B{C{x_xyz}}.

637 @kwarg ltp: The I{local tangent plane}, (geodetic) origin (L{Ltp},

638 L{LocalCartesian}).

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

640

641 @raise TypeError: Invalid B{C{x_xyz}} or B{C{ltp}}.

642

643 @raise UnitError: Invalid scalar B{C{x_xyz}}, B{C{y}} or B{C{z}}.

644 '''

645 if _isMeter(x_xyz):

646 xyz = None

647 t = (Meter(x=x_xyz or _0_0),

648 Meter(y=y or _0_0),

649 Meter(z=z or _0_0), ltp)

650 else:

651 xyz = _xyzLocal(XyzLocal, Xyz4Tuple, Local9Tuple, x_xyz=x_xyz) or x_xyz

652 t = xyz.xyz4 # xyz.x, xyz.y, xyz.z, xyz.ltp

653 self._x, self._y, self._z, _ = t

654 _init(self, xyz, ltp, name)

655

656 def __str__(self):

657 return self.toStr()

658

659 @Property_RO

660 def aer4(self):

661 '''Get the C{(azimuth, elevation, slantrange, ltp)} components (L{Aer4Tuple}).

662 '''

663 return _xyz2aer4(self)

664

665 @Property_RO

666 def azimuth(self):

667 '''Get the Azimuth, bearing from North (C{degrees360}).

668

669 @see: U{Azimuth<https://GSSC.ESA.int/navipedia/index.php/

670 Transformations_between_ECEF_and_ENU_coordinates>}.

671 '''

672 return self.aer4.azimuth

673

674 def classof(self, *args, **kwds): # PYCHOK no cover

675 '''Create another instance of this very class.

676

677 @arg args: Optional, positional arguments.

678 @kwarg kwds: Optional, keyword arguments.

679

680 @return: New instance (C{self.__class__}).

681 '''

682 kwds = _name1__(kwds, _or_nameof=self)

683 return self.__class__(*args, **_xkwds(kwds, ltp=self.ltp))

684

685 @Property_RO

686 def down(self):

687 '''Get the Down component (C{meter}).

688 '''

689 return Meter(down=-self.z)

690

691 @property_RO

692 def ecef(self):

693 '''Get this LTP's ECEF converter (C{Ecef...} I{instance}).

694 '''

695 return self.ltp.ecef

696

697 @Property_RO

698 def east(self):

699 '''Get the East component (C{meter}).

700 '''

701 return Meter(east=self.x)

702

703 @Property_RO

704 def elevation(self):

705 '''Get the Elevation, tilt above horizon (C{degrees90}).

706

707 @see: U{Elevation<https://GSSC.ESA.int/navipedia/index.php/

708 Transformations_between_ECEF_and_ENU_coordinates>}.

709 '''

710 return self.aer4.elevation # neg(degrees90(asin1(self.down / self.length))))

711

712 @Property_RO

713 def enu4(self):

714 '''Get the C{(east, north, up, ltp)} components (L{Enu4Tuple}).

715 '''

716 return Enu4Tuple(self.east, self.north, self.up, self.ltp, name=self.name)

717

718 @Property_RO

719 def groundrange(self):

720 '''Get the I{ground range}, distance (C{meter}).

721 '''

722 return Meter(groundrange=hypot(self.x, self.y))

723

724 @Property_RO

725 def ltp(self):

726 '''Get the I{local tangent plane} (L{Ltp}).

727 '''

728 return self._ltp

729

730 def _ltp_kwds_name3(self, ltp, kwds):

731 '''(INTERNAL) Helper for methods C{toCartesian} and C{toLatLon}.

732 '''

733 ltp = _ltp._xLtp(ltp, self.ltp)

734 kwds = _name1__(kwds, _or_nameof=self)

735 kwds = _name1__(kwds, _or_nameof=ltp)

736 return ltp, kwds, kwds.get(_name_, NN)

737

738 @Property_RO

739 def ned4(self):

740 '''Get the C{(north, east, down, ltp)} components (L{Ned4Tuple}).

741 '''

742 return Ned4Tuple(self.north, self.east, self.down, self.ltp, name=self.name)

743

744 @Property_RO

745 def north(self):

746 '''Get the North component (C{meter}).

747 '''

748 return Meter(north=self.y)

749

750 @Property_RO

751 def slantrange(self):

752 '''Get the I{slant Range}, distance (C{meter}).

753 '''

754 return self.aer4.slantrange

755

756 def toAer(self, Aer=None, **name_Aer_kwds):

757 '''Get the local I{Azimuth, Elevation, slant Range} components.

758

759 @kwarg Aer: Class to return AER (L{Aer}) or C{None}.

760 @kwarg name_Aer_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

761 additional B{C{Aer}} keyword arguments, ignored if C{B{Aer}

762 is None}.

763

764 @return: An B{C{Aer}} instance or an L{Aer4Tuple}C{(azimuth, elevation,

765 slantrange, ltp)} if C{B{Aer} is None}.

766

767 @raise TypeError: Invalid B{C{Aer}} or B{C{name_Aer_kwds}} item.

768 '''

769 return self.aer4._toAer(Aer, name_Aer_kwds)

770

771 def toCartesian(self, Cartesian=None, ltp=None, **name_Cartesian_kwds): # PYCHOK signature

772 '''Get the geocentric C{(x, y, z)} (ECEF) coordinates of this local.

773

774 @kwarg Cartesian: Optional class to return C{(x, y, z)} (C{Cartesian})

775 or C{None}.

776 @kwarg ltp: Optional I{local tangent plane} (LTP) (L{Ltp}), overriding

777 this C{ltp}.

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

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

780 C{B{Cartesian} is None}.

781

782 @return: A B{C{Cartesian}} instance or if C{B{Cartesian} is None}, an

783 L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)} with

784 C{M=None}, always.

785

786 @raise TypeError: Invalid B{C{ltp}}, B{C{Cartesian}} or B{C{name_Cartesian_kwds}} item.

787 '''

788 ltp, kwds, n = self._ltp_kwds_name3(ltp, name_Cartesian_kwds)

789 if Cartesian is None:

790 t = ltp._local2ecef(self, nine=True)

791 r = _xnamed(t, n) if n else t

792 else:

793 kwds = _xkwds(kwds, datum=ltp.datum, name=n)

794 xyz = ltp._local2ecef(self) # [:3]

795 r = Cartesian(*xyz, **kwds)

796 return r

797

798 def toEnu(self, Enu=None, **name_Enu_kwds):

799 '''Get the local I{East, North, Up} (ENU) components.

800

801 @kwarg Enu: Class to return ENU (L{Enu}) or C{None}.

802 @kwarg name_Enu_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

803 additional B{C{Enu}} keyword arguments, ignored if C{B{Enu}

804 is None}.

805

806 @return: An B{C{Enu}} instance or an L{Enu4Tuple}C{(east, north, up,

807 ltp)} if C{B{Enu} is None}.

808

809 @raise TypeError: Invalid B{C{Enu}} or B{C{name_Enu_kwds}} item.

810 '''

811 return self.enu4._toEnu(Enu, name_Enu_kwds)

812

813 def toLatLon(self, LatLon=None, ltp=None, **name_LatLon_kwds):

814 '''Get the geodetic C{(lat, lon, height)} coordinates if this local.

815

816 @kwarg LatLon: Optional class to return C{(x, y, z)} (C{LatLon}) or

817 C{None}.

818 @kwarg ltp: Optional I{local tangent plane} (LTP) (L{Ltp}), overriding

819 this ENU/NED/AER/XYZ's LTP.

820 @kwarg name_LatLon_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

821 additional B{C{LatLon}} keyword arguments, ignored if C{B{LatLon}

822 is None}.

823

824 @return: An B{C{LatLon}} instance or an L{Ecef9Tuple}C{(x, y, z, lat, lon,

825 height, C, M, datum)} if C{B{LatLon} is None}, with C{M=None}.

826

827 @raise TypeError: Invalid B{C{LatLon}}, B{C{ltp}} or B{C{name_LatLon_kwds}} item.

828 '''

829 ltp, kwds, n = self._ltp_kwds_name3(ltp, name_LatLon_kwds)

830 t = ltp._local2ecef(self, nine=True)

831 if LatLon is None:

832 r = _xnamed(t, n) if n else t

833 else:

834 kwds = _xkwds(kwds, height=t.height, datum=t.datum)

835 r = LatLon(t.lat, t.lon, **kwds) # XXX ltp?

836 return r

837

838 def toLocal9Tuple(self, M=False, **name):

839 '''Get this local as a C{Local9Tuple}.

840

841 @kwarg M: Optionally include the rotation matrix (C{bool}).

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

843

844 @return: L{Local9Tuple}C{(x, y, z, lat, lon, height, ltp, ecef, M)}

845 with C{ltp} this C{Ltp}, C{ecef} an L{Ecef9Tuple} and C{M}

846 an L{EcefMatrix} or C{None}.

847 '''

848 ltp = self.ltp # see C{self.toLatLon}

849 t = ltp._local2ecef(self, nine=True, M=M)

850 return Local9Tuple(self.x, self.y, self.z,

851 t.lat, t.lon, t.height,

852 ltp, t, t.M, name=t._name__(name))

853

854 def toNed(self, Ned=None, **name_Ned_kwds):

855 '''Get the local I{North, East, Down} (Ned) components.

856

857 @kwarg Ned: Class to return NED (L{Ned}) or C{None}.

858 @kwarg name_Ned_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

859 additional B{C{Ned}} keyword arguments, ignored if C{B{Ned}

860 is None}.

861

862 @return: An B{C{Ned}} instance or an L{Ned4Tuple}C{(north, east, down,

863 ltp)} if C{B{Ned} is None}.

864

865 @raise TypeError: Invalid B{C{Ned}} or B{C{name_Ned_kwds}} item.

866 '''

867 return self.ned4._toNed(Ned, name_Ned_kwds)

868

869 def toXyz(self, Xyz=None, **name_Xyz_kwds):

870 '''Get the local I{X, Y, Z} (XYZ) components.

871

872 @kwarg Xyz: Class to return XYZ (L{XyzLocal}, L{Enu}, L{Ned}, L{Aer})

873 or C{None}.

874 @kwarg name_Xyz_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

875 additional B{C{Xyz}} keyword arguments, ignored if C{B{Xyz}

876 is None}.

877

878 @return: An B{C{Xyz}} instance or an L{Xyz4Tuple}C{(x, y, z, ltp)} if

879 C{B{Xyz} is None}.

880

881 @raise TypeError: Invalid B{C{Xyz}} or B{C{name_Xyz_kwds}} item.

882 '''

883 return self.xyz4._toXyz(Xyz, name_Xyz_kwds)

884

885 @Property_RO

886 def up(self):

887 '''Get the Up component (C{meter}).

888 '''

889 return Meter(up=self.z)

890

891# @Property_RO

892# def x(self): # see: Vector3d.x

893# '''Get the X component (C{meter}).

894# '''

895# return self._x

896

897# @Property_RO

898# def xyz(self): # see: Vector3d.xyz

899# '''Get the I{local} C{(X, Y, Z)} coordinates (L{Vector3Tuple}C{(x, y, z)}).

900# '''

901# return Vector3Tuple(self.x, self.y, self.z, name=self.name) # like Ecef9Tuple.xyz, Local6tuple.xyz

902

903 @Property_RO

904 def xyz4(self):

905 '''Get the C{(x, y, z, ltp)} components (L{Xyz4Tuple}).

906 '''

907 return Xyz4Tuple(self.x, self.y, self.z, self.ltp, name=self.name)

908

909 @Property_RO

910 def xyzLocal(self):

911 '''Get this L{XyzLocal}.

912 '''

913 return self

914

915# @Property_RO

916# def y(self): # see: Vector3d.y

917# '''Get the Y component (C{meter}).

918# '''

919# return self._y

920

921# @Property_RO

922# def z(self): # see: Vector3d.z

923# '''Get the Z component (C{meter}).

924# '''

925# return self._z

926

927

928class Xyz4Tuple(_Abc4Tuple):

929 '''4-Tuple C{(x, y, z, ltp)}, all in C{meter} except C{ltp}.

930 '''

931 _Names_ = (_x_, _y_, _z_, _ltp_)

932 _Units_ = ( Meter, Meter, Meter, _Pass)

933

934 def _toXyz(self, Cls, Cls_kwds):

935 '''(INTERNAL) Return C{Cls(..., **Cls_kwds)} instance.

936 '''

937 return self._2Cls(XyzLocal, Cls, Cls_kwds)

938

939 @property_RO

940 def xyz4(self):

941 '''Get the C{(x, y, z, ltp)} components (L{Xyz4Tuple}).

942 '''

943 return self

944

945 @Property_RO

946 def xyzLocal(self):

947 '''Get this L{Xyz4Tuple} as an L{XyzLocal}.

948 '''

949 return XyzLocal(*self, name=self.name)

950

951

952class Enu(XyzLocal):

953 '''Local C{Eeast-North-Up} (ENU) location in a I{local tangent plane}.

954

955 @see: U{East, North, Up (ENU)<https://GSSC.ESA.int/navipedia/index.php/

956 Transformations_between_ECEF_and_ENU_coordinates>} coordinates.

957 '''

958 _toStr = _enu_

959

960 def __init__(self, east_enu, north=0, up=0, ltp=None, **name):

961 '''New L{Enu}.

962

963 @arg east_enu: Scalar East component (C{meter}) or a previous

964 I{local} instance (L{Enu}, L{Enu4Tuple}, L{Aer},

965 L{Aer4Tuple}, L{Local9Tuple}, L{Ned}, L{Ned4Tuple},

966 L{XyzLocal} or L{Xyz4Tuple}).

967 @kwarg north: Scalar North component (C{meter}), iff B{C{east_enu}}

968 is C{meter}, ignored otherwise.

969 @kwarg up: Scalar Up component (C{meter}, normal from the surface

970 of the ellipsoid or sphere), iff B{C{east_enu}} is

971 C{meter}, ignored otherwise.

972 @kwarg ltp: The I{local tangent plane}, (geodetic) origin (L{Ltp},

973 L{LocalCartesian}).

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

975

976 @raise TypeError: Invalid B{C{east_enu}} or B{C{ltp}}.

977

978 @raise UnitError: Invalid B{C{east_enu}}, B{C{north}} or B{C{up}}.

979 '''

980 XyzLocal.__init__(self, east_enu, north, up, ltp=ltp, **name)

981

982 def toUvw(self, location, Uvw=None, **name_Uvw_kwds):

983 '''Get the I{u, v, w} (UVW) components at a location.

984

985 @arg location: The geodetic (C{LatLon}) or geocentric (C{Cartesian},

986 L{Vector3d}) location, like a Point-Of-View.

987 @kwarg Uvw: Class to return UWV (L{Uvw}) or C{None}.

988 @kwarg name_Uvw_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

989 additional B{L{Uvw}} keyword arguments, ignored if C{B{Uvw}

990 is None}.

991

992 @return: A B{C{Uvw}} instance or a L{Uvw3Tuple}C{(u, v, w)} if C{B{Uvw}

993 is None}.

994

995 @raise TypeError: Invalid B{C{location}} or B{C{name_Uvw_kwds}} item.

996

997 @see: Function U{lookAtSpheroid<https://PyPI.org/project/pymap3d>}.

998 '''

999 try:

1000 sa, ca, sb, cb = sincos2_(*location.philam)

1001 except Exception as x:

1002 raise _TypeError(location=location, cause=x)

1003 e, n, u, _ = self.enu4

1004

1005 t = fdot_(ca, u, -sa, n)

1006 U = fdot_(cb, t, -sb, e)

1007 V = fdot_(cb, e, sb, t)

1008 W = fdot_(ca, n, sa, u)

1009

1010 n, kwds = _name2__(name_Uvw_kwds, _or_nameof=self)

1011 return Uvw3Tuple(U, V, W, name=n) if Uvw is None else \

1012 Uvw(U, V, W, name=n, **kwds)

1013

1014 @Property_RO

1015 def xyzLocal(self):

1016 '''Get this ENU as an L{XyzLocal}.

1017 '''

1018 return XyzLocal(*self.xyz4, name=self.name)

1019

1020

1021class Enu4Tuple(_Abc4Tuple):

1022 '''4-Tuple C{(east, north, up, ltp)}, in C{meter} except C{ltp}.

1023 '''

1024 _Names_ = (_east_, _north_, _up_, _ltp_)

1025 _Units_ = ( Meter, Meter, Meter, _Pass)

1026

1027 def _toEnu(self, Cls, Cls_kwds):

1028 '''(INTERNAL) Return C{Cls(..., **Cls_kwds)} instance.

1029 '''

1030 return self._2Cls(Enu, Cls, Cls_kwds)

1031

1032 @Property_RO

1033 def xyzLocal(self):

1034 '''Get this L{Enu4Tuple} as an L{XyzLocal}.

1035 '''

1036 return XyzLocal(*self, name=self.name)

1037

1038

1039class Local9Tuple(_NamedTuple):

1040 '''9-Tuple C{(x, y, z, lat, lon, height, ltp, ecef, M)} with I{local} C{x},

1041 C{y}, C{z} all in C{meter}, I{geodetic} C{lat}, C{lon}, C{height}, I{local

1042 tangent plane} C{ltp} (L{Ltp}), C{ecef} (L{Ecef9Tuple}) with I{geocentric}

1043 C{x}, C{y}, C{z}, I{geodetic} C{lat}, C{lon}, C{height} and I{concatenated}

1044 rotation matrix C{M} (L{EcefMatrix}) or C{None}.

1045 '''

1046 _Names_ = (_x_, _y_, _z_, _lat_, _lon_, _height_, _ltp_, _ecef_, _M_)

1047 _Units_ = ( Meter, Meter, Meter, Lat, Lon, Height, _Pass, _Pass, _Pass)

1048

1049 @Property_RO

1050 def azimuth(self):

1051 '''Get the I{local} Azimuth, bearing from North (C{degrees360}).

1052 '''

1053 return self.xyzLocal.aer4.azimuth

1054

1055 @Property_RO

1056 def down(self):

1057 '''Get the I{local} Down, C{-z} component (C{meter}).

1058 '''

1059 return -self.z

1060

1061 @Property_RO

1062 def east(self):

1063 '''Get the I{local} East, C{x} component (C{meter}).

1064 '''

1065 return self.x

1066

1067 @Property_RO

1068 def elevation(self):

1069 '''Get the I{local} Elevation, tilt I{above} horizon (C{degrees90}).

1070 '''

1071 return self.xyzLocal.aer4.elevation

1072

1073 @Property_RO

1074 def groundrange(self):

1075 '''Get the I{local} ground range, distance (C{meter}).

1076 '''

1077 return self.xyzLocal.aer4.groundrange

1078

1079 @Property_RO

1080 def lam(self):

1081 '''Get the I{geodetic} longitude in C{radians} (C{float}).

1082 '''

1083 return self.philam.lam

1084

1085 @Property_RO

1086 def latlon(self):

1087 '''Get the I{geodetic} lat-, longitude in C{degrees} (L{LatLon2Tuple}C{(lat, lon)}).

1088 '''

1089 return LatLon2Tuple(self.lat, self.lon, name=self.name)

1090

1091 @Property_RO

1092 def latlonheight(self):

1093 '''Get the I{geodetic} lat-, longitude in C{degrees} and height (L{LatLon3Tuple}C{(lat, lon, height)}).

1094 '''

1095 return self.latlon.to3Tuple(self.height)

1096

1097 @Property_RO

1098 def north(self):

1099 '''Get the I{local} North, C{y} component (C{meter}).

1100 '''

1101 return self.y

1102

1103 @Property_RO

1104 def phi(self):

1105 '''Get the I{geodetic} latitude in C{radians} (C{float}).

1106 '''

1107 return self.philam.phi

1108

1109 @Property_RO

1110 def philam(self):

1111 '''Get the I{geodetic} lat-, longitude in C{radians} (L{PhiLam2Tuple}C{(phi, lam)}).

1112 '''

1113 return PhiLam2Tuple(radians(self.lat), radians(self.lon), name=self.name)

1114

1115 @Property_RO

1116 def philamheight(self):

1117 '''Get the I{geodetic} lat-, longitude in C{radians} and height (L{PhiLam3Tuple}C{(phi, lam, height)}).

1118 '''

1119 return self.philam.to3Tuple(self.height)

1120

1121 @Property_RO

1122 def slantrange(self):

1123 '''Get the I{local} slant Range, distance (C{meter}).

1124 '''

1125 return self.xyzLocal.aer4.slantrange

1126

1127 def toAer(self, Aer=None, **name_Aer_kwds):

1128 '''Get the I{local} I{Azimuth, Elevation, slant Range} (AER) components.

1129

1130 @kwarg Aer: Class to return AER (L{Aer}) or C{None}.

1131 @kwarg name_Aer_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

1132 additional B{L{Aer}} keyword arguments, ignored if C{B{Aer}

1133 is None}.

1134

1135 @return: An B{C{Aer}} instance or an L{Aer4Tuple}C{(azimuth, elevation,

1136 slantrange, ltp)} if C{B{Aer} is None}.

1137

1138 @raise TypeError: Invalid B{C{Aer}} or B{C{name_Aer_kwds}} item.

1139 '''

1140 return self.xyzLocal.toAer(Aer=Aer, **name_Aer_kwds)

1141

1142 def toCartesian(self, Cartesian=None, **name_Cartesian_kwds):

1143 '''Convert this I{local} to I{geocentric} C{(x, y, z)} (ECEF).

1144

1145 @kwarg Cartesian: Optional I{geocentric} class to return C{(x, y, z)}

1146 (C{Cartesian}) or C{None}.

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

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

1149 C{B{Cartesian} is None}.

1150

1151 @return: A C{B{Cartesian}(x, y, z, **B{Cartesian_kwds})} instance or a

1152 L{Vector4Tuple}C{(x, y, z, h)} if C{B{Cartesian} is None}.

1153

1154 @raise TypeError: Invalid B{C{Cartesian}} or B{C{name_Cartesian_kwds}} item.

1155 '''

1156 return self.ecef.toCartesian(Cartesian=Cartesian, **name_Cartesian_kwds) # PYCHOK _Tuple

1157

1158 def toEnu(self, Enu=None, **name_Enu_kwds):

1159 '''Get the I{local} I{East, North, Up} (ENU) components.

1160

1161 @kwarg Enu: Class to return ENU (L{Enu}) or C{None}.

1162 @kwarg name_Enu_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

1163 additional B{L{Enu}} keyword arguments, ignored if C{B{Enu}

1164 is None}.

1165

1166 @return: ENU as an L{Enu} instance or if C{B{Enu} is None}, an

1167 L{Enu4Tuple}C{(east, north, up, ltp)}.

1168

1169 @raise TypeError: Invalid B{C{Enu}} or B{C{name_Enu_kwds}} item.

1170 '''

1171 return self.xyzLocal.toEnu(Enu=Enu, **name_Enu_kwds)

1172

1173 def toLatLon(self, LatLon=None, **name_LatLon_kwds):

1174 '''Convert this I{local} to I{geodetic} C{(lat, lon, height)}.

1175

1176 @kwarg LatLon: Optional I{geodetic} class to return C{(lat, lon, height)}

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

1178 @kwarg name_LatLon_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

1179 additional B{C{LatLon}} keyword arguments, ignored if

1180 C{B{LatLon} is None}.

1181

1182 @return: An C{B{LatLon}(lat, lon, **B{LatLon_kwds})} instance or if

1183 C{B{LatLon} is None}, a L{LatLon4Tuple}C{(lat, lon, height,

1184 datum)} or L{LatLon3Tuple}C{(lat, lon, height)} if C{datum}

1185 is specified or not.

1186

1187 @raise TypeError: Invalid B{C{LatLon}} or B{C{name_LatLon_kwds}}.

1188 '''

1189 return self.ecef.toLatLon(LatLon=LatLon, **name_LatLon_kwds) # PYCHOK _Tuple

1190

1191 def toNed(self, Ned=None, **name_Ned_kwds):

1192 '''Get the I{local} I{North, East, Down} (NED) components.

1193

1194 @kwarg Ned: Class to return NED (L{Ned}) or C{None}.

1195 @kwarg name_Ned_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

1196 additional B{L{Ned}} keyword arguments, ignored if C{B{Ned}

1197 is None}.

1198

1199 @return: An B{C{Ned}} instance or an L{Ned4Tuple}C{(north, east, down,

1200 ltp)} if C{B{Ned} is None}.

1201

1202 @raise TypeError: Invalid B{C{Ned}} or B{C{name_Ned_kwds}} item.

1203 '''

1204 return self.xyzLocal.toNed(Ned=Ned, **name_Ned_kwds)

1205

1206 def toXyz(self, Xyz=None, **name_Xyz_kwds):

1207 '''Get the I{local} I{X, Y, Z} (XYZ) components.

1208

1209 @kwarg Xyz: Class to return XYZ (L{XyzLocal}) or C{None}.

1210 @kwarg name_Xyz_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

1211 additional B{C{Xyz}} keyword arguments, ignored if C{B{Xyz}

1212 is None}.

1213

1214 @return: An B{C{Xyz}} instance or an L{Xyz4Tuple}C{(x, y, z, ltp)} if

1215 C{B{Xyz} is None}.

1216

1217 @raise TypeError: Invalid B{C{Xyz}} or B{C{name_Xyz_kwds}} item.

1218 '''

1219 return self.xyzLocal.toXyz(Xyz=Xyz, **name_Xyz_kwds)

1220

1221 @Property_RO

1222 def up(self):

1223 '''Get the I{local} Up, C{z} component (C{meter}).

1224 '''

1225 return self.z

1226

1227 @Property_RO

1228 def xyz(self):

1229 '''Get the I{local} C{(X, Y, Z)} components (L{Vector3Tuple}C{(x, y, z)}).

1230 '''

1231 return Vector3Tuple(self.x, self.y, self.z, name=self.name) # like Ecef9Tuple.xyz

1232

1233 @Property_RO

1234 def xyzLocal(self):

1235 '''Get this L{Local9Tuple} as an L{XyzLocal}.

1236 '''

1237 return XyzLocal(*self.xyz, ltp=self.ltp, name=self.name) # PYCHOK .ltp

1238

1239

1240_XyzLocals4 = XyzLocal, Enu, Ned, Aer # PYCHOK in .ltp

1241_XyzLocals5 = _XyzLocals4 + (Local9Tuple,) # PYCHOK in .ltp

1242

1243

1244class Uvw(_Vector3d):

1245 '''3-D C{u-v-w} (UVW) components.

1246 '''

1247 _toStr = _uvw_

1248

1249 def __init__(self, u_uvw, v=0, w=0, **name):

1250 '''New L{Uvw}.

1251

1252 @arg u_uvw: Scalar U component (C{meter}) or a previous instance (L{Uvw},

1253 L{Uvw3Tuple}, L{Vector3d}).

1254 @kwarg v: V component (C{meter}), iff B{C{u_uvw}} is C{meter}, ignored

1255 otherwise.

1256 @kwarg w: W component (C{meter}), iff B{C{u_uvw}} is C{meter}, ignored

1257 otherwise.

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

1259

1260 @raise TypeError: Invalid B{C{east_enu}}.

1261

1262 @raise UnitError: Invalid B{C{east_enu}}, B{C{v}} or B{C{w}}.

1263 '''

1264 Vector3d.__init__(self, u_uvw, v, w, **name)

1265

1266 def toEnu(self, location, Enu=Enu, **name_Enu_kwds):

1267 '''Get the I{East, North, Up} (ENU) components at a location.

1268

1269 @arg location: The geodetic (C{LatLon}) or geocentric (C{Cartesian},

1270 L{Vector3d}) location from where to cast the L{Los}.

1271 @kwarg Enu: Class to return ENU (L{Enu}) or C{None}.

1272 @kwarg name_Enu_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

1273 additional B{L{Enu}} keyword arguments, ignored if C{B{Enu}

1274 is None}.

1275

1276 @return: An B{C{Enu}} instance or an L{Enu4Tuple}C{(east, north, up, ltp)}

1277 with C{ltp=None} if C{B{Enu} is None}.

1278

1279 @raise TypeError: Invalid B{C{location}}, B{C{Enu}} or B{C{name_Enu_kwds}} item.

1280

1281 @see: Function U{lookAtSpheroid<https://PyPI.org/project/pymap3d>}.

1282 '''

1283 try:

1284 sa, ca, sb, cb = sincos2_(*location.philam)

1285 except Exception as x:

1286 raise _TypeError(location=location, cause=x)

1287 u, v, w = self.uvw

1288

1289 t = fdot_(cb, u, sb, v)

1290 E = fdot_(cb, v, -sb, u)

1291 N = fdot_(ca, w, -sa, t)

1292 U = fdot_(ca, t, sa, w)

1293

1294 n, kwds = _name2__(name_Enu_kwds, _or_nameof=self)

1295 return Enu4Tuple(E, N, U, name=n) if Enu is None else \

1296 Enu(E, N, U, name=n, **kwds)

1297

1298 u = Vector3d.x

1299

1300 @Property_RO

1301 def uvw(self):

1302 '''Get the C{(U, V, W)} components (L{Uvw3Tuple}C{(u, v, w)}).

1303 '''

1304 return Uvw3Tuple(self.u, self.v, self.w, name=self.name)

1305

1306 v = Vector3d.y

1307 w = Vector3d.z

1308

1309

1310class Uvw3Tuple(_NamedTuple):

1311 '''3-Tuple C{(u, v, w)}, in C{meter}.

1312 '''

1313 _Names_ = ('u', 'v', 'w')

1314 _Units_ = ( Meter, Meter, Meter)

1315

1316

1317class Los(Aer):

1318 '''A Line-Of-Sight (LOS) from a C{LatLon} or C{Cartesian} location.

1319 '''

1320

1321 def __init__(self, azimuth_aer, elevation=0, **name):

1322 '''New L{Los}.

1323

1324 @arg azimuth_aer: Scalar azimuth, bearing from North (compass C{degrees})

1325 or a previous instance (L{Aer}, L{Aer4Tuple}, L{Enu},

1326 L{Enu4Tuple} or L{Los}).

1327 @kwarg elevation: Scalar angle I{above} the horizon (C{degrees}, horizon

1328 is 0, zenith +90, nadir -90), if B{C{azimuth_aer}} is

1329 C{degrees}, ignored otherwise.

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

1331

1332 @raise TypeError: Invalid B{C{azimuth_aer}}.

1333

1334 @raise UnitError: Invalid B{C{azimuth_aer}} or B{C{elevation}}.

1335 '''

1336 t = Aer(azimuth_aer, elevation)

1337 Aer.__init__(self, t.azimuth, t.elevation, slantrange=_1_0, **name)

1338

1339 def toUvw(self, location, Uvw=Uvw, **name_Uvw_kwds):

1340 '''Get this LOS' I{target} (UVW) components from a location.

1341

1342 @arg location: The geodetic (C{LatLon}) or geocentric (C{Cartesian},

1343 L{Vector3d}) location from where to cast this LOS.

1344

1345 @see: Method L{Enu.toUvw} for further details.

1346 '''

1347 return self.toEnu().toUvw(location, Uvw=Uvw, **name_Uvw_kwds)

1348

1349 def toEnu(self, Enu=Enu, **name_Enu_kwds):

1350 '''Get this LOS as I{East, North, Up} (ENU) components.

1351

1352 @see: Method L{Aer.toEnu} for further details.

1353 '''

1354 return Aer.toEnu(self, Enu=Enu, **name_Enu_kwds)

1355

1356

1357class Footprint5Tuple(_NamedTuple):

1358 '''5-Tuple C{(center, upperleft, upperight, loweright, lowerleft)}

1359 with the C{center} and 4 corners of the I{local} projection of

1360 a C{Frustum}, each an L{Xyz4Tuple}, L{XyzLocal}, C{LatLon}, etc.

1361

1362 @note: Misspelling of C{upperight} and C{loweright} is I{intentional}.

1363 '''

1364 _Names_ = (_center_, 'upperleft', 'upperight', 'loweright', 'lowerleft')

1365 _Units_ = (_Pass, _Pass, _Pass, _Pass, _Pass)

1366

1367 def toLatLon5(self, ltp=None, LatLon=None, **name_LatLon_kwds):

1368 '''Convert this footprint's C{center} and 4 corners to I{geodetic}

1369 C{LatLon(lat, lon, height)}s, C{LatLon3Tuple}s or C{LatLon4Tuple}s.

1370

1371 @kwarg ltp: The I{local tangent plane} (L{Ltp}), overriding this

1372 footprint's C{center} or C{frustrum} C{ltp}.

1373 @kwarg LatLon: Optional I{geodetic} class (C{LatLon}) or C{None}.

1374 @kwarg name_LatLon_kwds: Optional C{B{name}=NN} (C{str}) and optionally,

1375 additional B{C{LatLon}} keyword arguments, ignored if C{B{LatLon}

1376 is None}.

1377

1378 @return: A L{Footprint5Tuple} of 5 C{B{LatLon}(lat, lon, **B{name_LatLon_kwds})}

1379 instances or if C{B{LatLon} is None}, 5 L{LatLon3Tuple}C{(lat, lon,

1380 height)}s respectively 5 L{LatLon4Tuple}C{(lat, lon, height, datum)}s

1381 depending on whether keyword argument C{datum} is un-/specified.

1382

1383 @raise TypeError: Invalid B{C{ltp}}, B{C{LatLon}} or B{C{name_LatLon_kwds}} item.

1384

1385 @see: Methods L{XyzLocal.toLatLon} and L{Footprint5Tuple.xyzLocal5}.

1386 '''

1387 ltp = _ltp._xLtp(ltp, self.center.ltp) # PYCHOK .center

1388 kwds = _name1__(name_LatLon_kwds, _or_nameof=self)

1389 kwds = _xkwds(kwds, ltp=ltp, LatLon=LatLon)

1390 return Footprint5Tuple(t.toLatLon(**kwds) for t in self.xyzLocal5())

1391

1392 def xyzLocal5(self, ltp=None):

1393 '''Return this footprint's C{center} and 4 corners as 5 L{XyzLocal}s.

1394

1395 @kwarg ltp: The I{local tangent plane} (L{Ltp}), overriding

1396 the {center} and corner C{ltp}s.

1397

1398 @return: A L{Footprint5Tuple} of 5 L{XyzLocal} instances.

1399

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

1401 '''

1402 if ltp is None:

1403 p = self

1404 else:

1405 p = _ltp._xLtp(ltp)

1406 p = tuple(Xyz4Tuple(t.x, t.y, t.z, p) for t in self)

1407 return Footprint5Tuple(t.xyzLocal for t in p)

1408

1409

1410def _er2gr(e, r):

1411 '''(INTERNAL) Elevation and slant range to ground range.

1412 '''

1413 c = cos(radians(e))

1414 return Meter_(groundrange=r * c)

1415

1416

1417def _init(inst, abc, ltp, name):

1418 '''(INTERNAL) Complete C{__init__}.

1419 '''

1420 if abc is None:

1421 n = _name__(**name)

1422 else:

1423 n = abc._name__(name)

1424 ltp = _xattr(abc, ltp=ltp)

1425 if ltp:

1426 inst._ltp = _ltp._xLtp(ltp)

1427 if n:

1428 inst.name = n

1429

1430

1431def _toStr2(inst, prec=None, fmt=Fmt.SQUARE, sep=_COMMASPACE_):

1432 '''(INTERNAL) Get attribute name and value strings, joined and bracketed.

1433 '''

1434 a = inst._toStr # 'aer', 'enu', 'ned', 'xyz'

1435 t = getattr(inst, a + _4_, ())[:len(a)] or getattr(inst, a)

1436 t = strs(t, prec=3 if prec is None else prec)

1437 if sep:

1438 t = sep.join(t)

1439 if fmt:

1440 t = fmt(t)

1441 return a, t

1442

1443

1444def _xyz2aer4(inst):

1445 '''(INTERNAL) Convert C{(x, y, z}) to C{(A, E, R)}.

1446 '''

1447 x, y, z, _ = inst.xyz4

1448 A = Azimuth(atan2b(x, y))

1449 E = Degrees(elevation=atan2d(z, hypot(x, y)))

1450 R = Meter(slantrange=hypot_(x, y, z))

1451 return Aer4Tuple(A, E, R, inst.ltp, name=inst.name)

1452

1453

1454def _xyzLocal(*Types, **name_inst):

1455 '''(INTERNAL) Get C{inst} or C{inst.xyzLocal}.

1456 '''

1457 n, inst = _xkwds_item2(name_inst)

1458 if isinstance(inst, Types):

1459 return None

1460 try:

1461 return inst.xyzLocal

1462 except (AttributeError, TypeError):

1463 raise _TypeError(n, inst, txt_not_=_local_)

1464

1465

1466__all__ += _ALL_DOCS(_AbcBase)

1467

1468# **) MIT License

1469#

1471#

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

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

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

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

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

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

1478#

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

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

1481#

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

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

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

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

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

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

1488# OTHER DEALINGS IN THE SOFTWARE.

Coverage for pygeodesy / ltpTuples.py: 96%

503 statements