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

Class LatLon

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

New n-vector based point on a spherical earth model.

Tools for working with points and paths on (a spherical model of) the earth's surface using vector-based methods.


Example:

>>> from sphericalNvector import LatLon
>>> p = LatLon(52.205, 0.119)

Instance Methods
 
alongTrackDistanceTo(self, start, end, radius=6371008.77141)
Compute the (signed) distance from the start to the closest point on the great circle path defined by a start and an end point.
 
bearingTo(self, other, **unused)
DEPRECATED, use method initialBearingTo.
 
crossTrackDistanceTo(self, start, end, radius=6371008.77141)
Compute the (signed) distance from this point to great circle defined by a start and 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 bearing.
 
distanceTo(self, other, radius=6371008.77141, wrap=False)
Compute the distance from this to an other point.
 
greatCircle(self, bearing)
Compute the vector normal to great circle obtained by heading on the given bearing from this point.
 
greatCircleTo(self, other)
Compute the vector normal to great circle obtained by heading from this to an other point or on a given bearing.
 
initialBearingTo(self, other, **unused)
Compute the initial bearing (forward azimuth) from this to an other point.
 
intermediateChordTo(self, other, fraction, height=None)
Locate the point projected from the point at given fraction on a straight line (chord) between this and an other point.
 
intermediateTo(self, other, fraction, height=None, **unused)
Locate the point at a given fraction between this and an other point.
 
intersection(self, end1, start2, end2, height=None)
Locate the intersection point of two paths each defined by two points or a start point and bearing from North.
 
isenclosedBy(self, points)
Check whether this point is enclosed by a (convex) polygon.
 
isEnclosedBy(self, points)
DEPRECATED, use method isenclosedBy.
 
iswithin(self, point1, point2)
Check whether this point is between two other points.
 
isWithin(self, point1, point2)
DEPRECATED, use method iswithin.
 
midpointTo(self, other, height=None)
Find the midpoint between this and an other point.
 
nearestOn(self, point1, point2, height=None, within=True, wrap=False)
Locate the point on the great circle arc between two points closest to this point.
 
nearestOn2(self, points, **closed_radius_height)
DEPRECATED, use method sphericalNvector.LatLon.nearestOn3.
 
nearestOn3(self, points, closed=False, radius=6371008.77141, height=None)
Locate the point on a path or polygon (with great circle arcs joining consecutive points) closest to this point.
 
toCartesian(self, **Cartesian_and_kwds)
Convert this point to Nvector-based cartesian (ECEF) coordinates.
 
toNvector(self, **Nvector_and_kwds)
Convert this point to Nvector components, including height.

Inherited from nvectorBase.LatLonNvectorBase: intersections2, others, triangulate, trilaterate, trilaterate5

Inherited from sphericalBase.LatLonSphericalBase: __init__, bearingTo2, finalBearingTo, maxLat, minLat, parse, rhumbBearingTo, rhumbDestination, rhumbDistanceTo, rhumbMidpointTo, 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__, 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)

 

Compute the (signed) distance 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) or initial bearing from start point (compass degrees360).
  • radius - Mean earth radius (meter).
Returns:
Distance along the great circle path (positive if after the start toward the end point of the path or negative if before the start point).
Raises:
  • TypeError - If start or end point is not LatLon.
  • Valuerror - Some points coincide.

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, **unused)

 

DEPRECATED, use method initialBearingTo.

Decorators:
  • @deprecated_method

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

 

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

Arguments:
  • start - Start point of great circle path (LatLon).
  • end - End point of great circle path (LatLon) or initial bearing from start point (compass degrees360).
  • radius - Mean earth radius (meter).
Returns:
Distance to great circle (negative if to the left or positive if to the right of the path).
Raises:
  • TypeError - If start or end point is not LatLon.
  • Valuerror - Some points coincide.

Example:

>>> p = LatLon(53.2611, -0.7972)
>>> s = LatLon(53.3206, -1.7297)
>>> d = p.crossTrackDistanceTo(s, 96)  # -305.7
>>> 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 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, overriding the default height (meter, same units as radius).
Returns:
Destination point (LatLon).
Raises:
  • Valuerror - Polar coincidence or invalid distance, bearing, radius or height.

