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.771415, wrap=False) Compute the (angular) distance (signed) from the start to the closest point on the great circle line 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.771415, wrap=False) Compute the (signed, angular) distance from this point to the great circle defined by a start and an end point. |
destination(self, distance, bearing, radius=6371008.771415, height=None) Locate the destination from this point after having travelled the given distance on the given initial bearing. |
distanceTo(self, other, radius=6371008.771415, wrap=False) Compute the (angular) distance from this to an other point. |
greatCircle(self, bearing, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds) 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 lines, each defined by two points or a start point and bearing from North. |
intersections2(self, rad1, other, rad2, radius=6371008.771415, 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) DEPRECATED, use method `isenclosedBy`. |
isenclosedBy(self, points, wrap=False) Check whether a (convex) polygon or composite encloses this point. |
midpointTo(self, other, height=None, fraction=0.5, wrap=False) Find the midpoint between this and an other point. |
nearestOn(self, point1, point2, radius=6371008.771415, **wrap_adjust_limit) Locate the point between two points closest to this point. |
nearestOn2(self, points, closed=False, radius=6371008.771415, **options) DEPRECATED, use method sphericalTrigonometry.LatLon.nearestOn3. |
nearestOn3(self, points, closed=False, radius=6371008.771415, **wrap_adjust_limit) 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.771415, wrap=False) Compute the angles, sides and area of a spherical triangle. |
trilaterate5(self, distance1, point2, distance2, point3, distance3, area=True, eps=0.9999999999999998, radius=6371008.771415, wrap=False) Trilaterate three points by area overlap or perimeter intersection of three corresponding circles. |
Inherited from `sphericalBase.LatLonSphericalBase`: `__init__`, `bearingTo2`, `finalBearingTo`, `intersecant2`, `maxLat`, `minLat`, `parse`, `rhumbAzimuthTo`, `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`, `normal`, `philam2`, `points`, `points2`, `radii11`, `rhumbLine`, `thomasTo`, `to2ab`, `to3llh`, `to3xyz`, `toEcef`, `toLocal`, `toLtp`, `toNormal`, `toStr`, `toVector`, `toVector3d`, `vincentysTo` Inherited from `named._NamedBase`: `__repr__`, `others`, `toRepr` Inherited from `named._Named`: `__imatmul__`, `__matmul__`, `__rmatmul__`, `attrs`, `classof`, `copy`, `dup`, `methodname`, `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`, `clipid`, `height`, `isEllipsoidal`, `isEllipsoidalLatLon`, `isSpherical`, `isnormal`, `lam`, `lat`, `latlon`, `latlonheight`, `lon`, `phi`, `philam`, `philamheight`, `xyz`, `xyzh` Inherited from `named._Named`: `classname`, `classnaming`, `iteration`, `name`, `named`, `named2`, `named3`, `named4` Inherited from `object`: `__class__`

Method Details

### alongTrackDistanceTo (self, start, end, radius=6371008.771415, wrap=False) |
Compute the (angular) distance (signed) from the start to the closest point on the great circle line defined by a start and an end point. That is, if a perpendicular is drawn from this point to the great circle line, the along-track distance is the distance from the start point to the point where the perpendicular crosses the line. Arguments: `start` - Start point of the great circle line (LatLon). `end` - End point of the great circle line (LatLon). `radius` - Mean earth radius (`meter`) or `None`. `wrap` - If `True`, wrap or normalize and unroll the `start` and `end` point (`bool`). Returns: Distance along the great circle line (`meter`, same units as `radius`) or `radians` if `radius is None`, positive if after the `start` toward the `end` point of the line, negative if before or `0` if at 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` - If `True`, wrap or normalize and unroll the `other` point (`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.771415, wrap=False) |
Compute the (signed, angular) distance from this point to the great circle defined by a start and an end point. Arguments: `start` - Start point of the great circle line (LatLon). `end` - End point of the great circle line (LatLon). `radius` - Mean earth radius (`meter`) or `None`. `wrap` - If `True`, wrap or normalize and unroll the `start` and `end` point (`bool`). Returns: Distance to the great circle (negative if to the left or positive if to the right of the line) (`meter`, same units as `radius` or `radians` if `radius` is `None`). Raises: `TypeError` - If `start` or `end` 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.771415, 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'

