pygeodesy 24.10.24__py2.py3-none-any.whl → 24.12.12__py2.py3-none-any.whl

pygeodesy/mgrs.py

@@ -55,7 +55,7 @@ from pygeodesy.utm import toUtm8, _to3zBlat, Utm, _UTM_ZONE_MAX, _UTM_ZONE_MIN
 # from pygeodesy.utmupsBase import _UTM_ZONE_MAX, _UTM_ZONE_MIN  # from .utm
 
 __all__ = _ALL_LAZY.mgrs
-__version__ = '24.10.13'
+__version__ = '24.11.06'
 
 _AN_    = 'AN'  # default south pole grid tile and band B
 _AtoPx_ = _AtoZnoIO_.tillP
@@ -594,15 +594,14 @@ def toMgrs(utmups, Mgrs=Mgrs, **name_Mgrs_kwds):
     '''Convert a UTM or UPS coordinate to an MGRS grid reference.
 
        @arg utmups: A UTM or UPS coordinate (L{Utm}, L{Etm} or L{Ups}).
-       @kwarg Mgrs: Optional class to return the MGRS grid reference
-                    (L{Mgrs}) or C{None}.
-       @kwarg name_Mgrs_kwds: Optional C{B{name}=NN} (C{str}) and optional,
-                   additional B{C{Mgrs}} keyword arguments, ignored if
-                   C{B{Mgrs} is None}.
+       @kwarg Mgrs: Optional class to return the MGRS grid reference (L{Mgrs})
+                    or C{None}.
+       @kwarg name_Mgrs_kwds: Optional C{B{name}=NN} (C{str}) and optionally,
+                   additional B{C{Mgrs}} keyword arguments, ignored if C{B{Mgrs}
+                   is None}.
 
-       @return: The MGRS grid reference as B{C{Mgrs}} or if C{B{Mgrs} is
-                None} as an L{Mgrs6Tuple}C{(zone, EN, easting, northing,
-                band, datum)}.
+       @return: The MGRS grid reference as B{C{Mgrs}} or if C{B{Mgrs} is None} as
+                an L{Mgrs6Tuple}C{(zone, EN, easting, northing, band, datum)}.
 
        @raise MGRSError: Invalid B{C{utmups}}.
 
@@ -732,7 +731,7 @@ if __name__ == '__main__':
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/named.py

@@ -15,6 +15,7 @@ standard Python C{namedtuple}s.
 
 from pygeodesy.basics import isidentifier, iskeyword, isstr, itemsorted, len2, \
                             _xcopy, _xdup, _xinstanceof, _xsubclassof, _zip
+# from pygeodesy.ecef import EcefKarney  # _MODS
 from pygeodesy.errors import _AssertionError, _AttributeError, _incompatible, \
                              _IndexError, _KeyError, LenError, _NameError, \
                              _NotImplementedError, _TypeError, _TypesError, \
@@ -28,14 +29,16 @@ from pygeodesy.interns import MISSING, NN, _AT_, _COLON_, _COLONSPACE_, _COMMA_,
                              _NL_, _NN_, _no_, _other_, _s_, _SPACE_, _std_, \
                              _UNDER_, _vs_
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS
+# from pygeodesy.ltp import Ltp, _toLocal, _toLtp  # _MODS
+# from pygeodesy.ltpTuples import Aer, Enu, Ned  # _MODS
 from pygeodesy.props import _allPropertiesOf_n, deprecated_method, _hasProperty, \
                             _update_all, property_doc_, Property_RO, property_RO, \
-                            _update_attrs
+                            _update_attrs, property_ROver
 from pygeodesy.streprs import attrs, Fmt, lrstrip, pairs, reprs, unstr
 # from pygeodesy.units import _toUnit  # _MODS
 
 __all__ = _ALL_LAZY.named
-__version__ = '24.10.14'
+__version__ = '24.12.05'
 
 _COMMANL_           = _COMMA_ + _NL_
 _COMMASPACEDOT_     = _COMMASPACE_ + _DOT_
@@ -141,6 +144,10 @@ class _Named(object):
     _classnaming = False  # prefixed (C{bool})
 #   _updates     = 0      # OBSOLETE Property/property updates
 
+    def __format__(self, fmt):  # PYCHOK no cover
+        '''Not implemented.'''
+        return _NotImplemented(self, fmt)
+
     def __imatmul__(self, other):  # PYCHOK no cover
         '''Not implemented.'''
         return _NotImplemented(self, other)  # PYCHOK Python 3.5+
@@ -892,6 +899,148 @@ class _NamedEnumItem(_NamedBase):
                 raise _AssertionError(t)
 
 
+class _NamedLocal(object):
+    '''(INTERNAL) Base class for C{CartesianBase}, C{Ecef9Tuple} and C{LatLonBase}.
+     '''
+
+    @property_ROver
+    def Ecef(self):
+        '''Get the ECEF I{class} (L{EcefKarney}), I{once}.
+        '''
+        return _MODS.ecef.EcefKarney
+
+    @property_RO
+    def _ecef9(self):
+        '''I{Must be overloaded}.'''
+        notOverloaded(self)
+
+    @Property_RO
+    def _Ltp(self):
+        '''(INTERNAL) Cache this instance' LTP (L{Ltp}).
+        '''
+        return self._ltp.Ltp(self._ecef9, ecef=self.Ecef(self.datum), name=self.name)
+
+    @property_ROver
+    def _ltp(self):
+        '''(INTERNAL) Get module L{pygeodesy.ltp}, I{once}.
+        '''
+        return _MODS.ltp
+
+    def _ltp_toLocal(self, ltp, Cls_and_kwds, **nam_Cls):  # overloaded in C{Ecef9Tuple}
+        '''(INTERNAL) Invoke C{ltp._toLocal}.
+        '''
+        Cls, kwds = self._ltp_toLocal2(Cls_and_kwds, **nam_Cls)
+        return self._ltp._toLocal(self, ltp, Cls, kwds)  # self._ecef9
+
+    def _ltp_toLocal2(self, Cls_and_kwds, _None=None, **nam_Cls):
+        '''(INTERNAL) Return 2-tuple C{(Cls, kwds)}.
+        '''
+        Cls, kwds = _xkwds_pop2(Cls_and_kwds, **nam_Cls)
+        if Cls is not _None:  # validate Cls
+            n, LoC = _xkwds_item2(nam_Cls)
+            if LoC is not Cls:
+                _xsubclassof(LoC, **{n: Cls})
+        return Cls, kwds
+
+    @property_ROver
+    def _ltpTuples(self):
+        '''(INTERNAL) Get module L{pygeodesy.ltpTuples}, I{once}.
+        '''
+        return _MODS.ltpTuples
+
+    def toAer(self, ltp=None, **Aer_and_kwds):
+        '''Convert this instance to I{local} I{Azimuth, Elevation, slant Range} (AER) components.
+
+           @kwarg ltp: The I{local tangent plane} (LTP) to use (L{Ltp}), overriding this
+                       instance' L{LTP<pygeodesy.named._NamedLocal.toLtp>}.
+           @kwarg Aer_and_kwds: Optional AER class C{B{Aer}=}L{Aer<pygeodesy.ltpTuples.Aer>}
+                      to use and optionally, additional B{C{Aer}} keyword arguments.
+
+           @return: An B{C{Aer}} instance.
+
+           @raise TypeError: Invalid B{C{ltp}}.
+
+           @see: Method L{toLocal<pygeodesy.named._NamedLocal.toLocal>}.
+        '''
+        return self._ltp_toLocal(ltp, Aer_and_kwds, Aer=self._ltpTuples.Aer)
+
+    def toEnu(self, ltp=None, **Enu_and_kwds):
+        '''Convert this instance to I{local} I{East, North, Up} (ENU) components.
+
+           @kwarg ltp: The I{local tangent plane} (LTP) to use (L{Ltp}), overriding this
+                       instance' L{LTP<pygeodesy.named._NamedLocal.toLtp>}.
+           @kwarg Enu_and_kwds: Optional ENU class C{B{Enu}=}L{Enu<pygeodesy.ltpTuples.Enu>}
+                      to use and optionally, additional B{C{Enu}} keyword arguments.
+
+           @return: An B{C{Enu}} instance.
+
+           @raise TypeError: Invalid B{C{ltp}}.
+
+           @see: Method L{toLocal<pygeodesy.named._NamedLocal.toLocal>}.
+        '''
+        return self._ltp_toLocal(ltp, Enu_and_kwds, Enu=self._ltpTuples.Enu)
+
+    def toLocal(self, Xyz=None, ltp=None, **Xyz_kwds):
+        '''Convert this instance to I{local} components in a I{local tangent plane} (LTP)
+
+           @kwarg Xyz: Optional I{local} components class (L{XyzLocal}, L{Aer},
+                       L{Enu}, L{Ned}) or C{None}.
+           @kwarg ltp: The I{local tangent plane} (LTP) to use (L{Ltp}), overriding this
+                       cartesian's L{LTP<pygeodesy.named._NamedLocal.toLtp>}.
+           @kwarg Xyz_kwds: Optionally, additional B{C{Xyz}} keyword arguments, ignored
+                            if C{B{Xyz} is None}.
+
+           @return: An B{C{Xyz}} instance or a L{Local9Tuple}C{(x, y, z, lat, lon,
+                    height, ltp, ecef, M)} if C{B{Xyz} is None} (with C{M=None}).
+
+           @raise TypeError: Invalid B{C{ltp}}.
+        '''
+        return self._ltp_toLocal(ltp, Xyz_kwds, Xyz=Xyz, _None=Xyz)
+
+    def toLtp(self, Ecef=None, **name):
+        '''Return the I{local tangent plane} (LTP) for this instance.
+
+           @kwarg Ecef: Optional ECEF I{class} (L{EcefKarney}, ... L{EcefYou}), overriding
+                        this instance' L{Ecef<pygeodesy.named._NamedLocal.Ecef>}.
+           @kwarg name: Optional C{B{name}=NN} (C{str}).
+
+           @return: An B{C{Ltp}} instance.
+        '''
+        return self._ltp._toLtp(self, Ecef, self._ecef9, name)  # needs self.Ecef and self._Ltp
+
+    def toNed(self, ltp=None, **Ned_and_kwds):
+        '''Convert this instance to I{local} I{North, East, Down} (NED) components.
+
+           @kwarg ltp: The I{local tangent plane} (LTP) to use (L{Ltp}), overriding this
+                       instance' L{LTP<pygeodesy.named._NamedLocal.toLtp>}.
+           @kwarg Ned_and_kwds: Optional NED class C{B{Ned}=}L{Ned<pygeodesy.ltpTuples.Ned>}
+                      to use and optionally, additional B{C{Ned}} keyword arguments.
+
+           @return: An B{C{Ned}} instance.
+
+           @raise TypeError: Invalid B{C{ltp}}.
+
+           @see: Method L{toLocal<pygeodesy.named._NamedLocal.toLocal>}.
+        '''
+        return self._ltp_toLocal(ltp, Ned_and_kwds, Ned=self._ltpTuples.Ned)
+
+    def toXyz(self, ltp=None, **Xyz_and_kwds):
+        '''Convert this instance to I{local} I{X, Y, Z} (XYZ) components.
+
+           @kwarg ltp: The I{local tangent plane} (LTP) to use (L{Ltp}), overriding this
+                       instance' L{LTP<pygeodesy.named._NamedLocal.toLtp>}.
+           @kwarg Xyz_and_kwds: Optional XYZ class C{B{Xyz}=}L{Xyz<pygeodesy.ltpTuples.XyzLocal>}
+                      to use and optionally, additional B{C{Xyz}} keyword arguments.
+
+           @return: An B{C{Xyz}} instance.
+
+           @raise TypeError: Invalid B{C{ltp}}.
+
+           @see: Method L{toLocal<pygeodesy.named._NamedLocal.toLocal>}.
+        '''
+        return self._ltp_toLocal(ltp, Xyz_and_kwds, Xyz=self._ltpTuples.XyzLocal)
+
+
 # from pygeodesy.props import _NamedProperty
 
 
@@ -1446,11 +1595,12 @@ def _xvalid(name, underOK=False):
 __all__ += _ALL_DOCS(_Named,
                      _NamedBase,  # _NamedDict,
                      _NamedEnum, _NamedEnumItem,
+                     _NamedLocal,
                      _NamedTuple)
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/namedTuples.py

@@ -8,10 +8,11 @@ are all instances of some C{Named...Tuple} class, all sub-classes
 of C{_NamedTuple} defined in C{pygeodesy.named}.
 '''
 
