Package pygeodesy :: Module ellipsoidalBase :: Class LatLonEllipsoidalBase |
[frames] | no frames]

# Class LatLonEllipsoidalBase

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

Known Subclasses:
  - ellipsoidalBaseDI.LatLonEllipsoidalBaseDI
  - , ellipsoidalNvector.LatLon

(INTERNAL) Base class for ellipsoidal `LatLon`s.

Instance Methods
__init__(self, lat, lon, height=0, datum=None, reframe=None, epoch=None, name='') Create an ellipsoidal `LatLon` point frome the given lat-, longitude and height on the given datum and with the given reference frame and epoch. |
antipode(self, height=None) Return the antipode, the point diametrically opposite to this point. |
convertDatum(self, datum2) DEPRECATED, use method toDatum. |
convertRefFrame(self, reframe2) DEPRECATED, use method toRefFrame. |
distanceTo2(self, other) Approximate the distance and (initial) bearing between this and an other (ellipsoidal) point based on the radii of curvature. |
elevation2(self, adjust=True, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, timeout=2) Return elevation of this point for its or the given datum. |
ellipsoid(self, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) Return the ellipsoid of this point's datum or the given datum. |
ellipsoids(self, other) Check the type and ellipsoid of this and an other point's datum. |
geoidHeight2(self, adjust=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, timeout=2) Return geoid height of this point for its or the given datum. |
intersection3(self, end1, other, end2, height=None, wrap=True, equidistant=None, tol=0.001) Interatively compute the intersection point of two paths, each defined by a start and end point. |
intersections2(self, radius1, other, radius2, height=None, wrap=True, equidistant=None, tol=0.001) Interatively compute the intersection points of two circles, each defined by a center point and a radius. |
nearestOn(self, point1, point2, within=True, height=None, wrap=True, equidistant=None, tol=0.001) Interatively locate the closest point between two other points. |
parse(self, strllh, height=0, datum=None, epoch=None, reframe=None, sep=',', name='') Parse a string representing a similar, ellipsoidal `LatLon` point, consisting of `"lat, lon[, height]"`. |
to3xyz(self) DEPRECATED, use method `toEcef`. |
toDatum(self, datum2, height=None, name='') Convert this point to an other datum. |
toEtm(self) Convert this `LatLon` point to an ETM coordinate. |
toLcc(self) Convert this `LatLon` point to a Lambert location. |
toMgrs(self, center=False) Convert this `LatLon` point to an MGRS coordinate. |
toOsgr(self) Convert this `LatLon` point to an OSGR coordinate. |
toRefFrame(self, reframe2, height=None, name='') Convert this point to an other reference frame. |
toUps(self, pole=`'``N``'`, falsed=True) Convert this `LatLon` point to a UPS coordinate. |
toUtm(self, center=False) Convert this `LatLon` point to a UTM coordinate. |
toUtmUps(self, pole='') Convert this `LatLon` point to a UTM or UPS coordinate. |
toWm(self) Convert this `LatLon` point to a WM coordinate. |
trilaterate5(self, distance1, point2, distance2, point3, distance3, area=True, eps=1.0, wrap=False) Trilaterate three points by area overlap or perimeter intersection of three intersecting circles. |
Inherited from `latlonBase.LatLonBase`: `PointsIter`, `__eq__`, `__ne__`, `__str__`, `_distanceTo_`, `bounds`, `boundsOf`, `chordTo`, `compassAngle`, `compassAngleTo`, `cosineAndoyerLambertTo`, `cosineForsytheAndoyerLambertTo`, `cosineLawTo`, `destinationXyz`, `equals`, `equals3`, `equirectangularTo`, `euclideanTo`, `flatLocalTo`, `flatPolarTo`, `haversineTo`, `heightStr`, `hubenyTo`, `isantipode`, `isantipodeTo`, `isequalTo`, `isequalTo3`, `latlon2`, `latlon2round`, `latlon_`, `philam2`, `points`, `points2`, `thomasTo`, `to2ab`, `to3llh`, `toCartesian`, `toEcef`, `toLocal`, `toLtp`, `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
| Equidistant Get the prefered azimuthal equidistant projection class (EquidistantKarney or EquidistantExact).
| convergence Get this point's UTM or UPS meridian convergence (`degrees`) or `None` if not available or not converted from Utm or Ups.
| datum Property to get and set this points's datum (Datum).
| epoch Property to get and set this point's observed or `reframe` epoch (`float`).
| iteration Get the most recent `intersections2` or `nearestOn` iteration number (`int`) or `None` if not available/applicable.
| reframe Property to get and set this point's reference frame (RefFrame).
| scale Get this point's UTM grid or UPS point scale factor (`float`) or `None` if not converted from Utm or Ups.
Inherited from `latlonBase.LatLonBase`: `Ecef`, `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

