Coverage for pygeodesy/namedTuples.py: 95%

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

4u'''Named tuples.

6Tuples returned by C{pygeodesy} functions and class methods

7are all instances of some C{Named...Tuple} class, all sub-classes

8of C{_NamedTuple} defined in C{pygeodesy.named}.

9'''

11from pygeodesy.basics import isinstanceof, issubclassof, map1, _xinstanceof

12# from pygeodesy.cartesianBase import CartesianBase # _MODS

13from pygeodesy.constants import INT0, _0_5, fabs # PYCHOK used! _0_5

14# from pygeodesy.dms import toDMS # _MODS

15from pygeodesy.errors import _TypeError, _xattr, _xkwds, _xkwds_not, _xkwds_pop2

16# from pygeodesy.internals import typename # from .named

17from pygeodesy.interns import NN, _1_, _2_, _a_, _A_, _area_, _angle_, _b_, _B_, \

18 _band_, _beta_, _c_, _C_, _D_, _datum_, _distance_, \

19 _E_, _easting_, _end_, _fi_, _gamma_, _h_, _height_, \

20 _hemipole_, _initial_, _j_, _lam_, _lat_, _lon_, \

21 _n_, _northing_, _number_, _outside_, _phi_, _point_, \

22 _precision_, _points_, _radius_, _scale_, _start_, \

23 _x_, _y_, _z_, _zone_

24# from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS # from .named

25from pygeodesy.named import _NamedTuple, _Pass, _ALL_LAZY, _MODS, typename

26from pygeodesy.props import deprecated_property_RO, Property_RO, property_RO

27from pygeodesy.units import Band, Bearing, Degrees, Degrees2, Easting, FIx, \

28 Height, Int, Lam, Lat, Lon, Meter, Meter2, \

29 Northing, Number_, Phi, Precision_, Radians, \

30 Radius, Scalar, Str

31# from math import fabs # from .constants

33__all__ = _ALL_LAZY.namedTuples

34__version__ = '26.05.23'

36# __DUNDER gets mangled in class

37_closest_ = 'closest'

38_destination_ = 'destination'

39_elel_ = 'll'

40_final_ = 'final'

41_fraction_ = 'fraction'

44class Bearing2Tuple(_NamedTuple):

45 '''2-Tuple C{(initial, final)} bearings, both in compass C{degrees360}.

46 '''

47 _Names_ = (_initial_, _final_)

48 _Units_ = ( Bearing, Bearing)

51class Bounds2Tuple(_NamedTuple): # .geohash.py, .latlonBase.py, .points.py

52 '''2-Tuple C{(latlonSW, latlonNE)} with the bounds' lower-left and

53 upper-right corner as C{LatLon} instance.

54 '''

55 _Names_ = ('latlonSW', 'latlonNE')

56 _Units_ = (_Pass, _Pass)

59class Bounds4Tuple(_NamedTuple): # .geohash.py, .points.py

60 '''4-Tuple C{(latS, lonW, latN, lonE)} with the bounds' lower-left

61 C{(LatS, LowW)} and upper-right C{(latN, lonE)} corner lat- and

62 longitudes.

63 '''

64 _Names_ = ('latS', 'lonW', 'latN', 'lonE')

65 _Units_ = ( Lat, Lon, Lat, Lon)

67 def enclosures(self, S_other, *W_N_E):

68 '''Get the enclosures of this around an other L{Bounds4Tuple}.

70 @arg S_other: Bottom C{latS} (C{scalar}) or an other

71 L{Bounds4Tuple} instance.

72 @arg W_N_E: Left C{lonW}, top C{latN} and right C{lonE},

73 each a (C{scalar}) for C{scalar B{S_other}}.

75 @return: A L{Bounds4Tuple} with the I{margin} at each of

76 the 4 sides, positive if this side I{encloses}

77 (is on the I{outside} of) the other, negative

78 if not or zero if abutting.

79 '''

80 s, w, n, e, \

81 S, W, N, E = self._plus_other8(S_other, W_N_E)

82 return Bounds4Tuple(map1(float, S - s, W - w, n - N, e - E), # *map1

83 name=typename(Bounds4Tuple.enclosures))

85 @Property_RO

86 def latC(self):

87 '''Get the center latitude (C{degrees}).

88 '''

89 return Lat(latC=(self.latS + self.latN) * _0_5)

91 @Property_RO

92 def lonC(self):

93 '''Get the center longitude (C{degrees}).

94 '''

95 return Lon(lonC=(self.lonW + self.lonE) * _0_5)

97 def overlap(self, S_other, *W_N_E):

98 '''Intersect this with an other L{Bounds4Tuple}.

100 @arg S_other: Bottom C{latS} (C{scalar}) or an other

101 L{Bounds4Tuple} instance.

102 @arg W_N_E: Left C{lonW}, top C{latN} and right C{lonE},

103 each a (C{scalar}) for C{scalar B{S_other}}.

104

105 @return: C{None} if the bounds do not overlap, otherwise

106 the intersection of both as a L{Bounds4Tuple}.

107 '''

108 s, w, n, e, \

