Coverage for pygeodesy/nvectorBase.py : 98%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# -*- coding: utf-8 -*-
and function L{sumOf} for C{N-vectorial} ellipsoidal and spherical C{Cartesian}s and C{LatLon}s.
Pure Python implementation of C{n-vector}-based geodesy tools for ellipsoidal earth models, transcribed from JavaScript originals by I{(C) Chris Veness 2005-2016} and published under the same MIT Licence**, see U{Vector-based geodesy <https://www.Movable-Type.co.UK/scripts/latlong-vectors.html>}.
@newfield example: Example, Examples '''
property_RO, _xattrs _NorthPole_, _other_, _PARENTH_, \ _SouthPole_, _sumOf_ sumOf as _sumOf, _xyzhdn6
# from math import atan2, cos, sin
_sumOf_) # functions
'''Base class for ellipsoidal and spherical C{Nvector}s. '''
'''New n-vector normal to the earth's surface.
@arg x: An C{Nvector}, L{Vector3Tuple}, L{Vector4Tuple} or the C{X} coordinate (C{scalar}). @arg y: The C{Y} coordinate (C{scalar}) if B{C{x}} C{scalar}. @arg z: The C{Z} coordinate (C{scalar}) if B{C{x}} C{scalar}. @kwarg h: Optional height above surface (C{meter}). @kwarg ll: Optional, original latlon (C{LatLon}). @kwarg datum: Optional, I{pass-thru} datum (C{Datum}). @kwarg name: Optional name (C{str}).
@raise TypeError: Non-scalar B{C{x}}, B{C{y}} or B{C{z}} coordinate or B{C{x}} not an C{Nvector}, L{Vector3Tuple} or L{Vector4Tuple}.
@example:
>>> from pygeodesy.sphericalNvector import Nvector >>> v = Nvector(0.5, 0.5, 0.7071, 1) >>> v.toLatLon() # 45.0°N, 045.0°E, +1.00m '''
'''(INTERNAL) Zap cached attributes if updated. '''
def datum(self): '''Get the I{pass-thru} datum (C{Datum}) or C{None}. '''
def Ecef(self): '''Get the ECEF I{class} (L{EcefKarney} or L{EcefVeness}). '''
def h(self): '''Get the height above surface (C{meter}). '''
def h(self, h): '''Set the height above surface.
@arg h: New height (C{meter}).
@raise TypeError: If B{C{h}} invalid.
@raise VectorError: If B{C{h}} invalid. '''
def H(self): '''Get the height prefix (C{str}). '''
def H(self, H): '''Set the height prefix.
@arg H: New height prefix (C{str}). '''
'''Return a string for the height B{C{h}}.
@kwarg prec: Optional number of decimals, unstripped (C{int}). @kwarg m: Optional unit of the height (C{str}).
@see: Function L{hstr}. '''
def isEllipsoidal(self): '''Check whether this n-vector is ellipsoidal (C{bool} or C{None} if unknown). '''
def isSpherical(self): '''Check whether this n-vector is spherical (C{bool} or C{None} if unknown). '''
def lam(self): '''Get the (geodetic) longitude in C{radians} (C{float}). '''
def lat(self): '''Get the (geodetic) latitude in C{degrees} (C{float}). '''
def latlon(self): '''Get the (geodetic) lat-, longitude in C{degrees} (L{LatLon2Tuple}C{(lat, lon)}). '''
def latlonheight(self): '''Get the (geodetic) lat-, longitude in C{degrees} and height (L{LatLon3Tuple}C{(lat, lon, height)}). '''
def lon(self): '''Get the (geodetic) longitude in C{degrees} (C{float}). '''
def phi(self): '''Get the (geodetic) latitude in C{radians} (C{float}). '''
def philam(self): '''Get the (geodetic) lat-, longitude in C{radians} (L{PhiLam2Tuple}C{(phi, lam)}). '''
def philamheight(self): '''Get the (geodetic) lat-, longitude in C{radians} and height (L{PhiLam3Tuple}C{(phi, lam, height)}). '''
def to2ab(self): # PYCHOK no cover '''DEPRECATED, use property C{philam}.
@return: A L{PhiLam2Tuple}C{(phi, lam)}. ''' return self.philam
def to3abh(self, height=None): # PYCHOK no cover '''DEPRECATED, use method C{philamheight} or C{philam.to3Tuple}C{(}B{C{height}}C{)}.
@kwarg height: Optional height, overriding this n-vector's height (C{meter}).
@return: A L{PhiLam3Tuple}C{(phi, lam, height)}.
@raise ValueError: Invalid B{C{height}}. ''' return self.philamheight if height in (None, self.h) else \ self.philam.to3Tuple(height)
'''Convert this n-vector to C{Nvector}-based cartesian (ECEF) coordinates.
@kwarg h: Optional height, overriding this n-vector's height (C{meter}). @kwarg Cartesian: Optional class to return the (ECEF) coordinates (L{Cartesian}). @kwarg datum: Optional, spherical datum (C{Datum}). @kwarg Cartesian_kwds: Optional, additional B{C{Cartesian}} keyword arguments, ignored if B{C{Cartesian=None}}.
@return: The cartesian (ECEF) coordinates (B{C{Cartesian}}) or if B{C{Cartesian}} is C{None}, an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)} with C{C} and C{M} if available.
@raise TypeError: Invalid B{C{Cartesian}}.
@raise ValueError: Invalid B{C{h}}.
@example:
>>> v = Nvector(0.5, 0.5, 0.7071) >>> c = v.toCartesian() # [3194434, 3194434, 4487327] >>> p = c.toLatLon() # 45.0°N, 45.0°E '''
# Kenneth Gade eqn (22)
def to2ll(self): # PYCHOK no cover '''DEPRECATED, use property C{latlon}.
@return: A L{LatLon2Tuple}C{(lat, lon)}. ''' return self.latlon
def to3llh(self, height=None): # PYCHOK no cover '''DEPRECATED, use property C{latlonheight} or C{latlon.to3Tuple}C{)}B{C{height}}C{)}.
@kwarg height: Optional height, overriding this n-vector's height (C{meter}).
@return: A L{LatLon3Tuple}C{(lat, lon, height)}.
@raise ValueError: Invalid B{C{height}}. ''' return self.latlonheight if height in (None, self.h) else \ self.latlon.to3Tuple(height)
'''Convert this n-vector to an C{Nvector}-based geodetic point.
@kwarg height: Optional height, overriding this n-vector's height (C{meter}). @kwarg LatLon: Optional class to return the geodetic point (L{LatLon}) or C{None}. @kwarg datum: Optional, spherical datum (C{Datum}). @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword arguments, ignored if B{C{LatLon=None}}.
@return: The geodetic point (L{LatLon}) or if B{C{LatLon}} is is C{None}, an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)} with C{C} and C{M} if available.
@raise TypeError: Invalid B{C{LatLon}}.
@raise ValueError: Invalid B{C{height}}.
@example:
>>> v = Nvector(0.5, 0.5, 0.7071) >>> p = v.toLatLon() # 45.0°N, 45.0°E ''' # use self.Cartesian(Cartesian=None) if h == self.h and # d == self.datum, for better accuracy of the height
'''Return a string representation of this n-vector.
Height component is only included if non-zero.
@kwarg prec: Optional number of decimals, unstripped (C{int}). @kwarg fmt: Optional enclosing backets format (C{str}). @kwarg sep: Optional separator between components (C{str}).
@return: Comma-separated C{"(x, y, z [, h])"} enclosed in B{C{fmt}} brackets (C{str}).
@example:
>>> Nvector(0.5, 0.5, 0.7071).toStr() # (0.5, 0.5, 0.7071) >>> Nvector(0.5, 0.5, 0.7071, 1).toStr(-3) # (0.500, 0.500, 0.707, +1.00) '''
'''Convert this n-vector to a 3-D vector, I{ignoring the height}.
@kwarg norm: Normalize the 3-D vector (C{bool}).
@return: The (normalized) vector (L{Vector3d}). '''
def to4xyzh(self, h=None): # PYCHOK no cover '''DEPRECATED, use property C{xyzh} or C{xyz.to4Tuple}C{(}B{C{h}}C{)}. ''' return self.xyzh if h in (None, self.h) else \ self._xnamed(Vector4Tuple(self.x, self.y, self.z, h))
'''Normalize this n-vector to unit length.
@kwarg ll: Optional, original latlon (C{LatLon}).
@return: Normalized vector (C{Nvector}). '''
def xyzh(self): '''Get this n-vector's components (L{Vector4Tuple}C{(x, y, z, h)}) '''
'''(INTERNAL) Minimal, low-overhead C{n-vector}. '''
'''(INTERNAL) Base class for n-vector-based ellipsoidal and spherical C{LatLon} classes. '''
'''(INTERNAL) Zap cached attributes if updated.
@see: C{ellipsoidalNvector.LatLon} and C{sphericalNvector.LatLon} for the special case of B{C{_Nv}}. ''' if _Nv._fromll is not None: _Nv._fromll = None self._Nv = None
'''Refine the class comparison.
@arg other: The other point (C{LatLon}). @kwarg name: Optional, other's name (C{str}). @kwarg up: Number of call stack frames up (C{int}).
@raise TypeError: Incompatible B{C{other}} C{type}. '''
'''Convert this point to C{Nvector} components, I{including height}.
@kwarg Nvector_kwds: Optional, additional B{C{Nvector}} keyword arguments, ignored if B{C{Nvector=None}}.
@return: An B{C{Nvector}} or a L{Vector4Tuple}C{(x, y, z, h)} if B{C{Nvector}} is C{None}.
@raise TypeError: Invalid B{C{Nvector}} or B{C{Nvector_kwds}}. '''
'''Return the vectorial sum of two or more n-vectors.
@arg nvectors: Vectors to be added (C{Nvector}[]). @kwarg Vector: Optional class for the vectorial sum (C{Nvector}) or C{None}. @kwarg h: Optional height, overriding the mean height (C{meter}). @kwarg Vector_kwds: Optional, additional B{C{Vector}} keyword arguments, ignored if B{C{Vector=None}}.
@return: Vectorial sum (B{C{Vector}}) or a L{Vector4Tuple}C{(x, y, z, h)} if B{C{Vector}} is C{None}.
@raise VectorError: No B{C{nvectors}}. ''' raise VectorError(nvectors=n, txt=_Missing)
else:
# **) MIT License # # Copyright (C) 2016-2020 -- 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"), # to deal in the Software without restriction, including without limitation # the rights to use, copy, modify, merge, publish, distribute, sublicense, # and/or sell copies of the Software, and to permit persons to whom the # Software is furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included # in all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR # OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR # OTHER DEALINGS IN THE SOFTWARE. |