skyscapes.io.exovista
=====================

.. py:module:: skyscapes.io.exovista

.. autoapi-nested-parse::

   ExoVista FITS loader -- builds a ``skyscapes.scene.System`` directly.

   Mirrors the legacy ``skyscapes._legacy.loaders.from_exovista`` semantics
   for Star and Disk, but rebuilds each planet as a 1-planet
   ``KeplerianOrbit`` + ``GridAtmosphere`` pair stored in the
   ``System.planets`` tuple. No ghost padding -- variadic tuples make that
   unnecessary.



Functions
---------

.. autoapisummary::

   skyscapes.io.exovista._load_star
   skyscapes.io.exovista._load_single_planet
   skyscapes.io.exovista._load_disk
   skyscapes.io.exovista._earth_like_planet_indices_from_hdul
   skyscapes.io.exovista.get_earth_like_planet_indices
   skyscapes.io.exovista.from_exovista


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

.. py:function:: _load_star(hdul, fits_ext = 4)

   Load the FITS star extension into a Star.


.. py:function:: _load_single_planet(hdul, idx, star, wavelengths_nm, trig_solver, midplane_inc_deg, midplane_pa_deg)

   Load one planet and return ``(Planet, t0_d)``.

   The barycentric ``(r, v)`` state vectors from the FITS file are
   rotated into the on-sky frame at load time using the system midplane
   angles before being converted to Keplerian elements. This means
   ``KeplerianOrbit.propagate`` produces on-sky positions directly --
   no frame metadata is consulted at runtime.

   The contrast grid is indexed by phase angle beta = arccos(r_z / |r|),
   computed at load time with the same ``trig_solver`` the runtime
   ``System`` uses.


.. py:function:: _load_disk(hdul, fits_ext)

   Load the ExoVista disk extension into an ExovistaDisk.

   The contrast cube is already rendered in the on-sky frame by
   ExoVista; the system midplane angles (I, PA) live on
   ``System.midplane_inc_deg`` / ``System.midplane_pa_deg`` (populated
   by ``from_exovista`` from the same FITS star header), not on the
   disk itself.


.. py:function:: _earth_like_planet_indices_from_hdul(hdul)

   Earth-filter logic operating on an already-open HDUList.


.. py:function:: get_earth_like_planet_indices(fits_file)

   Identify Earth-like planets in an ExoVista FITS file.

   Classification criteria:
     - Scaled semi-major axis: 0.95 <= a / sqrt(L_star) < 1.67 AU
     - Planet radius: 0.8 / sqrt(a_scaled) <= R < 1.4 R_earth


.. py:function:: from_exovista(fits_file, planet_indices = None, only_earths = False)

   Load an ExoVista FITS file into a ``scene.System``.

   The system's midplane inclination and position angle (FITS star
   header keys ``I`` and ``PA``) are applied at load time as a frame
   rotation of each planet's state vector before its Keplerian
   elements are computed. The same angles are stored as
   ``System.midplane_inc_deg`` and ``System.midplane_pa_deg`` for
   downstream diagnostic use.

   Args:
       fits_file: Path to ExoVista FITS file.
       planet_indices: Planet indices to load (0-based). ``None`` = all.
       only_earths: If True and *planet_indices* is None, auto-filter Earths.

   Returns:
       ``scene.System`` with star, planets (tuple), disk, and midplane metadata.