109 S, W, N, E = self._plus_other8(S_other, W_N_E)

110 return None if s > N or n < S or w > E or e < W else \

111 Bounds4Tuple(max(s, S), max(w, W), min(n, N), min(e, E),

112 name=typename(Bounds4Tuple.overlap))

113

114 def _plus_other8(self, S_other, W_N_E):

115 # return this (s, w, n, e) + other (S, W, N, E)

116 if W_N_E:

117 S_other = map1(float, S_other, *W_N_E)

118 else:

119 _xinstanceof(Bounds4Tuple, S_other=S_other)

120 return self + S_other

121

122

123class Circle4Tuple(_NamedTuple):

124 '''4-Tuple C{(radius, height, lat, beta)} with the C{radius} and C{height}

125 of a parallel I{circle of latitude} at (geodetic) latitude C{lat} and

126 I{parametric (or reduced) auxiliary latitude} C{beta} on a I{biaxial

127 ellipsoid}.

128

129 The C{height} is the (signed) distance along the z-axis between the

130 parallel and the equator. At near-polar C{lat}s, the C{radius} is C{0},

131 the C{height} is the ellipsoid's polar radius (signed) and C{beta}

132 equals C{lat}. The latter are in C{degrees90}, always.

133

134 @see: Class L{Ellipse5Tuple}.

135 '''

136 _Names_ = (_radius_, _height_, _lat_, _beta_)

137 _Units_ = ( Radius, Height, Lat, Lat)

138

139 @property_RO

140 def abc3(self):

141 '''Get the non-negative semi-axes as 3-tuple C{(a, b, c)}.

142 '''

143 return map1(fabs, self.radius, self.radius, self.height) # PYCHOK named

144

145

146class Destination2Tuple(_NamedTuple): # .ellipsoidalKarney.py, -Vincenty.py

147 '''2-Tuple C{(destination, final)}, C{destination} in C{LatLon}

148 and C{final} bearing in compass C{degrees360}.

149 '''

150 _Names_ = (_destination_, _final_)

151 _Units_ = (_Pass, Bearing)

152

153

154class Destination3Tuple(_NamedTuple): # .karney.py

155 '''3-Tuple C{(lat, lon, final)}, destination C{lat}, C{lon} in

156 C{degrees90} respectively C{degrees180} and C{final} bearing

157 in compass C{degrees360}.

158 '''

159 _Names_ = (_lat_, _lon_, _final_)

160 _Units_ = ( Lat, Lon, Bearing)

161

162

163class Distance2Tuple(_NamedTuple): # .datum.py, .ellipsoidalBase.py

164 '''2-Tuple C{(distance, initial)}, C{distance} in C{meter} and

165 C{initial} bearing in compass C{degrees360}.

166 '''

167 _Names_ = (_distance_, _initial_)

168 _Units_ = ( Meter, Bearing)

169

170

171class Distance3Tuple(_NamedTuple): # .ellipsoidalKarney.py, -Vincenty.py

172 '''3-Tuple C{(distance, initial, final)}, C{distance} in C{meter}

173 and C{initial} and C{final} bearing, both in compass C{degrees360}.

174 '''

175 _Names_ = (_distance_, _initial_, _final_)

176 _Units_ = ( Meter, Bearing, Bearing)

177

178

179class Distance4Tuple(_NamedTuple): # .formy.py, .points.py

180 '''4-Tuple C{(distance2, delta_lat, delta_lon, unroll_lon2)} with

181 the distance in C{degrees squared}, the latitudinal C{delta_lat

182 = B{lat2} - B{lat1}}, the wrapped, unrolled and adjusted

183 longitudinal C{delta_lon = B{lon2} - B{lon1}} and C{unroll_lon2},

184 the unrolled or original B{C{lon2}}.

185

186 @note: Use Function L{pygeodesy.degrees2m} to convert C{degrees

187 squared} to C{meter} as M{degrees2m(sqrt(distance2), ...)}

188 or M{degrees2m(hypot(delta_lat, delta_lon), ...)}.

189 '''

190 _Names_ = ('distance2', 'delta_lat', 'delta_lon', 'unroll_lon2')

191 _Units_ = ( Degrees2, Degrees, Degrees, Degrees)

192

193

194class EasNor2Tuple(_NamedTuple): # .css, .osgr, .ups, .utm, .utmupsBase

195 '''2-Tuple C{(easting, northing)}, both in C{meter}, conventionally.

196 '''

197 _Names_ = (_easting_, _northing_)

198 _Units_ = ( Easting, Northing)

199

200

201class EasNor3Tuple(_NamedTuple): # .css.py, .lcc.py

202 '''3-Tuple C{(easting, northing, height)}, all in C{meter}, conventionally.

203 '''

204 _Names_ = (_easting_, _northing_, _height_)

205 _Units_ = ( Easting, Northing, Height)

206

207

208class _Convergence(object):

209 '''(INTERNAL) DEPRECATED Property C{convergence}, use property C{gamma}.'''

210 @deprecated_property_RO

211 def convergence(self):

212 '''DEPRECATED, use property C{gamma}.

213 '''

214 return self.gamma # PYCHOK self[.]

