Reference Ellipsoid (pygeoid.coordinates.ellipsoid.Ellipsoid)

Geometry of the reference ellipsoid.

class pygeoid.coordinates.ellipsoid.Ellipsoid(ellps=None, **kwargs)[source]

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’.

property equatorial_radius: Return semi-major or equatorial axis radius, in metres.

property polar_radius: Return semi-minor or polar axis radius, in metres.

property 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.

property reciprocal_flattening: Return reciprocal (inverse) flattening.

property 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.

property eccentricity_squared: Return first eccentricity squared.

property 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.

property second_eccentricity_squared: Return second eccentricity squared.

property 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.

property 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.

property 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.

property 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.

property 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='arithmetic')[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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, lat2)[source]

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, lon1, lon2)[source]

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, lon, azimuth, distance)[source]

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, lon1, lat2, lon2)[source]

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, lon1, lat2, lon2, npts)[source]

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)[source]

Return the radius of the parallel, in metres.

Parameters:: lat (Quantity) – Geodetic latitude.
Return type:: Unit(“m”)

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)[source]

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)[source]

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)[source]

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)[source]

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