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

Class LatLonEllipsoidalBase

   object --+            
            |            
 named._Named --+        
                |        
 named._NamedBase --+    
                    |    
latlonBase.LatLonBase --+
                        |
                       LatLonEllipsoidalBase
Known Subclasses:

(INTERNAL) Base class for ellipsoidal LatLons.

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=None, timeout=2)
Return elevation of this point for its or the given datum, ellipsoid or sphere.
 
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=None, timeout=2)
Return geoid height of this point for its or the given datum, ellipsoid or sphere.
 
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 two points or a start point and bearing from North.
 
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 on the geodesic between two other (ellipsoidal) 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.
 
toCss(self, **toCss_kwds)
Convert this LatLon point to a Cassini-Soldner location.
 
toDatum(self, datum2, height=None, name='')
Convert this point to an other datum.
 
toEtm(self, **toEtm8_kwds)
Convert this LatLon point to an ETM coordinate.
 
toLcc(self, **toLcc_kwds)
Convert this LatLon point to a Lambert location.
 
toMgrs(self, center=False)
Convert this LatLon point to an MGRS coordinate.
 
toOsgr(self, **toOsgr_kwds)
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, **toWm_kwds)
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__, 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, philam2, points, points2, radii11, thomasTo, to2ab, to3llh, toCartesian, toEcef, toLocal, toLtp, toNvector, toStr, toVector, toVector3d, vincentysTo

Inherited from named._NamedBase: __repr__, others, toRepr

Inherited from named._Named: __imatmul__, __matmul__, __rmatmul__, attrs, classof, copy, dup, 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
(INTERNAL) Class property with retrievable name.
  epoch
(INTERNAL) Class property with retrievable name.
  isEllipsoidalLatLon
Get LatLon base.
  iteration
Get the most recent intersections2 or nearestOn iteration number (int) or None if not available/applicable.
  reframe
(INTERNAL) Class property with retrievable name.
  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 is 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=None, timeout=2)

 

Return elevation of this point for its or the given datum, ellipsoid or sphere.

Arguments:
  • adjust - Adjust the elevation for a datum other than NAD83 (bool).
  • datum - Optional datum overriding this point's datum (Datum, Ellipsoid, Ellipsoid2, a_f2Tuple or scalar radius).
  • 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 errors.

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=None, timeout=2)

 

Return geoid height of this point for its or the given datum, ellipsoid or sphere.

Arguments:
  • adjust - Adjust the geoid height for a datum other than NAD83/NADV88 (bool).
  • datum - Optional datum overriding this point's datum (Datum, Ellipsoid, Ellipsoid2, a_f2Tuple or scalar radius).
  • 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 errors.

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 two points or a start point and bearing from North.

Arguments:
  • end1 - End point of this path (LatLon) or the initial bearing at this point (compass degrees360).
  • other - Start point of the other path (LatLon).
  • end2 - End point of the other path (LatLon) or the initial bearing at the other point (compass degrees360).
  • 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 pygeodesy.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 given tol.
  • TypeError - If end1, other or end2 point is not LatLon.

Note: For each path specified with an initial bearing, a pseudo-end point is computed as the destination along that bearing at about 1.5 times the distance from the start point to an initial gu-/estimate of the intersection point (and between 1/8 and 3/8 of the authalic earth perimeter).

See Also: The ellipsoidal case and Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES for more details about the iteration algorithm.

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 pygeodesy.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, aka radical center.
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 the given 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 on the geodesic between two other (ellipsoidal) 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 geodesic (bool).
  • height - Optional height for the closest point (meter, conventionally) or None or False for the interpolated height. If False, the closest takes the heights of the points into account.
  • wrap - Wrap and unroll longitudes (bool).
  • equidistant - An azimuthal equidistant projection (class or function pygeodesy.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 - Datum or ellipsoid of point1 or point2 is incompatible or no convergence for the given tol.

See Also: The ellipsoidal case and Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES for details about the iteration algorithm.

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 pygeodesy.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:

to3xyz (self)

 

DEPRECATED, use method toEcef.

Returns:
A Vector3Tuple(x, y, z).
Decorators:
  • @deprecated_method
Overrides: latlonBase.LatLonBase.to3xyz

Note: Overloads LatLonBase.to3xyz

toCss (self, **toCss_kwds)

 

Convert this LatLon point to a Cassini-Soldner location.

Arguments:
Returns:
The Cassini-Soldner location (Css).

See Also: Function pygeodesy.toCss.

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, **toEtm8_kwds)

 

Convert this LatLon point to an ETM coordinate.

Arguments:
Returns:
The ETM coordinate (Etm).

See Also: Function pygeodesy.toEtm8.

toLcc (self, **toLcc_kwds)

 

Convert this LatLon point to a Lambert location.

Arguments:
Returns:
The Lambert location (Lcc).

See Also: Function pygeodesy.toLcc.

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 toUtm and Mgrs.toLatLon.

toOsgr (self, **toOsgr_kwds)

 

Convert this LatLon point to an OSGR coordinate.

Arguments:
Returns:
The OSGR coordinate (Osgr).

See Also: Function pygeodesy.toOsgr.

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 pygeodesy.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 pygeodesy.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 pygeodesy.toUtmUps8.

toWm (self, **toWm_kwds)

 

Convert this LatLon point to a WM coordinate.

Arguments:
Returns:
The WM coordinate (Wm).

See Also: Function pygeodesy.toWm.

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 uses 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

(INTERNAL) Class property with retrievable name.

Get method:
datum(self) - Get this point's datum (Datum).
Set method:
datum(self, datum) - Set this point's datum without conversion.

epoch

(INTERNAL) Class property with retrievable name.

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.

isEllipsoidalLatLon

Get LatLon base.

Get method:
isEllipsoidalLatLon(self) - Get LatLon base.
Set method:
_fset_error(inst, val) - Throws an AttributeError, always.
Delete Method:
_fdel(inst) - Zap the cached/memoized property value.

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

(INTERNAL) Class property with retrievable name.

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.