Example:

>>> p = LatLon(51.4778, -0.0015)
>>> q = p.destination(7794, 300.7)
>>> q.toStr()  # 51.513546°N, 000.098345°W

JS name: destinationPoint.

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

 

Compute the distance from this to an other point.

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

Example:

>>> p = LatLon(52.205, 0.119)
>>> q = LatLon(48.857, 2.351);
>>> d = p.distanceTo(q)  # 404.3 km

greatCircle (self, bearing)

 

Compute the vector normal to great circle obtained by heading on the given 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:
N-vector representing the great circle (Nvector).

greatCircleTo (self, other)

 

Compute the vector normal to great circle obtained by heading from this to an other point or on a given bearing.

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

Arguments:
  • other - The other point (LatLon) or the bearing from this point (compass degrees360).
Returns:
N-vector representing the great circle (Nvector).
Raises:
  • TypeError - The other point is not LatLon.
  • Valuerror - Points coincide.

Example:

>>> p = LatLon(53.3206, -1.7297)
>>> gc = p.greatCircle(96.0)
>>> gc.toStr()  # (-0.79408, 0.12856, 0.59406)
>>> q = LatLon(53.1887, 0.1334)
>>> g = p.greatCircleTo(q)
>>> g.toStr()  # (-0.79408, 0.12859, 0.59406)

initialBearingTo (self, other, **unused)

 

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

Arguments:
  • other - The other point (LatLon).
  • unused - Optional keyword argument wrap ignored.
Returns:
Initial bearing (compass degrees360).
Raises:
  • Crosserror - This point coincides with the other point or the NorthPole, provided pygeodesy.crosserrors is True.
  • TypeError - The other point is not LatLon.

Example:

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

JS name: bearingTo.

intermediateChordTo (self, other, fraction, height=None)

 

Locate the point projected from the point at given fraction on a straight line (chord) between this and an other point.

Arguments:
  • other - The other point (LatLon).
  • fraction - Fraction between both points (float, between 0.0 for this and 1.0 for the other point).
  • height - Optional height at the intermediate point, overriding the fractional height (meter).
Returns:
Intermediate point (LatLon).
Raises:
  • TypeError - The other point is not LatLon.

Example:

>>> p = LatLon(52.205, 0.119)
>>> q = LatLon(48.857, 2.351)
>>> i = p.intermediateChordTo(q, 0.25)  # 51.3723°N, 000.7072°E

JS name: intermediatePointOnChordTo, intermediatePointDirectlyTo.

intermediateTo (self, other, fraction, height=None, **unused)

 

Locate the point at a given fraction between this and an other point.

Arguments:
  • other - The other point (LatLon).
  • fraction - Fraction between both points (float, between 0.0 for this and 1.0 for the other point).
  • height - Optional height at the intermediate point, overriding the fractional height (meter).
Returns:
Intermediate point (LatLon).
Raises:
  • TypeError - The other point is not LatLon.
  • Valuerror - Points coincide or invalid height.

Example:

>>> p = LatLon(52.205, 0.119)
>>> q = LatLon(48.857, 2.351)
>>> i = p.intermediateTo(q, 0.25)  # 51.3721°N, 000.7074°E

JS name: intermediatePointTo.

intersection (self, end1, start2, end2, height=None)

 

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

Arguments:
  • end1 - End point of the first path (LatLon) or the initial bearing at this point (compass degrees360).
  • start2 - Start point of the second path (LatLon).
  • end2 - End point of the second path (LatLon) or the initial bearing at the second point (compass degrees).
  • height - Optional height at the intersection point, overriding the mean height (meter).
Returns:
The intersection point (LatLon) or None if no unique intersection exists.
Raises:
  • TypeError - If start2, end1 or end2 point is not LatLon.
  • ValueError - Intersection is ambiguous or infinite or the paths are parallel, coincident or null.

Example:

>>> s = LatLon(51.8853, 0.2545)
>>> e = LatLon(49.0034, 2.5735)
>>> i = s.intersection(108.55, e, 32.44)  # 50.9076°N, 004.5086°E

