1

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

3

4 u'''Named tuples.

5

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

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

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

9'''

10

11 from pygeodesy.basics import map1, _xinstanceof

12# from pygeodesy.constants import INT0 # from .units

13 from pygeodesy.errors import _ALL_LAZY, _MODS, _xattr, _xkwds_not # _xkwds

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

15 _B_, _band_, _c_, _C_, _datum_, _D_, _distance_, \

16 _E_, _easting_, _end_, _fi_, _gamma_, _height_, \

17 _h_, _j_, _hemipole_, _initial_, _lam_, _lat_, \

18 _lon_, _n_, _northing_, _number_, _outside_, \

19 _phi_, _point_, _precision_, _points_, _radius_, \

20 _scale_, _start_, _x_, _y_, _z_, _zone_

21# from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS # from .errors

22 from pygeodesy.named import _NamedTuple, _Pass

23 from pygeodesy.props import deprecated_property_RO, property_RO

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

25 FIx, Height, Int, INT0, Lam, Lat, Lon, Meter, \

26 Meter2, Northing, Number_, Phi, Precision_, \

27 Radians, Radius, Scalar, Str

28

29__all__ = _ALL_LAZY.namedTuples

30__version__ = '23.11.20'

31

32# __DUNDER gets mangled in class

33_closest_ = 'closest'

34_destination_ = 'destination'

35_elel_ = 'll'

36_final_ = 'final'

37_fraction_ = 'fraction'

38

39

40 class Bearing2Tuple(_NamedTuple):

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

42 '''

43 _Names_ = (_initial_, _final_)

44 _Units_ = ( Bearing, Bearing)

45

46

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

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

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

50 '''

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

52 _Units_ = (_Pass, _Pass)

53

54

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

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

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

58 longitudes.

59 '''

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

61 _Units_ = ( Lat, Lon, Lat, Lon)

62

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

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

65

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

67 L{Bounds4Tuple} instance.

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

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

70

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

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

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

74 if not or zero if abutting.

75 '''

76 s, w, n, e = self

77 S, W, N, E = map1(float, S_other, *W_N_E) if W_N_E else S_other

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

79

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

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

82

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

84 L{Bounds4Tuple} instance.

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

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

87

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

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

90 '''

91 s, w, n, e = self

92 S, W, N, E = map1(float, S_other, *W_N_E) if W_N_E else S_other

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

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

95

96

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

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

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

100 '''

101 _Names_ = (_destination_, _final_)

102 _Units_ = (_Pass, Bearing)

103

104

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

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

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

108 in compass C{degrees360}.

109 '''

110 _Names_ = (_lat_, _lon_, _final_)

111 _Units_ = ( Lat, Lon, Bearing)

112

113

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

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

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

117 '''

118 _Names_ = (_distance_, _initial_)

119 _Units_ = ( Meter, Bearing)

120

121

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

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

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

125 '''

126 _Names_ = (_distance_, _initial_, _final_)

127 _Units_ = ( Meter, Bearing, Bearing)

128

129

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

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

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

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

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

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

136

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

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

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

140 '''

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

142 _Units_ = ( Degrees2, Degrees, Degrees, Degrees)

143

144

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

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

147 '''

148 _Names_ = (_easting_, _northing_)

149 _Units_ = ( Easting, Northing)

150

151

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

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

154 '''

155 _Names_ = (_easting_, _northing_, _height_)

156 _Units_ = ( Easting, Northing, Height)

157

158

159 class _Convergence(object):

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

161 @deprecated_property_RO

162 def convergence(self):

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

164 '''

165 return self.gamma # PYCHOK self[.]

166

167

168 class Forward4Tuple(_NamedTuple, _Convergence):

169 '''4-Tuple C{(easting, northing, gamma, scale)} in

170 C{meter}, C{meter}, meridian convergence C{gamma} at

171 point in C{degrees} and the C{scale} of projection

172 at point C{scalar}.

