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

# Class LatLon

               object --+
                        |
              bases.Named --+
                            |
                  bases.Based --+
                                |
           bases.LatLonHeightBase --+
                                    |
            nvector.LatLonNvectorBase --+
                                        |
               object --+               |
                        |               |
              bases.Named --+           |
                            |           |
                  bases.Based --+       |
                                |       |
           bases.LatLonHeightBase --+   |
                                    |   |
    sphericalBase.LatLonSphericalBase --+
                                        |
                                       LatLon

New n-vector based point on 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. |
copy(self) Copy this point. |
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) 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) Locate the point at a given fraction between this and an other point. |
intersection(self, end1, start2, end2, height=None) Locates the point of intersection of two paths each defined by two points or a start point and bearing from North. |
isEnclosedBy(self, points) Test whether this point is enclosed by a (convex) polygon defined by a list, sequence, set or tuple of points. |
isWithin(self, point1, point2) Test whether this point is within the extent of a segment joining two other points. |
midpointTo(self, other, height=None) Find the midpoint between this and an other point. |
nearestOn(self, point1, point2, height=None) Locate the closest point on the great circle segment between two points and this point. |
nearestOn2(self, points, radius=6371008.77141, height=None) Locate the closest point on the great circle segment between any two consecutive points of a path. |
toNvector(self) Convert this (geodetic) point to a (spherical) n-vector normal to the earth's surface. |
triangulate(self, bearing1, other, bearing2, height=None) Locate a point given this and an other point and bearings at this and the other point. |
trilaterate(self, distance1, point2, distance2, point3, distance3, radius=6371008.77141, height=None) Locate a point at given distances from this and two other points. |
Inherited from `nvector.LatLonNvectorBase`: `others`, `to4xyzh` Inherited from `sphericalBase.LatLonSphericalBase`: `finalBearingTo`, `maxLat`, `minLat`, `parse`, `rhumbBearingTo`, `rhumbDestination`, `rhumbDistanceTo`, `rhumbMidpointTo`, `toWm` Inherited from `bases.LatLonHeightBase`: `__eq__`, `__init__`, `__ne__`, `__str__`, `antipode`, `bounds`, `compassAngle`, `compassAngleTo`, `equals`, `equals3`, `equirectangularTo`, `isantipode`, `isantipodeTo`, `isequalTo`, `isequalTo3`, `latlon2round`, `latlon_`, `points`, `to2ab`, `to3llh`, `to3xyz`, `toStr` Inherited from `bases.Based`: `__repr__`, `classof`, `toStr2` Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
Inherited from `sphericalBase.LatLonSphericalBase`: `datum`, `isEllipsoidal`, `isSpherical` Inherited from `bases.LatLonHeightBase`: `height`, `lat`, `latlon`, `lon` Inherited from `bases.Named`: `classname`, `classnaming`, `name` 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. Parameters: `start` - Start point of great circle path (LatLon). `end` - End point of great circle path (LatLon) or initial bearing from start point (compass degrees). `radius` - Optional, 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` - The 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

### copy(self) |
Copy this point. Returns: The copy (LatLon or subclass thereof). Overrides: bases.Named.copy

### crossTrackDistanceTo(self, start, end, radius=6371008.77141) |
Compute the (signed) distance from this point to great circle defined by a start and end point. Parameters: `start` - Start point of great circle path (LatLon). `end` - End point of great circle path (LatLon) or initial bearing from start point (compass degrees). `radius` - Optional, 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` - The 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. Parameters: `distance` - Distance travelled (same units radius). `bearing` - Bearing from this point (compass degrees). `radius` - Optional, mean earth radius (meter). `height` - Optional height at destination, overriding the default height (meter). Returns: Destination point (LatLon). Raises: `Valuerror` - Polar coincidence. 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) |
Compute the distance from this to an other point. Parameters: `other` - The other point (LatLon). `radius` - Optional, mean earth radius (meter). Returns: Distance between this and the other point (meter, same units as radius). Raises: `TypeError` - The other point is not LatLon. 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. Parameters: `bearing` - Bearing from this point (compass degrees). Returns: N-vector representing great circle (Nvector). Example:
    >>> p = LatLon(53.3206, -1.7297)
    >>> gc = p.greatCircle(96.0)
    >>> gc.toStr()  # [-0.794, 0.129, 0.594]

