Package pygeodesy :: Module sphericalTrigonometry :: Class LatLon
[frames] | no frames]

Class LatLon

           object --+                
                    |                
         named._Named --+            
                        |            
         named._NamedBase --+        
                            |        
        latlonBase.LatLonBase --+    
                                |    
sphericalBase.LatLonSphericalBase --+
                                    |
                                   LatLon

New point on spherical model earth model.


Example:

>>> p = LatLon(52.205, 0.119)  # height=0

Instance Methods
 
alongTrackDistanceTo(self, start, end, radius=6371008.77141, wrap=False)
Compute the (angular) distance (signed) from the start to the closest point on the great circle path defined by a start and an end point.
 
bearingTo(self, other, wrap=False, raiser=False)
DEPRECATED, use method initialBearingTo.
 
crossingParallels(self, other, lat, wrap=False)
Return the pair of meridians at which a great circle defined by this and an other point crosses the given latitude.
 
crossTrackDistanceTo(self, start, end, radius=6371008.77141, wrap=False)
Compute the (angular) distance (signed) from this point to the great circle defined by a start and an end point.
 
destination(self, distance, bearing, radius=6371008.77141, height=None)
Locate the destination from this point after having travelled the given distance on the given initial bearing.
 
distanceTo(self, other, radius=6371008.77141, wrap=False)
Compute the (angular) distance from this to an other point.
 
greatCircle(self, bearing)
Compute the vector normal to great circle obtained by heading on the given initial bearing from this point.
 
initialBearingTo(self, other, wrap=False, raiser=False)
Compute the initial bearing (forward azimuth) from this to an other point.
 
intermediateTo(self, other, fraction, height=None, wrap=False)
Locate the point at given fraction between (or along) this and an other point.
 
intersection(self, end1, other, end2, height=None, wrap=False)
Compute the intersection point of two paths, each defined by two points or a start point and bearing from North.
 
intersections2(self, rad1, other, rad2, radius=6371008.77141, eps=0.0, height=None, wrap=True)
Compute the intersection points of two circles, each defined by a center point and radius.
 
isenclosedBy(self, points)
Check whether a (convex) polygon encloses this point.
 
isEnclosedBy(self, points)
DEPRECATED, use method isenclosedBy.
 
midpointTo(self, other, height=None, wrap=False)
Find the midpoint between this and an other point.
 
nearestOn(self, point1, point2, radius=6371008.77141, **options)
Locate the point between two points closest to this point.
 
nearestOn2(self, points, closed=False, radius=6371008.77141, **options)
DEPRECATED, use method sphericalTrigonometry.LatLon.nearestOn3.
 
nearestOn3(self, points, closed=False, radius=6371008.77141, **options)
Locate the point on a polygon closest to this point.
 
toCartesian(self, **Cartesian_datum_kwds)
Convert this point to Karney-based cartesian (ECEF) coordinates.
 
triangle7(self, otherB, otherC, radius=6371008.77141, wrap=False)
Compute the angles, sides and area of a spherical triangle.
 
trilaterate5(self, distance1, point2, distance2, point3, distance3, area=True, eps=1.0, radius=6371008.77141, wrap=False)
Trilaterate three points by area overlap or perimeter intersection of three corresponding circles.

Inherited from sphericalBase.LatLonSphericalBase: __init__, bearingTo2, finalBearingTo, maxLat, minLat, parse, rhumbBearingTo, rhumbDestination, rhumbDistanceTo, rhumbMidpointTo, toNvector, toWm

Inherited from latlonBase.LatLonBase: PointsIter, __eq__, __ne__, __str__, antipode, bounds, boundsOf, chordTo, circin6, circum3, circum4_, compassAngle, compassAngleTo, cosineAndoyerLambertTo, cosineForsytheAndoyerLambertTo, cosineLawTo, destinationXyz, equals, equals3, equirectangularTo, euclideanTo, flatLocalTo, flatPolarTo, hartzell, haversineTo, height4, heightStr, hubenyTo, isantipode, isantipodeTo, isequalTo, isequalTo3, latlon2, latlon2round, latlon_, nearestOn6, philam2, points, points2, radii11, thomasTo, to2ab, to3llh, to3xyz, toEcef, toLocal, toLtp, toStr, toVector, toVector3d, vincentysTo

Inherited from named._NamedBase: __repr__, others, toRepr

Inherited from named._Named: __imatmul__, __matmul__, __rmatmul__, attrs, classof, copy, dup, rename, toStr2

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __subclasshook__

Properties

Inherited from sphericalBase.LatLonSphericalBase: datum