### __init__ (self, lat, lon, height=0, datum=None, reframe=None, epoch=None, name='') (Constructor) |
Create an ellipsoidal `LatLon` point frome the given lat-, longitude and height on the given datum and with the given reference frame and epoch. Arguments: `lat` - Latitude (`degrees` or DMS `[N|S]`). `lon` - Longitude (`degrees` or DMS `str[E|W]`). `height` - Optional elevation (`meter`, the same units as the datum's half-axes). `datum` - Optional, ellipsoidal datum to use (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple). `reframe` - Optional reference frame (RefFrame). `epoch` - Optional epoch to observe for `reframe` (`scalar`), a non-zero, fractional calendar year; silently ignored if `reframe=None`. `name` - Optional name (string). Returns: New instance (`LatLon`). Raises: `RangeError` - Value of `lat` or `lon` outside the valid range and `rangerrors` set to `True`. `TypeError` - `datum` is not a datum, `reframe` is not a RefFrame or `epoch` is not `scalar` non-zero. `UnitError` - Invalid `lat`, `lon` or `height`. Overrides: object.__init__ Example:
    >>> p = LatLon(51.4778, -0.0016)  # height=0, datum=Datums.WGS84

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

### convertDatum (self, datum2) |
DEPRECATED, use method toDatum. Decorators: `@deprecated_method`

### convertRefFrame (self, reframe2) |
DEPRECATED, use method toRefFrame. Decorators: `@deprecated_method`

### distanceTo2 (self, other) |
Approximate the distance and (initial) bearing between this and an other (ellipsoidal) point based on the radii of curvature. Suitable only for short distances up to a few hundred Km or Miles and only between points not near-polar. Arguments: `other` - The other point (`LatLon`). Returns: An Distance2Tuple`(distance, initial)`. Raises: `TypeError` - The `other` point is not `LatLon`. `ValueError` - Incompatible datum ellipsoids. See Also: Method Ellipsoid.distance2 and Local, flat earth approximation aka Hubeny formula.

### elevation2 (self, adjust=True, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, timeout=2) |
Return elevation of this point for its or the given datum. Arguments: `adjust` - Adjust the elevation for a `datum` other than `NAD83` (`bool`). `datum` - Optional datum (Datum). `timeout` - Optional query timeout (`seconds`). Returns: An Elevation2Tuple`(elevation, data_source)` or `(None, error)` in case of errors. Notes: The adjustment applied is the difference in geocentric earth radius between the `datum` and `NAV83` upon which the elevations.elevation2 is based. NED elevation is only available for locations within the Conterminous US (CONUS). See Also: Function elevations.elevation2 and method Ellipsoid.Rgeocentric for further details and possible `error`s.

### ellipsoid (self, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) |
Return the ellipsoid of this point's datum or the given datum. Arguments: `datum` - Default datum (Datum). Returns: The ellipsoid (Ellipsoid or Ellipsoid2).

### ellipsoids (self, other) |
Check the type and ellipsoid of this and an other point's datum. Arguments: `other` - The other point (`LatLon`). Returns: This point's datum ellipsoid (Ellipsoid or Ellipsoid2). Raises: `TypeError` - The `other` point is not `LatLon`. `ValueError` - Incompatible datum ellipsoids.

### geoidHeight2 (self, adjust=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, timeout=2) |
Return geoid height of this point for its or the given datum. Arguments: `adjust` - Adjust the geoid height for a `datum` other than `NAD83/NADV88` (`bool`). `datum` - Optional datum (Datum). `timeout` - Optional query timeout (`seconds`). Returns: A GeoidHeight2Tuple`(height, model_name)` or `(None, error)` in case of errors. Notes: The adjustment applied is the difference in geocentric earth radius between the `datum` and `NAV83/NADV88` upon which the elevations.geoidHeight2 is based. The geoid height is only available for locations within the Conterminous US (CONUS). See Also: Function elevations.geoidHeight2 and method Ellipsoid.Rgeocentric for further details and possible `error`s.

### intersection3 (self, end1, other, end2, height=None, wrap=True, equidistant=None, tol=0.001) |
Interatively compute the intersection point of two paths, each defined by a start and end point. Arguments: `end1` - End point of this path (`LatLon`). `other` - Start point of the other path (`LatLon`). `end2` - End point of the other path (`LatLon`). `height` - Optional height at the intersection (`meter`, conventionally) or `None` for the mean height. `wrap` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection (class or function equidistant), or `None` for this point's preferred `.Equidistant`. `tol` - Tolerance for skew line distance and length and for convergence (`meter`, conventionally). Returns: An Intersection3Tuple`(point, outside1, outside2)` with `point` a `LatLon` instance. Raises: `ImportError` - Package geographiclib not installed or not found, but only if `equidistant=`EquidistantKarney. `IntersectionError` - Skew, colinear, parallel or otherwise non-intersecting paths or no convergence for the `tol`. `TypeError` - If `end1`, `other` or `end2` point is not `LatLon`.

### intersections2 (self, radius1, other, radius2, height=None, wrap=True, equidistant=None, tol=0.001) |
Interatively compute the intersection points of two circles, each defined by a center point and a radius. Arguments: `radius1` - Radius of this circle (`meter`, conventionally). `other` - Center of the other circle (`LatLon`). `radius2` - Radius of the other circle (`meter`, same units as `radius1`). `height` - Optional height for the intersection points (`meter`, conventionally) or `None` for the "radical height" at the radical line between both centers. `wrap` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection (class or function equidistant), or `None` for this point's preferred `.Equidistant`. `tol` - Convergence tolerance (`meter`, same units as `radius1` and `radius2`). Returns: 2-Tuple of the intersection points, each a `LatLon` instance. For abutting circles, both intersection points are the same instance. Raises: `ImportError` - Package geographiclib not installed or not found, but only if `equidistant=`EquidistantKarney. `IntersectionError` - Concentric, antipodal, invalid or non-intersecting circles or no convergence for `tol`. `TypeError` - Invalid `other` or `equidistant`. `UnitError` - Invalid `radius1`, `radius2` or `height`. See Also: The ellipsoidal case, Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES, circle-circle and sphere-sphere intersections.

### nearestOn (self, point1, point2, within=True, height=None, wrap=True, equidistant=None, tol=0.001) |
Interatively locate the closest point between two other points. Arguments: `point1` - Start point (`LatLon`). `point2` - End point (`LatLon`). `within` - If `True` return the closest point between `point1` and `point2`, otherwise the closest point elsewhere on the arc (`bool`). `height` - Optional height for the closest point (`meter`, conventionally) or `None` or `False` to interpolate the height. `height` - Optional height for the closest point (`meter`, conventionally) or `None` or `False` for the interpolated height. If `False`, the distance between points takes height into account. `wrap` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection (class or function equidistant), or `None` for this point's preferred `.Equidistant`. `tol` - Convergence tolerance (`meter`, conventionally). Returns: Closest point (`LatLon`). Raises: `ImportError` - Package geographiclib not installed or not found, but only if `equidistant=`EquidistantKarney. `TypeError` - Invalid `point1`, `point2` or `equidistant`. `ValueError` - No convergence for the `tol`.

### parse (self, strllh, height=0, datum=None, epoch=None, reframe=None, sep=',', name='') |
Parse a string representing a similar, ellipsoidal `LatLon` point, consisting of `"lat, lon[, height]"`. Arguments: `strllh` - Lat, lon and optional height (`str`), see function parse3llh. `height` - Optional, default height (`meter` or `None`). `datum` - Optional datum (Datum), overriding this datum without conversion. `epoch` - Optional datum (Epoch), overriding this epoch without conversion. `reframe` - Optional datum (RefFrame), overriding this reframe without conversion. `sep` - Optional separator (`str`). `name` - Optional instance name (`str`), overriding this name. Returns: The similar point (ellipsoidal `LatLon`). Raises: `ParseError` - Invalid `strllh`.

### to3xyz (self) |
DEPRECATED, use method `toEcef`. Returns: A Vector3Tuple`(x, y, z)`. Decorators: `@deprecated_method` Overrides: latlonBase.LatLonBase.to3xyz Note: Overloads `LatLonBase.to3xyz`

### toDatum (self, datum2, height=None, name='') |
Convert this point to an other datum. Arguments: `datum2` - Datum to convert to (Datum). `height` - Optional height, overriding the converted height (`meter`). `name` - Optional name (`str`), iff converted. Returns: The converted point (ellipsoidal `LatLon`) or a copy of this point if `datum2` matches this point's `datum`. Raises: `TypeError` - Invalid `datum2`. Example:
    >>> p = LatLon(51.4778, -0.0016)  # default Datums.WGS84
    >>> p.toDatum(Datums.OSGB36)  # 51.477284°N, 000.00002°E

### toEtm (self) |
Convert this `LatLon` point to an ETM coordinate. Returns: The ETM coordinate (Etm). See Also: Function toEtm8.

### toLcc (self) |
Convert this `LatLon` point to a Lambert location. Returns: The Lambert location (Lcc). See Also: Function toLcc in module lcc.

### toMgrs (self, center=False) |
Convert this `LatLon` point to an MGRS coordinate. Arguments: `center` - If `True`, try to un-center MGRS to its `lowerleft` (`bool`) or by `center meter` (`scalar`). Returns: The MGRS coordinate (Mgrs). See Also: Method Mgrs.toLatLon and toUtm.

### toOsgr (self) |
Convert this `LatLon` point to an OSGR coordinate. Returns: The OSGR coordinate (Osgr). See Also: Function toOsgr in module osgr.

### toRefFrame (self, reframe2, height=None, name='') |
Convert this point to an other reference frame. Arguments: `reframe2` - Reference frame to convert to (RefFrame). `height` - Optional height, overriding the converted height (`meter`). `name` - Optional name (`str`), iff converted. Returns: The converted point (ellipsoidal `LatLon`) or this point if conversion is `nil`, or a copy of this point if the `name` is non-empty. Raises: `TRFError` - This point's `reframe` is not defined or conversion from this point's `reframe` to `reframe2` is not available. `TypeError` - Invalid `reframe2`, not a RefFrame. Example:
    >>> p = LatLon(51.4778, -0.0016, reframe=RefFrames.ETRF2000)  # default Datums.WGS84
    >>> p.toRefFrame(RefFrames.ITRF2014)  # 51.477803°N, 000.001597°W, +0.01m
    >>> p.toRefFrame(RefFrames.ITRF2014, height=0)  # 51.477803°N, 000.001597°W

### toUps (self, pole=`'``N``'`, falsed=True) |
Convert this `LatLon` point to a UPS coordinate. Arguments: `pole` - Optional top/center of (stereographic) projection (`str`, 'N[orth]' or 'S[outh]'). `falsed` - False easting and northing (`bool`). Returns: The UPS coordinate (Ups). See Also: Function toUps8.

### toUtm (self, center=False) |
Convert this `LatLon` point to a UTM coordinate. Arguments: `center` - If `True`, un-center the UTM to its `lowerleft` (`bool`) or by `center meter` (`scalar`). Returns: The UTM coordinate (Utm). See Also: Method Mgrs.toUtm and function toUtm8.

### toUtmUps (self, pole='') |
Convert this `LatLon` point to a UTM or UPS coordinate. Arguments: `pole` - Optional top/center of UPS (stereographic) projection (`str`, 'N[orth]' or 'S[outh]'). Returns: The UTM or UPS coordinate (Utm or Ups). Raises: `TypeError` - Result in Utm or Ups. See Also: Function toUtmUps.

### toWm (self) |
Convert this `LatLon` point to a WM coordinate. Returns: The WM coordinate (Wm). See Also: Function toWm in module webmercator.

### trilaterate5 (self, distance1, point2, distance2, point3, distance3, area=True, eps=1.0, wrap=False) |
Trilaterate three points by area overlap or perimeter intersection of three intersecting circles. Arguments: `distance1` - Distance to this point (`meter`), same units as `eps`). `point2` - Second center point (`LatLon`). `distance2` - Distance to point2 (`meter`, same units as `eps`). `point3` - Third center point (`LatLon`). `distance3` - Distance to point3 (`meter`, same units as `eps`). `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`, conventionally). `wrap` - Wrap/unroll angular distances (`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 ellipsoidal `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 the `point#` with the smallest `distance#` `min` respectively `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 `points` or invalid `distance1`, `distance2` or `distance3`. Note: Ellipsoidal trilateration invokes methods `LatLon.intersections2` and `LatLon.nearestOn` based on Karney's Python geographiclib if installed, otherwise using the accurate (but slower) `ellipsoidalExact.LatLon` methods.

Property Details

### Equidistant Get the prefered azimuthal equidistant projection class (EquidistantKarney or EquidistantExact). Get method: Equidistant(self) - Get the prefered azimuthal equidistant projection class (EquidistantKarney or EquidistantExact). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### convergence Get this point's UTM or UPS meridian convergence (`degrees`) or `None` if not available or not converted from Utm or Ups. Get method: convergence(self) - Get this point's UTM or UPS meridian convergence (`degrees`) or `None` if not available or not converted from Utm or Ups. Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### datum Property to get and set this points's datum (Datum). Get method: datum(self) - Get this point's datum (Datum). Set method: datum(self, datum) - Set this point's datum without conversion.

### epoch Property to get and set this point's observed or `reframe` epoch (`float`). Get method: epoch(self) - Get this point's observed or `reframe` epoch (`float`) or `None`. Set method: epoch(self, epoch) - Set or clear this point's observed epoch.

### iteration Get the most recent `intersections2` or `nearestOn` iteration number (`int`) or `None` if not available/applicable. Get method: iteration(self) - Get the most recent `intersections2` or `nearestOn` iteration number (`int`) or `None` if not available/applicable. Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### reframe Property to get and set this point's reference frame (RefFrame). Get method: reframe(self) - Get this point's reference frame (RefFrame) or `None`. Set method: reframe(self, reframe) - Set or clear this point's reference frame.

### scale Get this point's UTM grid or UPS point scale factor (`float`) or `None` if not converted from Utm or Ups. Get method: scale(self) - Get this point's UTM grid or UPS point scale factor (`float`) or `None` if not converted from Utm or Ups. Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.