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

# Class LatLon

                   object --+
                            |
                 named._Named --+
                                |
                 named._NamedBase --+
                                    |
                latlonBase.LatLonBase --+
                                        |
    ellipsoidalBase.LatLonEllipsoidalBase --+
                                            |
                                           LatLon

Using the formulae devised by Thaddeus Vincenty (1975) for an (oblate) ellipsoidal model of the earth to compute the geodesic distance and bearings between two given points or the destination point given an start point and (initial) bearing.

Set the earth model to be used with the keyword argument datum. The default is Datums.WGS84, which is the most globally accurate. For other models, see the Datums in module datum.

Note: This implementation of Vincenty methods may not converge for some valid points, raising a VincentyError. In that case, a result may be obtained by increasing the tolerance `epsilon` and/or iteration `limit`, see properties LatLon.epsilon and LatLon.iterations.

Instance Methods
bearingTo(self, other, wrap=False) DEPRECATED, use method `initialBearingTo`. |
bearingTo2(self, other, wrap=False) Compute the initial and final bearing (forward and reverse azimuth) from this to an other point, using Vincenty's `inverse` method. |
destination(self, distance, bearing, height=None) Compute the destination point after having travelled for the given distance from this point along a geodesic given by an initial bearing, using Vincenty's `direct` method. |
destination2(self, distance, bearing, height=None) Compute the destination point and the final bearing (reverse azimuth) after having travelled for the given distance from this point along a geodesic given by an initial bearing, using Vincenty's `direct` method. |
distanceTo(self, other, wrap=False, **unused) Compute the distance between this and an other point along a geodesic, using Vincenty's `inverse` method. |
distanceTo3(self, other, wrap=False) Compute the distance, the initial and final bearing along a geodesic between this and an other point, using Vincenty's `inverse` method. |
finalBearingOn(self, distance, bearing) Compute the final bearing (reverse azimuth) after having travelled for the given distance along a geodesic given by an initial bearing from this point, using Vincenty's `direct` method. |
finalBearingTo(self, other, wrap=False) Compute the final bearing (reverse azimuth) after having travelled along a geodesic from this point to an other point, using Vincenty's `inverse` method. |
initialBearingTo(self, other, wrap=False) Compute the initial bearing (forward azimuth) to travel along a geodesic from this point to an other point, using Vincenty's `inverse` method. |
intermediateTo(self, other, fraction, height=None, wrap=False) Return the point at given fraction along the geodesic between this and an other point, using Vincenty's `direct` and `inverse` methods. |
toCartesian(self, **Cartesian_datum_kwds) Convert this point to `Vincenty`-based cartesian (ECEF) coordinates. |
Inherited from `ellipsoidalBase.LatLonEllipsoidalBase`: `__init__`, `antipode`, `convertDatum`, `convertRefFrame`, `distanceTo2`, `elevation2`, `ellipsoid`, `ellipsoids`, `geoidHeight2`, `intersections2`, `nearestOn`, `parse`, `to3xyz`, `toDatum`, `toEtm`, `toLcc`, `toOsgr`, `toRefFrame`, `toUps`, `toUtm`, `toUtmUps`, `toWm`, `trilaterate5` Inherited from `latlonBase.LatLonBase`: `__eq__`, `__ne__`, `__str__`, `_distanceTo_`, `bounds`, `boundsOf`, `chordTo`, `compassAngle`, `compassAngleTo`, `cosineAndoyerLambertTo`, `cosineForsytheAndoyerLambertTo`, `cosineLawTo`, `equals`, `equals3`, `equirectangularTo`, `euclideanTo`, `flatLocalTo`, `flatPolarTo`, `haversineTo`, `heightStr`, `hubenyTo`, `isantipode`, `isantipodeTo`, `isequalTo`, `isequalTo3`, `latlon2`, `latlon2round`, `latlon_`, `philam2`, `points`, `points2`, `thomasTo`, `to2ab`, `to3llh`, `toEcef`, `toNvector`, `toStr`, `toVector`, `toVector3d`, `vincentysTo` Inherited from `named._NamedBase`: `__repr__`, `others`, `toRepr` Inherited from `named._Named`: `_DOT_`, `attrs`, `classof`, `copy`, `rename`, `toStr2` Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
| Ecef Get the ECEF class (EcefVeness), lazily.
| epsilon Property to get and set the convergence epsilon (`scalar`).
| iterations Property to get and set the iteration limit (`int`).
Inherited from `ellipsoidalBase.LatLonEllipsoidalBase`: `convergence`, `datum`, `epoch`, `iteration`, `reframe`, `scale` Inherited from `latlonBase.LatLonBase`: `height`, `isEllipsoidal`, `isSpherical`, `lam`, `lat`, `latlon`, `latlonheight`, `lon`, `phi`, `philam`, `philamheight`, `xyz`, `xyzh` Inherited from `named._Named`: `classname`, `classnaming`, `name`, `named`, `named2`, `named3`, `named4` Inherited from `object`: `__class__`