Inherited from latlonBase.LatLonBase: Ecef, height, isEllipsoidal, isEllipsoidalLatLon, isSpherical, lam, lat, latlon, latlonheight, lon, phi, philam, philamheight, xyz, xyzh

Inherited from named._NamedBase: iteration

Inherited from named._Named: classname, classnaming, name, named, named2, named3, named4

Inherited from object: __class__

Method Details

alongTrackDistanceTo (self, start, end, radius=6371008.77141, wrap=False)

 

Compute the (angular) distance (signed) from the start to the closest point on the great circle path defined by a start and an end point.

That is, if a perpendicular is drawn from this point to the great circle path, the along-track distance is the distance from the start point to the point where the perpendicular crosses the path.

Arguments:
  • start - Start point of great circle path (LatLon).
  • end - End point of great circle path (LatLon).
  • radius - Mean earth radius (meter) or None.
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Distance along the great circle path (meter, same units as radius) or radians if radius is None, positive if after the start toward the end point of the path or negative if before the start point.
Raises:
  • TypeError - Invalid start or end point.
  • ValueError - Invalid radius.

Example:

>>> p = LatLon(53.2611, -0.7972)
>>> s = LatLon(53.3206, -1.7297)
>>> e = LatLon(53.1887, 0.1334)
>>> d = p.alongTrackDistanceTo(s, e)  # 62331.58

bearingTo (self, other, wrap=False, raiser=False)

 

DEPRECATED, use method initialBearingTo.

Decorators:
  • @deprecated_method

crossingParallels (self, other, lat, wrap=False)

 

Return the pair of meridians at which a great circle defined by this and an other point crosses the given latitude.

Arguments:
  • other - The other point defining great circle (LatLon).
  • lat - Latitude at the crossing (degrees).
  • wrap - Wrap and unroll longitudes (bool).
Returns:
2-Tuple (lon1, lon2), both in degrees180 or None if the great circle doesn't reach lat.

crossTrackDistanceTo (self, start, end, radius=6371008.77141, wrap=False)

 

Compute the (angular) distance (signed) from this point to the great circle defined by a start and an end point.

Arguments:
  • start - Start point of great circle path (LatLon).
  • end - End point of great circle path (LatLon).
  • radius - Mean earth radius (meter) or None.
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Distance to great circle (negative if to the left or positive if to the right of the path) (meter, same units as radius or radians if radius is None).
Raises:
  • TypeError - The start or end point is not LatLon.
  • ValueError - Invalid radius.

Example:

>>> p = LatLon(53.2611, -0.7972)
>>> s = LatLon(53.3206, -1.7297)
>>> e = LatLon(53.1887, 0.1334)
>>> d = p.crossTrackDistanceTo(s, e)  # -307.5

destination (self, distance, bearing, radius=6371008.77141, height=None)

 

Locate the destination from this point after having travelled the given distance on the given initial bearing.

Arguments:
  • distance - Distance travelled (meter, same units as radius).
  • bearing - Bearing from this point (compass degrees360).
  • radius - Mean earth radius (meter).
  • height - Optional height at destination (meter, same units a radius).
Returns:
Destination point (LatLon).
Raises:
  • ValueError - Invalid distance, bearing, radius or height.

Example:

>>> p1 = LatLon(51.4778, -0.0015)
>>> p2 = p1.destination(7794, 300.7)
>>> p2.toStr()  # '51.5135°N, 000.0983°W'

JS name: destinationPoint.

distanceTo (self, other, radius=6371008.77141, wrap=False)

 

Compute the (angular) distance from this to an other point.

Arguments:
  • other - The other point (LatLon).
  • radius - Mean earth radius (meter) or None.
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Distance between this and the other point (meter, same units as radius or radians if radius is None).
Raises:
  • TypeError - The other point is not LatLon.
  • ValueError - Invalid radius.

Example:

>>> p1 = LatLon(52.205, 0.119)
>>> p2 = LatLon(48.857, 2.351);
>>> d = p1.distanceTo(p2)  # 404300

greatCircle (self, bearing)

 

Compute the vector normal to great circle obtained by heading on the given initial bearing from this point.

Direction of vector is such that initial bearing vector b = c × n, where n is an n-vector representing this point.

Arguments:
  • bearing - Bearing from this point (compass degrees360).
Returns:
Vector representing great circle (Vector3d).
Raises:
  • ValueError - Invalid bearing.

Example:

>>> p = LatLon(53.3206, -1.7297)
>>> g = p.greatCircle(96.0)
>>> g.toStr()  # (-0.794, 0.129, 0.594)

initialBearingTo (self, other, wrap=False, raiser=False)

 

