curryer.compute.pointing
========================

.. py:module:: curryer.compute.pointing

.. autoapi-nested-parse::

   Pointing related calculations.

   @author: Brandon Stone



Attributes
----------

.. autoapisummary::

   curryer.compute.pointing.logger


Classes
-------

.. autoapisummary::

   curryer.compute.pointing.OccultType
   curryer.compute.pointing.PointingData


Functions
---------

.. autoapisummary::

   curryer.compute.pointing.calc_cosine
   curryer.compute.pointing.boresight_dot_object
   curryer.compute.pointing.check_fov
   curryer.compute.pointing.check_occult
   curryer.compute.pointing.legacy_instrument_dot_object


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

.. py:data:: logger

.. py:function:: calc_cosine(target_state, boresight_vector)

   Calculate the cosine angle between a boresight vector and one or more
   state vectors. Vectors will be normalized (inplace).

   :param target_state: Array of state vectors [N, 3] or [3].
   :type target_state: numpy.ndarray
   :param boresight_vector: Boresight vector [3].
   :type boresight_vector: numpy.ndarray

   :returns: Cosine values. Return is a scalar if `target_state` was a 1D array.
   :rtype: float or numpy.ndarray


.. py:function:: boresight_dot_object(instrument, target, ugps_times)

   Calculate the cosine between an instruments boresight and target.

   :param instrument: Instrument to calculate the cosine angles for. If an Instrument object,
                      it must contain a "frame" and "spacecraft". Otherwise they are
                      inferred from the instrument string.
   :type instrument: str or sds_spice.spicierpy.obj.Instrument
   :param target: Target ephemeris object (e.g., Earth, Sun).
   :type target: str or sds_spice.spicierpy.obj.Body
   :param ugps_times: One or more uGPS times to calculate values at.
   :type ugps_times: int or list of ints or numpy.ndarray

   :returns: Cosine angle between the boresight and target, in the `instrument` frame.
   :rtype: float or numpy.ndarray

   .. rubric:: Notes

   - The boresight is retrieve from the `instrument`'s kernel (IK).


.. py:function:: check_fov(ugps_times, instrument, target='MOON', observer=True, correction='LT+S', allow_nans=False)

   Check if there was an FOV event at the specified time.


.. py:class:: OccultType

   Bases: :py:obj:`enum.IntEnum`


   Types of planetary occultation.
   See: https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/occult_c.html


   .. py:attribute:: TOTAL_TARGET1_BY_TARGET2
      :value: -3



   .. py:attribute:: ANNULAR_TARGET1_BY_TARGET2
      :value: -2



   .. py:attribute:: PARTIAL_TARGET1_BY_TARGET2
      :value: -1



   .. py:attribute:: NO_OCCULT
      :value: 0



   .. py:attribute:: PARTIAL_TARGET2_BY_TARGET1
      :value: 1



   .. py:attribute:: ANNULAR_TARGET2_BY_TARGET1
      :value: 2



   .. py:attribute:: TOTAL_TARGET2_BY_TARGET1
      :value: 3



.. py:function:: check_occult(ugps_times, observer, target1='MOON', target2='SUN', correction='LT')

   Check if there was an FOV event at the specified time.


.. py:class:: PointingData(observer, qf_map=None, with_geolocate=False, microsecond_cadence=None)

   Bases: :py:obj:`curryer.compute.abstract.AbstractMissionData`


   Class for working with TIM pointing data.


   .. py:attribute:: DEFAULT_CADENCE
      :value: 10000000



   .. py:attribute:: DEFAULT_QF_MAP


   .. py:attribute:: observer


   .. py:attribute:: qf_map


   .. py:attribute:: with_geolocate
      :value: False



   .. py:attribute:: max_deltat
      :value: 0



   .. py:method:: get_pointing(ugps_times)

      Determine pointing values.

      :param ugps_times: Determine pointing at 1 or more times (uGPS).
      :type ugps_times: int or iter of int

      :returns: Table of [?] at each time.
      :rtype: pandas.DataFrame



.. py:function:: legacy_instrument_dot_object(spacecraft_to_eci_rotation, spacecraft_in_eci_state, object_in_eci_state, boresight_in_instrument_vector, spacecraft_to_instrument_rotation=None)

   Calculate the cosine angle between an instrument's boresight and an
   object (planet).

   :param spacecraft_to_eci_rotation: Rotation matrix (3x3 or Nx3x3) from the spacecraft's reference frame to
                                      the ECI (earth centered inertial) reference frame.
   :type spacecraft_to_eci_rotation: numpy.ndarray
   :param spacecraft_in_eci_state: State vector (3 or Nx3; x,y,z) of the spacecraft's location in the ECI
                                   reference frame.
   :type spacecraft_in_eci_state: numpy.ndarray
   :param object_in_eci_state: State vector (3 or Nx3; x,y,z) of the object's location in the ECI
                               reference frame. The object is typically a planet. For example, the
                               vector would be all zeros if the object was Earth.
   :type object_in_eci_state: numpy.ndarray
   :param boresight_in_instrument_vector: Pointing vector (3; x,y,z) of the instrument's boresight, in the
                                          instrument's reference frame (e.g., [1, 0, 0]).
   :type boresight_in_instrument_vector: numpy.ndarray
   :param spacecraft_to_instrument_rotation: Rotation matrix (3x3) from the spacecraft's reference frame to the
                                             instrument's reference frame. Default assumes they are the same.
   :type spacecraft_to_instrument_rotation: numpy.ndarray, optional

   :returns: Cosine angle based on the normalized dot product of the instrument
             boresight and the object's state vector(s). The return is a scalar
             numpy float if `spacecraft_to_eci_rotation` was a 2D array, otherwise
             it's a 1D array of floats.
   :rtype: numpy.float64 or numpy.ndarray

   .. rubric:: Notes

   - ECI and J2000 are considered the same spatial reference frame.
   - Based on the java implementation in tim_processing:
       src/java/processing/tim/pointing_data/TCTEPointingDataServer.java
   - Java implementation difference - A "Quat4d" & "Vector3d" transformation
   includes a matrix transposition; likely a quaternion format difference.