asp_plot.planetary_source
=========================

.. py:module:: asp_plot.planetary_source

.. autoapi-nested-parse::

   Planetary (LOLA/MOLA) altimetry source.

   Owns the planetary-altimetry side of :class:`asp_plot.altimetry.Altimetry`:
   loading LOLA (Moon) and MOLA (Mars) point clouds from ODE GDS CSV exports,
   sampling the ASP DEM at those points, and exporting a pc_align-ready CSV.

   The class holds its own data (``planetary_points``) and reads the
   cross-cutting ``dem_fn`` / ``directory`` / ``aligned_dem_fn`` from the
   coordinating :class:`Altimetry` instance passed at construction.



Attributes
----------

.. autoapisummary::

   asp_plot.planetary_source.GDS_BASE_URL
   asp_plot.planetary_source.MARS_IAU_SPHERE_RADIUS
   asp_plot.planetary_source.MOON_IAU_SPHERE_RADIUS
   asp_plot.planetary_source.logger


Classes
-------

.. autoapisummary::

   asp_plot.planetary_source.PlanetarySource


Functions
---------

.. autoapisummary::

   asp_plot.planetary_source.gds_query_async


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

.. py:class:: PlanetarySource(alt)

   Load and analyze LOLA (Moon) / MOLA (Mars) altimetry against an ASP DEM.

   :param alt: The coordinating :class:`asp_plot.altimetry.Altimetry` instance.
               Cross-cutting paths (``dem_fn``, ``directory``, ``aligned_dem_fn``)
               are read from it so a single source of truth describes the DEM
               under analysis.
   :type alt: Altimetry


   .. py:method:: load_planetary_csv(csv_path)

      Load LOLA or MOLA altimetry data from a GDS topo CSV file.

      The CSV is obtained via the ``request_planetary_altimetry`` CLI
      tool, which submits an async query to the ODE GDS API and emails
      the user a download link.  The user downloads and unzips the
      result, then passes the ``*_topo_csv.csv`` file here.

      Automatically selects the LOLA or MOLA parser based on the DEM's
      planetary body.

      :param csv_path: Path to a ``*_topo_csv.csv`` file from the ODE GDS.
      :type csv_path: str



   .. py:method:: planetary_to_dem_dh(n_sigma=3)

      Compute height differences between planetary altimetry and DEM.

      Reprojects ``self.planetary_points`` to the DEM CRS, interpolates
      DEM heights at altimetry locations, and computes the difference
      ``altimetry_minus_dem = height - dem_height``. When
      ``aligned_dem_fn`` is set, also populates ``aligned_dem_height``
      and ``altimetry_minus_aligned_dem`` so pre/post-alignment plots can
      share a single sample. Outliers beyond ``n_sigma`` × std from the
      mean (computed on the unaligned dh) are removed by default.

      :param n_sigma: Remove dh outliers beyond this many standard deviations from
                      the mean. Default 3. Pass None to skip outlier filtering.
      :type n_sigma: float or None, optional
      :param The results are stored as new columns on ``self.planetary_points``.:



   .. py:method:: to_csv_for_pc_align_planetary(filename_prefix='planetary_for_pc_align')

      Export ``self.planetary_points`` to a CSV for pc_align.

      Writes columns ``lon, lat, radius_m`` (planetary radius from the
      body center, in meters). Used as the ``planetary_csv`` argument
      to :meth:`asp_plot.alignment.Alignment.pc_align_dem_to_planetary_csv`.

      :param filename_prefix: Prefix for the output CSV filename. Saved in
                              ``self.alt.directory``.
      :type filename_prefix: str, optional

      :returns: Absolute path to the created CSV file.
      :rtype: str



   .. py:attribute:: alt


   .. py:attribute:: planetary_points
      :value: None



.. py:function:: gds_query_async(query_type, bounds, results_code, email=None, **extra_params)

   Submit an async query to the ODE GDS REST API.

   :param query_type: GDS query type, e.g. ``"lolardr"`` or ``"molapedr"``.
   :type query_type: str
   :param bounds: Dictionary with ``westernlon``, ``easternlon``, ``minlat``,
                  ``maxlat`` keys.
   :type bounds: dict
   :param results_code: GDS results format code (e.g. ``"u"`` for LOLA, ``"v"`` for MOLA).
   :type results_code: str
   :param email: Email for notification when query finishes.
   :type email: str or None, optional
   :param \*\*extra_params: Additional GDS query parameters (e.g. ``channel="ttttt"``).

   :returns: Job ID for polling.
   :rtype: str


.. py:data:: GDS_BASE_URL
   :value: 'https://oderest.rsl.wustl.edu/livegds'


.. py:data:: MARS_IAU_SPHERE_RADIUS

.. py:data:: MOON_IAU_SPHERE_RADIUS

.. py:data:: logger