### distanceTo (self, other, radius=6371008.771415, 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` - If `True`, wrap or normalize and unroll the `other` point (`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, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds) |
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`). `Vector` - Vector class to return the great circle, overriding the default Vector3d. `Vector_kwds` - Optional, additional keyword argunents for `Vector`. Returns: Vector representing great circle (`Vector`). 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` - If `True`, wrap or normalize and unroll the `other` point (`bool`). `raiser` - Optionally, raise CrossError (`bool`), use `raiser=True` for behavior like `sphericalNvector.LatLon.initialBearingTo`. Returns: Initial bearing (compass `degrees360`). Raises: `CrossError` - If this and the `other` point coincide, provided both `raiser` is `True` and 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

### 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` - If `True`, wrap or normalize and unroll the `other` point (`bool`). Returns: Intermediate point (LatLon). Raises: `TypeError` - The `other` point is not LatLon. `ValueError` - Invalid `fraction` or `height`. See Also: Methods `midpointTo` and `rhumbMidpointTo`. 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

### intersection (self, end1, other, end2, height=None, wrap=False) |
Compute the intersection point of two lines, each defined by two points or a start point and bearing from North. Arguments: `end1` - End point of this line (LatLon) or the initial bearing at this point (compass `degrees360`). `other` - Start point of the other line (LatLon). `end2` - End point of the other line (LatLon) or the initial bearing at the `other` point (compass `degrees360`). `height` - Optional height for intersection point, overriding the mean height (`meter`). `wrap` - If `True`, wrap or normalize and unroll `start2` and both `end*` points (`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 lines. `TypeError` - If `other` is not LatLon or `end1` or `end2` not `scalar` nor LatLon. `ValueError` - Invalid `height` or `null` line. 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.771415, 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` - If `True`, wrap or normalize and unroll the `other` point (`bool`). Returns: 2-Tuple of the intersection points, each a LatLon instance. For abutting circles, both intersection points are the same instance, aka the 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) |
DEPRECATED, use method `isenclosedBy`. Decorators: `@deprecated_method`

### isenclosedBy (self, points, wrap=False) |
Check whether a (convex) polygon or composite encloses this point. Arguments: `points` - The polygon points or composite (LatLon[], BooleanFHP or BooleanGH). `wrap` - If `True`, wrap or normalize and unroll the `points` (`bool`). Returns: `True` if this point is inside the polygon or composite, `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.

### midpointTo (self, other, height=None, fraction=0.5, 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`). `fraction` - Midpoint location from this point (`scalar`), may be negative or greater than 1.0. `wrap` - If `True`, wrap or normalize and unroll the `other` point (`bool`). Returns: Midpoint (LatLon). Raises: `TypeError` - The `other` point is not LatLon. `ValueError` - Invalid `height`. See Also: Methods `intermediateTo` and `rhumbMidpointTo`. 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.771415, **wrap_adjust_limit) |
Locate the point between two points closest to this point. Distances are approximated by function pygeodesy.equirectangular_, subject to the supplied `options`. Arguments: `point1` - Start point (LatLon). `point2` - End point (LatLon). `radius` - Mean earth radius (`meter`). `wrap_adjust_limit` - Optional keyword arguments for functions sphericalTrigonometry.nearestOn3 and pygeodesy.equirectangular_, Returns: Closest point on the great circle line (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`. See Also: Functions pygeodesy.equirectangular_ and pygeodesy.nearestOn5 and method sphericalTrigonometry.LatLon.nearestOn3.

### nearestOn2 (self, points, closed=False, radius=6371008.771415, **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.771415, **wrap_adjust_limit) |
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`). `wrap_adjust_limit` - Optional keyword arguments for function sphericalTrigonometry.nearestOn3 and 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: `LimitError` - Lat- and/or longitudinal delta exceeds `limit`, see function pygeodesy.equirectangular_. `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not `LatLon`. `ValueError` - Invalid `radius` or `options`. See Also: Functions pygeodesy.compassAngle, pygeodesy.equirectangular_ and pygeodesy.nearestOn5.

### 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.771415, 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` - If `True`, wrap or normalize and unroll the `otherB` and `otherC` points (`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=0.9999999999999998, radius=6371008.771415, 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` - If `True`, wrap or normalize and unroll `point2` and `point3` (`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 `point2` or `point3` or invalid `distance1`, `distance2`, `distance3` or `radius`.