215

216

217class Ellipse5Tuple(_NamedTuple): # in .triaxials.bases._UnOrderedTriaxialBase.ellipse5

218 '''5-Tuple C{(a, b, height, lat, beta)} with semi-axes C{a} and C{b} of a parallel

219 I{ellipse of latitude} at (geodetic) latitude C{lat} and I{parametric (or reduced)

220 auxiliary latitude} C{beta} of a I{triaxial ellipsoid}.

221

222 The C{height} is the (signed) distance between the parallel and the triaxial's

223 equatorial plane. At near-polar C{lat}s, C{a} and C{b} are C{0}, the C{height}

224 is the triaxial semi-axis C{c} (signed) and C{beta} equals C{lat}. The latter

225 are in C{degrees90}, always.

226

227 @see: Class L{Circle4Tuple}.

228 '''

229 _Names_ = (_a_, _b_, _height_, _lat_, _beta_)

230 _Units_ = ( Radius, Radius, Height, Lat, Lat)

231

232 @property_RO

233 def abc3(self):

234 '''Get the semi-axes as 3-tuple C{(a, b, c)}, non-negative.

235 '''

236 return map1(fabs, self.a, self.b, self.height) # PYCHOK namedTuple

237

238 @property_RO

239 def abc3ordered(self):

240 '''Get the semi-axes as 3-tuple C{(a, b, c)}, non-negative, ordered.

241 '''

242 return tuple(reversed(sorted(self.abc3)))

243

244 def toTriaxial(self, **Triaxial_and_kwds): # like .Ellipse.toTriaxial_

245 '''Return a L{Triaxial_<pygeodesy.Triaxial>} from this tuple's semi-axes C{abc3ordered}.

246

247 @kwarg Triaxial_and_kwds: Optional C{B{Triaxial}=Triaxial} class and additional

248 C{Triaxial} keyword arguments.

249 '''

250 T, kwds = _xkwds_pop2(Triaxial_and_kwds, Triaxial=_MODS.triaxials.Triaxial)

251 return T(*self.abc3ordered, **_xkwds(kwds, name=self.name)) # 'NN'

252

253 def toTriaxial_(self, **Triaxial_and_kwds): # like .Ellipse.toTriaxial_

254 '''Return a L{Triaxial_<pygeodesy.Triaxial_>} from this tuple's semi-axes C{abc3}.

255

256 @kwarg Triaxial_and_kwds: Optional C{B{Triaxial}=Triaxial_} class and additional

257 C{Triaxial_} keyword arguments.

258 '''

259 T, kwds = _xkwds_pop2(Triaxial_and_kwds, Triaxial=_MODS.triaxials.Triaxial_)

260 return T(*self.abc3, **_xkwds(kwds, name=self.name)) # 'NN'

261

262

263class Forward4Tuple(_NamedTuple, _Convergence):

264 '''4-Tuple C{(easting, northing, gamma, scale)} in C{meter}, C{meter}, meridian

265 convergence C{gamma} at point in C{degrees} and the C{scale} of projection at

266 point C{scalar}.

267 '''

268 _Names_ = (_easting_, _northing_, _gamma_, _scale_)

269 _Units_ = ( Easting, Northing, Degrees, Scalar)

270

271

272class Intersection3Tuple(_NamedTuple): # .css.py, .lcc.py

273 '''3-Tuple C{(point, outside1, outside2)} of an intersection C{point} and C{outside1},

274 the position of the C{point}, C{-1} if before the start, C{+1} if after the end and

275 C{0} if on or between the start and end point of the first line.

276

277 Similarly, C{outside2} is C{-2}, C{+2} or C{0} to indicate the position of the

278 intersection C{point} on the second line or path.

279

280 If a path was specified with an initial bearing instead of an end point, C{outside1}

281 and/or C{outside2} will be C{0} if the intersection C{point} is on the start point

282 or C{+1} respectively C{+2} if the intersection C{point} is after the start point,

283 in the direction of the bearing.

284 '''

285 _Names_ = (_point_, _outside_ + _1_, _outside_ + _2_)

286 _Units_ = (_Pass, Int, Int)

287

288

289class LatLon2Tuple(_NamedTuple):

290 '''2-Tuple C{(lat, lon)} in C{degrees90} and C{degrees180}.

291 '''

292 _Names_ = (_lat_, _lon_)

293 _Units_ = ( Lat, Lon)

294

295 def to3Tuple(self, height, **name):

296 '''Extend this L{LatLon2Tuple} to a L{LatLon3Tuple}.

297

298 @arg height: The height to add (C{scalar}).

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

300 this name.

301

302 @return: A L{LatLon3Tuple}C{(lat, lon, height)}.

303

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

305 '''

306 return self._xtend(LatLon3Tuple, height, **name)

307

308 def to4Tuple(self, height, datum, **name):

309 '''Extend this L{LatLon2Tuple} to a L{LatLon4Tuple}.

310

311 @arg height: The height to add (C{scalar}).

312 @arg datum: The datum to add (C{Datum}).

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

314 this name.

315

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

317

318 @raise TypeError: If B{C{datum}} not a C{Datum}.

319

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

321 '''

