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, lines 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.771415, wrap=False) Compute the (signed) distance from the start to the closest point on the great circle line defined by a start and an end point. |
bearingTo(self, other, **unused) DEPRECATED, use method initialBearingTo. |
crossTrackDistanceTo(self, start, end, radius=6371008.771415, wrap=False) Compute the (signed) distance from this point to great circle defined by a start and 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 bearing. |
distanceTo(self, other, radius=6371008.771415, 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, wrap=False) Compute the vector normal to great circle obtained by heading from this to an other point or on a given bearing. |
initialBearingTo(self, other, wrap=False, **unused) Compute the initial bearing (forward azimuth) from this to an other point. |
intermediateChordTo(self, other, fraction, height=None, wrap=False) 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, wrap=False) Locate the point at a given fraction between this and an other point. |
intersection(self, end1, start2, end2, height=None, wrap=False) Locate the intersection point of two lines each defined by two points or a start point and bearing from North. |
intersection2(self, end1, start2, end2, height=None, wrap=False) Locate the intersections of two (great circle) lines each defined by two points or by a start point and an (initial) bearing. |
isenclosedBy(self, points, wrap=False) Check whether a (convex) polygon or composite encloses this point. |
isEnclosedBy(self, points) DEPRECATED, use method `isenclosedBy`. |
iswithin(self, point1, point2, wrap=False) Check whether this point is between two other points. |
isWithin(self, point1, point2) DEPRECATED, use method `iswithin`. |
midpointTo(self, other, height=None, fraction=0.5, wrap=False) 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.771415, height=None, wrap=False) 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`, `intersecant2`, `maxLat`, `minLat`, `parse`, `rhumbAzimuthTo`, `rhumbBearingTo`, `rhumbDestination`, `rhumbDistanceTo`, `rhumbIntersecant2`, `rhumbMidpointTo` 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`, `nearestTo`, `normal`, `philam2`, `points`, `points2`, `radii11`, `rhumbLine`, `thomasTo`, `to2ab`, `to3llh`, `to3xyz`, `toDatum`, `toEcef`, `toLocal`, `toLtp`, `toNormal`, `toStr`, `toVector`, `toVector3d`, `toWm`, `vincentysTo` Inherited from `named._NamedBase`: `__repr__`, `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`, `napieradius`, `sphericalLatLon` Inherited from `latlonBase.LatLonBase`: `Ecef`, `clipid`, `ellipsoidalLatLon`, `height`, `isEllipsoidal`, `isSpherical`, `isnormal`, `lam`, `lat`, `latlon`, `latlonheight`, `lon`, `phi`, `philam`, `philamheight`, `xyz`, `xyzh` Inherited from `named._Named`: `classname`, `classnaming`, `iteration`, `name`, `named`, `named2`, `named3`, `named4`, `sizeof` Inherited from `object`: `__class__`

Method Details

### alongTrackDistanceTo (self, start, end, radius=6371008.771415, wrap=False) |
Compute the (signed) distance 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 great circle line (LatLon). `end` - End point of great circle line (LatLon) or initial bearing from start point (compass `degrees360`). `radius` - Mean earth radius (`meter`) or `None`. `wrap` - If `True`, wrap or normalize and unroll the `start` and `end` points (`bool`). Returns: Distance along the great circle line (`radians` if `radius is None` else `meter`, same units as `radius`), positive if "after" the start toward the end point of the line 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.771415, wrap=False) |
Compute the (signed) distance from this point to great circle defined by a start and end point. Arguments: `start` - Start point of great circle line (LatLon). `end` - End point of great circle line (LatLon) or initial bearing from start point (compass `degrees360`). `radius` - Mean earth radius (`meter`) or `None`. `wrap` - If `True`, wrap or normalize and unroll the `start` and `end` points (`bool`). Returns: Distance to great circle (`radians` if `radius is None` else `meter`, same units as `radius`), negative if to the left or positive if to the right of the line . 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.771415, 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

