Coverage for pygeodesy/latlonBase.py : 90%

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 -*-
After I{(C) Chris Veness 2011-2015} published under the same MIT Licence**, see U{https://www.Movable-Type.co.UK/scripts/latlong.html}, U{<https://www.Movable-Type.co.UK/scripts/geodesy/docs/latlon-ellipsoidal.js.html>} and U{https://www.Movable-Type.co.UK/scripts/latlong-vectors.html}.
@newfield example: Example, Examples '''
haversine, isantipode, points2, vincentys PhiLam2Tuple, Vector3Tuple
# XXX the following classes are listed only to get # Epydoc to include class and method documentation
'''(INTERNAL) Base class for C{LatLon} points on spherical or ellipsoidal earth models. '''
'''New C{LatLon}.
@param lat: Latitude (C{degrees} or DMS C{str} with N or S suffix). @param lon: Longitude (C{degrees} or DMS C{str} with E or W suffix). @keyword height: Optional height (C{meter} above or below the earth surface). @keyword name: Optional name (C{str}).
@return: New instance (C{LatLon}).
@raise RangeError: Value of B{C{lat}} or B{C{lon}} outside the valid range and C{rangerrors} set to C{True}.
@raise ValueError: Invalid B{C{lat}} or B{C{lon}}.
@example:
>>> p = LatLon(50.06632, -5.71475) >>> q = LatLon('50°03′59″N', """005°42'53"W""") '''
return not self.isequalTo(other)
'''(INTERNAL) Weighted, average height.
@param other: An other point (C{LatLon}). @keyword f: Optional fraction (C{float}).
@return: Average, fractional height (C{float}). '''
'''(INTERNAL) Reset caches if updated. ''' self._v3d = self._v4t = None
'''Return the antipode, the point diametrically opposite to this point.
@keyword height: Optional height of the antipode, height of this point otherwise (C{meter}).
@return: The antipodal point (C{LatLon}). '''
'''DEPRECATED, use method C{boundsOf}. ''' return self.boundsOf(wide, high, radius=radius)
'''Return the SE and NW lat-/longitude of a great circle bounding box centered at this location.
@param wide: Longitudinal box width (C{meter}, same units as B{C{radius}} or C{degrees} if B{C{radius}} is C{None}). @param high: Latitudinal box height (C{meter}, same units as B{C{radius}} or C{degrees} if B{C{radius}} is C{None}). @keyword radius: Optional, mean earth radius (C{meter}).
@return: A L{Bounds2Tuple}C{(latlonSW, latlonNE)}, the lower-left and upper-right corner (C{LatLon}).
@see: U{https://www.Movable-Type.co.UK/scripts/latlong-db.html} ''' else: w = 0 # XXX
self.classof(self.lat + h, self.lon + w, height=self.height))
'''DEPRECATED, use method C{compassAngleTo}. ''' return self.compassAngleTo(other)
'''Return the angle from North for the direction vector between this and an other point.
Suitable only for short, non-near-polar vectors up to a few hundred Km or Miles. Use method C{initialBearingTo} for larger distances.
@param other: The other point (C{LatLon}). @keyword adjust: Adjust the longitudinal delta by the cosine of the mean latitude (C{bool}). @keyword wrap: Wrap and L{unroll180} longitudes and longitudinal delta (C{bool}).
@return: Compass angle from North (C{degrees360}).
@raise TypeError: The B{C{other}} point is not C{LatLon}.
@note: Courtesy Martin Schultz.
@see: U{Local, flat earth approximation <https://www.EdWilliams.org/avform.htm#flat>}. ''' adjust=adjust, wrap=wrap)
def datum(self): '''Get this point's datum. I{Must be overloaded}. ''' self._notOverloaded('datum')
'''(INTERNAL) Helper for methods C{<func>To}. ''' radius=radius, **options)
def Ecef(self): '''Get the ECEF C{class} (L{EcefKarney} or L{EcefVeness}). '''
'''DEPRECATED, use method C{isequalTo}. ''' return self.isequalTo(other, eps=eps)
'''DEPRECATED, use method C{isequalTo3}. ''' return self.isequalTo3(other, eps=eps)
'''Compute the distance between this and an other point using the U{Equirectangular Approximation / Projection <https://www.Movable-Type.co.UK/scripts/latlong.html>}.
Suitable only for short, non-near-polar distances up to a few hundred Km or Miles. Use method C{haversineTo} or C{distanceTo*} for more accurate and/or larger distances.
See function L{equirectangular_} for more details, the available B{C{options}} and errors raised.
@param other: The other point (C{LatLon}). @keyword radius: Optional, mean earth radius (C{meter}) or C{None} for the mean radius of this point's datum ellipsoid. @keyword options: Optional keyword arguments for function L{equirectangular}.
@return: Distance (C{meter}, same units as B{C{radius}}).
@raise TypeError: The B{C{other}} point is not C{LatLon}.
@see: Function L{equirectangular}, methods C{euclideanTo}, C{distanceTo*}, C{haversineTo} and C{vincentysTo}. '''
'''Approximate the C{Euclidian} distance between this and an other point.
See function L{euclidean} for the available B{C{options}}.
@param other: The other point (C{LatLon}). @keyword radius: Optional, mean earth radius (C{meter}) or C{None} for the mean radius of this point's datum ellipsoid. @keyword options: Optional keyword arguments for function L{euclidean}.
@return: Distance (C{meter}, same units as B{C{radius}}).
@raise TypeError: The B{C{other}} point is not C{LatLon}.
@see: Function L{euclidean}, methods C{equirectangularTo}, C{distanceTo*}, C{haversineTo} and C{vincentysTo}. '''
'''Compute the distance between this and an other point using the U{Haversine<https://www.Movable-Type.co.UK/scripts/latlong.html>} formula.
@param other: The other point (C{LatLon}). @keyword radius: Optional, mean earth radius (C{meter}) or C{None} for the mean radius of this point's datum ellipsoid. @keyword wrap: Wrap and L{unroll180} longitudes (C{bool}).
@return: Distance (C{meter}, same units as B{C{radius}}).
@raise TypeError: The B{C{other}} point is not C{LatLon}.
@see: Function L{haversine}, methods C{equirectangularTo}, C{euclideanTo}, C{distanceTo*} and C{vincentysTo}. ''' return self._distanceTo(haversine, other, radius, wrap=wrap)
def height(self): '''Get the height (C{meter}). '''
def height(self, height): '''Set the height.
@param height: New height (C{meter}).
@raise TypeError: Invalid B{C{height}} C{type}.
@raise ValueError: Invalid B{C{height}}. '''
'''Check whether this and an other point are antipodal, on diametrically opposite sides of the earth.
@param other: The other point (C{LatLon}). @keyword eps: Tolerance for near-equality (C{degrees}).
@return: C{True} if points are antipodal within the given tolerance, C{False} otherwise. ''' other.lat, other.lon, eps=eps)
'''DEPRECATED, use method C{isantipodeTo}. ''' return self.isantipodeTo(other, eps=eps)
'''Compare this point with an other point.
@param other: The other point (C{LatLon}). @keyword eps: Tolerance for equality (C{degrees}).
@return: C{True} if both points are identical, I{ignoring} height, C{False} otherwise.
@raise TypeError: The B{C{other}} point is not C{LatLon}.
@see: Method L{isequalTo3}.
@example:
>>> p = LatLon(52.205, 0.119) >>> q = LatLon(52.205, 0.119) >>> e = p.isequalTo(q) # True '''
abs(self.lon - other.lon) < eps else: self.lon == other.lon
'''Compare this point with an other point.
@param other: The other point (C{LatLon}). @keyword eps: Tolerance for equality (C{degrees}).
@return: C{True} if both points are identical I{including} height, C{False} otherwise.
@raise TypeError: The B{C{other}} point is not C{LatLon}.
@see: Method L{isequalTo}.
@example:
>>> p = LatLon(52.205, 0.119, 42) >>> q = LatLon(52.205, 0.119) >>> e = p.isequalTo3(q) # False '''
def lat(self): '''Get the latitude (C{degrees90}). '''
def lat(self, lat): '''Set the latitude.
@param lat: New latitude (C{str[N|S]} or C{degrees}).
@raise ValueError: Invalid B{C{lat}}. ''' lat = parseDMS(lat, suffix='NS', clip=90) self._update(lat != self._lat) self._lat = lat
def latlon(self): '''Get the lat- and longitude (L{LatLon2Tuple}). '''
def latlon(self, latlonh): '''Set the lat- and longitude and optionally the height.
@param latlonh: New lat-, longitude and height (2- or 3-tuple of C{degrees} and C{meter}).
@raise TypeError: Height of B{C{latlonh}} not C{scalar} or B{C{latlonh}} not C{list} or C{tuple}.
@raise ValueError: Invalid B{C{latlonh}} or M{len(latlonh)}.
@see: Function L{parse3llh} to parse a B{C{latlonh}} string into a 3-tuple (lat, lon, h). '''
raise ValueError('%s invalid: %r' % ('latlonh', latlonh)) else:
lon != self._lon or h != self._height)
def latlonheight(self): '''Get the lat-, longitude and height (L{LatLon3Tuple}). '''
'''DEPRECATED, use method C{latlon2}. ''' return self.latlon2(ndigits)
'''Return this point's lat- and longitude in C{degrees}, rounded.
@keyword ndigits: Number of decimal digits (C{int}).
@return: A L{LatLon2Tuple}C{(lat, lon)}, both C{float} and rounded away from zero.
@note: The C{round}ed values are always C{float}, also if B{C{ndigits}} is omitted. ''' round(self.lon, ndigits))
'''DEPRECATED, use method C{latlon2}. ''' return self.latlon2(ndigits)
def lon(self): '''Get the longitude (C{degrees180}). '''
def lon(self, lon): '''Set the longitude.
@param lon: New longitude (C{str[E|W]} or C{degrees}).
@raise ValueError: Invalid B{C{lon}}. ''' lon = parseDMS(lon, suffix='EW', clip=180) self._update(lon != self._lon) self._lon = lon
def philam(self): '''Get the lat- and longitude (L{PhiLam2Tuple}). '''
def philamheight(self): '''Get the lat-, longitude and height (L{PhiLam3Tuple}). '''
'''Return this point's lat- and longitude in C{radians}, rounded.
@keyword ndigits: Number of decimal digits (C{int}).
@return: A L{PhiLam2Tuple}C{(phi, lam)}, both C{float} and rounded away from zero.
@note: The C{round}ed values are always C{float}, also if B{C{ndigits}} is omitted. ''' r = self._ab or self.to2ab() r = PhiLam2Tuple(round(r.phi, ndigits), round(r.lam, ndigits)) return self._xnamed(r)
'''DEPRECATED, use method C{points2}. ''' return self.points2(points, closed=closed)
'''Check a path or polygon represented by points.
@param points: The path or polygon points (C{LatLon}[]) @keyword closed: Optionally, consider the polygon closed, ignoring any duplicate or closing final B{C{points}} (C{bool}).
@return: A L{Points2Tuple}C{(number, points)}, C{int} and C{list} or C{tuple}.
@raise TypeError: Some B{C{points}} are not C{LatLon}.
@raise ValueError: Insufficient number of B{C{points}}. '''
'''Return this point's lat- and longitude in C{radians}.
@return: A L{PhiLam2Tuple}C{(phi, lam)}. '''
'''Return this point's lat-, longitude and height.
@keyword height: Optional height, overriding this point's height (C{meter}).
@return: A L{LatLon3Tuple}C{(lat, lon, height)}. '''
'''DEPRECATED, use method C{toVector}, C{toNvector} or C{toEcef}.
@return: See method C{toVector} for C{B{Vector}=None}. '''
'''Convert this point to geocentric (ECEF cartesian) coordinates.
@keyword Cartesian: Optional (sub-)class to return the geocentric coordinates (C{Cartesian}) or C{None}. @keyword kwds: Optional, additional B{C{Cartesian}} keyword arguments, ignored if C{B{Cartesian}=None}.
@return: A B{C{Cartesian}} or if C{B{Cartesian}=None}, an L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)} with C{C} 0 and C{M} if available.
@raise TypeError: Invalid B{C{Cartesian}} or B{C{kwds}}. '''
'''Convert this point to a geocentric coordinates, alse known as I{Earth-Centered, Earth-Fixed} (U{ECEF <https://WikiPedia.org/wiki/ECEF>}).
@return: An L{Ecef9Tuple}C{(x, y, z, lat, lon, height, C, M, datum)} with C{C} 0 and C{M} if available.
@raise EcefError: A C{.datum} or an ECEF issue. '''
'''Convert this point to C{n-vector} (normal to the earth's surface) components, I{including height}.
@keyword h: Optional height, overriding this point's height (C{meter}). @keyword Nvector: Optional (sub-)class to return the C{n-vector} components (C{Nvector}) or C{None}. @keyword kwds: Optional, additional B{C{Nvector}} keyword arguments, ignored if C{B{Nvector}=None}.
@return: A B{C{Nvector}} or an L{Vector4Tuple}C{(x, y, z, h)} if C{B{Nvector}=None}.
@raise TypeError: Invalid B{C{Nvector}} or B{C{kwds}}. ''' else: # self.height, no kwds
'''Convert this point to a "lat, lon [+/-height]" string, formatted in the given form.
@keyword form: Optional format, F_D, F_DM, F_DMS for deg°, deg°min′, deg°min′sec″ (C{str}). @keyword prec: Optional number of decimal digits (0..8 or C{None}). @keyword m: Optional unit of the height (C{str}), use C{None} to exclude height from the returned string. @keyword sep: Optional separator to join (C{str}).
@return: Point in the specified form (C{str}).
@example:
>>> LatLon(51.4778, -0.0016).toStr() # 51°28′40″N, 000°00′06″W >>> LatLon(51.4778, -0.0016).toStr(F_D) # 51.4778°N, 000.0016°W >>> LatLon(51.4778, -0.0016, 42).toStr() # 51°28′40″N, 000°00′06″W, +42.00m
''' lonDMS(self.lon, form=form, prec=prec)]
'''Convert this point to C{n-vector} (normal to the earth's surface) components, I{ignoring height}.
@keyword Vector: Optional (sub-)class to return the C{n-vector} components (L{Vector3d}) or C{None}. @keyword kwds: Optional, additional B{C{Vector}} keyword arguments, ignored if C{B{Vector}=None}.
@return: A B{C{Vector}} or if C{B{Vector}=None}, an L{Vector3Tuple}C{(x, y, z)}.
@raise TypeError: Invalid B{C{Vector}} or B{C{kwds}}. ''' # Kenneth Gade eqn 3, but using right-handed # vector x -> 0°E,0°N, y -> 90°E,0°N, z -> 90°N
'''Convert this point to C{n-vector} (normal to the earth's surface) components, I{ignoring height}.
@return: Unit vector (L{Vector3d}). '''
'''Compute the distance between this and an other point using U{Vincenty's<https://WikiPedia.org/wiki/Great-circle_distance>} spherical formula.
@param other: The other point (C{LatLon}). @keyword radius: Optional, mean earth radius (C{meter}) or C{None} for the mean radius of this point's datum ellipsoid. @keyword wrap: Wrap and L{unroll180} longitudes (C{bool}).
@return: Distance (C{meter}, same units as B{C{radius}}).
@raise TypeError: The B{C{other}} point is not C{LatLon}.
@see: Function L{vincentys}, methods C{equirectangularTo}, C{euclideanTo}, C{distanceTo*} and C{haversineTo}. '''
# **) 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. |