Coverage for pygeodesy/ltp.py: 95%

423 statements  

« prev     ^ index     » next       coverage.py v7.6.1, created at 2025-04-25 13:15 -0400

1 

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

3 

4u'''I{Local Tangent Plane} (LTP) and I{local} cartesian coordinates. 

5 

6I{Local cartesian} and I{local tangent plane} classes L{LocalCartesian}, approximations L{ChLVa} 

7and L{ChLVe} and L{Ltp}, L{ChLV}, L{LocalError}, L{Attitude} and L{Frustum}. 

8 

9@see: U{Local tangent plane coordinates<https://WikiPedia.org/wiki/Local_tangent_plane_coordinates>} 

10 and class L{LocalCartesian}, transcoded from I{Charles Karney}'s C++ classU{LocalCartesian 

11 <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1LocalCartesian.html>}. 

12''' 

13# make sure int/int division yields float quotient, see .basics 

14from __future__ import division as _; del _ # PYCHOK semicolon 

15 

16from pygeodesy.basics import _args_kwds_names, _isin, map1, map2, _xinstanceof, \ 

17 _xsubclassof, typename # .datums 

18from pygeodesy.constants import EPS, INT0, _umod_360, _0_0, _0_01, _0_5, _1_0, \ 

19 _2_0, _60_0, _90_0, _100_0, _180_0, _3600_0, \ 

20 _N_1_0 # PYCHOK used! 

21# from pygeodesy.datums import _WGS84 # from .ecef 

22from pygeodesy.ecef import _EcefBase, EcefKarney, Ecef9Tuple, _llhn4, \ 

23 _xyzn4, _WGS84 

24from pygeodesy.errors import _NotImplementedError, _ValueError, _xattr, \ 

25 _xkwds, _xkwds_get, _xkwds_pop2 

26from pygeodesy.fmath import fabs, fdot, fdot_, Fhorner 

27from pygeodesy.fsums import _floor, fsumf_ 

28# from pygeodesy.internals import typename # from .basics 

29from pygeodesy.interns import _0_, _COMMASPACE_, _DOT_, _ecef_, _height_, _M_, \ 

30 _invalid_, _lat0_, _lon0_, _name_, _too_ 

31# from pygeodesy.lazily import _ALL_LAZY # from vector3d 

32from pygeodesy.ltpTuples import Attitude4Tuple, ChLVEN2Tuple, ChLV9Tuple, \ 

33 ChLVYX2Tuple, Footprint5Tuple, Local9Tuple, \ 

34 ChLVyx2Tuple, _XyzLocals4, _XyzLocals5, Xyz4Tuple 

35from pygeodesy.named import _name__, _name2__, _NamedBase, notOverloaded 

36from pygeodesy.namedTuples import LatLon3Tuple, LatLon4Tuple, Vector3Tuple 

37from pygeodesy.props import Property, Property_RO, property_doc_, \ 

38 property_ROver, _update_all 

39from pygeodesy.streprs import Fmt, strs, unstr 

40from pygeodesy.units import Bearing, Degrees, _isHeight, Meter 

41from pygeodesy.utily import cotd, _loneg, sincos2d, sincos2d_, tand, tand_, \ 

42 wrap180, wrap360 

43from pygeodesy.vector3d import _ALL_LAZY, Vector3d 

44 

45# from math import fabs, floor as _floor # from .fmath, .fsums 

46 

47__all__ = _ALL_LAZY.ltp 

48__version__ = '25.04.14' 

49 

50_height0_ = _height_ + _0_ 

51_narrow_ = 'narrow' 

52_wide_ = 'wide' 

53 

54 

55class Attitude(_NamedBase): 

56 '''The pose of a plane or camera in space. 

57 ''' 

58 _alt = Meter( alt =_0_0) 

59 _roll = Degrees(roll=_0_0) 

60 _tilt = Degrees(tilt=_0_0) 

61 _yaw = Bearing(yaw =_0_0) 

62 

63 def __init__(self, alt_attitude=INT0, tilt=INT0, yaw=INT0, roll=INT0, **name): 

64 '''New L{Attitude}. 

65 

66 @kwarg alt_attitude: Altitude (C{meter}) above earth or previous attitude 

67 (L{Attitude} or L{Attitude4Tuple}) with the C{B{alt}itude}, 

68 B{C{tilt}}, B{C{yaw}} and B{C{roll}}. 

69 @kwarg tilt: Pitch, elevation from horizontal (C{degrees180}), negative down 

70 (clockwise rotation along and around the x- or East axis). 

71 @kwarg yaw: Bearing, heading (compass C{degrees360}), clockwise from North 

72 (counter-clockwise rotation along and around the z- or Up axis). 

73 @kwarg roll: Roll, bank (C{degrees180}), positive to the right and down 

74 (clockwise rotation along and around the y- or North axis). 

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

76 

77 @raise AttitudeError: Invalid B{C{alt_attitude}}, B{C{tilt}}, B{C{yaw}} or 

78 B{C{roll}}. 

79 

80 @see: U{Principal axes<https://WikiPedia.org/wiki/Aircraft_principal_axes>} and 

81 U{Yaw, pitch, and roll rotations<http://MSL.CS.UIUC.edu/planning/node102.html>}. 

82 ''' 

83 if _isHeight(alt_attitude): 

84 t = Attitude4Tuple(alt_attitude, tilt, yaw, roll) 

85 else: 

86 try: 

87 t = alt_attitude.atyr 

88 except AttributeError: 

89 raise AttitudeError(alt=alt_attitude, tilt=tilt, yaw=yaw, rol=roll) 

90 for n, v in t.items(): 

91 if v: 

92 setattr(self, n, v) 

93 n = _name__(name, _or_nameof=t) 

94 if n: 

95 self.name = n 

96 

97 @property_doc_(' altitude above earth in C{meter}.') 

98 def alt(self): 

99 return self._alt 

100 

101 @alt.setter # PYCHOK setter! 

102 def alt(self, alt): # PYCHOK no cover 

103 a = Meter(alt=alt, Error=AttitudeError) 

104 if self._alt != a: 

105 _update_all(self) 

106 self._alt = a 

107 

108 altitude = alt 

109 

110 @Property_RO 

111 def atyr(self): 

112 '''Return this attitude's alt[itude], tilt, yaw and roll as an L{Attitude4Tuple}. 

113 ''' 

114 return Attitude4Tuple(self.alt, self.tilt, self.yaw, self.roll, name=self.name) 

115 

116 @Property_RO 

117 def matrix(self): 

118 '''Get the 3x3 rotation matrix C{R(yaw)·R(tilt)·R(roll)}, aka I{ZYX} (C{float}, row-order). 

119 

120 @see: Matrix M of case 10 in U{Appendix A 

121 <https://ntrs.NASA.gov/api/citations/19770019231/downloads/19770019231.pdf>}. 

122 ''' 

123 # to follow the definitions of rotation angles alpha, beta and gamma: 

124 # negate yaw since yaw is counter-clockwise around the z-axis, swap 

125 # tilt and roll since tilt is around the x- and roll around the y-axis 

126 sa, ca, sb, cb, sg, cg = sincos2d_(-self.yaw, self.roll, self.tilt) 

127 return ((ca * cb, fdot_(ca, sb * sg, -sa, cg), fdot_(ca, sb * cg, sa, sg)), 

128 (sa * cb, fdot_(sa, sb * sg, ca, cg), fdot_(sa, sb * cg, -ca, sg)), 

129 ( -sb, cb * sg, cb * cg)) 

130 

131 @property_doc_(' roll/bank in C{degrees180}, positive to the right and down.') 

132 def roll(self): 

133 return self._roll 

134 

135 @roll.setter # PYCHOK setter! 

136 def roll(self, roll): 