isenclosedBy (self, points)

 

Check whether this point is enclosed by a (convex) polygon.

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.

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

JS name: enclosedBy.

isEnclosedBy (self, points)

 

DEPRECATED, use method isenclosedBy.

Decorators:
  • @deprecated_method

iswithin (self, point1, point2)

 

Check whether this point is between two other points.

If this point is not on the great circle arc defined by both points, return whether it is within the area bound by perpendiculars to the great circle at each point (in the same hemispere).

Arguments:
  • point1 - Start point of the arc (LatLon).
  • point2 - End point of the arc (LatLon).
Returns:
True if this point is within the arc, False otherwise.
Raises:
  • TypeError - If point1 or point2 is not LatLon.

JS name: isBetween.

isWithin (self, point1, point2)

 

DEPRECATED, use method iswithin.

Decorators:
  • @deprecated_method

midpointTo (self, other, height=None)

 

Find the midpoint between this and an other point.

Arguments:
  • other - The other point (LatLon).
  • height - Optional height at the midpoint, overriding the mean height (meter).
Returns:
Midpoint (LatLon).
Raises:
  • TypeError - The other point is not LatLon.

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, height=None, within=True, wrap=False)

 

Locate the point on the great circle arc between two points closest to this point.

Arguments:
  • point1 - Start point of the arc (LatLon).
  • point2 - End point of the arc (LatLon).
  • height - Optional height, overriding the mean height for the point within the arc (meter), or None to interpolate the height.
  • within - If True return the closest point between both given points, otherwise the closest point elsewhere on the arc (bool).
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Closest point on the arc (LatLon).
Raises:
  • NotImplementedError - Keyword argument wrap=True not supported.
  • TypeError - Invalid point1 or point2.

Example:

>>> s1 = LatLon(51.0, 1.0)
>>> s2 = LatLon(51.0, 2.0)
>>> s = LatLon(51.0, 1.9)
>>> p = s.nearestOn(s1, s2)  # 51.0004°N, 001.9000°E
>>> d = p.distanceTo(s)  # 42.71 m
>>> s = LatLon(51.0, 2.1)
>>> p = s.nearestOn(s1, s2)  # 51.0000°N, 002.0000°E

JS name: nearestPointOnSegment.

nearestOn2 (self, points, **closed_radius_height)

 

DEPRECATED, use method sphericalNvector.LatLon.nearestOn3.

Returns:
... 2-Tuple (closest, distance) of the closest point (LatLon) on the polygon and the distance to that point from this point ...

nearestOn3 (self, points, closed=False, radius=6371008.77141, height=None)

 

Locate the point on a path or polygon (with great circle arcs joining consecutive points) closest to this point.

The closest point is either on within the extent of any great circle arc or the nearest of the arc's end points.

Arguments:
  • points - The path or polygon points (LatLon[]).
  • closed - Optionally, close the polygon (bool).
  • radius - Mean earth radius (meter) or None.
  • height - Optional height, overriding the mean height for a point within the arc (meter).
Returns:
A NearestOn3Tuple(closest, distance, angle) of the closest point (LatLon), the distance between this and the closest point in meter, same units as radius or in radians if radius is None and the angle from this to the closest point in compass degrees360.
Raises:
  • TypeError - Some points are not LatLon.
  • ValueError - No points.

toCartesian (self, **Cartesian_and_kwds)

 

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

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

toNvector (self, **Nvector_and_kwds)

 

Convert this point to Nvector components, including height.

Arguments:
  • Nvector_and_kwds - Optional Nvector and Nvector keyword arguments. Use Nvector=... to override this Nvector class or specify Nvector=None.
Returns:
The n-vector components (Nvector) or if Nvector is set to None, a Vector4Tuple(x, y, z, h) if Nvector.
Raises:
  • TypeError - Invalid Nvector_and_kwds argument.
Overrides: latlonBase.LatLonBase.toNvector

Example:

>>> p = LatLon(45, 45)
>>> n = p.toNvector()
>>> n.toStr()  # [0.50, 0.50, 0.70710]

JS name: toVector.