-from pygeodesy.basics import isinstanceof, map1, _xinstanceof
+from pygeodesy.basics import isinstanceof, issubclassof, map1, _xinstanceof
+# from pygeodesy.cartesianBase import CartesianBase  # _MODS
 # from pygeodesy.constants import INT0  # from .units
 # from pygeodesy.dms import toDMS  # _MODS
-from pygeodesy.errors import _xattr, _xkwds, _xkwds_not,  _ALL_LAZY, _MODS
+from pygeodesy.errors import _TypeError, _xattr, _xkwds, _xkwds_not
 from pygeodesy.interns import NN, _1_, _2_, _a_, _A_, _area_, _angle_, _b_, _B_, \
                              _band_, _c_, _C_, _D_, _datum_, _distance_, _E_, \
                              _easting_, _end_, _fi_, _gamma_, _h_, _height_, \
@@ -19,8 +20,8 @@ from pygeodesy.interns import NN, _1_, _2_, _a_, _A_, _area_, _angle_, _b_, _B_,
                              _n_, _northing_, _number_, _outside_, _phi_, \
                              _point_, _precision_, _points_, _radius_, _scale_, \
                              _start_, _x_, _y_, _z_, _zone_
-# from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS  # from .errors
-from pygeodesy.named import _NamedTuple, _Pass
+# from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS  # from .named
+from pygeodesy.named import _NamedTuple, _Pass,  _ALL_LAZY, _MODS
 from pygeodesy.props import deprecated_property_RO, property_RO
 from pygeodesy.units import Band, Bearing, Degrees, Degrees2, Easting, FIx, \
                             Height, Int, Lam, Lat, Lon, Meter, Meter2, \
