asp_plot.bodies
===============

.. py:module:: asp_plot.bodies

.. autoapi-nested-parse::

   Per-body facts for the planetary bodies asp_plot supports.

   Earth, the Moon, and Mars each carry a handful of constants that the rest of
   the package needs: an altimetry instrument name, an IAU sphere radius, a
   ``pc_align --datum`` string, a geocentric PROJ string, and a geographic CRS
   WKT.  Historically these were re-typed as ad-hoc ``{"moon": ..., "mars": ...}``
   dict literals at every use site.  This module collects them into one frozen
   :class:`Body` dataclass and a :data:`BODIES` registry so that adding a body (or
   correcting a constant) is a single-line change rather than a grep across files.

   The canonical body *detector* remains :func:`asp_plot.utils.detect_planetary_body`,
   which inspects a DEM's CRS WKT.  :func:`body_for_dem` wraps it to return the
   matching :class:`Body`.



Attributes
----------

.. autoapisummary::

   asp_plot.bodies.BODIES


Classes
-------

.. autoapisummary::

   asp_plot.bodies.Body


Functions
---------

.. autoapisummary::

   asp_plot.bodies.body_for_dem


Module Contents
---------------

.. py:class:: Body

   Immutable bundle of per-body facts.

   .. attribute:: name

      Canonical body name: ``"earth"``, ``"moon"``, or ``"mars"``.  Matches
      the strings returned by :func:`asp_plot.utils.detect_planetary_body`.

      :type: str

   .. attribute:: altimetry_instrument

      Reference altimetry instrument: ``"ICESat-2"``, ``"LOLA"``, or
      ``"MOLA"``.

      :type: str

   .. attribute:: iau_sphere_radius_m

      IAU mean sphere radius in meters, used to convert planetary radius to
      height above the sphere.  ``None`` for Earth, which uses an ellipsoid
      rather than a sphere.

      :type: float or None

   .. attribute:: datum

      ASP ``pc_align --datum`` string (``"D_MOON"`` / ``"D_MARS"``).
      ``None`` for Earth (pc_align infers the datum from the data).

      :type: str or None

   .. attribute:: geocentric_proj

      Body-centered geocentric ("ECEF-equivalent") PROJ string used to
      convert a Cartesian translation vector into the DEM's CRS.  ``None``
      for Earth, where ``EPSG:4978`` is used instead (PROJ refuses to
      operate across celestial bodies, so planets need an explicit string).

      :type: str or None

   .. attribute:: geographic_crs_wkt

      Geographic CRS WKT used when building planetary GeoDataFrames.
      ``None`` for Earth, whose data already carry a CRS.

      :type: str or None

   .. attribute:: semi_major_axis_m

      Ellipsoid semi-major axis in meters (fallback for building a
      geographic CRS when a DEM's own ellipsoid is unavailable).

      :type: float

   .. attribute:: inverse_flattening

      Ellipsoid inverse flattening (``0.0`` for the spherical bodies).

      :type: float


   .. py:attribute:: altimetry_instrument
      :type:  str


   .. py:attribute:: datum
      :type:  str | None


   .. py:attribute:: geocentric_proj
      :type:  str | None


   .. py:attribute:: geographic_crs_wkt
      :type:  str | None


   .. py:attribute:: iau_sphere_radius_m
      :type:  float | None


   .. py:attribute:: inverse_flattening
      :type:  float


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: semi_major_axis_m
      :type:  float


.. py:function:: body_for_dem(dem_fn, body=None)

   Return the :class:`Body` for a DEM.

   :param dem_fn: Path to the DEM file.
   :type dem_fn: str
   :param body: Body name to look up directly.  If ``None`` (default), the body is
                auto-detected from the DEM's CRS via
                :func:`asp_plot.utils.detect_planetary_body`.
   :type body: str or None, optional

   :rtype: Body


.. py:data:: BODIES