boinor.plotting.aitoff
======================

.. py:module:: boinor.plotting.aitoff

.. autoapi-nested-parse::

   Aitoff projection sky map plotting in J2000 equatorial coordinates.



Classes
-------

.. autoapisummary::

   boinor.plotting.aitoff.AitoffPlotter


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

.. py:class:: AitoffPlotter(epoch=None, ax=None, figsize=(12, 8), style='dark_background', show_ecliptic=True, ecliptic_obliquity=23.439281)

   All-sky map plotter using Aitoff projection in J2000 equatorial coordinates.

   This class provides functionality to plot celestial bodies and spacecraft
   positions on an all-sky Aitoff projection. It operates in J2000 equatorial
   coordinates (right ascension and declination) without Earth-orientation or
   horizon effects, making it suitable for inertial sky visualization.

   :param epoch: Epoch for the sky map. Defaults to current time.
   :type epoch: ~astropy.time.Time, optional
   :param ax: Matplotlib axes to use. If None, creates a new figure with Aitoff projection.
   :type ax: ~matplotlib.axes.Axes, optional
   :param figsize: Figure size in inches. Defaults to (12, 8).
   :type figsize: tuple, optional
   :param style: Matplotlib style to use. Defaults to 'dark_background' for night sky appearance.
   :type style: str, optional
   :param show_ecliptic: Whether to plot the ecliptic reference line. Defaults to True.
   :type show_ecliptic: bool, optional
   :param ecliptic_obliquity: Mean obliquity of the ecliptic in degrees (J2000). Defaults to 23.439281.
   :type ecliptic_obliquity: float, optional

   .. rubric:: Examples

   >>> from boinor.plotting.aitoff import AitoffPlotter
   >>> from astropy.time import Time
   >>> plotter = AitoffPlotter(epoch=Time.now())
   >>> plotter.plot_ra_dec(ra=0*u.deg, dec=0*u.deg, label="Test")
   >>> plotter.show()

   .. rubric:: Notes

   The Aitoff projection is a modified azimuthal map projection that displays
   the entire celestial sphere. Longitude values are converted to matplotlib's
   expected format ([-π, π]) and inverted to match standard sky map conventions
   where 0° longitude is on the left.

   .. rubric:: References

   - Aitoff projection: https://en.wikipedia.org/wiki/Aitoff_projection
   - J2000 coordinate system: https://en.wikipedia.org/wiki/Epoch_(astronomy)#J2000.0
   - Overview of Reference Frames and Coordinate Systems in SPICE: https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/pdf/individual_docs/17_frames_and_coordinate_systems.pdf


   .. py:attribute:: epoch


   .. py:attribute:: show_ecliptic
      :value: True



   .. py:attribute:: ecliptic_obliquity


   .. py:method:: plot_ra_dec(ra, dec, label=None, color=None, marker='o', markersize=12, **kwargs)

      Plot a point on the sky map using right ascension and declination.

      :param ra: Right ascension. If float, assumed to be in radians.
      :type ra: ~astropy.units.Quantity or float
      :param dec: Declination. If float, assumed to be in radians.
      :type dec: ~astropy.units.Quantity or float
      :param label: Label for the plotted point.
      :type label: str, optional
      :param color: Color for the marker. If None, uses matplotlib default.
      :type color: str, optional
      :param marker: Marker style. Defaults to 'o'.
      :type marker: str, optional
      :param markersize: Size of the marker. Defaults to 12.
      :type markersize: float, optional
      :param \*\*kwargs: Additional keyword arguments passed to matplotlib's plot function.

      :returns: The plotted line/marker object.
      :rtype: ~matplotlib.lines.Line2D



   .. py:method:: plot_spice_position(target, observer='EARTH', frame='J2000', abcorr='LT+S', label=None, color=None, marker='o', markersize=12, **kwargs)

      Plot a body position using SPICE ephemeris.

      :param target: SPICE target name or NAIF ID code.
      :type target: str or int
      :param observer: SPICE observer name or NAIF ID code. Defaults to "EARTH".
      :type observer: str or int, optional
      :param frame: Reference frame. Defaults to "J2000".
      :type frame: str, optional
      :param abcorr: Aberration correction. Defaults to "LT+S" (light time + stellar aberration).
      :type abcorr: str, optional
      :param label: Label for the plotted point.
      :type label: str, optional
      :param color: Color for the marker. If None, uses matplotlib default.
      :type color: str, optional
      :param marker: Marker style. Defaults to 'o'.
      :type marker: str, optional
      :param markersize: Size of the marker. Defaults to 12.
      :type markersize: float, optional
      :param \*\*kwargs: Additional keyword arguments passed to matplotlib's plot function.

      :returns: The plotted line/marker object.
      :rtype: ~matplotlib.lines.Line2D

      :raises ImportError: If spiceypy is not installed.

      .. rubric:: Notes

      This method requires SPICE kernels to be loaded beforehand using
      ``spiceypy.furnsh()``. The position is computed in the specified frame
      and converted to J2000 equatorial coordinates (RA/Dec).



   .. py:method:: set_title(title=None)

      Set the plot title.

      :param title: Title text. If None, uses the epoch in UTC format.
      :type title: str, optional



   .. py:method:: set_labels()

      Set standard axis labels for the sky map.



   .. py:method:: set_ticks()

      Set standard tick labels for right ascension in hours.



   .. py:method:: show()

      Display the plot with legend and grid.



   .. py:method:: save(filename, **kwargs)

      Save the plot to a file.

      :param filename: Output filename.
      :type filename: str
      :param \*\*kwargs: Additional keyword arguments passed to matplotlib's savefig function.