spotter.viz
===========

.. py:module:: spotter.viz

.. autoapi-nested-parse::

   Visualization utilities for spherical maps and stellar surfaces.

   This module provides functions for plotting HEALPix maps, graticules, and
   generating videos of rotating stars.



Functions
---------

.. autoapisummary::

   spotter.viz.lon_lat_lines
   spotter.viz.rotation
   spotter.viz.rotate_lines
   spotter.viz.plot_lines
   spotter.viz.graticule
   spotter.viz.show
   spotter.viz.video


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

.. py:function:: lon_lat_lines(n: int = 6, pts: int = 100, radius: float = 1.0)

   Generate latitude and longitude lines on a sphere.

   :param n: Number of latitude lines (and longitude lines if tuple).
   :type n: int or tuple, optional
   :param pts: Number of points per line.
   :type pts: int, optional
   :param radius: Sphere radius.
   :type radius: float, optional

   :returns: * **lat** (*ndarray*) -- Latitude lines.
             * **lon** (*ndarray*) -- Longitude lines.


.. py:function:: rotation(inc, obl, theta)

   Compute the rotation for given inclination, obliquity, and phase.

   :param inc: Inclination in radians.
   :type inc: float
   :param obl: Obliquity in radians.
   :type obl: float
   :param theta: Rotation phase in radians.
   :type theta: float

   :returns: **R** -- Rotation object.
   :rtype: scipy.spatial.transform.Rotation


.. py:function:: rotate_lines(lines, inc, obl, theta)

   Rotate lines by given inclination, obliquity, and phase.

   :param lines: Input lines.
   :type lines: ndarray
   :param inc: Inclination in radians.
   :type inc: float
   :param obl: Obliquity in radians.
   :type obl: float
   :param theta: Rotation phase in radians.
   :type theta: float

   :returns: **rotated_lines** -- Rotated lines.
   :rtype: ndarray


.. py:function:: plot_lines(lines, axis=(0, 1), ax=None, **kwargs)

   Plot lines on a matplotlib axis.

   :param lines: Lines to plot.
   :type lines: ndarray
   :param axis: Axes to plot (default (0, 1)).
   :type axis: tuple, optional
   :param ax: Axis to plot on.
   :type ax: matplotlib axis, optional
   :param \*\*kwargs: Additional plot arguments.


.. py:function:: graticule(inc: float, obl: float = 0.0, theta: float = 0.0, pts: int = 100, radius: float = 1.0, n=6, ax=None, **kwargs)

   Plot a graticule (latitude/longitude grid) on a sphere.

   :param inc: Inclination in radians.
   :type inc: float
   :param obl: Obliquity in radians.
   :type obl: float, optional
   :param theta: Rotation phase in radians.
   :type theta: float, optional
   :param pts: Number of points per line.
   :type pts: int, optional
   :param radius: Sphere radius.
   :type radius: float, optional
   :param n: Number of latitude/longitude lines.
   :type n: int or tuple, optional
   :param ax: Axis to plot on.
   :type ax: matplotlib axis, optional
   :param \*\*kwargs: Additional plot arguments.


.. py:function:: show(y, inc=np.pi / 2, obl=0.0, u=None, xsize=800, phase=0.0, ax=None, radius=None, period=None, rv=False, **kwargs)

   Show a rendered map with graticule.

   :param y: HEALPix map.
   :type y: array_like
   :param inc: Inclination in radians.
   :type inc: float, optional
   :param obl: Obliquity in radians.
   :type obl: float, optional
   :param u: Limb darkening coefficients.
   :type u: array_like or None, optional
   :param xsize: Output image size.
   :type xsize: int, optional
   :param phase: Rotation phase in radians.
   :type phase: float, optional
   :param ax: Axis to plot on.
   :type ax: matplotlib axis, optional
   :param \*\*kwargs: Additional plot arguments.


.. py:function:: video(y, inc=None, obl=0.0, u=None, duration=4, fps=10, radius=None, period=None, rv=False, **kwargs)

   Create an HTML video of a rotating map (for Jupyter notebooks).

   :param y: HEALPix map.
   :type y: array_like
   :param inc: Inclination in radians.
   :type inc: float, optional
   :param obl: Obliquity in radians.
   :type obl: float, optional
   :param u: Limb darkening coefficients.
   :type u: array_like or None, optional
   :param duration: Duration of the video in seconds.
   :type duration: int, optional
   :param fps: Frames per second.
   :type fps: int, optional
   :param render_fun: A function of phase that renders the star. Default is core.render
   :type render_fun: callable, optional
   :param \*\*kwargs: Additional plot arguments.

   :rtype: None