orbix.observatory.keepout
=========================

.. py:module:: orbix.observatory.keepout

.. autoapi-nested-parse::

   Sun/Earth keepout zone checks.

   Determines whether a target star is observable based on angular separation
   from bright solar system bodies.  Port of the keepout logic from
   ``EXOSIMS.Prototypes.Observatory.keepout``, simplified to Sun + Earth (the
   Moon is dropped as negligible against the L2 geometry; see ``is_observable``).



Functions
---------

.. autoapisummary::

   orbix.observatory.keepout._unit_vector
   orbix.observatory.keepout._angular_sep
   orbix.observatory.keepout._target_ecliptic_dir
   orbix.observatory.keepout.body_angle
   orbix.observatory.keepout.is_observable


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

.. py:function:: _unit_vector(v)

   Normalize vector to unit length.


.. py:function:: _angular_sep(v1, v2)

   Angular separation between two direction vectors (radians).


.. py:function:: _target_ecliptic_dir(ra_rad, dec_rad, mjd)

   Unit vector toward a target in heliocentric ecliptic frame.


.. py:function:: body_angle(obs_pos_eclip, body_pos_eclip, ra_rad, dec_rad, mjd)

   Angle between a solar system body and a target as seen from the observatory.

   :param obs_pos_eclip: Observatory heliocentric ecliptic position (AU).
   :param body_pos_eclip: Body heliocentric ecliptic position (AU).
   :param ra_rad: Target RA in radians.
   :param dec_rad: Target Dec in radians.
   :param mjd: MJD for coordinate conversion.

   :returns: Angular separation in radians.


.. py:function:: is_observable(obs_pos_eclip, ra_rad, dec_rad, mjd, ko_sun_min_deg = 45.0, ko_sun_max_deg = 180.0, ko_earth_min_deg = 0.0, ko_earth_max_deg = 180.0)

   Check if a target is observable (outside all keepout zones).

   :param obs_pos_eclip: Observatory heliocentric ecliptic position (AU), shape ``(3,)``.
   :param ra_rad: Target right ascension in radians.
   :param dec_rad: Target declination in radians.
   :param mjd: Modified Julian Date.
   :param ko_sun_min_deg: Minimum Sun keepout angle (degrees).
   :param ko_sun_max_deg: Maximum Sun keepout angle (degrees).
   :param ko_earth_min_deg: Minimum Earth keepout angle (degrees).
   :param ko_earth_max_deg: Maximum Earth keepout angle (degrees).

   :returns: True if the target is observable, False if it falls in a keepout zone.