322 return self.to3Tuple(height).to4Tuple(datum, **name)

323

324

325class LatLon3Tuple(_NamedTuple):

326 '''3-Tuple C{(lat, lon, height)} in C{degrees90}, C{degrees180}

327 and C{meter}, conventionally.

328 '''

329 _Names_ = (_lat_, _lon_, _height_)

330 _Units_ = ( Lat, Lon, Height)

331

332 def to4Tuple(self, datum, **name):

333 '''Extend this L{LatLon3Tuple} to a L{LatLon4Tuple}.

334

335 @arg datum: The datum to add (C{Datum}).

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

337 this name.

338

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

340

341 @raise TypeError: If B{C{datum}} not a C{Datum}.

342 '''

343 _xinstanceof(_MODS.datums.Datum, datum=datum)

344 return self._xtend(LatLon4Tuple, datum, **name)

345

346

347class LatLon4Tuple(LatLon3Tuple): # .cartesianBase, .css, .ecef, .lcc

348 '''4-Tuple C{(lat, lon, height, datum)} in C{degrees90},

349 C{degrees180}, C{meter} and L{Datum}.

350 '''

351 _Names_ = (_lat_, _lon_, _height_, _datum_)

352 _Units_ = ( Lat, Lon, Height, _Pass)

353

354

355def _LL4Tuple(lat, lon, height, datum, LatLon, LatLon_kwds, inst=None,

356 iteration=None, **name):

357 '''(INTERNAL) Return a L{LatLon4Tuple} or a B{C{LatLon}} instance.

358 '''

359 if LatLon is None: # ignore LatLon_kwds

360 r = LatLon4Tuple(lat, lon, height, datum, **name)

361 else:

362 kwds = {} if inst is None else _xkwds_not(None,

363# datum=_xattr(inst, datum=None),

364 epoch=_xattr(inst, epoch=None),

365 reframe=_xattr(inst, reframe=None)) # PYCHOK indent

366 kwds.update(datum=datum, height=height, **name)

367 if LatLon_kwds:

368 kwds.update(LatLon_kwds)

369 r = LatLon(lat, lon, **kwds)

370 if iteration is not None: # like .named._namedTuple.__new__

371 r._iteration = iteration

372 return r

373

374

375class LatLonDatum3Tuple(_NamedTuple): # .lcc.py, .osgr.py

376 '''3-Tuple C{(lat, lon, datum)} in C{degrees90}, C{degrees180}

377 and L{Datum}.

378 '''

379 _Names_ = (_lat_, _lon_, _datum_)

380 _Units_ = ( Lat, Lon, _Pass)

381

382

383class LatLonDatum5Tuple(LatLonDatum3Tuple, _Convergence): # .ups.py, .utm.py, .utmupsBase.py

384 '''5-Tuple C{(lat, lon, datum, gamma, scale)} in C{degrees90},

385 C{degrees180}, L{Datum}, C{degrees} and C{float}.

386 '''

387 _Names_ = LatLonDatum3Tuple._Names_ + (_gamma_, _scale_)

388 _Units_ = LatLonDatum3Tuple._Units_ + ( Degrees, Scalar)

389

390

391class LatLonPrec3Tuple(_NamedTuple): # .gars.py, .wgrs.py

392 '''3-Tuple C{(lat, lon, precision)} in C{degrees}, C{degrees}

393 and C{int}.

394 '''

395 _Names_ = (_lat_, _lon_, _precision_)

396 _Units_ = ( Lat, Lon, Precision_)

397

398 def to5Tuple(self, height, radius, **name):

399 '''Extend this L{LatLonPrec3Tuple} to a L{LatLonPrec5Tuple}.

400

401 @arg height: The height to add (C{float} or C{None}).

402 @arg radius: The radius to add (C{float} or C{None}).

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

404 this name.

405

406 @return: A L{LatLonPrec5Tuple}C{(lat, lon, precision,

407 height, radius)}.

408 '''

409 return self._xtend(LatLonPrec5Tuple, height, radius, **name)

410

411

412class LatLonPrec5Tuple(LatLonPrec3Tuple): # .wgrs.py

413 '''5-Tuple C{(lat, lon, precision, height, radius)} in C{degrees},

414 C{degrees}, C{int} and C{height} or C{radius} in C{meter} (or

415 C{None} if missing).

416 '''

417 _Names_ = LatLonPrec3Tuple._Names_ + (_height_, _radius_)

418 _Units_ = LatLonPrec3Tuple._Units_ + ( Height, Radius)

419

420

421class _NamedTupleTo(_NamedTuple): # in .testNamedTuples

422 '''(INTERNAL) Base for C{-.toDegrees}, C{-.toRadians}.

423 '''

424 def _Degrees3(self, *xs, **toDMS_kwds):

425 '''(INTERNAL) Convert C{xs} from C{Radians} to C{Degrees} or C{toDMS}.

426 '''

427 if toDMS_kwds:

428 toDMS_kwds = _xkwds(toDMS_kwds, ddd=1, pos=NN)

429 toDMS, s = _MODS.dms.toDMS, None

430 else:

431 toDMS, s = None, self

432 for x in xs:

433 if not isinstanceof(x, Degrees):

434 x, s = x.toDegrees(), None

435 yield toDMS(x, **toDMS_kwds) if toDMS else x

436 yield s

437

438 def _Radians3(self, *xs, **unused):

439 '''(INTERNAL) Convert C{xs} from C{Degrees} to C{Radians}.

440 '''

441 s = self

442 for x in xs:

443 if not isinstanceof(x, Radians):

444 x, s = x.toRadians(), None

445 yield x

446 yield s

447

448

449class NearestOn2Tuple(_NamedTuple): # .ellipsoidalBaseDI

450 '''2-Tuple C{(closest, fraction)} of the C{closest} point

451 on and C{fraction} along a line (segment) between two

452 points. The C{fraction} is C{0} if the closest point

453 is the first or C{1} the second of the two points.

454 Negative C{fraction}s indicate the closest point is

455 C{before} the first point. For C{fraction > 1.0}

456 the closest point is after the second point.

457 '''

458 _Names_ = (_closest_, _fraction_)

459 _Units_ = (_Pass, _Pass)

460

461

462class NearestOn3Tuple(_NamedTuple): # .points.py, .sphericalTrigonometry

463 '''3-Tuple C{(closest, distance, angle)} of the C{closest}

464 point on the polygon, either a C{LatLon} instance or a

465 L{LatLon3Tuple}C{(lat, lon, height)} and the C{distance}

466 and C{angle} to the C{closest} point are in C{meter}

467 respectively compass C{degrees360}.

468 '''

469 _Names_ = (_closest_, _distance_, _angle_)

470 _Units_ = (_Pass, Meter, Degrees)

471

472

473# NearestOn4Tuple DEPRECATED, see .deprecated.classes.NearestOn4Tuple

474

475

476class NearestOn5Tuple(_NamedTuple):

477 '''5-Tuple C{(lat, lon, distance, angle, height)} all in C{degrees},

478 except C{height}. The C{distance} is the L{pygeodesy.equirectangular}

479 distance between the closest and the reference B{C{point}} in C{degrees}.

480 The C{angle} from the reference B{C{point}} to the closest point is in

481 compass C{degrees360}, see function L{pygeodesy.compassAngle}. The

482 C{height} is the (interpolated) height at the closest point in C{meter}

483 or C{0}.

484 '''

485 _Names_ = (_lat_, _lon_, _distance_, _angle_, _height_)

486 _Units_ = ( Lat, Lon, Degrees, Degrees, Meter)

487

488

489class NearestOn6Tuple(_NamedTuple): # .latlonBase.py, .vector3d.py

490 '''6-Tuple C{(closest, distance, fi, j, start, end)} with the C{closest}

491 point, the C{distance} in C{meter}, conventionally and the C{start}

492 and C{end} point of the path or polygon edge. Fractional index C{fi}

493 (an L{FIx} instance) and index C{j} indicate the path or polygon edge

494 and the fraction along that edge with the C{closest} point. The

495 C{start} and C{end} points may differ from the given path or polygon

496 points at indices C{fi} respectively C{j}, when unrolled (C{wrap} is

497 C{True}). Also, the C{start} and/or C{end} point may be the same

498 instance as the C{closest} point, for example when the very first

499 path or polygon point is the nearest.

500 '''

501 _Names_ = (_closest_, _distance_, _fi_, _j_, _start_, _end_)

502 _Units_ = (_Pass, Meter, FIx, Number_, _Pass , _Pass)

503

504

505class NearestOn8Tuple(_NamedTuple): # .ellipsoidalBaseDI

506 '''8-Tuple C{(closest, distance, fi, j, start, end, initial, final)},

507 like L{NearestOn6Tuple} but extended with the C{initial} and the

508 C{final} bearing at the reference respectively the C{closest}

509 point, both in compass C{degrees}.

510 '''

511 _Names_ = NearestOn6Tuple._Names_ + Distance3Tuple._Names_[-2:]

512 _Units_ = NearestOn6Tuple._Units_ + Distance3Tuple._Units_[-2:]

513

514

515class PhiLam2Tuple(_NamedTuple): # .frechet, .hausdorff, .latlonBase, .points, .vector3d

516 '''2-Tuple C{(phi, lam)} with latitude C{phi} in C{radians[PI_2]}

517 and longitude C{lam} in C{radians[PI]}.

518

519 @note: Using C{phi/lambda} for lat-/longitude in C{radians}

520 follows Chris Veness' U{convention

521 <https://www.Movable-Type.co.UK/scripts/latlong.html>}.

522 '''

523 _Names_ = (_phi_, _lam_)

524 _Units_ = ( Phi, Lam)

525

526 def to3Tuple(self, height, **name):

527 '''Extend this L{PhiLam2Tuple} to a L{PhiLam3Tuple}.

528

529 @arg height: The height to add (C{scalar}).

530 @kwarg name: Optional C{B{name}=NN} (C{str}),

531 overriding this name.

532

533 @return: A L{PhiLam3Tuple}C{(phi, lam, height)}.

534

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

536 '''

