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}")