173 '''

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

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

176

177

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

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

180 C{point} and C{outside1}, the position of the C{point},

181 C{-1} if before the start, C{+1} if after the end and C{0}

182 if on or between the start and end point of the first line.

183 Similarly, C{outside2} is C{-2}, C{+2} or C{0} to indicate

184 the position of C{point} on the second line or path. If a

185 path was specified with an initial bearing instead of an

186 end point, C{outside1} and/or C{outside2} will be C{0} if

187 the intersection C{point} is on the start point or C{+1}

188 respectively C{+2} if the intersection C{point} is after

189 the start point, in the direction of the bearing.

190 '''

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

192 _Units_ = (_Pass, Int, Int)

193

194

195 class LatLon2Tuple(_NamedTuple):

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

197 '''

198 _Names_ = (_lat_, _lon_)

199 _Units_ = ( Lat, Lon)

200

201 def to3Tuple(self, height):

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

203

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

205

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

207

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

209 '''

210 return self._xtend(LatLon3Tuple, height)

211

212 def to4Tuple(self, height, datum):

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

214

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

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

217

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

219

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

221

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

223 '''

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

225

226

227 class LatLon3Tuple(_NamedTuple):

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

229 and C{meter}, conventionally.

230 '''

231 _Names_ = (_lat_, _lon_, _height_)

232 _Units_ = ( Lat, Lon, Height)

233

234 def to4Tuple(self, datum):

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

236

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

238

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

240

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

242 '''

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

244 return self._xtend(LatLon4Tuple, datum)

245

246

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

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

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

250 '''

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

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

253

254

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

256 iteration=None, name=NN):

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

258 '''

259 if LatLon is None: # ignore LatLon_kwds

260 r = LatLon4Tuple(lat, lon, height, datum, name=name)

261 else:

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

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

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

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

266 kwds.update(datum=datum, height=height, name=name)

267 if LatLon_kwds:

268 kwds.update(LatLon_kwds)

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

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

271 r._iteration = iteration

272 return r

273

274

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

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

277 and L{Datum}.

278 '''

279 _Names_ = (_lat_, _lon_, _datum_)

280 _Units_ = ( Lat, Lon, _Pass)

281

282

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

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

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

286 '''

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

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

289

290

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

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

293 and C{int}.

294 '''

295 _Names_ = (_lat_, _lon_, _precision_)

296 _Units_ = ( Lat, Lon, Precision_)

297

298 def to5Tuple(self, height, radius):

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

300

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

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

303

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

305 height, radius)}.

306 '''

307 return self._xtend(LatLonPrec5Tuple, height, radius)

308

309

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

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

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

313 C{None} if missing).

314 '''

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

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

317

318

319 class NearestOn2Tuple(_NamedTuple): # .ellipsoidalBaseDI.py

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

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

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

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

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

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

326 the closest point is after the second point.

327 '''

328 _Names_ = (_closest_, _fraction_)

329 _Units_ = (_Pass, _Pass)

330

331

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

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

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

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

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

337 respectively compass C{degrees360}.

338 '''

339 _Names_ = (_closest_, _distance_, _angle_)

340 _Units_ = (_Pass, Meter, Degrees)

341

342

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

344

345

346 class NearestOn5Tuple(_NamedTuple):

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

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

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

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

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

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

353 or C{0}.

354 '''

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

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

357

358

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

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

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

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

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

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

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

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

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

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

369 path or polygon point is the nearest.

370 '''

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

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

373

374

375 class NearestOn8Tuple(_NamedTuple): # .ellipsoidalBaseDI.py

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

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

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

379 point, both in compass C{degrees}.

380 '''

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

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

383

384

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

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

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

388

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

390 follows Chris Veness' U{convention

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

392 '''

393 _Names_ = (_phi_, _lam_)

394 _Units_ = ( Phi, Lam)

395

396 def to3Tuple(self, height):

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

398

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

400

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

402

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

404 '''

405 return self._xtend(PhiLam3Tuple, height)

406

407 def to4Tuple(self, height, datum):

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

409

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

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

412

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

414

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

416

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

418 '''

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

420

421

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

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

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

425 C{height} in C{meter}.

426

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

428 follows Chris Veness' U{convention

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