537 return self._xtend(PhiLam3Tuple, height, **name)

538

539 def to4Tuple(self, height, datum):

540 '''Extend this L{PhiLam2Tuple} to a L{PhiLam4Tuple}.

541

542 @arg height: The height to add (C{scalar}).

543 @arg datum: The datum to add (C{Datum}).

544

545 @return: A L{PhiLam4Tuple}C{(phi, lam, height, datum)}.

546

547 @raise TypeError: If B{C{datum}} not a C{Datum}.

548

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

550 '''

551 return self.to3Tuple(height).to4Tuple(datum)

552

553

554class PhiLam3Tuple(_NamedTuple): # .nvector.py, extends -2Tuple

555 '''3-Tuple C{(phi, lam, height)} with latitude C{phi} in

556 C{radians[PI_2]}, longitude C{lam} in C{radians[PI]} and

557 C{height} in C{meter}.

558

559 @note: Using C{phi/lambda} for lat-/longitude in C{radians}

560 follows Chris Veness' U{convention

561 <https://www.Movable-Type.co.UK/scripts/latlong.html>}.

562 '''

563 _Names_ = (_phi_, _lam_, _height_)

564 _Units_ = ( Phi, Lam, Height)

565

566 def to4Tuple(self, datum, **name):

567 '''Extend this L{PhiLam3Tuple} to a L{PhiLam4Tuple}.

568

569 @arg datum: The datum to add (C{Datum}).

570 @kwarg name: Optional C{B{name}=NN} (C{str}),

571 overriding this name.

572

573 @return: A L{PhiLam4Tuple}C{(phi, lam, height, datum)}.

574

575 @raise TypeError: If B{C{datum}} not a C{Datum}.

576 '''

577 _xinstanceof(_MODS.datums.Datum, datum=datum)

578 return self._xtend(PhiLam4Tuple, datum, **name)

579

580

581class PhiLam4Tuple(_NamedTuple): # extends -3Tuple

582 '''4-Tuple C{(phi, lam, height, datum)} with latitude C{phi} in

583 C{radians[PI_2]}, longitude C{lam} in C{radians[PI]}, C{height}

584 in C{meter} and L{Datum}.

585

586 @note: Using C{phi/lambda} for lat-/longitude in C{radians}

587 follows Chris Veness' U{convention

588 <https://www.Movable-Type.co.UK/scripts/latlong.html>}.

589 '''

590 _Names_ = (_phi_, _lam_, _height_, _datum_)

591 _Units_ = ( Phi, Lam, Height, _Pass)

592

593

594class Point3Tuple(_NamedTuple):

595 '''3-Tuple C{(x, y, ll)} in C{meter}, C{meter} and C{LatLon}.

596 '''

597 _Names_ = (_x_, _y_, _elel_)

598 _Units_ = ( Meter, Meter, _Pass)

599

600

601class Points2Tuple(_NamedTuple): # .formy, .latlonBase

602 '''2-Tuple C{(number, points)} with the C{number} of points

603 and -possible reduced- C{list} or C{tuple} of C{points}.

604 '''

605 _Names_ = (_number_, _points_)

606 _Units_ = ( Number_, _Pass)

607

608

609class Reverse4Tuple(_NamedTuple, _Convergence):

610 '''4-Tuple C{(lat, lon, gamma, scale)} with C{lat}- and

611 C{lon}gitude in C{degrees}, meridian convergence C{gamma}

612 at point in C{degrees} and the C{scale} of projection at

613 point C{scalar}.

614 '''

615 _Names_ = (_lat_, _lon_, _gamma_, _scale_)

616 _Units_ = ( Lat, Lon, Degrees, Scalar)

617

618

619class Triangle7Tuple(_NamedTuple):

620 '''7-Tuple C{(A, a, B, b, C, c, area)} with interior angles C{A},

621 C{B} and C{C} in C{degrees}, spherical sides C{a}, C{b} and C{c}

622 in C{meter} conventionally and the C{area} of a (spherical)

623 triangle in I{square} C{meter} conventionally.

624 '''

625 _Names_ = (_A_, _a_, _B_, _b_, _C_, _c_, _area_)

626 _Units_ = ( Degrees, Meter, Degrees, Meter, Degrees, Meter, Meter2)

627

628

629class Triangle8Tuple(_NamedTuple):

630 '''8-Tuple C{(A, a, B, b, C, c, D, E)} with interior angles C{A},

631 C{B} and C{C}, spherical sides C{a}, C{b} and C{c}, the I{spherical

632 deficit} C{D} and the I{spherical excess} C{E} of a (spherical)

633 triangle, all in C{radians}.

634 '''

635 _Names_ = (_A_, _a_, _B_, _b_, _C_, _c_, _D_, _E_)

636 _Units_ = ( Radians, Radians, Radians, Radians, Radians, Radians, Radians, Radians)

637

638

639class Trilaterate5Tuple(_NamedTuple): # .latlonBase, .nvector