### 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. Parameters: `other` - The other point (LatLon) or the bearing from this point (compass degrees). Returns: N-vector representing 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. Parameters: `other` - The other point (LatLon). `unused` - Optional keyword argument wrap ignored. Returns: Initial bearing (compass degrees). Raises: `TypeError` - The other point is not LatLon. `Valuerror` - Points or polar coincidence. Example:
    >>> p1 = LatLon(52.205, 0.119)
    >>> p2 = LatLon(48.857, 2.351)
    >>> b = p1.bearingTo(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. Parameters: `other` - The other point (LatLon). `fraction` - Fraction between both points (float, 0.0 = this point, 1.0 = 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) |
Locate the point at a given fraction between this and an other point. Parameters: `other` - The other point (LatLon). `fraction` - Fraction between both points (float, 0.0 = this point, 1.0 = 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. 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) |
Locates the point of intersection of two paths each defined by two points or a start point and bearing from North. Parameters: `end1` - End point of first path (LatLon) or the initial bearing at this point (compass degrees). `start2` - Start point of the second path (LatLon). `end2` - End point of 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: Intersection point (LatLon). Raises: `TypeError` - The start2, end1 or end2 is not LatLon. `Valuerror` - Points coincide. 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) |
Test whether this point is enclosed by a (convex) polygon defined by a list, sequence, set or tuple of points. Parameters: `points` - The points defining the polygon (LatLon[]). Returns: True if the polygon encloses this point (bool). Raises: `TypeError` - Some points are not LatLon. `ValueError` - Insufficient number of points. 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.

### isWithin(self, point1, point2) |
Test whether this point is within the extent of a segment joining two other points. If this point is not on the great circle 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). Parameters: `point1` - Start point of the segment (LatLon). `point2` - End point of the segment (LatLon). Returns: True if this point is within the segment (bool). Raises: `TypeError` - If point1 or point2 is not LatLon. JS name: isBetween.

### midpointTo(self, other, height=None) |
Find the midpoint between this and an other point. Parameters: `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) |
Locate the closest point on the great circle segment between two points and this point. If this point is within the extent of the segment between both end points, the returned point is on the segment. Otherwise the returned point is the closest of the segment end points. Parameters: `point1` - Start point of the segment (LatLon). `point2` - End point of the segment (LatLon). `height` - Optional height, overriding the mean height for the point if within segment (meter). Returns: Closest point on segment (LatLon). Raises: `TypeError` - If point1 or point2 is not LatLon. 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, radius=6371008.77141, height=None) |
Locate the closest point on the great circle segment between any two consecutive points of a path. If this point is within the extent of any segment, the closest point is on the segment. Otherwise the closest point is the nearest of the segment end points. Parameters: `points` - The points of the path (LatLon[]). `radius` - Optional, mean earth radius (meter). `height` - Optional height, overriding the mean height for a point if within segment (meter). Returns: 2-Tuple (closest, distance) of the closest point (LatLon) on the path and the distance to that point in meter, rather the units of radius. Raises: `TypeError` - Some points are not LatLon. `ValueError` - No points.

### toNvector(self) |
Convert this (geodetic) point to a (spherical) n-vector normal to the earth's surface. Returns: N-vector representing this point (Nvector). Example:
    >>> p = LatLon(45, 45)
    >>> n = p.toNvector()
    >>> n.toStr()  # [0.50, 0.50, 0.70710]
JS name: toVector.

### triangulate(self, bearing1, other, bearing2, height=None) |
Locate a point given this and an other point and bearings at this and the other point. Parameters: `bearing1` - Bearing at this point (compass degrees). `other` - The other point (LatLon). `bearing2` - Bearing at the other point (compass degrees). `height` - Optional height at the triangulated point, overriding the mean height (meter). Returns: Triangulated point (LatLon). Raises: `TypeError` - The other point is not LatLon. `Valuerror` - Points coincide. Example:
    >>> p = LatLon("47°18.228'N","002°34.326'W")  # Basse Castouillet
    >>> q = LatLon("47°18.664'N","002°31.717'W")  # Basse Hergo
    >>> t = p.triangulate(7, q, 295)  # 47.323667°N, 002.568501°W'

### trilaterate(self, distance1, point2, distance2, point3, distance3, radius=6371008.77141, height=None) |
Locate a point at given distances from this and two other points. See also Trilateration. Parameters: `distance1` - Distance to this point (same units as radius). `point2` - Second reference point (LatLon). `distance2` - Distance to point2 (same units as radius). `point3` - Third reference point (LatLon). `distance3` - Distance to point3 (same units as radius). `radius` - Optional, mean earth radius (meter). `height` - Optional height at trilaterated point, overriding the mean height (meter or same unit as radius). Returns: Trilaterated point (LatLon). Raises: `TypeError` - One of the points is not LatLon. `ValueError` - Distance(s) exceeds trilateration or some points coincide.