Package pygeodesy :: Module latlonBase :: Class LatLonBase |
[frames] | no frames]

# Class LatLonBase

      object --+
               |
    named._Named --+
                   |
    named._NamedBase --+
                       |
                      LatLonBase

Known Subclasses:
  - ellipsoidalBase.LatLonEllipsoidalBase
  - , nvectorBase.LatLonNvectorBase
  - , sphericalBase.LatLonSphericalBase

(INTERNAL) Base class for `LatLon` points on spherical or ellipsoidal earth models.

Instance Methods
__eq__(self, other) |
__init__(self, lat, lon, height=0, name=`'````'`) New `LatLon`. |
__ne__(self, other) |
__str__(self) Default `str(self)`. |
antipode(self, height=None) Return the antipode, the point diametrically opposite to this point. |
bounds(self, wide, high, radius=6371008.77141) DEPRECATED, use method `boundsOf`. |
boundsOf(self, wide, high, radius=6371008.77141) Return the SE and NW lat-/longitude of a great circle bounding box centered at this location. |
compassAngle(self, other) DEPRECATED, use method `compassAngleTo`. |
compassAngleTo(self, other, adjust=True, wrap=False) Return the angle from North for the direction vector between this and an other point. |
equals(self, other, eps=None) DEPRECATED, use method `isequalTo`. |
equals3(self, other, eps=None) DEPRECATED, use method `isequalTo3`. |
equirectangularTo(self, other, radius=None, **options) Compute the distance between this and an other point using the Equirectangular Approximation / Projection. |
euclideanTo(self, other, radius=None, **options) Approximate the `Euclidian` distance between this and an other point. |
haversineTo(self, other, radius=None, wrap=False) Compute the distance between this and an other point using the Haversine formula. |
isantipode(self, other, eps=2.22044604925e-16) DEPRECATED, use method `isantipodeTo`. |
isantipodeTo(self, other, eps=2.22044604925e-16) Check whether this and an other point are antipodal, on diametrically opposite sides of the earth. |
isequalTo(self, other, eps=None) Compare this point with an other point. |
isequalTo3(self, other, eps=None) Compare this point with an other point. |
latlon2(self, ndigits=0) Return this point's lat- and longitude in `degrees`, rounded. |
latlon2round(self, ndigits=0) DEPRECATED, use method `latlon2`. |
latlon_(self, ndigits=0) DEPRECATED, use method `latlon2`. |
philam2(self, ndigits=0) Return this point's lat- and longitude in `radians`, rounded. |
points(self, points, closed=True) DEPRECATED, use method `points2`. |
points2(self, points, closed=True) Check a path or polygon represented by points. |
to2ab(self) DEPRECATED, use property `philam`. |
to3llh(self, height=None) DEPRECATED, use property `latlonheight` or `latlon.to3Tuple(height)`. |
to3xyz(self) DEPRECATED, use method `toNvector`, `toVector`, `toVector3d` or property `xyz` or perhaps (geocentric) `toEcef`. |
toCartesian(self, Cartesian=None, **kwds) Convert this point to cartesian (ECEF) coordinates. |
toEcef(self) Convert this point to geocentric coordinates, also known as Earth-Centered, Earth-Fixed (ECEF). |
toNvector(self, h=None, Nvector=None, **kwds) Convert this point to `n-vector` (normal to the earth's surface) components, including height. |
toStr(self, form=`'``dms``'`, prec=None, m=`'``m``'`, sep=`'``,` `'`) Convert this point to a "lat, lon [+/-height]" string, formatted in the given form. |
toVector(self, Vector=None, **kwds) Convert this point to `n-vector` (normal to the earth's surface) components, ignoring height. |
toVector3d(self) Convert this point to `n-vector` (normal to the earth's surface) components, ignoring height. |
vincentysTo(self, other, radius=None, wrap=False) Compute the distance between this and an other point using Vincenty's spherical formula. |
Inherited from `named._NamedBase`: `__repr__`, `others`, `toStr2` Inherited from `named._Named`: `_dot_`, `attrs`, `classof`, `copy` Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
| Ecef An immutable property (`Read Only`).
| datum An immutable property (`Read Only`).
| height Property to get and set the height (`meter`).
| isEllipsoidal An immutable property (`Read Only`).
| isSpherical An immutable property (`Read Only`).
| lam An immutable property (`Read Only`).
| lat Property to get and set the latitude (`degrees90`).
| latlon Property to get and set the lat- and longitude, optionally height.
| latlonheight An immutable property (`Read Only`).
| lon Property to get and set the longitude (`degrees180`).
| phi An immutable property (`Read Only`).
| philam An immutable property (`Read Only`).
| philamheight An immutable property (`Read Only`).
| xyz An immutable property (`Read Only`).
| xyzh An immutable property (`Read Only`).
Inherited from `named._Named`: `classname`, `classnaming`, `name`, `named`, `named2` Inherited from `object`: `__class__`

Method Details

### __init__(self, lat, lon, height=0, name=`'````'`) (Constructor) |
New `LatLon`. Parameters: `lat` - Latitude (`degrees` or DMS `str` with N or S suffix). `lon` - Longitude (`degrees` or DMS `str` with E or W suffix). `height` - Optional height (`meter` above or below the earth surface). `name` - Optional name (`str`). Returns: New instance (`LatLon`). Raises: `RangeError` - Value of `lat` or `lon` outside the valid range and `rangerrors` set to `True`. `ValueError` - Invalid `lat` or `lon`. Overrides: object.__init__ Example:
    >>> p = LatLon(50.06632, -5.71475)
    >>> q = LatLon('50°03′59″N', """005°42'53"W""")

### __str__(self) (Informal representation operator) |
Default `str(self)`. Overrides: object.__str__ (inherited documentation)

### antipode(self, height=None) |
Return the antipode, the point diametrically opposite to this point. Parameters: `height` - Optional height of the antipode, height of this point otherwise (`meter`). Returns: The antipodal point (`LatLon`).

### boundsOf(self, wide, high, radius=6371008.77141) |
Return the SE and NW lat-/longitude of a great circle bounding box centered at this location. Parameters: `wide` - Longitudinal box width (`meter`, same units as `radius` or `degrees` if `radius` is `None`). `high` - Latitudinal box height (`meter`, same units as `radius` or `degrees` if `radius` is `None`). `radius` - Mean earth radius (`meter`). Returns: A Bounds2Tuple`(latlonSW, latlonNE)`, the lower-left and upper-right corner (`LatLon`). See Also: https://www.Movable-Type.co.UK/scripts/latlong-db.html

### compassAngleTo(self, other, adjust=True, wrap=False) |
Return the angle from North for the direction vector between this and an other point. Suitable only for short, non-near-polar vectors up to a few hundred Km or Miles. Use method `initialBearingTo` for larger distances. Parameters: `other` - The other point (`LatLon`). `adjust` - Adjust the longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap and unroll180 longitudes and longitudinal delta (`bool`). Returns: Compass angle from North (`degrees360`). Raises: `TypeError` - The `other` point is not `LatLon`. Note: Courtesy Martin Schultz. See Also: Local, flat earth approximation.

### equirectangularTo(self, other, radius=None, **options) |
Compute the distance between this and an other point using the Equirectangular Approximation / Projection. Suitable only for short, non-near-polar distances up to a few hundred Km or Miles. Use method `haversineTo` or `distanceTo*` for more accurate and/or larger distances. See function equirectangular_ for more details, the available `options` and errors raised. Parameters: `other` - The other point (`LatLon`). `radius` - Mean earth radius (`meter`) or `None` for the mean radius of this point's datum ellipsoid. `options` - Optional keyword arguments for function equirectangular. Returns: Distance (`meter`, same units as `radius`). Raises: `TypeError` - The `other` point is not `LatLon`. See Also: Function equirectangular, methods `euclideanTo`, `distanceTo*`, `haversineTo` and `vincentysTo`.

### euclideanTo(self, other, radius=None, **options) |
Approximate the `Euclidian` distance between this and an other point. See function euclidean for the available `options`. Parameters: `other` - The other point (`LatLon`). `radius` - Mean earth radius (`meter`) or `None` for the mean radius of this point's datum ellipsoid. `options` - Optional keyword arguments for function euclidean. Returns: Distance (`meter`, same units as `radius`). Raises: `TypeError` - The `other` point is not `LatLon`. See Also: Function euclidean, methods `equirectangularTo`, `distanceTo*`, `haversineTo` and `vincentysTo`.

### haversineTo(self, other, radius=None, wrap=False) |
Compute the distance between this and an other point using the Haversine formula. Parameters: `other` - The other point (`LatLon`). `radius` - Mean earth radius (`meter`) or `None` for the mean radius of this point's datum ellipsoid. `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Distance (`meter`, same units as `radius`). Raises: `TypeError` - The `other` point is not `LatLon`. See Also: Function haversine, methods `equirectangularTo`, `euclideanTo`, `distanceTo*` and `vincentysTo`.

### isantipodeTo(self, other, eps=2.22044604925e-16) |
Check whether this and an other point are antipodal, on diametrically opposite sides of the earth. Parameters: `other` - The other point (`LatLon`). `eps` - Tolerance for near-equality (`degrees`). Returns: `True` if points are antipodal within the given tolerance, `False` otherwise.

### isequalTo(self, other, eps=None) |
Compare this point with an other point. Parameters: `other` - The other point (`LatLon`). `eps` - Tolerance for equality (`degrees`). Returns: `True` if both points are identical, ignoring height, `False` otherwise. Raises: `TypeError` - The `other` point is not `LatLon`. See Also: Method isequalTo3. Example:
    >>> p = LatLon(52.205, 0.119)
    >>> q = LatLon(52.205, 0.119)
    >>> e = p.isequalTo(q)  # True

### isequalTo3(self, other, eps=None) |
Compare this point with an other point. Parameters: `other` - The other point (`LatLon`). `eps` - Tolerance for equality (`degrees`). Returns: `True` if both points are identical including height, `False` otherwise. Raises: `TypeError` - The `other` point is not `LatLon`. See Also: Method isequalTo. Example:
    >>> p = LatLon(52.205, 0.119, 42)
    >>> q = LatLon(52.205, 0.119)
    >>> e = p.isequalTo3(q)  # False

### latlon2(self, ndigits=0) |
Return this point's lat- and longitude in `degrees`, rounded. Parameters: `ndigits` - Number of decimal digits (`int`). Returns: A LatLon2Tuple`(lat, lon)`, both `float` and rounded away from zero. Note: The `round`ed values are always `float`, also if `ndigits` is omitted.

### philam2(self, ndigits=0) |
Return this point's lat- and longitude in `radians`, rounded. Parameters: `ndigits` - Number of decimal digits (`int`). Returns: A PhiLam2Tuple`(phi, lam)`, both `float` and rounded away from zero. Note: The `round`ed values are always `float`, also if `ndigits` is omitted.

### points2(self, points, closed=True) |
Check a path or polygon represented by points. Parameters: `points` - The path or polygon points (`LatLon`[]) `closed` - Optionally, consider the polygon closed, ignoring any duplicate or closing final `points` (`bool`). Returns: A Points2Tuple`(number, points)`, `int` and `list` or `tuple`. Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`.

### to2ab(self) |
DEPRECATED, use property `philam`. Returns: A PhiLam2Tuple`(phi, lam)`.

### to3llh(self, height=None) |
DEPRECATED, use property `latlonheight` or `latlon.to3Tuple(height)`. Returns: A LatLon3Tuple`(lat, lon, height)`.

### to3xyz(self) |
DEPRECATED, use method `toNvector`, `toVector`, `toVector3d` or property `xyz` or perhaps (geocentric) `toEcef`. Returns: A Vector3Tuple`(x, y, z)`, see property `xyz`.

### toCartesian(self, Cartesian=None, **kwds) |
Convert this point to cartesian (ECEF) coordinates. Parameters: `Cartesian` - Optional (sub-)class to return the geocentric coordinates (`Cartesian`) or `None`. `kwds` - Optional, additional `Cartesian` keyword arguments, ignored if `Cartesian=None`. Returns: A `Cartesian` or if `Cartesian=None`, an Ecef9Tuple`(x, y, z, lat, lon, height, C, M, datum)` with `C` 0 and `M` if available. Raises: `TypeError` - Invalid `Cartesian` or `kwds`.

### toEcef(self) |
Convert this point to geocentric coordinates, also known as Earth-Centered, Earth-Fixed (ECEF). Returns: An Ecef9Tuple`(x, y, z, lat, lon, height, C, M, datum)` with `C` 0 and `M` if available. Raises: `EcefError` - A `.datum` or an ECEF issue.

### toNvector(self, h=None, Nvector=None, **kwds) |
Convert this point to `n-vector` (normal to the earth's surface) components, including height. Parameters: `h` - Optional height, overriding this point's height (`meter`). `Nvector` - Optional (sub-)class to return the `n-vector` components (`Nvector`) or `None`. `kwds` - Optional, additional `Nvector` keyword arguments, ignored if `Nvector=None`. Returns: A `Nvector` or an Vector4Tuple`(x, y, z, h)` if `Nvector=None`. Raises: `TypeError` - Invalid `Nvector` or `kwds`.

### toStr(self, form=`'``dms``'`, prec=None, m=`'``m``'`, sep=`'``,` `'`) |
Convert this point to a "lat, lon [+/-height]" string, formatted in the given form. Parameters: `form` - Optional format, F_D, F_DM, F_DMS for deg°, deg°min′, deg°min′sec″ (`str`). `prec` - Optional number of decimal digits (0..8 or `None`). `m` - Optional unit of the height (`str`), use `None` to exclude height from the returned string. `sep` - Optional separator to join (`str`). Returns: Point in the specified form (`str`). Raises: `AssertionError` - Always, see function notOverloaded. Overrides: named._Named.toStr Example:
    >>> LatLon(51.4778, -0.0016).toStr()  # 51°28′40″N, 000°00′06″W
    >>> LatLon(51.4778, -0.0016).toStr(F_D)  # 51.4778°N, 000.0016°W
    >>> LatLon(51.4778, -0.0016, 42).toStr()  # 51°28′40″N, 000°00′06″W, +42.00m

### toVector(self, Vector=None, **kwds) |
Convert this point to `n-vector` (normal to the earth's surface) components, ignoring height. Parameters: `Vector` - Optional (sub-)class to return the `n-vector` components (Vector3d) or `None`. `kwds` - Optional, additional `Vector` keyword arguments, ignored if `Vector=None`. Returns: A `Vector` or an Vector3Tuple`(x, y, z)` if `Vector=None`. Raises: `TypeError` - Invalid `Vector` or `kwds`. Note: These are `n-vector` x, y and z components, NOT (geocentric) ECEF x, y and z coordinates!

### toVector3d(self) |
Convert this point to `n-vector` (normal to the earth's surface) components, ignoring height. Returns: Unit vector (Vector3d). Note: These are `n-vector` x, y and z components, NOT (geocentric) ECEF x, y and z coordinates!

### vincentysTo(self, other, radius=None, wrap=False) |
Compute the distance between this and an other point using Vincenty's spherical formula. Parameters: `other` - The other point (`LatLon`). `radius` - Mean earth radius (`meter`) or `None` for the mean radius of this point's datum ellipsoid. `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Distance (`meter`, same units as `radius`). Raises: `TypeError` - The `other` point is not `LatLon`. See Also: Function vincentys, methods `equirectangularTo`, `euclideanTo`, `distanceTo*` and `haversineTo`.

Property Details

### Ecef An immutable property (`Read Only`). Get Method: Ecef(self) - Get the ECEF `class` (EcefKarney or EcefVeness). Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### datum An immutable property (`Read Only`). Get Method: datum(self) - (INTERNAL) Must be overloaded. Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### height Property to get and set the height (`meter`). Get Method: height(self) - Get the height (`meter`). Set Method: height(self, height) - Set the height.

### isEllipsoidal An immutable property (`Read Only`). Get Method: isEllipsoidal(self) - Check whether this point is ellipsoidal (`bool` or `None` if unknown). Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### isSpherical An immutable property (`Read Only`). Get Method: isSpherical(self) - Check whether this point is spherical (`bool` or `None` if unknown). Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### lam An immutable property (`Read Only`). Get Method: lam(self) - Get the longitude (`radians`). Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### lat Property to get and set the latitude (`degrees90`). Get Method: lat(self) - Get the latitude (`degrees90`). Set Method: lat(self, lat) - Set the latitude.

### latlon Property to get and set the lat- and longitude, optionally height. Get Method: latlon(self) - Get the lat- and longitude (LatLon2Tuple`(lat, lon)`). Set Method: latlon(self, latlonh) - Set the lat- and longitude and optionally the height.

### latlonheight An immutable property (`Read Only`). Get Method: latlonheight(self) - Get the lat-, longitude and height (LatLon3Tuple`(lat, lon, height)`). Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### lon Property to get and set the longitude (`degrees180`). Get Method: lon(self) - Get the longitude (`degrees180`). Set Method: lon(self, lon) - Set the longitude.

### phi An immutable property (`Read Only`). Get Method: phi(self) - Get the latitude (`radians`). Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### philam An immutable property (`Read Only`). Get Method: philam(self) - Get the lat- and longitude (PhiLam2Tuple`(phi, lam)`). Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### philamheight An immutable property (`Read Only`). Get Method: philamheight(self) - Get the lat-, longitude in `radians` and height (PhiLam3Tuple`(phi, lam, height)`). Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### xyz An immutable property (`Read Only`). Get Method: xyz(self) - Get the `n-vector` X, Y and Z components (Vector3Tuple`(x, y, z)`) Set Method: immutable(inst, value) - Throws an `AttributeError`, always.

### xyzh An immutable property (`Read Only`). Get Method: xyzh(self) - Get the `n-vector` X, Y, Z and H components (Vector4Tuple`(x, y, z, h)`) Set Method: immutable(inst, value) - Throws an `AttributeError`, always.