.. _coordinates:
Coordinate conversions
======================
Boule's :class:`~boule.Ellipsoid` and :class:`~boule.Sphere` classes can be
used with `pymap3d `__ for
converting between different coordinate systems.
While pymap3d defines some ellipsoids internally, you may want to use one from
Boule if:
* You want to be certain that the parameters used for coordinate conversions
and gravity calculations are consistent.
* Need to :ref:`define your own ellipsoid ` either because
you need different parameters than the built-in ones or they aren't available
in either Boule or pymap3d.
.. admonition:: Help!
:class: hint
If an ellipsoid you need isn't in Boule yet, please `reach out
`__ to the team and consider adding it
yourself. It requires no special knowledge of the code and is a great way
to help the project!
Geodetic to spherical
---------------------
The example below will show you how to convert geodetic latitude and height
into geocentric spherical latitude and radius.
.. jupyter-execute::
import boule as bl
import pymap3d
import numpy as np
latitude = np.linspace(-90, 90, 45)
longitude = 40
height = 481_000 # ICESat-2 orbit height in meters
latitude_sph, longitude_sph, radius = pymap3d.geodetic2spherical(
latitude, longitude, height, ell=bl.WGS84,
)
print("Geodetic latitude:", latitude)
print("Spherical latitude:", latitude_sph)
print()
print("Geodetic longitude:", longitude)
print("Spherical longitude:", longitude_sph)
print()
print("Height (m):", height)
print("Radius (m):", radius)
Notice that:
1. The latitude is slightly different except for the poles and equator.
2. The longitude is the same in both coordinates systems.
3. The radius (distance from the center of the ellipsoid) varies even though
the height is constant.
.. tip::
We used the WGS84 ellipsoid here but the workflow is the same for any
other oblate ellipsoid or sphere. Checkout :ref:`ellipsoids` for options.
Geodetic to Cartesian
---------------------
Another common coordinate conversion done in global studies is from geodetic
latitude, longitude, and height to geocentric Cartesian X, Y, and Z.
The example below performs this conversion for the location of the
`Insight lander `__ on Mars based on
[Parker2019]_:
.. jupyter-execute::
X, Y, Z = pymap3d.geodetic2ecef(
lat=4.502384, lon=135.623447, alt=-2613.426, ell=bl.MARS,
)
print(f"X = {X} m")
print(f"Y = {Y} m")
print(f"Z = {Z} m")