@@ -28,7 +29,7 @@ from pygeodesy.units import Band, Bearing, Degrees, Degrees2, Easting, FIx, \
                             Radius, Scalar, Str,  INT0
 
 __all__ = _ALL_LAZY.namedTuples
-__version__ = '24.08.18'
+__version__ = '24.11.22'
 
 # __DUNDER gets mangled in class
 _closest_     = 'closest'
@@ -636,6 +637,17 @@ class Vector2Tuple(_NamedTuple):
     _Names_ = (_x_,    _y_)
     _Units_ = ( Scalar, Scalar)
 
+    def toCartesian(self, Cartesian, **Cartesian_kwds):
+        '''Return this C{Vector2Tuple} as a C{Cartesian}.
+
+           @arg Cartesian: The C{Cartesian} class to use.
+           @kwarg Cartesian_kwds: Optional, additional C{Cartesian}
+                                  keyword arguments.
+
+           @return: The C{B{Cartesian}} instance with C{z=0}.
+        '''
+        return _v2Cls(self.xyz, Cartesian, Cartesian_kwds)
+
     def to3Tuple(self, z=INT0, **name):
         '''Extend this L{Vector2Tuple} to a L{Vector3Tuple}.
 
@@ -649,6 +661,18 @@ class Vector2Tuple(_NamedTuple):
         '''
         return self._xtend(Vector3Tuple, z, **name)
 
