The ellipsoid is defined by four parameters: semimajor axis, flattening,
geocentric gravitational constant, and angular velocity. It spins around
its semiminor axis and has constant gravity potential at its surface. The
internal density structure of the ellipsoid is unspecified but must be such
that the constant potential condition is satisfied.
This class is read-only: Input parameters and attributes cannot be
changed after instantiation.
Units: All input parameters and derived attributes are in SI units.
Parameters:
name (str) – A short name for the ellipsoid, for example "WGS84".
semimajor_axis (float) – The semimajor axis of the ellipsoid. The equatorial (large) radius.
Definition: \(a\).
Units: \(m\).
flattening (float) – The (first) flattening of the ellipsoid.
Definition: \(f = (a - b)/a\).
Units: adimensional.
geocentric_grav_const (float) – The geocentric gravitational constant. The product of the mass of the
ellipsoid \(M\) and the gravitational constant \(G\).
Definition: \(GM\). Units:
\(m^3.s^{-2}\).
angular_velocity (float) – The angular velocity of the rotating ellipsoid.
Definition: \(\omega\).
Units: \(\\rad.s^{-1}\).
long_name (str or None) – A long name for the ellipsoid, for example "WorldGeodeticSystem1984" (optional).
reference (str or None) – Citation for the ellipsoid parameter values (optional).
comments (str or None) – Additional comments regarding the ellipsoid (optional).
Caution
Use boule.Sphere if you desire zero flattening because there
are singularities for this particular case in the normal gravity
calculations.
Examples
We can define an ellipsoid by setting the 4 key numerical parameters and
some metadata about where they came from:
>>> ellipsoid=Ellipsoid(... name="WGS84",... long_name="World Geodetic System 1984",... semimajor_axis=6378137,... flattening=1/298.257223563,... geocentric_grav_const=3986004.418e8,... angular_velocity=7292115e-11,... reference=(... "Hofmann-Wellenhof, B., & Moritz, H. (2006). Physical Geodesy "... "(2nd, corr. ed. 2006 edition ed.). Wien ; New York: Springer."... ),... )>>> print(ellipsoid)Ellipsoid(name='WGS84', ...)>>> print(ellipsoid.long_name)World Geodetic System 1984
The class then defines several derived attributes based on the input
parameters:
The (first) eccentricity of the ellipsoid. The ratio between the linear
eccentricity and the semimajor axis.
Definition: \(e = \dfrac{\sqrt{a^2 - b^2}}{a} = \sqrt{2f - f^2}\).
Units: adimensional.
The norm of the gravity acceleration vector (gravitational +
centrifugal accelerations) at the equator on the surface of the
ellipsoid. Units: \(m/s^2\).
The norm of the gravity acceleration vector (gravitational +
centrifugal accelerations) at the poles on the surface of the
ellipsoid. Units: \(m/s^2\).
The linear eccentricity of the ellipsoid. The distance between the
ellipsoid’s center and one of its foci.
Definition: \(E = \sqrt{a^2 - b^2}\).
Units: \(m\).
The normal gravity potential on the surface of the ellipsoid.
Definition: \(U_0 = \dfrac{GM}{E} \arctan{\dfrac{E}{b}}
+ \dfrac{1}{3} \omega^2 a^2\).
Units: \(m^2 / s^2\).
The second eccentricity of the ellipsoid. The ratio between the linear
eccentricity and the semiminor axis.
Definition: \(e^\prime = \dfrac{\sqrt{a^2 - b^2}}{b}
= \dfrac{\sqrt{2f - f^2}}{1 - f}\).
Units: adimensional.
Radial distance from the center of the ellipsoid to its surface.
Can be calculated from either geocentric geodetic or geocentric
spherical latitudes.
Parameters:
latitude (float or array) – Latitude coordinates on geodetic coordinate system in degrees.
geodetic (bool) – If True (default), will assume that latitudes are geodetic
latitudes. Otherwise, will assume that they are geocentric
spherical latitudes.
Returns:
geocentric_radius (float or array) – The geocentric radius for the given latitude(s) in the same units
as the ellipsoid axis.
Tip
No elevation is taken into account. If you need the geocentric
radius at a height other than zero, use
pymap3d.geodetic2spherical instead.
Notes
The geocentric surface radius \(R\) is a function of the geocentric
geodetic latitude \(\phi\) and the semimajor and semiminor axis,
\(a\) and \(b\)[1]:
This can be useful if you already have the geocentric spherical
latitudes and need the geocentric radius of the ellipsoid (for example,
in spherical harmonic synthesis). In these cases, the coordinate
conversion route is not possible since we need the radial coordinates
to do that in the first place.
Convert from geodetic to geocentric spherical coordinates.
The geodetic datum is defined by this ellipsoid. The coordinates are
converted following [Vermeille2002].
Parameters:
longitude (array) – Longitude coordinates on geodetic coordinate system in degrees.
latitude (array) – Latitude coordinates on geodetic coordinate system in degrees.
height (array) – Ellipsoidal heights in meters.
Returns:
longitude (array) – Longitude coordinates on geocentric spherical coordinate system in
degrees.
The longitude coordinates are not modified during this conversion.
spherical_latitude (array) – Converted latitude coordinates on geocentric spherical coordinate
system in degrees.
radius (array) – Converted spherical radius coordinates in meters.
Normal gravity of the ellipsoid at the given latitude and height.
Computes the magnitude of the gradient of the gravity potential
(gravitational + centrifugal; see [HofmannWellenhofMoritz2006])
generated by the ellipsoid at the given geodetic latitude \(\phi\)
and height above the ellipsoid \(h\) (geometric height).
\[\gamma(\phi, h) = \|\vec{\nabla}U(\phi, h)\|\]
in which \(U = V + \Phi\) is the gravity potential of the
ellipsoid, \(V\) is the gravitational potential of the ellipsoid,
and \(\Phi\) is the centrifugal potential.
Assumes that the internal density distribution of the ellipsoid is such
that the gravity potential is constant at its surface.
Based on closed-form expressions by [Lakshmanan1991] and corrected by
[LiGotze2001] which don’t require the free-air correction.
Caution
These expressions are only valid for heights on or above the
surface of the ellipsoid.
Parameters:
latitude (float or array) – The geodetic latitude where the normal gravity will be computed (in
degrees).
height (float or array) – The ellipsoidal (geometric) height of computation the point (in
meters).
si_units (bool) – Return the value in mGal (False, default) or m/s² (True)
Returns:
gamma (float or array) – The normal gravity in mGal or m/s².
The prime vertical radius of curvature for a given geodetic latitude.
Note
This function receives the sine of the latitude as input to avoid
repeated computations of trigonometric functions in
methods/functions that rely on it.
Parameters:
sinlat (float or array-like) – Sine of the geocentric geodetic latitude.
Returns:
prime_vertical_radius (float or array-like) – Prime vertical radius given in the same units as the semi-major
axis
Notes
The prime vertical radius of curvature \(N\) is defined as [2]: