From aa4c40667511f5d0e97c64bc1ee678f5e138628f Mon Sep 17 00:00:00 2001 From: markwieczorek Date: Fri, 4 Oct 2024 19:12:17 +0200 Subject: [PATCH] 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 | 2 +- doc/user_guide/coordinates.rst | 51 ++++++++++++++++++++++------------ 2 files changed, 35 insertions(+), 18 deletions(-) diff --git a/doc/references.rst b/doc/references.rst index e618eb3c..d2946234 100644 --- a/doc/references.rst +++ b/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 `__ .. [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 `__ .. [Lakshmanan1991] Lakshmanan, J. (1991). The generalized gravity anomaly: Endoscopic microgravity. Geophysics, 56(5), 712-723. doi:`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 `__ .. [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 `__ .. [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 `__ .. [Maia2024] Maia, J. (2024). Spherical harmonic models of the shape of Mercury [Data set]. Zenodo. doi:`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 `__ .. [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 `__ .. [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 `__ -.. [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 `__ .. [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 `__ .. [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 `__ .. [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 `__ diff --git a/doc/user_guide/coordinates.rst b/doc/user_guide/coordinates.rst index cf084b6e..3975f25b 100644 --- a/doc/user_guide/coordinates.rst +++ b/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 `__ 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 ` 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 `, 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 `__ 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 `__ 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}")