430 '''

431 _Names_ = (_phi_, _lam_, _height_)

432 _Units_ = ( Phi, Lam, Height)

433

434 def to4Tuple(self, datum):

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

436

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

438

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

440

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

442 '''

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

444 return self._xtend(PhiLam4Tuple, datum)

445

446

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

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

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

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

451

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

453 follows Chris Veness' U{convention

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

455 '''

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

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

458

459

460 class Point3Tuple(_NamedTuple):

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

462 '''

463 _Names_ = (_x_, _y_, _elel_)

464 _Units_ = ( Meter, Meter, _Pass)

465

466

467 class Points2Tuple(_NamedTuple): # .formy.py, .latlonBase.py

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

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

470 '''

471 _Names_ = (_number_, _points_)

472 _Units_ = ( Number_, _Pass)

473

474

475 class Reverse4Tuple(_NamedTuple, _Convergence):

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

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

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

479 point C{scalar}.

480 '''

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

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

483

484

485 class Triangle7Tuple(_NamedTuple):

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

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

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

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

490 '''

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

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

493

494

495 class Triangle8Tuple(_NamedTuple):

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

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

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

499 triangle, all in C{radians}.

500 '''

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

502 _Units_ = ( Radians, Radians, Radians, Radians, Radians, Radians, Radians, Radians)

503

504

505 class Trilaterate5Tuple(_NamedTuple): # .latlonBase.py, .nvector.py

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

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

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

509 are the smallest respectively largest overlap found. For perimeter

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

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

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

513 C{0} meaning concentric.

514

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

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

517 details on corner cases, like concentric or single trilaterated

518 results.

519 '''

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

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

522

523

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

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

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

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

528 '''

529 _Names_ = (_zone_, _hemipole_)

530 _Units_ = ( Number_, Str)

531

532

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

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

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

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

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

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

539 '''

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

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

542

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

544 if Error is not None:

545 e = Easting( e, Error=Error)

546 n = Northing(n, Error=Error)

547 return _NamedTuple.__new__(cls, z, h, e, n, B, name=name)

548

549

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

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

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

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

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

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

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

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

558 '''

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

560 _band_, _datum_, _gamma_, _scale_)

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

562 Band, _Pass, Degrees, Scalar)

563

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

565 if Error is not None:

566 e = Easting( e, Error=Error)

567 n = Northing(n, Error=Error)

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

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

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

571

572

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

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

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

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

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

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

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

580 '''

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

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

583

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

585 if Error is not None:

586 lat = Lat(lat, Error=Error)

587 lon = Lon(lon, Error=Error)

588 return _NamedTuple.__new__(cls, z, B, h, lat, lon, name=name)

589

590

591 class Vector2Tuple(_NamedTuple):

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

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

594 '''

595 _Names_ = (_x_, _y_)

596 _Units_ = ( Scalar, Scalar)

597

598 def to3Tuple(self, z=INT0):

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

600

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

602

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

604

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

606 '''

607 return self._xtend(Vector3Tuple, z)

608

609

610 class Vector3Tuple(_NamedTuple):

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

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

613 '''

614 _Names_ = (_x_, _y_, _z_)

615 _Units_ = ( Scalar, Scalar, Scalar)

616

617 def to4Tuple(self, h):

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

619

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

621

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

623

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

625 '''

626 return self._xtend(Vector4Tuple, h)

627

628 @property_RO

629 def xyz(self):

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

631 '''

632 return self

633

634

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

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

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

638 '''

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

640 _Units_ = ( Scalar, Scalar, Scalar, Height)

641

642 def to3Tuple(self):

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

644

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

646 '''

647 return self.xyz

648

649 @property_RO

650 def xyz(self):

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

652 '''

653 return Vector3Tuple(*self[:3])

654

655# **) MIT License

656#

657# Copyright (C) 2016-2023 -- mrJean1 at Gmail -- All Rights Reserved.

658#

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

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

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

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

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

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

665#

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

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

668#

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

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

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

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

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

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

675# OTHER DEALINGS IN THE SOFTWARE.

676

677# % env PYGEODESY_FOR_DOCS=1 python -m pygeodesy.named

678# all 71 locals OK