Compute the initial bearing (forward azimuth) from this to an other point.

Arguments:
  • other - The other point (spherical LatLon).
  • wrap - Wrap and unroll longitudes (bool).
  • raiser - Optionally, raise CrossError (bool), use raiser=True for behavior like sphericalNvector.LatLon.initialBearingTo.
Returns:
Initial bearing (compass degrees360).
Raises:

Example:

>>> p1 = LatLon(52.205, 0.119)
>>> p2 = LatLon(48.857, 2.351)
>>> b = p1.initialBearingTo(p2)  # 156.2

JS name: bearingTo.

intermediateTo (self, other, fraction, height=None, wrap=False)

 

Locate the point at given fraction between (or along) this and an other point.

Arguments:
  • other - The other point (LatLon).
  • fraction - Fraction between both points (scalar, 0.0 at this and 1.0 at the other point).
  • height - Optional height, overriding the intermediate height (meter).
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Intermediate point (LatLon).
Raises:
  • TypeError - The other point is not LatLon.
  • ValueError - Invalid fraction or height.

Example:

>>> p1 = LatLon(52.205, 0.119)
>>> p2 = LatLon(48.857, 2.351)
>>> p = p1.intermediateTo(p2, 0.25)  # 51.3721°N, 000.7073°E

JS name: intermediatePointTo.

intersection (self, end1, other, end2, height=None, wrap=False)

 

Compute the intersection point of two paths, each defined by two points or a start point and bearing from North.

Arguments:
  • end1 - End point of this path (LatLon) or the initial bearing at this point (compass degrees360).
  • other - Start point of the other path (LatLon).
  • end2 - End point of the other path (LatLon) or the initial bearing at the other start point (compass degrees360).
  • height - Optional height for intersection point, overriding the mean height (meter).
  • wrap - Wrap and unroll longitudes (bool).
Returns:
The intersection point (LatLon). An alternate intersection point might be the antipode to the returned result.
Raises:
  • IntersectionError - Ambiguous or infinite intersection or colinear, parallel or otherwise non-intersecting paths.
  • TypeError - If other is not LatLon or end1 or end2 not scalar nor LatLon.
  • ValueError - Invalid height or null path.

Example:

>>> p = LatLon(51.8853, 0.2545)
>>> s = LatLon(49.0034, 2.5735)
>>> i = p.intersection(108.547, s, 32.435)  # '50.9078°N, 004.5084°E'

intersections2 (self, rad1, other, rad2, radius=6371008.77141, eps=0.0, height=None, wrap=True)

 

Compute the intersection points of two circles, each defined by a center point and radius.

Arguments:
  • rad1 - Radius of the this circle (meter or radians, see radius).
  • other - Center point of the other circle (LatLon).
  • rad2 - Radius of the other circle (meter or radians, see radius).
  • radius - Mean earth radius (meter or None if rad1, rad2 and eps are given in radians).
  • eps - Required overlap (meter or radians, see radius).
  • height - Optional height for the intersection points (meter, conventionally) or None for the "radical height" at the radical line between both centers.
  • wrap - Wrap and unroll longitudes (bool).
Returns:
2-Tuple of the intersection points, each a LatLon instance. For abutting circles, both intersection points are the same instance, aka radical center.
Raises:
  • IntersectionError - Concentric, antipodal, invalid or non-intersecting circles.
  • TypeError - If other is not LatLon.
  • ValueError - Invalid rad1, rad2, radius, eps or height.

isenclosedBy (self, points)

 

Check whether a (convex) polygon encloses this point.

Arguments:
  • points - The polygon points (LatLon[]).
Returns:
True if the polygon encloses this point, False otherwise.
Raises:
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid points, non-convex polygon.

See Also: Functions pygeodesy.isconvex, pygeodesy.isenclosedBy and pygeodesy.ispolar especially if the points may enclose a pole or wrap around the earth longitudinally.

Example:

>>> b = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1)
>>> p = LatLon(45,1, 1.1)
>>> inside = p.isEnclosedBy(b)  # True

isEnclosedBy (self, points)

 

DEPRECATED, use method isenclosedBy.

Decorators:
  • @deprecated_method

midpointTo (self, other, height=None, wrap=False)

 

Find the midpoint between this and an other point.

Arguments:
  • other - The other point (LatLon).
  • height - Optional height for midpoint, overriding the mean height (meter).
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Midpoint (LatLon).
Raises:
  • TypeError - The other point is not LatLon.
  • ValueError - Invalid height.

Example:

>>> p1 = LatLon(52.205, 0.119)
>>> p2 = LatLon(48.857, 2.351)
>>> m = p1.midpointTo(p2)  # '50.5363°N, 001.2746°E'