640 '''5-Tuple C{(min, minPoint, max, maxPoint, n)} with C{min} and C{max}

641 in C{meter}, the corresponding trilaterated C{minPoint} and C{maxPoint}

642 as C{LatLon} and the number C{n}. For area overlap, C{min} and C{max}

643 are the smallest respectively largest overlap found. For perimeter

644 intersection, C{min} and C{max} represent the closest respectively

645 farthest intersection margin. Count C{n} is the total number of

646 trilaterated overlaps or intersections found, C{0, 1, 2...6} with

647 C{0} meaning concentric.

648

649 @see: The C{ellipsoidalKarney-}, C{ellipsoidalVincenty-} and

650 C{sphericalTrigonometry.LatLon.trilaterate5} method for further

651 details on corner cases, like concentric or single trilaterated

652 results.

653 '''

654 _Names_ = (min.__name__, 'minPoint', max.__name__, 'maxPoint', _n_)

655 _Units_ = (Meter, _Pass, Meter, _Pass, Number_)

656

657

658class UtmUps2Tuple(_NamedTuple): # .epsg.py

659 '''2-Tuple C{(zone, hemipole)} as C{int} and C{str}, where

660 C{zone} is C{1..60} for UTM or C{0} for UPS and C{hemipole}

661 C{'N'|'S'} is the UTM hemisphere or the UPS pole.

662 '''

663 _Names_ = (_zone_, _hemipole_)

664 _Units_ = ( Number_, Str)

665

666

667class UtmUps5Tuple(_NamedTuple): # .mgrs.py, .ups.py, .utm.py, .utmups.py

668 '''5-Tuple C{(zone, hemipole, easting, northing, band)} as C{int},

669 C{str}, C{meter}, C{meter} and C{band} letter, where C{zone} is

670 C{1..60} for UTM or C{0} for UPS, C{hemipole} C{'N'|'S'} is the UTM

671 hemisphere or the UPS pole and C{band} is C{""} or the I{longitudinal}

672 UTM band C{'C'|'D'|..|'W'|'X'} or I{polar} UPS band C{'A'|'B'|'Y'|'Z'}.

673 '''

674 _Names_ = (_zone_, _hemipole_, _easting_, _northing_, _band_)

675 _Units_ = ( Number_, Str, Easting, Northing, Band)

676

677 def __new__(cls, z, h, e, n, B, Error=None, **name):

678 if Error is not None:

679 e = Easting( e, Error=Error)

680 n = Northing(n, Error=Error)

681 return _NamedTuple.__new__(cls, z, h, e, n, B, **name)

682

683

684class UtmUps8Tuple(_NamedTuple, _Convergence): # .ups, .utm, .utmups

685 '''8-Tuple C{(zone, hemipole, easting, northing, band, datum,

686 gamma, scale)} as C{int}, C{str}, C{meter}, C{meter}, C{band}

687 letter, C{Datum}, C{degrees} and C{scalar}, where C{zone} is

688 C{1..60} for UTM or C{0} for UPS, C{hemipole} C{'N'|'S'} is

689 the UTM hemisphere or the UPS pole and C{band} is C{""} or

690 the I{longitudinal} UTM band C{'C'|'D'|..|'W'|'X'} or

691 I{polar} UPS band C{'A'|'B'|'Y'|'Z'}.

692 '''

693 _Names_ = (_zone_, _hemipole_, _easting_, _northing_,

694 _band_, _datum_, _gamma_, _scale_)

695 _Units_ = ( Number_, Str, Easting, Northing,

696 Band, _Pass, Degrees, Scalar)

697

698 def __new__(cls, z, h, e, n, B, d, g, s, Error=None, **name): # PYCHOK 11 args

699 if Error is not None:

700 e = Easting( e, Error=Error)

701 n = Northing(n, Error=Error)

702 g = Degrees(gamma=g, Error=Error)

703 s = Scalar(scale=s, Error=Error)

704 return _NamedTuple.__new__(cls, z, h, e, n, B, d, g, s, **name)

705

706

707class UtmUpsLatLon5Tuple(_NamedTuple): # .ups.py, .utm.py, .utmups.py

708 '''5-Tuple C{(zone, band, hemipole, lat, lon)} as C{int},

709 C{str}, C{str}, C{degrees90} and C{degrees180}, where

710 C{zone} is C{1..60} for UTM or C{0} for UPS, C{band} is

711 C{""} or the I{longitudinal} UTM band C{'C'|'D'|..|'W'|'X'}

712 or I{polar} UPS band C{'A'|'B'|'Y'|'Z'} and C{hemipole}

713 C{'N'|'S'} is the UTM hemisphere or the UPS pole.

714 '''

715 _Names_ = (_zone_, _band_, _hemipole_, _lat_, _lon_)

716 _Units_ = ( Number_, Band, Str, Lat, Lon)

717

718 def __new__(cls, z, B, h, lat, lon, Error=None, **name):

719 if Error is not None:

720 lat = Lat(lat, Error=Error)

721 lon = Lon(lon, Error=Error)

722 return _NamedTuple.__new__(cls, z, B, h, lat, lon, **name)

723

724

725class Vector2Tuple(_NamedTuple):

726 '''2-Tuple C{(x, y)} of (geocentric) components, each in

727 C{meter} or the same C{units}.

728 '''

729 _Names_ = (_x_, _y_)

730 _Units_ = ( Scalar, Scalar)

731

732 def toCartesian(self, Cartesian, **Cartesian_kwds):

733 '''Return this C{Vector2Tuple} as a C{Cartesian}.

734

735 @arg Cartesian: The C{Cartesian} class to use.

736 @kwarg Cartesian_kwds: Optional, additional C{Cartesian}

737 keyword arguments.

738

739 @return: The C{B{Cartesian}} instance with C{z=0}.

740 '''

741 return _v2Cls(self.xyz, Cartesian, Cartesian_kwds)

742

743 def to3Tuple(self, z=INT0, **name):

744 '''Extend this L{Vector2Tuple} to a L{Vector3Tuple}.

745

746 @kwarg z: The Z component add (C{scalar}).

747 @kwarg name: Optional C{B{name}=NN} (C{str}),

748 overriding this name.

749

750 @return: A L{Vector3Tuple}C{(x, y, z)}.

751

752 @raise ValueError: Invalid B{C{z}}.

753 '''

754 return self._xtend(Vector3Tuple, z, **name)

755

756 @property_RO

757 def xyz(self):

758 '''Get X, Y and Z=0 components (C{Vector3Tuple}).

759 '''

760 return Vector3Tuple(*self.xyz3)

761

762 @property_RO

763 def xyz3(self):

764 '''Get X, Y and Z=0 components as C{3-tuple}.

765 '''

766 return self.x, self.y, INT0

767

768

769class Vector3Tuple(_NamedTuple):

770 '''3-Tuple C{(x, y, z)} of (geocentric) components, all in

771 C{meter} or the same C{units}.

772 '''

773 _Names_ = (_x_, _y_, _z_)

774 _Units_ = ( Scalar, Scalar, Scalar)

775

776 def toCartesian(self, Cartesian, **Cartesian_kwds):

777 '''Return this C{Vector3Tuple} as a C{Cartesian}.

778

779 @arg Cartesian: The C{Cartesian} class to use.

780 @kwarg Cartesian_kwds: Optional, additional C{Cartesian}

781 keyword arguments.

782

783 @return: The C{B{Cartesian}} instance.

784 '''

785 return _v2Cls(self, Cartesian, Cartesian_kwds)

786

787 def to4Tuple(self, h=INT0, **name):

788 '''Extend this L{Vector3Tuple} to a L{Vector4Tuple}.

789

790 @arg h: The height to add (C{scalar}).

791 @kwarg name: Optional C{B{name}=NN} (C{str}),

792 overriding this name.

793

794 @return: A L{Vector4Tuple}C{(x, y, z, h)}.

795

796 @raise ValueError: Invalid B{C{h}}.

797 '''

798 return self._xtend(Vector4Tuple, h, **name)

799

800 @property_RO

801 def xyz(self):

802 '''Get X, Y and Z components (C{Vector3Tuple}).

803 '''

804 return self

805

806 @property_RO

807 def xyz3(self):

808 '''Get X, Y and Z components as C{3-tuple}.

809 '''

810 return tuple(self)

811

812

813class Vector4Tuple(_NamedTuple): # .nvector.py

814 '''4-Tuple C{(x, y, z, h)} of (geocentric) components, all

815 in C{meter} or the same C{units}.

816 '''

817 _Names_ = (_x_, _y_, _z_, _h_)

818 _Units_ = ( Scalar, Scalar, Scalar, Height)

819

820 def toCartesian(self, Cartesian, **Cartesian_kwds):

821 '''Return this C{Vector4Tuple} as a C{Cartesian}.

822

823 @arg Cartesian: The C{Cartesian} class to use.

824 @kwarg Cartesian_kwds: Optional, additional C{Cartesian}

825 keyword arguments.

826

827 @return: The C{B{Cartesian}} instance.

828 '''

829 return _v2Cls(self, Cartesian, Cartesian_kwds)

830

831 def to3Tuple(self):

832 '''Reduce this L{Vector4Tuple} to a L{Vector3Tuple}.

833

834 @return: A L{Vector3Tuple}C{(x, y, z)}.

835 '''

836 return self.xyz

837

838 @property_RO

839 def xyz(self):

840 '''Get X, Y and Z components (L{Vector3Tuple}).

841 '''

842 return Vector3Tuple(*self.xyz)

843

844 @property_RO

845 def xyz3(self):

846 '''Get X, Y and Z components as C{3-tuple}.

847 '''

848 return tuple(self[:3])

849

850

851def _v2Cls(v, Cls, Cartesian_kwds): # in .vector3d

852 if issubclassof(Cls, _MODS.cartesianBase.CartesianBase): # _MODS.vector3d.Vector3d)

853 return Cls(v, **Cartesian_kwds)

854 raise _TypeError(Cartesian=Cls, **Cartesian_kwds)

855

856# **) MIT License

857#

859#

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

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

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

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

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

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

866#

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

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

869#

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

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

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

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

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

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

876# OTHER DEALINGS IN THE SOFTWARE.

Coverage for pygeodesy / namedTuples.py: 95%

271 statements