.. _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")