### distanceTo (self, other, radius=6371008.771415, 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` - 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` - 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, wrap=False) |
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`). `wrap` - If `True`, wrap or normalize and unroll the `other` point (`bool`). 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, wrap=False, **unused) |
Compute the initial bearing (forward azimuth) from this to an other point. Arguments: `other` - The other point (LatLon). `wrap` - If `True`, wrap or normalize and unroll the `other` point (`bool`). 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

### intermediateChordTo (self, other, fraction, height=None, wrap=False) |
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`). `wrap` - If `True`, wrap or normalize and unroll the `other` point (`bool`). 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

### intermediateTo (self, other, fraction, height=None, wrap=False) |
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`). `wrap` - If `True`, wrap or normalize and unroll the `other` point (`bool`). Returns: Intermediate point (LatLon). Raises: `TypeError` - The `other` point is not LatLon. `Valuerror` - Points coincide or invalid `height`. See Also: Methods `midpointTo` and `rhumbMidpointTo`. 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

### intersection (self, end1, start2, end2, height=None, wrap=False) |
Locate the intersection point of two lines each defined by two points or a start point and bearing from North. Arguments: `end1` - End point of the first line (LatLon) or the initial bearing at this point (compass `degrees360`). `start2` - Start point of the second line (LatLon). `end2` - End point of the second line (LatLon) or the initial bearing at the second point (compass `degrees`). `height` - Optional height at the intersection point, overriding the mean height (`meter`). `wrap` - If `True`, wrap or normalize and unroll all start and end points (`bool`). Returns: The intersection point (LatLon). Raises: `TypeError` - If `start2`, `end1` or `end2` point is not LatLon. `ValueError` - Intersection is ambiguous or infinite or the lines are parallel, coincident or null. See Also: Function sphericalNvector.intersection and method intersection2. 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

### intersection2 (self, end1, start2, end2, height=None, wrap=False) |
Locate the intersections of two (great circle) lines each defined by two points or by a start point and an (initial) bearing. Arguments: `end1` - End point of the first line (LatLon) or the initial bearing at this point (compass `degrees360`). `start2` - Start point of the second line (LatLon). `end2` - End point of the second line (LatLon) or the initial bearing at the second start point (compass `degrees360`). `height` - Optional height at the intersection and antipodal point, overriding the mean height (`meter`). `wrap` - If `True`, wrap or normalize and unroll `start2` and both `end*` points (`bool`). Returns: 2-Tuple `(intersection, antipode)`, each a `LatLon`. Raises: `TypeError` - If `start2`, `end1` or `end2` point is not LatLon. `ValueError` - Intersection is ambiguous or infinite or the lines are parallel, coincident or null. See Also: Function sphericalNvector.intersection2 and method intersection.

### 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. See Also: Functions pygeodesy.isconvex, pygeodesy.isenclosedBy and pygeodesy.ispolar especially if the `points` may enclose a pole or wrap around the earth longitudinally.

### isEnclosedBy (self, points) |
DEPRECATED, use method `isenclosedBy`. Decorators: `@deprecated_method`

### iswithin (self, point1, point2, wrap=False) |
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). `wrap` - If `True`, wrap or normalize and unroll `point1` and `point2` (`bool`). Returns: `True` if this point is within the (great circle) arc, `False` otherwise. Raises: `TypeError` - If `point1` or `point2` is not LatLon.

### isWithin (self, point1, point2) |
DEPRECATED, use method `iswithin`. Decorators: `@deprecated_method`

### 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 at the 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. 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, 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 great circle arc (`bool`). `wrap` - If `True`, wrap or normalize and unroll `point1` and `point2` (`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

### 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.771415, height=None, wrap=False) |
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`). `wrap` - If `True`, wrap or normalize and unroll the `points` (`bool`). 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. Specify `Nvector=...` to override this Nvector class or use `Nvector=None`. Returns: The `n-vector` components (Nvector) or if `Nvector` is set to `None`, a Vector4Tuple`(x, y, z, h)`. 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]