Update coordinate conversions web documentation (#212)

Improve documentation page for Coordinate conversions. Reorganize the
section headings to include: Geodetic to geocentric spherical, Geodetic
to geocentric spherical using pymap3d, and Geocentric spherical to
geodetic. Fix how the spherical to geodetic calculation was performed
starting from the Cartesian geocentric coordinates instead of the
planetocentric ones referenced to the geoid.

doc/references.rst

@@ -16,6 +16,7 @@ References
 .. [Karimi2017] Karimi, R., Azmoudeh Ardalan, A., & Vasheghani Farahani, S. (2017, October). The size, shape and orientation of the asteroid Vesta based on data from the Dawn mission. Earth and Planetary Science Letters. Elsevier BV. doi:`10.1016/j.epsl.2017.07.033 <https://doi.org/10.1016/j.epsl.2017.07.033>`__
 .. [Konopliv2018] Konopliv, A. S., Park, R. S., Vaughan, A. T., Bills, B. G., Asmar, S. W., Ermakov, A. I., Rambaux, N., Raymond, C. A., Castillo-Rogez, J. C., Russell, C. T., Smith, D. E., & Zuber, M. T. (2018). The Ceres gravity field, spin pole, rotation period and orbit from the Dawn radiometric tracking and optical data. Icarus, 299, 411–429. doi:`10.1016/j.icarus.2017.08.005 <https://doi.org/10.1016/j.icarus.2017.08.005>`__
 .. [Lakshmanan1991] Lakshmanan, J. (1991). The generalized gravity anomaly: Endoscopic microgravity. Geophysics, 56(5), 712-723. doi:`10.1190/1.1443090 <https://doi.org/10.1190/1.1443090>`__
+.. [LeMaistre2023] Le Maistre, S., Rivoldini, A., Caldiero, A., Yseboodt, M., Baland, R.-M., Beuthe, M., Van Hoolst, T., Dehant, V., Folkner, W. M., Buccino, D., Kahan, D., Marty, J.-C., Antonangeli, D., Badro, J., Drilleau, M., Konopliv, A., Péters, M.-J., Plesa, A.-C., Samuel, H., Tosi, N., Wieczorek, M., Lognonné, P., Panning, M., Smrekar, S. & Banerdt, W. B. (2023). Spin state and deep interior structure of Mars from InSight radio tracking. Nature, 1–5. doi:`10.1038/s41586-023-06150-0 <https://doi.org/10.1038/s41586-023-06150-0>`__
 .. [Lemoine1998] Lemoine, F. G., Kenyon, S. C., Factor, J. K., Trimmer, R. G., Pavlis, N. K., Chinn, D. S., Cox, C. M., Klosko, S. M., Lutchke, S. B., Torrence, M. H., Wang, Y. M., Williamson, R. G., Pavlis, E. C., Rapp, R. H., & Olson, T. R. (1998). The Development of the Joint NASA GSFC and the National Imagery and Mapping Agency (NIMA) Geopotential Model EGM96. NASA Goddard Space Flight Center, `NASA/TP 1998-206861 <https://cddis.nasa.gov/926/egm96/egm96.html>`__
 .. [LiGotze2001] Li, X. and H. J. Gotze, (2001). Tutorial: Ellipsoid, geoid, gravity, geodesy, and geophysics, Geophysics, 66(6), p. 1660-1668, doi:`10.1190/1.1487109 <https://doi.org/10.1190/1.1487109>`__
 .. [Maia2024] Maia, J. (2024). Spherical harmonic models of the shape of Mercury [Data set]. Zenodo. doi:`10.5281/zenodo.10809345 <https://doi.org/10.5281/zenodo.10809345>`__
@@ -25,7 +26,6 @@ References
 .. [Nimmo2017] Nimmo, F., Umurhan, O., Lisse, C. M., Bierson, C. J., Lauer, T. R., Buie, M. W., Throop, H. B., Kammer, J. A., Roberts, J. H., McKinnon, W. B., Zangari, A. M., Moore, J. M., Stern, S. A., Young, L. A., Weaver, H. A., Olkin, C. B., & Ennico, K. (2017). Mean radius and shape of Pluto and Charon from New Horizons images. Icarus, 287, 12–29. doi:`10.1016/j.icarus.2016.06.027 <https://doi.org/10.1016/j.icarus.2016.06.027>`__
 .. [Park2019] Park, R. S., Vaughan, A. T., Konopliv, A. S., Ermakov, A. I., Mastrodemos, N., Castillo-Rogez, J. C., Joy, S. P., Nathues, A., Polanskey, C. A., Rayman, M. D., Riedel, J. E., Raymond, C. A., Russell, C. T., & Zuber, M. T. (2019). High-resolution shape model of Ceres from stereophotoclinometry using Dawn Imaging Data. Icarus, 319, 812–827. doi:`10.1016/j.icarus.2018.10.024 <https://doi.org/10.1016/j.icarus.2018.10.024>`__
 .. [Park2024] Park, R. S., Mastrodemos, N., Jacobson, R. A., Berne, A., Vaughan, A. T., Hemingway, D. J., Leonard, E. J., Castillo-Rogez, J. C., Cockell, C. S., Keane, J. T., Konopliv, A. S., Nimmo, F., Riedel, J. E., Simons, M., & Vance, S. (2024). The Global Shape, Gravity Field, and Libration of Enceladus. Journal of Geophysical Research: Planets, 129(1), e2023JE008054. doi:`10.1029/2023JE008054 <https://doi.org/10.1029/2023JE008054>`__
-.. [Parker2019] Parker, T. J., Golombek, M. P., Calef, F. J., Williams, N. R., LeMaistre, S., Folkner, W., ... & Hausmann, R. (2019). Localization of the InSight lander. In 50th Annual Lunar and Planetary Science Conference (No. 2132, p. 1948). `PDF available <https://www.hou.usra.edu/meetings/lpsc2019/pdf/1948.pdf>`__
 .. [Pěč1983] Pěč, K. & Martinec, Z. (1983). Expansion of geoid heights over a triaxial Earth's ellipsoid into a spherical harmonic series.  Studia Geophysica et Geodaetica, 27, 217-232. doi: `10.1007/BF01592791 <https://doi.org/10.1007/BF01592791>`__
 .. [Russell2012] Russell, C. T., Raymond, C. A., Coradini, A., McSween, H. Y., Zuber, M. T., Nathues, A., et al. (2012). Dawn at Vesta: Testing the Protoplanetary Paradigm. Science. doi:`10.1126/science.1219381 <https://doi.org/10.1126/science.1219381>`__
 .. [Thomas1998] Thomas, P. C., Davies, M. E., Colvin, T. R., Oberst, J., Schuster, P., Neukum, G., Carr, M. H., McEwen, A., Schubert, G., & Belton, M. J. S. (1998). The Shape of Io from Galileo Limb Measurements. Icarus, 135(1), 175–180. doi: `10.1006/icar.1998.5987 <https://doi.org/10.1006/icar.1998.5987>`__

doc/user_guide/coordinates.rst

@@ -46,8 +46,8 @@ Notice that:
     We used the WGS84 ellipsoid here but the workflow is the same for any
     other oblate ellipsoid. Checkout :ref:`ellipsoids` for options.
 
-Other conversions using pymap3d
--------------------------------
+Geodetic to geocentric spherical using pymap3d
+----------------------------------------------
 
 Boule's :class:`~boule.Ellipsoid` and :class:`~boule.Sphere` classes can be
 used with `pymap3d <https://github.com/geospace-code/pymap3d/>`__ for
@@ -57,13 +57,14 @@ 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 <defining_ellipsoids>` either because
-  you need different parameters than the built-in ones or they aren't available
-  in either Boule or pymap3d.
+* You need to :ref:`define your own ellipsoid <defining_ellipsoids>`, either
+  because you need different parameters than the built-in ones or they aren't
+  available in either Boule or pymap3d.
 
 The example below converts between geodetic and geocentric spherical using
 ``pymap3d.geodetic2spherical`` instead of
-:meth:`boule.Ellipsoid.geodetic_to_spherical` to achieve the same outcome:
+:meth:`boule.Ellipsoid.geodetic_to_spherical` to achieve the same outcome as
+in the previous example.
 
 .. jupyter-execute::
 
@@ -84,17 +85,33 @@ The example below converts between geodetic and geocentric spherical using
     print("Height (m):", height)
     print("Radius (m):", radius)
 
-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 <https://en.wikipedia.org/wiki/InSight>`__ on Mars based on
-[Parker2019]_ using the Martian ellipsoid defined in Boule:
+Geocentric spherical to geodetic
+--------------------------------
+
+Another common coordinate conversion used in global studies is from geocentric
+spherical to geodetic coordinates. The example below demonstrate this
+conversion using the Cartesian coordinates of the
+`Insight lander <https://en.wikipedia.org/wiki/InSight>`__ on Mars from
+[LeMaistre2023]_ and the Martian ellipsoid defined in Boule.
 
 .. jupyter-execute::
 
-    X, Y, Z = pymap3d.geodetic2ecef(
-        lat=4.502384, lon=135.623447, alt=-2613.426, ell=bl.Mars2009,
-    )
-    print(f"X = {X} m")
-    print(f"Y = {Y} m")
-    print(f"Z = {Z} m")
+  import boule as bl
+  import numpy as np
+
+  xyz = [-2_417_504.5, 2_365_954.5, 266_266.7]  # InSight lander coordinates
+
+  # convert Cartesian to geocentric spherical
+  radius = np.linalg.norm(xyz)
+  latitude_sph = np.rad2deg(np.atan2(xyz[2], np.linalg.norm(xyz[0:2])))
+  longitude_sph = np.rad2deg(np.atan2(xyz[1], xyz[0]))
+
+  mars_ellipsoid = bl.Mars2009
+
+  longitude, latitude, height = mars_ellipsoid.spherical_to_geodetic(
+    longitude_sph, latitude_sph, radius,
+  )
+
+  print(f"Geodetic longitude: {longitude}")
+  print(f"Geodetic latitude: {latitude}")
+  print(f"Ellipsoidal height (m): {height}")