geeViz.outputLib.themes¶

Unified theme system for geeViz output libraries.

Provides a Theme class that holds all resolved color values for backgrounds, text, accents, borders, and chart styling. Used by charts, thumbs, and reports for consistent colors.

Usage:

from geeViz.outputLib.themes import get_theme

# Named presets
dark  = get_theme("dark")
light = get_theme("light")
teal  = get_theme("teal")

# Auto-generate from a single color
red_bg = get_theme(bg_color="#F00")           # dark text auto-picked
custom = get_theme(bg_color="#1a1a2e", font_color="#eee")

# Access colors in different formats
dark.bg_hex          # '#272822'
dark.bg_rgb          # (39, 40, 34)
dark.text_hex        # '#f8f8f2'
dark.is_dark         # True
dark.grid_rgba       # 'rgba(248,248,242,0.15)'

Functions

`apply_matplotlib_theme`(obj[, theme, ...])	Best-effort theming for a matplotlib Figure, Axes, or seaborn Grid.
`apply_plotly_theme`(fig[, theme, bg_color, ...])	Apply a theme's colors to a Plotly figure in-place.
`apply_theme`(chart[, theme, bg_color, font_color])	Apply the geeViz theme to a chart from any supported library.
`get_default_theme`()	Return the module-level default `Theme` (dark theme).
`get_theme`([theme, bg_color, font_color])	Resolve a `Theme` from a preset name, instance, or custom colors.
`register_preset`(name, theme)	Register a named theme preset for later retrieval via `get_theme()`.
`set_default_theme`(name)	Set the theme name used when `apply_theme` / `theme()` are called with no explicit theme argument.
`theme`([name, bg_color, font_color])	Return a context manager that themes matplotlib for the `with` block.

Classes

Theme(bg, text[, accent, highlight, ...])

Resolved color theme for geeViz visualizations.

class geeViz.outputLib.themes.Theme(bg, text, accent=None, highlight=None, surface=None, border=None, divider=None, swatch_outline=None, muted_text=None, is_dark=None, title_font_size=18, label_font_size=12, font_family='Roboto Condensed')[source]¶

Bases: object

Resolved color theme for geeViz visualizations.

A Theme holds all of the resolved color values needed to style charts, thumbnails, reports, and other geeViz outputs consistently. All colors are stored internally as (R, G, B) tuples with integer components in the 0–255 range. Convenience properties provide hex-string, RGB-tuple, and RGBA-string formats for direct use in Plotly layouts, HTML/CSS, and Pillow operations.

Colors that are not explicitly provided to the constructor are automatically derived from the bg and text colors using perceptually reasonable blending and HSL manipulation.

bg¶

Background color as an (R, G, B) tuple.

Type:: tuple

text¶

Primary text/foreground color as an (R, G, B) tuple.

Type:: tuple

accent¶

Accent color for headings and links as an (R, G, B) tuple. Derived from text if not provided.

Type:: tuple

highlight¶

Highlight/emphasis color as an (R, G, B) tuple. Derived from accent if not provided.

Type:: tuple

surface¶

Card or panel background color, slightly offset from bg, as an (R, G, B) tuple.

Type:: tuple

border¶

Border and table-line color as an (R, G, B) tuple.

Type:: tuple

divider¶

Subtle separator/divider color as an (R, G, B) tuple.

Type:: tuple

swatch_outline¶

Legend swatch outline color as an (R, G, B) tuple.

Type:: tuple

muted_text¶

Secondary/caption text color as an (R, G, B) tuple.

Type:: tuple

is_dark¶

True if this is a dark-background theme (background luminance < 128).

Type:: bool

Example

>>> from geeViz.outputLib.themes import Theme
>>> t = Theme(bg=(39, 40, 34), text=(248, 248, 242))
>>> t.is_dark
True
>>> t.bg_hex
'#272822'

Initialize a Theme with explicit or auto-derived colors.

Any color parameter that is None will be automatically derived from bg and text using perceptually reasonable defaults (blending, HSL shifts, etc.).

Parameters:

bg (tuple) – Background color as an (R, G, B) tuple or list with integer values 0–255.
text (tuple) – Primary text color as an (R, G, B) tuple or list with integer values 0–255.
accent (tuple, optional) – Accent color for headings/links. Defaults to None (auto-derived from text).
highlight (tuple, optional) – Highlight/emphasis color. Defaults to None (auto-derived from accent).
surface (tuple, optional) – Card/panel background color. Defaults to None (auto-derived by blending bg slightly toward white or black).
border (tuple, optional) – Border/table-line color. Defaults to None (30 % blend of bg toward text).
divider (tuple, optional) – Subtle separator color. Defaults to None (15 % blend of bg toward text).
swatch_outline (tuple, optional) – Legend swatch outline color. Defaults to None (25 % blend of bg toward text).
muted_text (tuple, optional) – Secondary/caption text color. Defaults to None (55 % blend of bg toward text).
is_dark (bool, optional) – Force dark/light classification. Defaults to None (auto-detected from bg luminance).

Returns:

A fully resolved theme instance.

Return type:

Theme

Example

>>> t = Theme(bg=(0, 0, 0), text=(255, 255, 255))
>>> t.is_dark
True
>>> t.border  # auto-derived
(77, 77, 77)

bg¶

text¶

is_dark¶

accent¶

highlight¶

surface¶

border¶

divider¶

swatch_outline¶

muted_text¶

title_font_size¶

label_font_size¶

font_family¶

property legend_title_font_size¶: Legend title font size (1.15x label size).

property bg_hex¶

Return the background color as a hex string.

Returns:: Background color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(39, 40, 34), text=(248, 248, 242)).bg_hex
'#272822'

property text_hex¶

Return the text color as a hex string.

Returns:: Text color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(39, 40, 34), text=(248, 248, 242)).text_hex
'#f8f8f2'

property accent_hex¶

Return the accent color as a hex string.

Returns:: Accent color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255), accent=(0, 191, 165)).accent_hex
'#00bfa5'

property highlight_hex¶

Return the highlight color as a hex string.

Returns:: Highlight color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255), highlight=(255, 131, 76)).highlight_hex
'#ff834c'

property surface_hex¶

Return the surface/panel color as a hex string.

Returns:: Surface color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(255, 255, 255), text=(0, 0, 0)).surface_hex
'#f5f5f5'

property border_hex¶

Return the border color as a hex string.

Returns:: Border color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).border_hex
'#4d4d4d'

property divider_hex¶

Return the divider color as a hex string.

Returns:: Divider color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).divider_hex
'#262626'

property muted_text_hex¶

Return the muted text color as a hex string.

Returns:: Muted text color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).muted_text_hex
'#8c8c8c'

property swatch_outline_hex¶

Return the swatch outline color as a hex string.

Returns:: Swatch outline color in '#RRGGBB' format.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).swatch_outline_hex
'#404040'

property bg_rgb¶

Return the background color as an RGB tuple.

This is an alias for the bg attribute, provided for symmetry with the *_hex properties.

Returns:: Background color as (R, G, B) with values 0–255.
Return type:: tuple

Example

>>> Theme(bg=(39, 40, 34), text=(248, 248, 242)).bg_rgb
(39, 40, 34)

property text_rgb¶

Return the text color as an RGB tuple.

This is an alias for the text attribute, provided for symmetry with the *_hex properties.

Returns:: Text color as (R, G, B) with values 0–255.
Return type:: tuple

Example

>>> Theme(bg=(39, 40, 34), text=(248, 248, 242)).text_rgb
(248, 248, 242)

property grid_rgba¶

Return a chart gridline color with appropriate alpha.

Uses an alpha of 0.15 for dark themes and 0.1 for light themes to keep gridlines subtle against the background.

Returns:: RGBA color string, e.g. 'rgba(248,248,242,0.15)'.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).grid_rgba
'rgba(255,255,255,0.15)'

property line_rgba¶

Return a chart axis line color with appropriate alpha.

Uses an alpha of 0.25 for dark themes and 0.2 for light themes.