+    @property_RO
+    def xyz(self):
+        '''Get X, Y and Z=0 components (C{Vector3Tuple}).
+        '''
+        return Vector3Tuple(*self.xyz3)
+
+    @property_RO
+    def xyz3(self):
+        '''Get X, Y and Z=0 components as C{3-tuple}.
+        '''
+        return self.x, self.y, INT0
+
 
 class Vector3Tuple(_NamedTuple):
     '''3-Tuple C{(x, y, z)} of (geocentric) components, all in
@@ -657,6 +681,17 @@ class Vector3Tuple(_NamedTuple):
     _Names_ = (_x_,    _y_,    _z_)
     _Units_ = ( Scalar, Scalar, Scalar)
 
+    def toCartesian(self, Cartesian, **Cartesian_kwds):
+        '''Return this C{Vector3Tuple} as a C{Cartesian}.
+
+           @arg Cartesian: The C{Cartesian} class to use.
+           @kwarg Cartesian_kwds: Optional, additional C{Cartesian}
+                                  keyword arguments.
+
+           @return: The C{B{Cartesian}} instance.
+        '''
+        return _v2Cls(self, Cartesian, Cartesian_kwds)
+
     def to4Tuple(self, h=INT0, **name):
         '''Extend this L{Vector3Tuple} to a L{Vector4Tuple}.
 
@@ -690,6 +725,17 @@ class Vector4Tuple(_NamedTuple):  # .nvector.py
     _Names_ = (_x_,    _y_,    _z_,    _h_)
     _Units_ = ( Scalar, Scalar, Scalar, Height)
 
+    def toCartesian(self, Cartesian, **Cartesian_kwds):
+        '''Return this C{Vector4Tuple} as a C{Cartesian}.
+
+           @arg Cartesian: The C{Cartesian} class to use.
+           @kwarg Cartesian_kwds: Optional, additional C{Cartesian}
+                                  keyword arguments.
+
+           @return: The C{B{Cartesian}} instance.
+        '''
+        return _v2Cls(self, Cartesian, Cartesian_kwds)
+
     def to3Tuple(self):
         '''Reduce this L{Vector4Tuple} to a L{Vector3Tuple}.
 
@@ -701,7 +747,7 @@ class Vector4Tuple(_NamedTuple):  # .nvector.py
     def xyz(self):
         '''Get X, Y and Z components (L{Vector3Tuple}).
         '''
-        return Vector3Tuple(*self[:3])
+        return Vector3Tuple(*self.xyz)
 
     @property_RO
     def xyz3(self):
@@ -710,9 +756,14 @@ class Vector4Tuple(_NamedTuple):  # .nvector.py
         return tuple(self[:3])
 
 
+def _v2Cls(v, Cls, Cartesian_kwds):  # in .vector3d
+    if issubclassof(Cls, _MODS.cartesianBase.CartesianBase):  # _MODS.vector3d.Vector3d)
+        return Cls(v, **Cartesian_kwds)
+    raise _TypeError(Cartesian=Cls, **Cartesian_kwds)
+
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),