Method Details

### bearingTo2 (self, other, wrap=False) |
Compute the initial and final bearing (forward and reverse azimuth) from this to an other point, using Vincenty's `inverse` method. See methods initialBearingTo and finalBearingTo for more details. Arguments: `other` - The other point (LatLon). `wrap` - Wrap and unroll longitudes (`bool`). Returns: A Bearing2Tuple`(initial, final)`. Raises: `TypeError` - The `other` point is not LatLon. `ValueError` - If this and the `other` point's Datum ellipsoids are not compatible. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit and/or if this and the `other` point are coincident or near-antipodal.

### destination (self, distance, bearing, height=None) |
Compute the destination point after having travelled for the given distance from this point along a geodesic given by an initial bearing, using Vincenty's `direct` method. See method destination2 for more details. Arguments: `distance` - Distance (`meter`). `bearing` - Initial bearing (compass `degrees360`). `height` - Optional height, overriding the default height (`meter`, same units as `distance`). Returns: The destination point (LatLon). Raises: `TypeError` - The `other` point is not LatLon. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit. Example:
    >>> p = LatLon(-37.95103, 144.42487)
    >>> d = p.destination(54972.271, 306.86816)  # 37.6528°S, 143.9265°E

### destination2 (self, distance, bearing, height=None) |
Compute the destination point and the final bearing (reverse azimuth) after having travelled for the given distance from this point along a geodesic given by an initial bearing, using Vincenty's `direct` method. The distance must be in the same units as this point's datum axes, conventionally `meter`. The distance is measured on the surface of the ellipsoid, ignoring this point's height. The initial and final bearing (forward and reverse azimuth) are in compass `degrees360`. The destination point's height and datum are set to this point's height and datum, unless the former is overridden. Arguments: `distance` - Distance (`meter`). `bearing` - Initial bearing (compass `degrees360`). `height` - Optional height, overriding the default height (`meter`, same units as `distance`). Returns: A Destination2Tuple`(destination, final)`. Raises: `TypeError` - The `other` point is not LatLon. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit. Example:
    >>> p = LatLon(-37.95103, 144.42487)
    >>> b = 306.86816
    >>> d, f = p.destination2(54972.271, b)
    >>> d
    LatLon(37°39′10.14″S, 143°55′35.39″E)  # 37.652818°S, 143.926498°E
    >>> f
    307.1736313846706

### distanceTo (self, other, wrap=False, **unused) |
Compute the distance between this and an other point along a geodesic, using Vincenty's `inverse` method. See method distanceTo3 for more details. Arguments: `other` - The other point (LatLon). `wrap` - Wrap and unroll longitudes (`bool`). Returns: Distance (`meter`). Raises: `TypeError` - The `other` point is not LatLon. `ValueError` - If this and the `other` point's Datum ellipsoids are not compatible. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit and/or if this and the `other` point are coincident or near-antipodal. Example:
    >>> p = LatLon(50.06632, -5.71475)
    >>> q = LatLon(58.64402, -3.07009)
    >>> d = p.distanceTo(q)  # 969,954.166 m

### distanceTo3 (self, other, wrap=False) |
Compute the distance, the initial and final bearing along a geodesic between this and an other point, using Vincenty's `inverse` method. The distance is in the same units as this point's datum axes, conventially meter. The distance is measured on the surface of the ellipsoid, ignoring this point's height. The initial and final bearing (forward and reverse azimuth) are in compass `degrees360` from North. Arguments: `other` - Destination point (LatLon). `wrap` - Wrap and unroll longitudes (`bool`). Returns: A Distance3Tuple`(distance, initial, final)`. Raises: `TypeError` - The `other` point is not LatLon. `ValueError` - If this and the `other` point's Datum ellipsoids are not compatible. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit and/or if this and the `other` point are coincident or near-antipodal.

