Reference Ellipsoid (pygeoid.coordinates.ellipsoid.Ellipsoid)

Geometry of the reference ellipsoid.

class pygeoid.coordinates.ellipsoid.Ellipsoid(ellps: Optional[str] = None, **kwargs)

Class represents an ellipsoid of revolution and its geometry.

This class uses proj.Geod class from pyproj package, so any valid init string for Proj are accepted as arguments. See pyproj.Geod.__new__ documentation (https://pyproj4.github.io/pyproj/stable/api/geod.html) for more information.

Parameters:ellps (str, optional) – Ellipsoid name, most common ellipsoids are accepted. Default is ‘GRS80’.

equatorial_radius

Return semi-major or equatorial axis radius, in metres.

polar_radius

Return semi-minor or polar axis radius, in metres.

flattening

Return flattening of the ellipsoid.

Notes

The flattening of the ellipsoid \(f\) is

\[f = \frac{a - b}{a},\]

where \(a\) and \(b\) – equatorial and polar axis of the ellipsoid respectively.

reciprocal_flattening

Return reciprocal (inverse) flattening.

eccentricity

Return first eccentricity.

Notes

The first eccentricity of the ellipsoid \(e\) is

\[e = \sqrt{\frac{a^2 - b^2}{a^2}},\]

where \(a\) and \(b\) – equatorial and polar axis of the ellipsoid respectively.

eccentricity_squared

Return first eccentricity squared.

second_eccentricity

Return second eccentricity.

Notes

The second eccentricity of the ellipsoid \(e'\) is

\[e' = \sqrt{\frac{a^2 - b^2}{b^2}}\]

where \(a\) and \(b\) – equatorial and polar axis of the ellipsoid respectively.

second_eccentricity_squared

Return second eccentricity squared.

linear_eccentricity

Return linear eccentricity, in metres.

Notes

The linear eccentricity of the ellipsoid \(E\) is

\[E = ae,\]

where \(a\) – equatorial radius of the ellipsoid, \(e\) – (first) eccentricity.

polar_curvature_radius

Return polar radius of curvature, in metres.

Notes

The polar radius of curvature of the ellipsoid \(c\) is

\[c = \frac{a^2}{b},\]

where \(a\) and \(b\) – equatorial and polar axis of the ellipsoid respectively.

quadrant_distance

Return arc of meridian from equator to pole, in metres.

Notes

The arc length of meridian from equator to pole is

\[Q = c\frac{\pi}{2}\left( 1 - \frac{3}{4}e'^2 + \frac{45}{64}e'^4 + \frac{175}{256}e'^6 + \frac{11025}{16384}e'^8\right),\]

where \(c\) – polar radius of curvature, \(e'\) – second eccentricity.

surface_area

Return surface area of the ellipsoid, in squared metres.

Notes

The surface area of the ellipsoid is

\[A = 2\pi a^2 \left[1 + \frac{1 - e^2}{2e} \ln{\left( \frac{1 + e}{1 - e}\right)}\right],\]

where \(a\) – equatorial axis of the ellipsoid, \(e\) – (first) eccentricity.

volume

Return volume of the ellipsoid, in cubical metres.

Notes

The volume of the ellipsoid is

\[V = \frac{4}{3}\pi a^2 b,\]

where \(a\) and \(b\) – equatorial and polar axis of the ellipsoid respectively.

mean_radius(kind: str = 'arithmetic')

Return the radius of a sphere.

Parameters:kind ({'arithmetic', 'same_area', 'same_volume'}, optional) –

Controls what kind of radius is returned.

• ’arithmetic’ returns the arithmetic mean value

  \(R_m\) of the 3 semi-axis of the ellipsoid.

• ’same_area’ returns the authalic radius \(R_A\) of

  the sphere with the same surface area as the ellipsoid.

• ’same_volume’ returns the radius \(R_V\) of

  the sphere with the same volume as the ellipsoid.

Default is ‘arithmetic’.

Returns:Mean radius of the ellipsoid, in metres. Return type:float

Notes

The arithmetic mean radius of the ellipsoid is

\[R_m = \frac{2a + b}{2},\]

where \(a\) and \(b\) are equatorial and polar axis of the ellipsoid respectively.

A sphere with the same surface area as the elliposid has the radius

\[R_A = \sqrt{\frac{A}{4\pi}},\]

where \(A\) is the surface area of the ellipsoid.

A sphere with the same volume as the ellipsoid has the radius

\[R_V = a^2 b.\]

meridian_curvature_radius(lat: Unit("deg")) -> Unit("m")

Return radius of curvature of meridian normal section.

Parameters:lat (Quantity) – Geodetic latitude. Returns:Value of the radius of curvature of meridian normal section. Return type:Quantity

Notes

The radius of curvature of meridian normal section \(M\) is

\[M = \frac{c}{V^3},\]

where \(c\) – polar radius of curvature, \(V\) – auxiliary function which depends on geodetic latitude.

prime_vertical_curvature_radius(lat: Unit("deg")) -> Unit("m")

Return radius of curvature of prime vertical normal section.

Parameters:lat (Quantity) – Geodetic latitude. Returns:Value of the radius of curvature of prime vertical normal section. Return type:Quantity

Notes

The radius of curvature of prime vertical \(N\) is

\[N = \frac{c}{V},\]

where \(c\) – polar radius of curvature, \(V\) – auxiliary function which depends on geodetic latitude.

mean_curvature(lat: Unit("deg")) → <Quantity 1. 1 / m>

Return mean curvature, in inverse metres.

Parameters:lat (Quantity) – Geodetic latitude. Returns:Value of the mean curvature. Return type:Quantity

Notes

The mean curvature is \(1/\sqrt{MN}\), where \(M\) – radius of curvature of meridian normal section, \(N\) – radius of curvature of prime vertical.

gaussian_curvature(lat: Unit("deg")) → <Quantity 1. 1 / m>

Return Gaussian curvature, in inverse metres.

Parameters:lat (Quantity) – Geodetic latitude. Returns:Value of the Gaussian radius of curvature. Return type:Quantity

Notes

The Gaussian curvature is \(1/MN\), where \(M\) – radius of curvature of meridian normal section, \(N\) – radius of curvature of prime vertical.

average_curvature(lat: Unit("deg")) → <Quantity 1. 1 / m>

Return average curvature, in inverse metres.

Parameters:lat (Quantity) – Geodetic latitude. Returns:Value of the average curvature. Return type:Quantity

Notes

The average curvature is

\[\frac{1}{2} \left( \frac{1}{M} + \frac{1}{N} \right),\]

where \(M\) – radius of curvature of meridian normal section, \(N\) – radius of curvature of prime vertical.

meridian_arc_distance(lat1: Unit("deg"), lat2: Unit("deg")) -> Unit("m")

Return the distance between two parallels lat1 and lat2.

Parameters:

• lat1 (Quantity) – Geodetic latitude of the first point.
• lat2 (Quantity) – Geodetic latitude of the second point.

Returns:

The distance between two parallels.

Return type:

Quantity

parallel_arc_distance(lat: Unit("deg"), lon1: Unit("deg"), lon2: Unit("deg"))

Return the distance between two points on a parallel.

Parameters:

• lat (Quantity) – Geodetic latitude of the parallel.
• lon1 (Quantity) – Geodetic longitude of the first point.
• lon2 (Quantity) – Geodetic longitude of the second point.

Returns:

The distance between two meridians along the parallel.

Return type:

Quantity

fwd(lat: Unit("deg"), lon: Unit("deg"), azimuth: Unit("deg"), distance: Unit("m"))

Solve forward geodetic problem.

Returns latitudes, longitudes and back azimuths of terminus points given latitudes lat and longitudes lon of initial points, plus forward `azimuth`s and `distance`s.

This method use pyproj.Geod.fwd as a backend.

Parameters:

• lat (Quantity) – Geodetic latitude of the initial point.
• lon (Quantity) – Longitude of the initial point.
• azimuth (Quantity) – Geodetic azimuth.
• distance (Quantity) – Distance.

Returns:

• lat (~astropy.units.Quantity) – Geodetic latitude of the terminus point.
• lon (~astropy.units.Quantity) – Longitude of the terminus point.
• back_azimuth (~astropy.units.Quantity) – Back geodetic azimuth.

inv(lat1: Unit("deg"), lon1: Unit("deg"), lat2: Unit("deg"), lon2: Unit("deg"))

Solve inverse geodetic problem.

Returns forward and back azimuths, plus distances between initial points (specified by lat1, lon1) and terminus points (specified by lat1, lon2).

This method use pyproj.Geod.inv as a backend.

Parameters:

• lat1 (Quantity) – Geodetic latitude of the initial point.
• lon1 (Quantity) – Longitude of the initial point.
• lat2 (Quantity) – Geodetic latitude of the terminus point.
• lon2 (Quantity) – Longitude of the terminus point.

Returns:

• azimuth (~astropy.units.Quantity) – Geodetic azimuth.
• back_azimuth (~astropy.units.Quantity) – Back geodetic azimuth.
• distance (~astropy.units.Quantity) – Distance, in metres.

npts(lat1: Unit("deg"), lon1: Unit("deg"), lat2: Unit("deg"), lon2: Unit("deg"), npts: int) -> Unit("deg")

Return equaly spaced points along geodesic line.

Given a single initial point and terminus point (specified by lat1, lon1 and lat2, lon2), returns a list of longitude/latitude pairs describing npts equally spaced intermediate points along the geodesic between the initial and terminus points.

This method use pyproj.Geod.npts as a backend.

Parameters:

• lat1 (Quantity) – Geodetic latitude of the initial point.
• lon1 (Quantity) – Longitude of the initial point.
• lat2 (Quantity) – Geodetic latitude of the terminus point.
• lon2 (Quantity) – Longitude of the terminus point.
• npts (int) – Number of intermediate points.

Returns:

points – List of latitudes and longitudes of the intermediate points.

Return type:

Quantity list of tuples

circle_radius(lat: Unit("deg")) -> Unit("m")

Return the radius of the parallel, in metres.

Parameters:lat (Quantity) – Geodetic latitude.

Notes

The radius of the parallel \(\phi\) is

\[r_\phi = N \cos{\phi},\]

where \(N\) – radius of curvature of prime vertical, \(\phi\) – geodetic latitude.

polar_equation(lat: Unit("deg")) -> Unit("m")

Return radius of the ellipsoid with respect to the origin.

Parameters:lat (Quantity) – Geocentric latitude. Returns:Geocentric radius of the parallel. Return type:Quantity

Notes

The polar equation of the ellipsoid is

\[r = \frac{ab}{\sqrt{a^2\sin^2{\vartheta} + b^2\cos^2{\vartheta}}},\]

where \(a\) and \(b\) – equatorial and polar axis of the ellipsoid respectively, \(\vartheta\) – geocentric latitude.

geocentric_latitude(lat: Unit("deg")) -> Unit("deg")

Convert geodetic latitude to geocentric latitude.

Parameters:lat (Quantity) – Geodetic latitude. Returns:Geocentric (spherical) latitude. Return type:Quantity

Notes

The relationship between geodetic \(\phi\) and geocentric \(\vartheta\) latitudes is

\[\vartheta = \tan^{-1}{\left(\left(1 - f\right)^2\tan\phi\right)},\]

where \(f\) – flattening of the ellipsoid.

reduced_latitude(lat: Unit("deg")) -> Unit("deg")

Convert geodetic latitude to reduced (parametric) latitude.

Parameters:lat (Quantity) – Geodetic latitude. Returns:Reduced latitude. Return type:Quantity

Notes

The relationship between geodetic \(\phi\) and reduced \(\beta\) latitudes is

\[\beta = \tan^{-1}{\left(\left(1 - f\right)\tan\phi\right)},\]

where \(f\) – flattening of the ellipsoid.

authalic_latitude(lat: Unit("deg")) -> Unit("deg")

Convert geodetic latitude to authalic latitude.

Authalic latitude will return a geocentric latitude on a sphere having the same surface area as the ellipsoid. It will preserve areas with relative to the ellipsoid. The authalic radius can be calculated from mean_radius(kind=’same_area’) method.

Parameters:lat (Quantity) – Geodetic latitude. Returns:Authalic latitude. Return type:Quantity