Returns:: RGBA color string, e.g. 'rgba(248,248,242,0.25)'.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).line_rgba
'rgba(255,255,255,0.25)'

property zeroline_rgba¶

Return a chart zero-line color with appropriate alpha.

Uses an alpha of 0.2 for dark themes and 0.15 for light themes.

Returns:: RGBA color string, e.g. 'rgba(248,248,242,0.2)'.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).zeroline_rgba
'rgba(255,255,255,0.2)'

property surface_rgba¶

Return the surface color with alpha for table row striping.

Uses an alpha of 0.5 for dark themes and 0.3 for light themes so that alternating rows are visible but not overpowering.

Returns:: RGBA color string for the surface, e.g. 'rgba(55,46,44,0.5)'.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).surface_rgba
'rgba(15,15,15,0.5)'

property error_bg_rgba¶

Return an error-box background color with appropriate alpha.

Uses the highlight color with an alpha of 0.1 for dark themes and 0.08 for light themes, producing a tinted but unobtrusive error background.

Returns:: RGBA color string for the error background.
Return type:: str

Example

>>> t = Theme(bg=(0, 0, 0), text=(255, 255, 255),
...           highlight=(255, 0, 0))
>>> t.error_bg_rgba
'rgba(255,0,0,0.1)'

property tooltip_bg_rgba¶

Return a tooltip background as a semi-transparent inverse of bg.

Dark themes get a near-black tooltip (rgba(0,0,0,0.85)); light themes get a near-white tooltip (rgba(255,255,255,0.92)).

Returns:: RGBA color string for tooltip backgrounds.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).tooltip_bg_rgba
'rgba(0,0,0,0.85)'

property button_bg_rgba¶

Return a toolbar button background color.

Uses the muted text color at 15 % opacity.

Returns:: RGBA color string for button backgrounds.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).button_bg_rgba
'rgba(140,140,140,0.15)'

property button_hover_rgba¶

Return a toolbar button hover background color.

Uses the muted text color at 30 % opacity.

Returns:: RGBA color string for button hover backgrounds.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).button_hover_rgba
'rgba(140,140,140,0.3)'

property button_border_rgba¶

Return a toolbar button border color.

Uses the muted text color at 30 % opacity.

Returns:: RGBA color string for button borders.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).button_border_rgba
'rgba(140,140,140,0.3)'

property link_stroke_rgba¶

Return a Sankey link stroke color for gradient edges.

Dark themes use a faint white stroke (rgba(255,255,255,0.15)); light themes use a faint black stroke (rgba(0,0,0,0.08)).

Returns:: RGBA color string for Sankey link strokes.
Return type:: str

Example

>>> Theme(bg=(0, 0, 0), text=(255, 255, 255)).link_stroke_rgba
'rgba(255,255,255,0.15)'

geeViz.outputLib.themes.register_preset(name, theme)[source]¶

Presets are stored in a module-level dictionary keyed by the lower-cased name. Calling this function with a name that already exists will overwrite the previous preset.

Parameters:

name (str) – Preset name (e.g. "dark", "ocean"). Stored in lower case.
theme (Theme) – A Theme instance to register.

Returns:

None

Example

>>> t = Theme(bg=(0, 0, 0), text=(255, 255, 255))
>>> register_preset("midnight", t)
>>> get_theme("midnight").bg_hex
'#000000'

geeViz.outputLib.themes.get_theme(theme=None, bg_color=None, font_color=None)[source]¶

Resolve a Theme from a preset name, instance, or custom colors.

This is the main entry point for obtaining a theme. It accepts a preset name ("dark", "light", "teal"), a Theme instance (pass-through), a color string or tuple (treated as bg_color), or None. When bg_color and/or font_color are also supplied alongside a preset, they override the preset’s background and text colors respectively, and accent/highlight are re-derived from the new colors.

Parameters:

theme (str or Theme or tuple or None, optional) – A preset name ("dark", "light", "teal"), a Theme instance (returned as-is unless overrides are given), a color string or (R, G, B) tuple (treated as bg_color), or None. Defaults to None.
bg_color (str or tuple, optional) – Background color override in any format accepted by resolve_color(). Overrides the preset’s background when combined with theme. Defaults to None.
font_color (str or tuple, optional) – Text/font color override in any format accepted by resolve_color(). Overrides the preset’s text when combined with theme. Defaults to None.

Returns:

A fully resolved Theme instance.

Return type:

Theme

Example

>>> get_theme("dark").bg_hex
'#272822'
>>> get_theme("light").is_dark
False
>>> get_theme(bg_color="#F00").is_dark
True
>>> get_theme("dark", font_color="yellow").text_hex
'#ffff00'

geeViz.outputLib.themes.apply_plotly_theme(fig, theme=None, bg_color=None, font_color=None)[source]¶

Apply a theme’s colors to a Plotly figure in-place.

Resolves a Theme from the provided arguments (using get_theme()) and then updates the figure’s layout – including paper/plot background, font colors, axis grid/line/zeroline colors, title, legend, and annotation colors – to match the theme.

Parameters:

fig (plotly.graph_objects.Figure) – The Plotly figure to style. Modified in-place.
theme (str or Theme or tuple or None, optional) – Preset name, Theme instance, or color string/tuple. Passed through to get_theme(). Defaults to None.
bg_color (str or tuple, optional) – Background color override. Defaults to None.
font_color (str or tuple, optional) – Font color override. Defaults to None.

Returns:

The same figure, modified in-place, for method chaining convenience.

Return type:

plotly.graph_objects.Figure

Example

>>> import plotly.graph_objects as go
>>> fig = go.Figure(data=[go.Bar(x=[1, 2], y=[3, 4])])
>>> fig = apply_plotly_theme(fig, "dark")
>>> fig.layout.paper_bgcolor
'#272822'

geeViz.outputLib.themes.set_default_theme(name)[source]¶

Set the theme name used when apply_theme / theme() are called with no explicit theme argument.

Typical use: the agent calls this once per request based on the user’s chat-UI theme (dark/light), and any subsequent chart code in that request picks up the right theme automatically.

geeViz.outputLib.themes.get_default_theme()[source]¶

Return the module-level default Theme (dark theme).

Used by reports.py and other consumers when no explicit theme argument is passed. Change set_default_theme("light") to switch process-wide.

Returns:: The active default theme instance.
Return type:: Theme

geeViz.outputLib.themes.apply_matplotlib_theme(obj, theme=None, bg_color=None, font_color=None)[source]¶

Best-effort theming for a matplotlib Figure, Axes, or seaborn Grid.

Walks the object’s artists and updates facecolors, text colors, spine/tick/grid colors, and legend colors to match the theme. Returns the object unchanged in shape so calls can be chained.

For best results, set the theme BEFORE plotting via the theme() context manager — matplotlib’s styling is global rcParams state and post-hoc theming has to walk every artist (which works for most common plot types but can miss exotic ones).

geeViz.outputLib.themes.apply_theme(chart, theme=None, bg_color=None, font_color=None)[source]¶

Apply the geeViz theme to a chart from any supported library.

Detects the chart type and routes to the appropriate themer: - Plotly Figure → apply_plotly_theme() - Matplotlib Figure/Axes → apply_matplotlib_theme() - Seaborn FacetGrid/PairGrid/JointGrid → unwrap, then matplotlib - Anything else → return unchanged with a one-line warning

Parameters:

chart – The chart object (any of the above).
theme – Theme name, Theme instance, or color string. Defaults to whatever get_default_theme() returns.
font_color (bg_color /) – Optional overrides passed to get_theme.

Returns:

The same chart object, themed in-place where applicable.

Example

>>> import seaborn as sns
>>> fig = sns.heatmap(corr).get_figure()
>>> fig = apply_theme(fig)           # matches the chat UI
>>> # ... or with explicit override:
>>> fig = apply_theme(fig, theme="light")

geeViz.outputLib.themes.theme(name=None, bg_color=None, font_color=None)[source]¶

Return a context manager that themes matplotlib for the with block.

See _ThemeContext.