137 r = Degrees(roll=roll, wrap=wrap180, Error=AttitudeError) 

138 if self._roll != r: 

139 _update_all(self) 

140 self._roll = r 

141 

142 bank = roll 

143 

144 def rotate(self, x_xyz, y=None, z=None, Vector=None, **name_Vector_kwds): 

145 '''Transform a (local) cartesian by this attitude's matrix. 

146 

147 @arg x_xyz: X component of vector (C{scalar}) or (3-D) vector (C{Cartesian}, 

148 L{Vector3d} or L{Vector3Tuple}). 

149 @kwarg y: Y component of vector (C{scalar}), same units as B{C{x}}. 

150 @kwarg z: Z component of vector (C{scalar}), same units as B{C{x}}. 

151 @kwarg Vector: Class to return transformed point (C{Cartesian}, L{Vector3d} 

152 or C{Vector3Tuple}) or C{None}. 

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

154 additional B{C{Vector}} keyword arguments, ignored if C{B{Vector} 

155 is None}. 

156 

157 @return: A named B{C{Vector}} instance or if C{B{Vector} is None}, 

158 a named L{Vector3Tuple}C{(x, y, z)}. 

159 

160 @raise AttitudeError: Invalid B{C{x_xyz}}, B{C{y}} or B{C{z}}. 

161 

162 @raise TypeError: Invalid B{C{Vector}} or B{C{name_Vector_kwds}} item. 

163 

164 @see: U{Yaw, pitch, and roll rotations<http://MSL.CS.UIUC.edu/planning/node102.html>}. 

165 ''' 

166 try: 

167 try: 

168 xyz = map2(float, x_xyz.xyz3) 

169 except AttributeError: 

170 xyz = map1(float, x_xyz, y, z) 

171 except (TypeError, ValueError) as x: 

172 raise AttitudeError(x_xyz=x_xyz, y=y, z=z, cause=x) 

173 

174 x, y, z = (fdot(r, *xyz) for r in self.matrix) 

175 n, kwds = _name2__(name_Vector_kwds, _or_nameof=self) 

176 return Vector3Tuple(x, y, z, name=n) if Vector is None else \ 

177 Vector(x, y, z, name=n, **kwds) 

178 

179 @property_doc_(' tilt/pitch/elevation from horizontal in C{degrees180}, negative down.') 

180 def tilt(self): 

181 return self._tilt 

182 

183 @tilt.setter # PYCHOK setter! 

184 def tilt(self, tilt): 

185 t = Degrees(tilt=tilt, wrap=wrap180, Error=AttitudeError) 

186 if self._tilt != t: 

187 _update_all(self) 

188 self._tilt = t 

189 

190 elevation = pitch = tilt 

191 

192 def toStr(self, prec=6, sep=_COMMASPACE_, **unused): # PYCHOK signature 

193 '''Format this attitude as string. 

194 

195 @kwarg prec: The C{float} precision, number of decimal digits (0..9). 

196 Trailing zero decimals are stripped for B{C{prec}} values 

197 of 1 and above, but kept for negative B{C{prec}} values. 

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

199 

200 @return: This attitude (C{str}). 

201 ''' 

202 return self.atyr.toStr(prec=prec, sep=sep) 

203 

204 @Property_RO 

205 def tyr3d(self): 

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

207 

