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

Class LatLonBase

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

(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.
 
flatLocalTo(self, other, wrap=False)
Compute the distance between this and an other point using the ellipsoidal Earth to plane projection formula.
 
flatPolarTo(self, other, radius=None, wrap=False)
Compute the distance between this and an other point using the polar coordinate flat-Earth formula.
 
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, **Cartesian_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, **Nvector_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, **Vector_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
  datum
  height
Property to get and set the height (meter).
  isEllipsoidal
  isSpherical
  lam
  lat
Property to get and set the latitude (degrees90).
  latlon
Property to get and set the lat- and longitude, optionally height.
  latlonheight
  lon
Property to get and set the longitude (degrees180).
  phi
  philam
  philamheight
  xyz
  xyzh

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.

Arguments:
  • 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.

Arguments:
  • 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.

Arguments:
  • 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).

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.

Arguments:
  • 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.

Arguments:
  • 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 distanceTo*, euclideanTo, flatLocalTo, flatPolarTo, 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.

Arguments:
  • 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 distanceTo*, equirectangularTo, flat_localrTo, flatPolarTo, haversineTo and vincentysTo.

flatLocalTo (self, other, wrap=False)

 

Compute the distance between this and an other point using the ellipsoidal Earth to plane projection formula.

Arguments:
  • other - The other point (LatLon).
  • wrap - Wrap and unroll180 longitudes (bool).
Returns:
Distance (meter, same units as this datum's ellipsoid axes).
Raises:
  • TypeError - The other point is not LatLon.

See Also: Function flatLocal, methods distanceTo*, equirectangularTo, euclideanTo, flatPolarTo, haversineTo, and vincentysTo and local, flat Earth approximation.

flatPolarTo (self, other, radius=None, wrap=False)

 

Compute the distance between this and an other point using the polar coordinate flat-Earth formula.

Arguments:
  • 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 flatPolar, methods distanceTo*, equirectangularTo, euclideanTo, flatLocalTo, haversineTo, and vincentysTo.

haversineTo (self, other, radius=None, wrap=False)

 

Compute the distance between this and an other point using the Haversine formula.

Arguments:
  • 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 distanceTo*, equirectangularTo, euclideanTo, flatLocalTo, flatPolarTo 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.

Arguments:
  • 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.

Arguments:
  • 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.

Arguments:
  • 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.

Arguments:
  • ndigits - Number of decimal digits (int).
Returns:
A LatLon2Tuple(lat, lon), both float and rounded away from zero.

Note: The rounded values are always float, also if ndigits is omitted.

philam2 (self, ndigits=0)

 

Return this point's lat- and longitude in radians, rounded.

Arguments:
  • ndigits - Number of decimal digits (int).
Returns:
A PhiLam2Tuple(phi, lam), both float and rounded away from zero.

Note: The rounded values are always float, also if ndigits is omitted.

points2 (self, points, closed=True)

 

Check a path or polygon represented by points.

Arguments:
  • 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, **Cartesian_kwds)

 

Convert this point to cartesian (ECEF) coordinates.

Arguments:
  • Cartesian - Optional class to return the geocentric coordinates (Cartesian) or None.
  • Cartesian_kwds - Optional, additional Cartesian keyword arguments, ignored if Cartesian=None.
Returns:
A Cartesian or if Cartesian is None, an Ecef9Tuple(x, y, z, lat, lon, height, C, M, datum) with C=0 and M if available.
Raises:
  • TypeError - Invalid Cartesian or Cartesian_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:

toNvector (self, h=None, Nvector=None, **Nvector_kwds)

 

Convert this point to n-vector (normal to the earth's surface) components, including height.

Arguments:
  • h - Optional height, overriding this point's height (meter).
  • Nvector - Optional class to return the n-vector components (Nvector) or None.
  • Nvector_kwds - Optional, additional Nvector keyword arguments, ignored if Nvector=None.
Returns:
A Nvector or an Vector4Tuple(x, y, z, h) if Nvector is None.
Raises:
  • TypeError - Invalid Nvector or Nvector_kwds.

toStr (self, form='dms', prec=None, m='m', sep=', ')

 

Convert this point to a "lat, lon [+/-height]" string, formatted in the given form.

Arguments:
  • 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:
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, **Vector_kwds)

 

Convert this point to n-vector (normal to the earth's surface) components, ignoring height.

Arguments:
  • Vector - Optional class to return the n-vector components (Vector3d) or None.
  • Vector_kwds - Optional, additional Vector keyword arguments, ignored if Vector=None.
Returns:
A Vector or a Vector3Tuple(x, y, z) if Vector is 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.

Arguments:
  • 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 distanceTo*, equirectangularTo, euclideanTo, flatLocalTo, flatPolarTo and haversineTo.


Property Details

Ecef

Get method:
Ecef(self) - Get the ECEF class (EcefKarney or EcefVeness).
Set method:
immutable(inst, value) - Throws an AttributeError, always.

datum

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

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

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

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

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

Get method:
phi(self) - Get the latitude (radians).
Set method:
immutable(inst, value) - Throws an AttributeError, always.

philam

Get method:
philam(self) - Get the lat- and longitude (PhiLam2Tuple(phi, lam)).
Set method:
immutable(inst, value) - Throws an AttributeError, always.

philamheight

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

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

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.