smx.plotting.theme
==================

.. py:module:: smx.plotting.theme

.. autoapi-nested-parse::

   SMX visual theme system.

   All plotting helpers accept an optional ``theme`` argument of type
   :class:`SMXTheme`.  When omitted, :data:`DEFAULT_THEME` is used.

   Example — using the default theme::

       from smx.plotting import plot_zone_ranking_over_spectrum
       plot_zone_ranking_over_spectrum(..., output_path="out.html")

   Example — overriding selected fields::

       from smx.plotting.theme import SMXTheme
       my_theme = SMXTheme(font_family="Georgia", colorscale="Blues")
       plot_zone_ranking_over_spectrum(..., output_path="out.html", theme=my_theme)



Attributes
----------

.. autoapisummary::

   smx.plotting.theme.DEFAULT_THEME


Classes
-------

.. autoapisummary::

   smx.plotting.theme.SMXTheme


Functions
---------

.. autoapisummary::

   smx.plotting.theme.blend_with_white
   smx.plotting.theme.build_blended_colorscale


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

.. py:class:: SMXTheme

   Visual style configuration shared across all SMX plots.

   Parameters
   ----------
   template : str
       Plotly layout template (e.g. ``'plotly_white'``, ``'simple_white'``).
   font_family : str
       CSS font-family string applied to all text in the figure.
   font_size : int
       Base font size (px) for axis labels, tick labels, and annotations.
   class_colors : dict[str, str]
       Mapping from class label to hex/CSS color string.  Labels not present
       fall back to ``fallback_palette``.
   fallback_palette : list[str]
       Ordered list of colors used for class labels not found in
       ``class_colors``.
   colorscale : str
       Plotly colorscale name used for LRC-score zone bands and the colorbar.
   zone_opacity : float
       Opacity applied to zone background rectangles (vrect).
   reference_line_color : str
       Color for the overall reference/mean spectrum line.
   reference_line_width : int
       Stroke width (px) for the reference spectrum line.
   reference_line_dash : str
       Plotly dash style for the reference spectrum (e.g. ``'dash'``).
   class_line_width : int
       Stroke width (px) for per-class mean spectrum lines.
   threshold_color : str
       Color for reconstructed threshold spectrum lines.
   threshold_line_width : int
       Stroke width (px) for threshold spectrum lines.
   threshold_line_dash : str
       Plotly dash style for threshold lines.
   zone_boundary_color : str
       Color for the vertical dotted zone-boundary lines.
   zone_boundary_width : int
       Stroke width (px) for zone boundary lines.
   zone_boundary_dash : str
       Plotly dash style for zone boundary lines.
   colorbar_thickness : int
       Thickness (px) of the LRC-score colorbar.
   colorbar_len : float
       Fractional length of the colorbar relative to the plot height.
   annotation_font_size : int
       Font size (px) used for zone-label annotations above the plot.


   .. py:attribute:: template
      :type:  str
      :value: 'plotly_white'



   .. py:attribute:: font_family
      :type:  str
      :value: 'Inter, Helvetica Neue, Arial, sans-serif'



   .. py:attribute:: font_size
      :type:  int
      :value: 13



   .. py:attribute:: class_colors
      :type:  Dict[str, str]


   .. py:attribute:: fallback_palette
      :type:  List[str]
      :value: ['#e41a1c', '#377eb8', '#4daf4a', '#984ea3', '#ff7f00', '#a65628', '#f781bf', '#999999']



   .. py:attribute:: colorscale
      :type:  str
      :value: 'YlOrRd'



   .. py:attribute:: zone_opacity
      :type:  float
      :value: 0.28



   .. py:attribute:: reference_line_color
      :type:  str
      :value: '#2b2b2b'



   .. py:attribute:: reference_line_width
      :type:  int
      :value: 2



   .. py:attribute:: reference_line_dash
      :type:  str
      :value: 'dash'



   .. py:attribute:: class_line_width
      :type:  int
      :value: 2



   .. py:attribute:: threshold_color
      :type:  str
      :value: '#c0392b'



   .. py:attribute:: threshold_line_width
      :type:  int
      :value: 3



   .. py:attribute:: threshold_line_dash
      :type:  str
      :value: 'dash'



   .. py:attribute:: zone_boundary_color
      :type:  str
      :value: 'rgba(80,80,80,0.25)'



   .. py:attribute:: zone_boundary_width
      :type:  int
      :value: 1



   .. py:attribute:: zone_boundary_dash
      :type:  str
      :value: 'dot'



   .. py:attribute:: colorbar_thickness
      :type:  int
      :value: 15



   .. py:attribute:: colorbar_len
      :type:  float
      :value: 0.75



   .. py:attribute:: annotation_font_size
      :type:  int
      :value: 11



   .. py:method:: resolve_class_color(label: str, _used: list | None = None) -> str

      Return the color for *label*, falling back to the palette if needed.

      Parameters
      ----------
      label : str
          Class label to resolve.
      _used : list, optional
          Mutable list of already-consumed palette colors, used when
          assigning palette colors sequentially across multiple labels.



   .. py:method:: plotly_layout(**overrides) -> dict

      Return a ``fig.update_layout`` kwargs dict with theme base values.

      Any keyword passed as *overrides* takes precedence.



.. py:data:: DEFAULT_THEME

.. py:function:: blend_with_white(rgb_str: str, opacity: float) -> str

   Return the rgb string from compositing *rgb_str* over white at *opacity*.

   Used to match colorscale colors to the actual rendered appearance of zone
   background rectangles, which are drawn with fractional opacity over a white
   plot background.


.. py:function:: build_blended_colorscale(colorscale: str, opacity: float, n_stops: int = 32) -> list

   Build a Plotly colorscale whose colors are pre-blended with white.

   Parameters
   ----------
   colorscale : str
       Plotly colorscale name (e.g. ``'YlOrRd'``).
   opacity : float
       Opacity used when compositing over white.
   n_stops : int
       Number of discrete color stops in the returned colorscale.

   Returns
   -------
   list of [float, str]
       Colorscale in Plotly's ``[[position, color], ...]`` format.