### finalBearingOn (self, distance, bearing) |
Compute the final bearing (reverse azimuth) after having travelled for the given distance along a geodesic given by an initial bearing from this point, using Vincenty's `direct` method. See method destination2 for more details. Arguments: `distance` - Distance (`meter`). `bearing` - Initial bearing (compass `degrees360`). Returns: Final bearing (compass `degrees360`). Raises: `TypeError` - The `other` point is not LatLon. `ValueError` - If this and the `other` point's Datum ellipsoids are not compatible. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit. Example:
    >>> p = LatLon(-37.95103, 144.42487)
    >>> b = 306.86816
    >>> f = p.finalBearingOn(54972.271, b)  # 307.1736

### finalBearingTo (self, other, wrap=False) |
Compute the final bearing (reverse azimuth) after having travelled along a geodesic from this point to an other point, using Vincenty's `inverse` method. See method distanceTo3 for more details. Arguments: `other` - The other point (LatLon). `wrap` - Wrap and unroll longitudes (`bool`). Returns: Final bearing (compass `degrees360`). Raises: `TypeError` - The `other` point is not LatLon. `ValueError` - If this and the `other` point's Datum ellipsoids are not compatible. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit and/or if this and the `other` point are coincident or near-antipodal. Example:
    >>> p = new LatLon(50.06632, -5.71475)
    >>> q = new LatLon(58.64402, -3.07009)
    >>> f = p.finalBearingTo(q)  # 11.2972°
    >>> p = LatLon(52.205, 0.119)
    >>> q = LatLon(48.857, 2.351)
    >>> f = p.finalBearingTo(q)  # 157.9

### initialBearingTo (self, other, wrap=False) |
Compute the initial bearing (forward azimuth) to travel along a geodesic from this point to an other point, using Vincenty's `inverse` method. See method distanceTo3 for more details. Arguments: `other` - The other point (LatLon). `wrap` - Wrap and unroll longitudes (`bool`). Returns: Initial bearing (compass `degrees360`). Raises: `TypeError` - The `other` point is not LatLon. `ValueError` - If this and the `other` point's Datum ellipsoids are not compatible. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit and/or if this and the `other` point are coincident or near-antipodal. Example:
    >>> p = LatLon(50.06632, -5.71475)
    >>> q = LatLon(58.64402, -3.07009)
    >>> b = p.initialBearingTo(q)  # 9.141877°
    >>> p = LatLon(52.205, 0.119)
    >>> q = LatLon(48.857, 2.351)
    >>> b = p.initialBearingTo(q)  # 156.11064°
JS name: bearingTo.

### intermediateTo (self, other, fraction, height=None, wrap=False) |
Return the point at given fraction along the geodesic between this and an other point, using Vincenty's `direct` and `inverse` methods. Arguments: `other` - The other point (LatLon). `fraction` - Fraction between both points ranging from 0, meaning this to 1, the other point (`float`). `height` - Optional height, overriding the fractional height (`meter`). `wrap` - Wrap and unroll longitudes (`bool`). Returns: Intermediate point (LatLon). Raises: `TypeError` - The `other` point is not LatLon. `UnitError` - Invalid `fraction` or `height`. `ValueError` - If this and the `other` point's Datum ellipsoids are not compatible. `VincentyError` - Vincenty fails to converge for the current LatLon.epsilon and LatLon.iterations limit and/or if this and the `other` point are coincident or near-antipodal. See Also: Methods distanceTo3 and destination. Example:
    >>> p = ellipsoidalVincenty.LatLon(52.205, 0.119)
    >>> q = ellipsoidalVincenty.LatLon(48.857, 2.351)
    >>> i = p.intermediateTo(q, 0.25)  # 51.372275°N, 000.707253°E

### toCartesian (self, **Cartesian_datum_kwds) |
Convert this point to `Vincenty`-based cartesian (ECEF) coordinates. Arguments: `Cartesian_datum_kwds` - Optional Cartesian, `datum` and other keyword arguments, ignored if `Cartesian=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` or other `Cartesian_datum_kwds`. Overrides: latlonBase.LatLonBase.toCartesian

Property Details

### Ecef Get the ECEF class (EcefVeness), lazily. Get method: _fget(inst) Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst)

### epsilon Property to get and set the convergence epsilon (`scalar`). Get method: epsilon(self) - Get the convergence epsilon (`scalar`). Set method: epsilon(self, eps) - Set the convergence epsilon.

### iterations Property to get and set the iteration limit (`int`). Get method: iterations(self) - Get the iteration limit (`int`). Set method: iterations(self, limit) - Set the iteration limit.