nearestOn (self, point1, point2, radius=6371008.77141, **options)

 

Locate the point between two points closest to this point.

Distances are approximated by function pygeodesy.equirectangular_, subject to the supplied options.

Arguments:
Returns:
Closest point on the great circle path (LatLon).
Raises:
  • LimitError - Lat- and/or longitudinal delta exceeds limit, see function pygeodesy.equirectangular_.
  • NotImplementedError - Keyword argument within=False is not (yet) supported.
  • TypeError - Invalid point1 or point2.
  • ValueError - Invalid radius or options.

nearestOn2 (self, points, closed=False, radius=6371008.77141, **options)

 

DEPRECATED, use method sphericalTrigonometry.LatLon.nearestOn3.

Returns:
... 2-Tuple (closest, distance) of the closest point (LatLon) on the polygon and the distance to that point from this point in meter, same units of radius.
Decorators:
  • @deprecated_method

nearestOn3 (self, points, closed=False, radius=6371008.77141, **options)

 

Locate the point on a polygon closest to this point.

Distances are approximated by function pygeodesy.equirectangular_, subject to the supplied options.

Arguments:
  • points - The polygon points (LatLon[]).
  • closed - Optionally, close the polygon (bool).
  • radius - Mean earth radius (meter).
  • options - Optional keyword arguments for function pygeodesy.equirectangular_.
Returns:
A NearestOn3Tuple(closest, distance, angle) of the closest point (LatLon), the pygeodesy.equirectangular_ distance between this and the closest point converted to meter, same units as radius. The angle from this to the closest point is in compass degrees360, like function pygeodesy.compassAngle.
Raises:

toCartesian (self, **Cartesian_datum_kwds)

 

Convert this point to Karney-based cartesian (ECEF) coordinates.

Arguments:
  • Cartesian_datum_kwds - Optional Cartesian, datum and other keyword arguments, ignored if Cartesian is None. Use Cartesian=... to override this Cartesian class or specify Cartesian=None.
Returns:
The cartesian point (Cartesian) or if Cartesian is None, an Ecef9Tuple(x, y, z, lat, lon, height, C, M, datum) with C and M if available.
Raises:
  • TypeError - Invalid Cartesian_datum_kwds argument.
Overrides: latlonBase.LatLonBase.toCartesian

triangle7 (self, otherB, otherC, radius=6371008.77141, wrap=False)

 

Compute the angles, sides and area of a spherical triangle.

Arguments:
  • otherB - Second triangle point (LatLon).
  • otherC - Third triangle point (LatLon).
  • radius - Mean earth radius, ellipsoid or datum (meter, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple) or None.
  • wrap - Wrap/unroll angular distances (bool).
Returns:
Triangle7Tuple(A, a, B, b, C, c, area) or if radius is None, a Triangle8Tuple(A, a, B, b, C, c, D, E).

See Also: Function triangle7 and Spherical trigonometry.

trilaterate5 (self, distance1, point2, distance2, point3, distance3, area=True, eps=1.0, radius=6371008.77141, wrap=False)

 

Trilaterate three points by area overlap or perimeter intersection of three corresponding circles.

Arguments:
  • distance1 - Distance to this point (meter, same units as radius).
  • point2 - Second center point (LatLon).
  • distance2 - Distance to point2 (meter, same units as radius).
  • point3 - Third center point (LatLon).
  • distance3 - Distance to point3 (meter, same units as radius).
  • area - If True compute the area overlap, otherwise the perimeter intersection of the circles (bool).
  • eps - The required minimal overlap for area=True or the intersection margin for area=False (meter, same units as radius).
  • radius - Mean earth radius (meter, conventionally).
  • wrap - Wrap/unroll angular distances (bool).
Returns:
A Trilaterate5Tuple(min, minPoint, max, maxPoint, n) with min and max in meter, same units as eps, the corresponding trilaterated points minPoint and maxPoint as spherical LatLon and n, the number of trilatered points found for the given eps.

If only a single trilaterated point is found, min is max, minPoint is maxPoint and n = 1.

For area=True, min and max are the smallest respectively largest radial overlap found.

For area=False, min and max represent the nearest respectively farthest intersection margin.

If area=True and all 3 circles are concentric, n = 0 and minPoint and maxPoint are both the point# with the smallest distance# min and max the largest distance#.

Raises:
  • IntersectionError - Trilateration failed for the given eps, insufficient overlap for area=True or no intersection or all (near-)concentric for area=False.
  • TypeError - Invalid point2 or point3.
  • ValueError - Coincident points or invalid distance1, distance2, distance3 or radius.