208 @see: U{Yaw, pitch, and roll rotations<http://MSL.CS.UIUC.edu/planning/node102.html>}. 

209 ''' 

210 def _r2d(r): 

211 return fsumf_(_N_1_0, *r) 

212 

213 return Vector3d(*map(_r2d, self.matrix), name__=tyr3d) 

214 

215 @property_doc_(' yaw/bearing/heading in compass C{degrees360}, clockwise from North.') 

216 def yaw(self): 

217 return self._yaw 

218 

219 @yaw.setter # PYCHOK setter! 

220 def yaw(self, yaw): 

221 y = Bearing(yaw=yaw, Error=AttitudeError) 

222 if self._yaw != y: 

223 _update_all(self) 

224 self._yaw = y 

225 

226 bearing = heading = yaw 

227 

228 

229class AttitudeError(_ValueError): 

230 '''An L{Attitude} or L{Attitude4Tuple} issue. 

231 ''' 

232 pass 

233 

234 

235class Frustum(_NamedBase): 

236 '''A rectangular pyramid, typically representing a camera's I{field-of-view} 

237 (fov) and the intersection with (or projection to) a I{local tangent plane}. 

238 

239 @see: U{Viewing frustum<https://WikiPedia.org/wiki/Viewing_frustum>}. 

240 ''' 

241 _h_2 = _0_0 # half hfov in degrees 

242 _ltp = None # local tangent plane 

243 _tan_h_2 = _0_0 # tan(_h_2) 

244 _v_2 = _0_0 # half vfov in degrees 

245 

246 def __init__(self, hfov, vfov, ltp=None, **name): 

247 '''New L{Frustum}. 

248 

249 @arg hfov: Horizontal field-of-view (C{degrees180}). 

250 @arg vfov: Vertical field-of-view (C{degrees180}). 

251 @kwarg ltp: Optional I{local tangent plane} (L{Ltp}). 

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

253 

254 @raise LocalError: Invalid B{C{hfov}} or B{C{vfov}}. 

255 ''' 

256 self._h_2 = h = _fov_2(hfov=hfov) 

257 self._v_2 = _fov_2(vfov=vfov) 

258 

259 self._tan_h_2 = tand(h, hfov_2=h) 

260 

261 if ltp: 

262 self._ltp = _xLtp(ltp) 

263 if name: 

264 self.name # PYCHOK effect 

265 

266 def footprint5(self, alt_attitude, tilt=0, yaw=0, roll=0, z=_0_0, ltp=None, **name): # MCCABE 15 

267 '''Compute the center and corners of the intersection with (or projection 

268 to) the I{local tangent plane} (LTP). 

269 

270 @arg alt_attitude: An altitude (C{meter}) above I{local tangent plane} or 

271 an attitude (L{Attitude} or L{Attitude4Tuple}) with the 

272 C{B{alt}itude}, B{C{tilt}}, B{C{yaw}} and B{C{roll}}. 

273 @kwarg tilt: Pitch, elevation from horizontal (C{degrees}), negative down 

274 (clockwise rotation along and around the x- or East axis). 

275 @kwarg yaw: Bearing, heading (compass C{degrees}), clockwise from North 

276 (counter-clockwise rotation along and around the z- or Up axis). 

277 @kwarg roll: Roll, bank (C{degrees}), positive to the right and down 

278 (clockwise rotation along and around the y- or North axis). 

279 @kwarg z: Optional height of the footprint (C{meter}) above I{local tangent plane}. 

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

281 frustum's C{ltp}. 

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

283 

284 @return: A L{Footprint5Tuple}C{(center, upperleft, upperight, loweright, 

285 lowerleft)} with the C{center} and 4 corners, each an L{Xyz4Tuple}. 

286 

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

288 

289 @raise UnitError: Invalid B{C{altitude}}, B{C{tilt}}, B{C{roll}} or B{C{z}}. 

290 

291 @raise ValueError: If B{C{altitude}} too low, B{C{z}} too high or B{C{tilt}} 

292 or B{C{roll}} -including B{C{vfov}} respectively B{C{hfov}}- 

293 over the horizon. 

294 

295 @see: U{Principal axes<https://WikiPedia.org/wiki/Aircraft_principal_axes>}. 

296 ''' 

297 def _xy2(a, e, h_2, tan_h_2, r): 

298 # left and right corners, or swapped 

299 if r < EPS: # no roll 

300 r = a * tan_h_2 

301 l = -r # PYCHOK l is ell 

302 else: # roll 

303 r, l = tand_(r - h_2, r + h_2, roll_hfov=r) # PYCHOK l is ell 

304 r *= -a # negate right positive 

305 l *= -a # PYCHOK l is ell 

306 y = a * cotd(e, tilt_vfov=e) 

307 return (l, y), (r, y) 

308 

309 def _xyz5(b, xy5, z, ltp): 

310 # rotate (x, y)'s by bearing, clockwise 

311 sc = sincos2d(b) 

312 for x, y in xy5: 

313 yield Xyz4Tuple(fdot(sc, x, y), 

314 fdot(sc, -x, y), z, ltp) 

315 

316 try: 

317 a, t, y, r = alt_attitude.atyr 

318 except AttributeError: 

319 a, t, y, r = alt_attitude, tilt, yaw, roll 

320 

321 a = Meter(altitude=a) 

322 if a < EPS: # too low 

323 raise _ValueError(altitude=a) 

324 if z: # PYCHOK no cover 

325 z = Meter(z=z) 

326 a -= z 

327 if a < EPS: # z above a 

328 raise _ValueError(altitude_z=a) 

329 else: 

330 z = _0_0 

331 

332 b = Degrees(yaw=y, wrap=wrap360) # bearing 

333 e = -Degrees(tilt=t, wrap=wrap180) # elevation, pitch 

334 if not EPS < e < _180_0: 

335 raise _ValueError(tilt=t) 

336 if e > _90_0: 

337 e = _loneg(e) 

338 b = _umod_360(b + _180_0) 

339 

340 r = Degrees(roll=r, wrap=wrap180) # roll center 

341 x = (-a * tand(r, roll=r)) if r else _0_0 

342 y = a * cotd(e, tilt=t) # ground range 

343 if fabs(y) < EPS: 

344 y = _0_0 

345 

346 v, h, t = self._v_2, self._h_2, self._tan_h_2 

347 # center and corners, clockwise from upperleft, rolled 

348 xy5 = ((x, y),) + _xy2(a, e - v, h, t, r) \ 

349 + _xy2(a, e + v, -h, -t, r) # swapped 

350 # turn center and corners by yaw, clockwise 

351 p = self.ltp if ltp is None else ltp # None OK 

352 return Footprint5Tuple(_xyz5(b, xy5, z, p), **name) # *_xyz5 

353 

354 @Property_RO 

355 def hfov(self): 

356 '''Get the horizontal C{fov} (C{degrees}). 

357 ''' 

358 return Degrees(hfov=self._h_2 * _2_0) 

359 

360 @Property_RO 

361 def ltp(self): 

362 '''Get the I{local tangent plane} (L{Ltp}) or C{None}. 

363 ''' 

364 return self._ltp 

365 

366 def toStr(self, prec=3, fmt=Fmt.F, sep=_COMMASPACE_): # PYCHOK signature 

367 '''Convert this frustum to a "hfov, vfov, ltp" string. 

368 

369 @kwarg prec: Number of (decimal) digits, unstripped (0..8 or C{None}). 

370 @kwarg fmt: Optional, C{float} format (C{letter}). 

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

372 

373 @return: Frustum in the specified form (C{str}). 

374 ''' 

375 t = self.hfov, self.vfov 

376 if self.ltp: 

377 t += self.ltp, 

378 t = strs(t, prec=prec, fmt=fmt) 

379 return sep.join(t) if sep else t 

380 

381 @Property_RO 

382 def vfov(self): 

383 '''Get the vertical C{fov} (C{degrees}). 

384 ''' 

385 return Degrees(vfov=self._v_2 * _2_0) 

386 

387 

388class LocalError(_ValueError): 

389 '''A L{LocalCartesian} or L{Ltp} related issue. 

390 ''' 

391 pass 

392 

393 

394class LocalCartesian(_NamedBase): 

395 '''Conversion between geodetic C{(lat, lon, height)} and I{local 

396 cartesian} C{(x, y, z)} coordinates with I{geodetic} origin 

397 C{(lat0, lon0, height0)}, transcoded from I{Karney}'s C++ class 

398 U{LocalCartesian<https://GeographicLib.SourceForge.io/C++/doc/ 

399 classGeographicLib_1_1LocalCartesian.html>}. 

400 

401 The C{z} axis is normal to the ellipsoid, the C{y} axis points due 

402 North. The plane C{z = -height0} is tangent to the ellipsoid. 

403 

404 The conversions all take place via geocentric coordinates using a 

405 geocentric L{EcefKarney}, by default the WGS84 datum/ellipsoid. 

406 

407 @see: Class L{Ltp}. 

408 ''' 

409 _ecef = EcefKarney(_WGS84) 

410 _Ecef = EcefKarney 

411 _lon00 = INT0 # self.lon0 

412 _t0 = None # origin (..., lat0, lon0, height0, ...) L{Ecef9Tuple} 

413 _9Tuple = Local9Tuple 

414 

415 def __init__(self, latlonh0=INT0, lon0=INT0, height0=INT0, ecef=None, **lon00_name): 

416 '''New L{LocalCartesian} converter. 

417 

418 @kwarg latlonh0: The (geodetic) origin (C{LatLon}, L{LatLon4Tuple}, L{Ltp} 

419 L{LocalCartesian} or L{Ecef9Tuple}) or the C{scalar} 

420 latitude of the (goedetic) origin (C{degrees}). 

421 @kwarg lon0: Longitude of the (goedetic) origin (C{degrees}), required if 

422 B{C{latlonh0}} is C{scalar}, ignored otherwise. 

423 @kwarg height0: Optional height (C{meter}, conventionally) at the (goedetic) 

424 origin perpendicular to and above (or below) the ellipsoid's 

425 surface, like B{C{lon0}}. 

426 @kwarg ecef: An ECEF converter (L{EcefKarney} I{only}), like B{C{lon0}}. 

427 @kwarg lon00_name: Optional C{B{name}=NN} (C{str}) and keyword argument 

428 C{B{lon00}=B{lon0}} for the arbitrary I{polar} longitude 

429 (C{degrees}), see method C{reverse} and property C{lon00} 

430 for further details. 

431 

432 @raise LocalError: If B{C{latlonh0}} not C{LatLon}, L{LatLon4Tuple}, L{Ltp}, 

433 L{LocalCartesian} or L{Ecef9Tuple} or B{C{latlonh0}}, 

434 B{C{lon0}}, B{C{height0}} or B{C{lon00}} invalid. 

435 

436 @raise TypeError: Invalid B{C{ecef}} or not L{EcefKarney}. 

437 

438 @note: If BC{latlonh0} is an L{Ltp} or L{LocalCartesian}, only C{lat0}, C{lon0}, 

439 C{height0} and I{polar} C{lon00} are copied, I{not} the ECEF converter. 

440 ''' 

441 self.reset(latlonh0, lon0=lon0, height0=height0, ecef=ecef, **lon00_name) 

442 

443 def __eq__(self, other): 

444 '''Compare this and an other instance. 

445 

446 @arg other: The other ellipsoid (L{LocalCartesian} or L{Ltp}). 

447 

448 @return: C{True} if equal, C{False} otherwise. 

449 ''' 

450 return other is self or (isinstance(other, self.__class__) and 

451 other.ecef == self.ecef and 

452 other._t0 == self._t0) 

453 

454 @Property_RO 

455 def datum(self): 

456 '''Get the ECEF converter's datum (L{Datum}). 

457 ''' 

458 return self.ecef.datum 

459 

460 @Property_RO 

461 def ecef(self): 

462 '''Get the ECEF converter (L{EcefKarney}). 

463 ''' 

464 return self._ecef 

465 

466 def _ecef2local(self, ecef, Xyz, name_Xyz_kwds): 

467 '''(INTERNAL) Convert geocentric/geodetic to local, like I{forward}. 

468 

469 @arg ecef: Geocentric (and geodetic) (L{Ecef9Tuple}). 

470 @arg Xyz: An L{XyzLocal}, L{Aer}, L{Enu} or L{Ned} I{class} or C{None}. 

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

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

473 is None}. 

474 

475 @return: An C{B{Xyz}(x, y, z, ltp, **B{name_Xyz_kwds}} instance or 

476 if C{B{Xyz} is None}, a L{Local9Tuple}C{(x, y, z, lat, lon, 

477 height, ltp, ecef, M)} with this C{ltp}, B{C{ecef}} 

478 (L{Ecef9Tuple}) converted to this C{datum} and C{M=None}, 

479 always. 

480 

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

482 ''' 

483 _xinstanceof(Ecef9Tuple, ecef=ecef) 

484 if ecef.datum != self.datum: 

485 ecef = ecef.toDatum(self.datum) 

486 n, kwds = _name2__(name_Xyz_kwds, _or_nameof=ecef) 

487 x, y, z = self.M.rotate(ecef.xyz, *self._t0_xyz) 

488 r = Local9Tuple(x, y, z, ecef.lat, ecef.lon, ecef.height, 

489 self, ecef, None, name=n) 

490 if Xyz: 

491 _xsubclassof(*_XyzLocals4, Xyz=Xyz) # Vector3d 

492 r = r.toXyz(Xyz=Xyz, name=n, **kwds) 

493 return r 

494 

495 @Property_RO 

496 def ellipsoid(self): 

497 '''Get the ECEF converter's ellipsoid (L{Ellipsoid}). 

498 ''' 

499 return self.ecef.datum.ellipsoid 

500 

501 def forward(self, latlonh, lon=None, height=0, M=False, **name): 

502 '''Convert I{geodetic} C{(lat, lon, height)} to I{local} cartesian 

503 C{(x, y, z)}. 

504 

505 @arg latlonh: Either a C{LatLon}, L{Ltp}, L{Ecef9Tuple} or C{scalar} 

506 (geodetic) latitude (C{degrees}). 

507 @kwarg lon: Optional C{scalar} (geodetic) longitude for C{scalar} 

508 B{C{latlonh}} (C{degrees}). 

509 @kwarg height: Optional height (C{meter}, conventionally) perpendicular 

510 to and above (or below) the ellipsoid's surface. 

511 @kwarg M: Optionally, return the I{concatenated} rotation L{EcefMatrix}, 

512 iff available (C{bool}). 

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

514 

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

516 with I{local} C{x}, C{y}, C{z}, I{geodetic} C{(lat}, C{lon}, 

517 C{height}, this C{ltp}, C{ecef} (L{Ecef9Tuple}) with 

518 I{geocentric} C{x}, C{y}, C{z} (and I{geodetic} C{lat}, 

519 C{lon}, C{height}) and the I{concatenated} rotation matrix 

520 C{M} (L{EcefMatrix}) if requested. 

521 

522 @raise LocalError: If B{C{latlonh}} not C{scalar}, C{LatLon}, L{Ltp}, 

523 L{Ecef9Tuple} or invalid or if B{C{lon}} not 

524 C{scalar} for C{scalar} B{C{latlonh}} or invalid 

525 or if B{C{height}} invalid. 

526 ''' 

527 lat, lon, h, n = _llhn4(latlonh, lon, height, Error=LocalError, **name) 

528 t = self.ecef._forward(lat, lon, h, n, M=M) 

529 x, y, z = self.M.rotate(t.xyz, *self._t0_xyz) 

530 m = self.M.multiply(t.M) if M else None 

531 return self._9Tuple(x, y, z, lat, lon, h, self, t, m, name=n or self.name) 

532 

533 @Property_RO 

534 def height0(self): 

535 '''Get the origin's height (C{meter}). 

536 ''' 

537 return self._t0.height 

538 

539 @Property_RO 

540 def lat0(self): 

541 '''Get the origin's latitude (C{degrees}). 

542 ''' 

543 return self._t0.lat 

544 

545 @Property_RO 

546 def latlonheight0(self): 

547 '''Get the origin's lat-, longitude and height (L{LatLon3Tuple}C{(lat, lon, height)}). 

548 ''' 

549 return LatLon3Tuple(self.lat0, self.lon0, self.height0, name=self.name) 

550 

551 def _local2ecef(self, local, nine=False, M=False): 

552 '''(INTERNAL) Convert I{local} to geocentric/geodetic, like I{.reverse}. 

553 

554 @arg local: Local (L{XyzLocal}, L{Enu}, L{Ned}, L{Aer} or L{Local9Tuple}). 

555 @kwarg nine: If C{True}, return a 9-, otherwise a 3-tuple (C{bool}). 

556 @kwarg M: Include the rotation matrix (C{bool}). 

557 

558 @return: A I{geocentric} 3-tuple C{(x, y, z)} or if C{B{nine}=True}, an 

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

560 rotation matrix C{M} (L{EcefMatrix}) if requested. 

561 ''' 

562 _xinstanceof(*_XyzLocals5, local=local) 

563 t = self.M.unrotate(local.xyz, *self._t0_xyz) 

564 if nine: 

565 t = self.ecef.reverse(*t, M=M) 

566 return t 

567 

568 @Property_RO 

569 def lon0(self): 

570 '''Get the origin's longitude (C{degrees}). 

571 ''' 

572 return self._t0.lon 

573 

574 @Property 

575 def lon00(self): 

576 '''Get the arbitrary, I{polar} longitude (C{degrees}). 

577 ''' 

578 return self._lon00 

579 

580 @lon00.setter # PYCHOK setter! 

581 def lon00(self, lon00): 

582 '''Set the arbitrary, I{polar} longitude (C{degrees}). 

583 ''' 

584 # lon00 <https://GitHub.com/mrJean1/PyGeodesy/issues/77> 

585 self._lon00 = Degrees(lon00=lon00) 

586 

587 @Property_RO 

588 def M(self): 

589 '''Get the rotation matrix (C{EcefMatrix}). 

590 ''' 

591 return self._t0.M 

592 

593 def reset(self, latlonh0=INT0, lon0=INT0, height0=INT0, ecef=None, **lon00_name): 

594 '''Reset this converter, see L{LocalCartesian.__init__} for more details. 

595 ''' 

596 _, name = _xkwds_pop2(lon00_name, lon00=None) # PYCHOK get **name 

597 if isinstance(latlonh0, LocalCartesian): 

598 if self._t0: 

599 _update_all(self) 

600 self._ecef = latlonh0.ecef 

601 self._lon00 = latlonh0.lon00 

602 self._t0 = latlonh0._t0 

603 n = _name__(name, _or_nameof=latlonh0) 

604 else: 

605 n = _name__(name, _or_nameof=self) 

606 lat0, lon0, height0, n = _llhn4(latlonh0, lon0, height0, suffix=_0_, 

607 Error=LocalError, name=n) 

608 if ecef: # PYCHOK no cover 

609 _xinstanceof(self._Ecef, ecef=ecef) 

610 _update_all(self) 

611 self._ecef = ecef 

612 elif self._t0: 

613 _update_all(self) 

614 self._t0 = self.ecef._forward(lat0, lon0, height0, n, M=True) 

615 self.lon00 = _xattr(latlonh0, lon00=_xkwds_get(lon00_name, lon00=lon0)) 

616 if n: 

617 self.rename(n) 

618 

619 def reverse(self, xyz, y=None, z=None, M=False, **lon00_name): 

620 '''Convert I{local} C{(x, y, z)} to I{geodetic} C{(lat, lon, height)}. 

621 

622 @arg xyz: A I{local} (L{XyzLocal}, L{Enu}, L{Ned}, L{Aer}, L{Local9Tuple}) or 

623 local C{x} coordinate (C{scalar}). 

624 @kwarg y: Local C{y} coordinate for C{scalar} B{C{xyz}} and B{C{z}} (C{meter}). 

625 @kwarg z: Local C{z} coordinate for C{scalar} B{C{xyz}} and B{C{y}} (C{meter}). 

626 @kwarg M: Optionally, return the I{concatenated} rotation L{EcefMatrix}, iff 

627 available (C{bool}). 

628 @kwarg lon00_name: Optional C{B{name}=NN} (C{str}) and keyword argument 

629 C{B{lon00}=B{lon0}} for the arbitrary I{polar} longitude 

630 (C{degrees}), overriding see the property C{B{lon00}=B{lon0}} 

631 value. The I{polar} longitude (C{degrees}) is returned with 

632 I{polar} latitudes C{abs(B{lat0}) == 90} for local C{B{x}=0} 

633 and C{B{y}=0} locations. 

634 

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

636 I{local} C{x}, C{y}, C{z}, I{geodetic} C{lat}, C{lon}, C{height}, 

637 this C{ltp}, an C{ecef} (L{Ecef9Tuple}) with the I{geocentric} C{x}, 

638 C{y}, C{z} (and I{geodetic} C{lat}, C{lon}, C{height}) and the 

639 I{concatenated} rotation matrix C{M} (L{EcefMatrix}) if requested. 

640 

641 @raise LocalError: Invalid B{C{xyz}} or C{scalar} C{x} or B{C{y}} and/or B{C{z}} 

642 not C{scalar} for C{scalar} B{C{xyz}}. 

643 ''' 

644 lon00, name =_xkwds_pop2(lon00_name, lon00=self.lon00) 

645 x, y, z, n = _xyzn4(xyz, y, z, _XyzLocals5, Error=LocalError, name=name) 

646 c = self.M.unrotate((x, y, z), *self._t0_xyz) 

647 t = self.ecef.reverse(*c, M=M, lon00=lon00) 

648 m = self.M.multiply(t.M) if M else None 

649 return self._9Tuple(x, y, z, t.lat, t.lon, t.height, self, t, m, name=n or self.name) 

650 

651 @Property_RO 

652 def _t0_xyz(self): 

653 '''(INTERNAL) Get C{(x0, y0, z0)} as L{Vector3Tuple}. 

654 ''' 

655 return self._t0.xyz 

656 

657 def toStr(self, prec=9, **unused): # PYCHOK signature 

658 '''Return this L{LocalCartesian} as a string. 

659 

660 @kwarg prec: Precision, number of (decimal) digits (0..9). 

661 

662 @return: This L{LocalCartesian} representation (C{str}). 

663 ''' 

664 return self.attrs(_lat0_, _lon0_, _height0_, _M_, _ecef_, _name_, prec=prec) 

665 

666 

667class Ltp(LocalCartesian): 

668 '''A I{local tangent plan} (LTP), a sub-class of C{LocalCartesian} with 

669 (re-)configurable ECEF converter. 

670 ''' 

671 _Ecef = _EcefBase 

672 

673 def __init__(self, latlonh0=INT0, lon0=INT0, height0=INT0, ecef=None, **lon00_name): 

674 '''New C{Ltp}, see L{LocalCartesian.__init__} for more details. 

675 

676 @kwarg ecef: Optional ECEF converter (L{EcefKarney}, L{EcefFarrell21}, 

677 L{EcefFarrell22}, L{EcefSudano}, L{EcefVeness} or 

678 L{EcefYou} I{instance}), overriding the default 

679 L{EcefKarney}C{(datum=Datums.WGS84)} for C{scalar}. 

680 

681 @see: Class L{LocalCartesian<LocalCartesian.__init__>} for further details. 

682 

683 @raise TypeError: Invalid B{C{ecef}}. 

684 ''' 

685 LocalCartesian.reset(self, latlonh0, lon0=lon0, height0=height0, 

686 ecef=ecef, **lon00_name) 

687 

688 @Property 

689 def ecef(self): 

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

691 ''' 

692 return self._ecef 

693 

694 @ecef.setter # PYCHOK setter! 

695 def ecef(self, ecef): 

696 '''Set this LTP's ECEF converter (C{Ecef...} I{instance}). 

697 

698 @raise TypeError: Invalid B{C{ecef}}. 

699 ''' 

700 _xinstanceof(_EcefBase, ecef=ecef) 

701 if self._ecef != ecef: # PYCHOK no cover 

702 self.reset(self._t0) 

703 self._ecef = ecef 

704 

705 

706class _ChLV(object): 

707 '''(INTERNAL) Base class for C{ChLV*} classes. 

708 ''' 

709 _03_falsing = ChLVyx2Tuple(0.6e6, 0.2e6) 

710# _92_falsing = ChLVYX2Tuple(2.0e6, 1.0e6) # _95_ - _03_ 

711 _95_falsing = ChLVEN2Tuple(2.6e6, 1.2e6) 

712 

713 def _ChLV9Tuple(self, fw, M, name, *Y_X_h_lat_lon_h): 

714 '''(INTERNAL) Helper for C{ChLVa/e.forward} and C{.reverse}. 

715 ''' 

716 if bool(M): # PYCHOK no cover 

717 m = self.forward if fw else self.reverse # PYCHOK attr 

718 n = _DOT_(*map1(typename, type(self), m)) 

719 raise _NotImplementedError(unstr(n, M=M), txt=None) 

720 t = Y_X_h_lat_lon_h + (self, self._t0, None) # PYCHOK _t0 

721 return ChLV9Tuple(t, name=name) 

722 

723 @property_ROver 

724 def _enh_n_h(self): 

725 '''(INTERNAL) Get C{ChLV*.reverse} args[1:4] names, I{once}. 

726 ''' 

727 t = _args_kwds_names(_ChLV.reverse)[1:4] 

728 # assert _args_kwds_names( ChLV.reverse)[1:4] == t 

729 # assert _args_kwds_names(ChLVa.reverse)[1:4] == t 

730 # assert _args_kwds_names(ChLVe.reverse)[1:4] == t 

731 return t # overwrite property_ROver 

732 

733 def forward(self, latlonh, lon=None, height=0, M=None, **name): # PYCHOK no cover 

734 '''Convert WGS84 geodetic to I{Swiss} projection coordinates. I{Must be overloaded}. 

735 

736 @arg latlonh: Either a C{LatLon}, L{Ltp} or C{scalar} (geodetic) latitude (C{degrees}). 

737 @kwarg lon: Optional, C{scalar} (geodetic) longitude for C{scalar} B{C{latlonh}} (C{degrees}). 

738 @kwarg height: Optional, height, vertically above (or below) the surface of the ellipsoid 

739 (C{meter}) for C{scalar} B{C{latlonh}} and B{C{lon}}. 

740 @kwarg M: If C{True}, return the I{concatenated} rotation L{EcefMatrix} iff available 

741 for C{ChLV} only, C{None} otherwise (C{bool}). 

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

743 

744 @return: A L{ChLV9Tuple}C{(Y, X, h_, lat, lon, height, ltp, ecef, M)} with the unfalsed 

745 I{Swiss Y, X} coordinates, I{Swiss h_} height, the given I{geodetic} C{lat}, 

746 C{lon} and C{height}, this C{ChLV*} instance and C{ecef} (L{Ecef9Tuple}) at 

747 I{Bern, Ch} and rotation matrix C{M}. The returned C{ltp} is this C{ChLV}, 

748 C{ChLVa} or C{ChLVe} instance. 

749 

750 @raise LocalError: Invalid or non-C{scalar} B{C{latlonh}}, B{C{lon}} or B{C{height}}. 

751 ''' 

752 notOverloaded(self, latlonh, lon=lon, height=height, M=M, **name) 

753 

754 def reverse(self, enh_, n=None, h_=0, M=None, **name): # PYCHOK no cover 

755 '''Convert I{Swiss} projection to WGS84 geodetic coordinates. 

756 

757 @arg enh_: A Swiss projection (L{ChLV9Tuple}) or the C{scalar}, falsed I{Swiss E_LV95} 

758 or I{y_LV03} easting (C{meter}). 

759 @kwarg n: Falsed I{Swiss N_LV85} or I{x_LV03} northing for C{scalar} B{C{enh_}} and 

760 B{C{h_}} (C{meter}). 

761 @kwarg h_: I{Swiss h'} height for C{scalar} B{C{enh_}} and B{C{n}} (C{meter}). 

762 @kwarg M: If C{True}, return the I{concatenated} rotation L{EcefMatrix} iff available 

763 for C{ChLV} only, C{None} otherwise (C{bool}). 

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

765 

766 @return: A L{ChLV9Tuple}C{(Y, X, h_, lat, lon, height, ltp, ecef, M)} with the unfalsed 

767 I{Swiss Y, X} coordinates, I{Swiss h_} height, the given I{geodetic} C{lat}, 

768 C{lon} and C{height}, this C{ChLV*} instance and C{ecef} (L{Ecef9Tuple}) at 

769 I{Bern, Ch} and rotation matrix C{M}. The returned C{ltp} is this C{ChLV}, 

770 C{ChLVa} or C{ChLVe} instance. 

771 

772 @raise LocalError: Invalid or non-C{scalar} B{C{enh_}}, B{C{n}} or B{C{h_}}. 

773 ''' 

774 notOverloaded(self, enh_, n=n, h_=h_, M=M, **name) 

775 

776 @staticmethod 

777 def _falsing2(LV95): 

778 '''(INTERNAL) Get the C{LV95} or C{LV03} falsing. 

779 ''' 

780 return _ChLV._95_falsing if _isin(LV95, True, 95) else ( 

781 _ChLV._03_falsing if _isin(LV95, False, 3) else ChLVYX2Tuple(0, 0)) 

782 

783 @staticmethod 

784 def _llh2abh_3(lat, lon, h): 

785 '''(INTERNAL) Helper for C{ChLVa/e.forward}. 

786 ''' 

787 def _deg2ab(deg, sLL): 

788 # convert degrees to arc-seconds 

789 def _dms(ds, p, q, swap): 

790 d = _floor(ds) 

791 t = (ds - d) * p 

792 m = _floor(t) 

793 s = (t - m) * p 

794 if swap: 

795 d, s = s, d 

796 return d + (m + s * q) * q 

797 

798 s = _dms(deg, _60_0, _0_01, False) # deg2sexag 

799 s = _dms( s, _100_0, _60_0, True) # sexag2asec 

800 return (s - sLL) / ChLV._s_ab 

801 

802 a = _deg2ab(lat, ChLV._sLat) # phi', lat_aux 

803 b = _deg2ab(lon, ChLV._sLon) # lam', lng_aux 

804 h_ = fsumf_(h, -ChLV.Bern.height, 2.73 * b, 6.94 * a) 

805 return a, b, h_ 

806 

807 @staticmethod 

808 def _YXh_2abh3(Y, X, h_): 

809 '''(INTERNAL) Helper for C{ChLVa/e.reverse}. 

810 ''' 

811 def _YX2ab(YX): 

812 return YX * ChLV._ab_m 

813 

814 a, b = map1(_YX2ab, Y, X) 

815 h = fsumf_(h_, ChLV.Bern.height, -12.6 * a, -22.64 * b) 

816 return a, b, h 

817 

818 def _YXh_n4(self, enh_, n, h_, **name): 

819 '''(INTERNAL) Helper for C{ChLV*.reverse}. 

820 ''' 

821 Y, X, h_, name = _xyzn4(enh_, n, h_, ChLV9Tuple, 

822 _xyz_y_z_names=self._enh_n_h, **name) 

823 if isinstance(enh_, ChLV9Tuple): 

824 Y, X = enh_.Y, enh_.X 

825 else: # isscalar(enh_) 

826 Y, X = ChLV.unfalse2(Y, X) # PYCHOK ChLVYX2Tuple 

827 return Y, X, h_, name 

828 

829 

830class ChLV(_ChLV, Ltp): 

831 '''Conversion between I{WGS84 geodetic} and I{Swiss} projection coordinates using 

832 L{pygeodesy.EcefKarney}'s Earth-Centered, Earth-Fixed (ECEF) methods. 

833 

834 @see: U{Swiss projection formulas<https://www.SwissTopo.admin.CH/en/maps-data-online/ 

835 calculation-services.html>}, page 7ff, U{NAVREF<https://www.SwissTopo.admin.CH/en/ 

836 maps-data-online/calculation-services/navref.html>}, U{REFRAME<https://www.SwissTopo.admin.CH/ 

837 en/maps-data-online/calculation-services/reframe.html>} and U{SwissTopo Scripts GPS WGS84 

838 <-> LV03<https://GitHub.com/ValentinMinder/Swisstopo-WGS84-LV03>}. 

839 ''' 

840 _9Tuple = ChLV9Tuple 

841 

842 _ab_d = 0.36 # a, b units per degree, ... 

843 _ab_m = 1.0e-6 # ... per meter and ... 

844 _ab_M = _1_0 # ... per 1,000 Km or 1 Mm 

845 _s_d = _3600_0 # arc-seconds per degree ... 

846 _s_ab = _s_d / _ab_d # ... and per a, b unit 

847 _sLat = 169028.66 # Bern, Ch in ... 

848 _sLon = 26782.5 # ... arc-seconds ... 

849 # lat, lon, height == 46°57'08.66", 7°26'22.50", 49.55m ("new" 46°57'07.89", 7°26'22.335") 

850 Bern = LatLon4Tuple(_sLat / _s_d, _sLon / _s_d, 49.55, _WGS84, name='Bern') 

851 

852 def __init__(self, latlonh0=Bern, **other_Ltp_kwds): 

853 '''New ECEF-based I{WGS84-Swiss} L{ChLV} converter, centered at I{Bern, Ch}. 

854 

855 @kwarg latlonh0: The I{geodetic} origin and height, overriding C{Bern, Ch}. 

856 @kwarg other_Ltp_kwds: Optional, other L{Ltp.__init__} keyword arguments. 

857 

858 @see: L{Ltp.__init__} for more information. 

859 ''' 

860 Ltp.__init__(self, latlonh0, **_xkwds(other_Ltp_kwds, ecef=None, name=ChLV.Bern.name)) 

861 

862 def forward(self, latlonh, lon=None, height=0, M=None, **name): # PYCHOK unused M 

863 # overloaded for the _ChLV.forward.__doc__ 

864 return Ltp.forward(self, latlonh, lon=lon, height=height, M=M, **name) 

865 

866 def reverse(self, enh_, n=None, h_=0, M=None, **name): # PYCHOK signature 

867 # overloaded for the _ChLV.reverse.__doc__ 

868 Y, X, h_, n = self._YXh_n4(enh_, n, h_, **name) 

869 return Ltp.reverse(self, Y, X, h_, M=M, name=n) 

870 

871 @staticmethod 

872 def false2(Y, X, LV95=True, **name): 

873 '''Add the I{Swiss LV95} or I{LV03} falsing. 

874 

875 @arg Y: Unfalsed I{Swiss Y} easting (C{meter}). 

876 @arg X: Unfalsed I{Swiss X} northing (C{meter}). 

877 @kwarg LV95: If C{True}, add C{LV95} falsing, if C{False} add 

878 C{LV03} falsing, otherwise leave unfalsed. 

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

880 

881 @return: A L{ChLVEN2Tuple}C{(E_LV95, N_LV95)} or a 

882 L{ChLVyx2Tuple}C{(y_LV03, x_LV03)} with falsed B{C{Y}} 

883 and B{C{X}}, otherwise a L{ChLVYX2Tuple}C{(Y, X)} 

884 with B{C{Y}} and B{C{X}} as-is. 

885 ''' 

886 e, n = t = _ChLV._falsing2(LV95) 

887 return t.classof(e + Y, n + X, **name) 

888 

889 @staticmethod 

890 def isLV03(e, n): 

891 '''Is C{(B{e}, B{n})} a valid I{Swiss LV03} projection? 

892 

893 @arg e: Falsed (or unfalsed) I{Swiss} easting (C{meter}). 

894 @arg n: Falsed (or unfalsed) I{Swiss} northing (C{meter}). 

895 

896 @return: C{True} if C{(B{e}, B{n})} is a valid, falsed I{Swiss 

897 LV03}, projection C{False} otherwise. 

898 ''' 

899 # @see: U{Map<https://www.SwissTopo.admin.CH/en/knowledge-facts/ 

900 # surveying-geodesy/reference-frames/local/lv95.html>} 

901 return 400.0e3 < e < 900.0e3 and 40.0e3 < n < 400.0e3 

902 

903 @staticmethod 

904 def isLV95(e, n, raiser=True): 

905 '''Is C{(B{e}, B{n})} a valid I{Swiss LV95} or I{LV03} projection? 

906 

907 @arg e: Falsed (or unfalsed) I{Swiss} easting (C{meter}). 

908 @arg n: Falsed (or unfalsed) I{Swiss} northing (C{meter}). 

909 @kwarg raiser: If C{True}, throw a L{LocalError} if B{C{e}} and 

910 B{C{n}} are invalid I{Swiss LV95} nor I{LV03}. 

911 

912 @return: C{True} or C{False} if C{(B{e}, B{n})} is a valid I{Swiss 

913 LV95} respectively I{LV03} projection, C{None} otherwise. 

914 ''' 

915 if ChLV.isLV03(e, n): 

916 return False 

917 elif ChLV.isLV03(e - 2.0e6, n - 1.0e6): # _92_falsing = _95_ - _03_ 

918 return True 

919 elif raiser: # PYCHOK no cover 

920 raise LocalError(unstr(ChLV.isLV95, e=e, n=n)) 

921 return None 

922 

923 @staticmethod 

924 def unfalse2(e, n, LV95=None, **name): 

925 '''Remove the I{Swiss LV95} or I{LV03} falsing. 

926 

927 @arg e: Falsed I{Swiss E_LV95} or I{y_LV03} easting (C{meter}). 

928 @arg n: Falsed I{Swiss N_LV95} or I{x_LV03} northing (C{meter}). 

929 @kwarg LV95: If C{True}, remove I{LV95} falsing, if C{False} remove 

930 I{LV03} falsing, otherwise use method C{isLV95(B{e}, B{n})}. 

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

932 

933 @return: A L{ChLVYX2Tuple}C{(Y, X)} with the unfalsed B{C{e}} 

934 respectively B{C{n}}. 

935 ''' 

936 Y, X = _ChLV._falsing2(ChLV.isLV95(e, n) if LV95 is None else LV95) 

937 return ChLVYX2Tuple(e - Y, n - X, **name) 

938 

939 

940class ChLVa(_ChLV, LocalCartesian): 

941 '''Conversion between I{WGS84 geodetic} and I{Swiss} projection coordinates 

942 using the U{Approximate<https://www.SwissTopo.admin.CH/en/maps-data-online/ 

943 calculation-services.html>} formulas, page 13. 

944 

945 @see: Older U{references<https://GitHub.com/alphasldiallo/Swisstopo-WGS84-LV03>}. 

946 ''' 

947 def __init__(self, name=ChLV.Bern.name): 

948 '''New I{Approximate WGS84-Swiss} L{ChLVa} converter, centered at I{Bern, Ch}. 

949 

950 @kwarg name: Optional C{B{name}=Bern.name} (C{str}). 

951 ''' 

952 LocalCartesian.__init__(self, latlonh0=ChLV.Bern, name=name) 

953 

954 def forward(self, latlonh, lon=None, height=0, M=None, **name): 

955 # overloaded for the _ChLV.forward.__doc__ 

956 lat, lon, h, n = _llhn4(latlonh, lon, height, **name) 

957 a, b, h_ = _ChLV._llh2abh_3(lat, lon, h) 

958 a2, b2 = a**2, b**2 

959 

960 Y = fdot_(211455.93, b, 

961 -10938.51, b * a, 

962 -0.36, b * a2, 

963 -44.54, b * b2, start=72.37) # + 600_000 

964 X = fdot_(308807.95, a, 

965 3745.25, b2, 

966 76.63, a2, 

967 -194.56, b2 * a, 

968 119.79, a2 * a, start=147.07) # + 200_000 

969 return self._ChLV9Tuple(True, M, n, Y, X, h_, lat, lon, h) 

970 

971 def reverse(self, enh_, n=None, h_=0, M=None, **name): # PYCHOK signature 

972 # overloaded for the _ChLV.reverse.__doc__ 

973 Y, X, h_, n = self._YXh_n4(enh_, n, h_, **name) 

974 a, b, h = _ChLV._YXh_2abh3(Y, X, h_) 

975 ab_d, a2, b2 = ChLV._ab_d, a**2, b**2 

976 

977 lat = fdot_(3.238272, b, 

978 -0.270978, a2, 

979 -0.002528, b2, 

980 -0.0447, a2 * b, 

981 -0.014, b2 * b, start=16.9023892) / ab_d 

982 lon = fdot_(4.728982, a, 

983 0.791484, a * b, 

984 0.1306, a * b2, 

985 -0.0436, a * a2, start=2.6779094) / ab_d 

986 return self._ChLV9Tuple(False, M, n, Y, X, h_, lat, lon, h) 

987 

988 

989class ChLVe(_ChLV, LocalCartesian): 

990 '''Conversion between I{WGS84 geodetic} and I{Swiss} projection coordinates 

991 using the U{Ellipsoidal approximate<https://www.SwissTopo.admin.CH/en/ 

992 maps-data-online/calculation-services.html>} formulas, pp 10-11 and U{Bolliger, 

993 J.<https://eMuseum.GGGS.CH/literatur-lv/liste-Dateien/1967_Bolliger_a.pdf>} 

994 pp 148-151 (also U{GGGS<https://eMuseum.GGGS.CH/literatur-lv/liste.htm>}). 

995 

996 @note: Methods L{ChLVe.forward} and L{ChLVe.reverse} have an additional keyword 

997 argument C{B{gamma}=False} to approximate the I{meridian convergence}. 

998 If C{B{gamma}=True} a 2-tuple C{(t, gamma)} is returned with C{t} the 

999 usual result (C{ChLV9Tuple}) and C{gamma}, the I{meridian convergence} 

1000 (decimal C{degrees}). To convert C{gamma} to C{grades} or C{gons}, 

1001 use function L{pygeodesy.degrees2grades}. 

1002 

1003 @see: Older U{references<https://GitHub.com/alphasldiallo/Swisstopo-WGS84-LV03>}. 

1004 ''' 

1005 def __init__(self, name=ChLV.Bern.name): 

1006 '''New I{Approximate WGS84-Swiss} L{ChLVe} converter, centered at I{Bern, Ch}. 

1007 

1008 @kwarg name: Optional C{B{name}=Bern.name} (C{str}). 

1009 ''' 

1010 LocalCartesian.__init__(self, latlonh0=ChLV.Bern, name=name) 

1011 

1012 def forward(self, latlonh, lon=None, height=0, M=None, gamma=False, **name): # PYCHOK gamma 

1013 # overloaded for the _ChLV.forward.__doc__ 

1014 lat, lon, h, n = _llhn4(latlonh, lon, height, **name) 

1015 a, b, h_ = _ChLV._llh2abh_3(lat, lon, h) 

1016 ab_M, z, _H = ChLV._ab_M, 0, Fhorner 

1017 

1018 B1 = _H(a, 211428.533991, -10939.608605, -2.658213, -8.539078, -0.00345, -0.007992) 

1019 B3 = _H(a, -44.232717, 4.291740, -0.309883, 0.013924) 

1020 B5 = _H(a, 0.019784, -0.004277) 

1021 Y = _H(b, z, B1, z, B3, z, B5).fover(ab_M) # 1,000 Km! 

1022 

1023 B0 = _H(a, z, 308770.746371, 75.028131, 120.435227, 0.009488, 0.070332, -0.00001) 

1024 B2 = _H(a, 3745.408911, -193.792705, 4.340858, -0.376174, 0.004053) 

1025 B4 = _H(a, -0.734684, 0.144466, -0.011842) 

1026 X = _H(b, B0, z, B2, z, B4, z, 0.000488).fover(ab_M) # 1,000 Km! 

1027 

1028 t = self._ChLV9Tuple(True, M, n, Y, X, h_, lat, lon, h) 

1029 if gamma: 

1030 U1 = _H(a, 2255515.207166, 2642.456961, 1.284180, 2.577486, 0.001165) 

1031 U3 = _H(a, -412.991934, 64.106344, -2.679566, 0.123833) 

1032 U5 = _H(a, 0.204129, -0.037725) 

1033 g = _H(b, z, U1, z, U3, z, U5).fover(ChLV._ab_m) # * ChLV._ab_d degrees? 

1034 t = t, g 

1035 return t 

1036 

1037 def reverse(self, enh_, n=None, h_=0, M=None, gamma=False, **name): # PYCHOK gamma 

1038 # overloaded for the _ChLV.reverse.__doc__ 

1039 Y, X, h_, n = self._YXh_n4(enh_, n, h_, **name) 

1040 a, b, h = _ChLV._YXh_2abh3(Y, X, h_) 

1041 s_d, _H, z = ChLV._s_d, Fhorner, 0 

1042 

1043 A0 = _H(b, ChLV._sLat, 32386.4877666, -25.486822, -132.457771, 0.48747, 0.81305, -0.0069) 

1044 A2 = _H(b, -2713.537919, -450.442705, -75.53194, -14.63049, -2.7604) 

1045 A4 = _H(b, 24.42786, 13.20703, 4.7476) 

1046 lat = _H(a, A0, z, A2, z, A4, z, -0.4249).fover(s_d) 

1047 

1048 A1 = _H(b, 47297.3056722, 7925.714783, 1328.129667, 255.02202, 48.17474, 9.0243) 

1049 A3 = _H(b, -442.709889, -255.02202, -96.34947, -30.0808) 

1050 A5 = _H(b, 9.63495, 9.0243) 

1051 lon = _H(a, ChLV._sLon, A1, z, A3, z, A5).fover(s_d) 

1052 # == (ChLV._sLon + a * (A1 + a**2 * (A3 + a**2 * A5))) / s_d 

1053 

1054 t = self._ChLV9Tuple(False, M, n, Y, X, h_, lat, lon, h) 

1055 if gamma: 

1056 U1 = _H(b, 106679.792202, 17876.57022, 4306.5241, 794.87772, 148.1545, 27.8725) 

1057 U3 = _H(b, -1435.508, -794.8777, -296.309, -92.908) 

1058 U5 = _H(b, 29.631, 27.873) 

1059 g = _H(a, z, U1, z, U3, z, U5).fover(ChLV._s_ab) # degrees 

1060 t = t, g 

1061 return t 

1062 

1063 

1064def _fov_2(**fov): 

1065 # Half a field-of-view angle in C{degrees}. 

1066 f = Degrees(Error=LocalError, **fov) * _0_5 

1067 if EPS < f < _90_0: 

1068 return f 

1069 t = _invalid_ if f < 0 else _too_(_wide_ if f > EPS else _narrow_) 

1070 raise LocalError(txt=t, **fov) 

1071 

1072 

1073def _toLocal(inst, ltp, Xyz, Xyz_kwds): 

1074 '''(INTERNAL) Helper for C{CartesianBase.toAer}, C{CartesianBase.toEnu}, 

1075 C{CartesianBase.toLocal}, C{CartesianBase.toNed} and C{latLonBase.toLocal}. 

1076 ''' 

1077 return _xLtp(ltp, inst._Ltp)._ecef2local(inst._ecef9, Xyz, Xyz_kwds) 

1078 

1079 

1080def _toLtp(inst, Ecef, ecef9, name): 

1081 '''(INTERNAL) Helper for C{CartesianBase.toLtp}, C{ecef.toLtp} and C{latLonBase.toLtp}. 

1082 ''' 

1083 return inst._Ltp if (not name) and _isin(Ecef, None, inst.Ecef) else \ 

1084 Ltp(ecef9, ecef=Ecef(inst.datum), name=inst._name__(name)) 

1085 

1086 

1087def tyr3d(tilt=INT0, yaw=INT0, roll=INT0, Vector=Vector3d, **name_Vector_kwds): 

1088 '''Convert an attitude pose into a (3-D) direction vector. 

1089 

1090 @kwarg tilt: Pitch, elevation from horizontal (C{degrees}), negative down 

1091 (clockwise rotation along and around the x-axis). 

1092 @kwarg yaw: Bearing, heading (compass C{degrees360}), clockwise from North 

1093 (counter-clockwise rotation along and around the z-axis). 

1094 @kwarg roll: Roll, bank (C{degrees}), positive to the right and down 

1095 (clockwise rotation along and around the y-axis). 

1096 @kwarg Vector: Class to return the direction vector (C{Cartesian}, 

1097 L{Vector3d} or C{Vector3Tuple}) or C{None}. 

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

1099 additional B{C{Vector}} keyword arguments, ignored if C{B{Vector} 

1100 is None}. 

1101 

1102 @return: A named B{C{Vector}} instance or if C{B{Vector} is None}, 

1103 a named L{Vector3Tuple}C{(x, y, z)}. 

1104 

1105 @raise AttitudeError: Invalid B{C{tilt}}, B{C{yaw}} or B{C{roll}}. 

1106 

1107 @raise TypeError: Invalid B{C{Vector}} or B{C{name_Vector_kwds}}. 

1108 

1109 @see: U{Yaw, pitch, and roll rotations<http://MSL.CS.UIUC.edu/planning/node102.html>} 

1110 and function L{pygeodesy.hartzell} argument C{los}, Line-Of-Sight. 

1111 ''' 

1112 v = Attitude4Tuple(_0_0, tilt, yaw, roll).tyr3d 

1113 if Vector is not type(v): 

1114 n, kwds = _name2__(name_Vector_kwds, name__=tyr3d) 

1115 v = Vector3Tuple(v.x, v.y, v.z, name=n) if Vector is None else \ 

1116 Vector(v.x, v.y, v.z, name=n, **kwds) 

1117 elif name_Vector_kwds: 

1118 n, _ = _name2__(name_Vector_kwds) 

1119 if n: 

1120 v = v.copy(name=n) 

1121 return v 

1122 

1123 

1124def _xLtp(ltp, *dflt): 

1125 '''(INTERNAL) Validate B{C{ltp}} if not C{None} else B{C{dflt}}. 

1126 ''' 

1127 if dflt and ltp is None: 

1128 ltp = dflt[0] 

1129 _xinstanceof(Ltp, LocalCartesian, ltp=ltp) 

1130 return ltp 

1131 

1132# **) MIT License 

1133# 

1134# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved. 

1135# 

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

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

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

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

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

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

1142# 

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

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

1145# 

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

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

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

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

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

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

1152# OTHER DEALINGS IN THE SOFTWARE.