san-diego 0.2.0

Utilities for working with colors and Plotly-friendly palettes.

san-diego

Small Python utilities for working with colors, image palettes, and Plotly-friendly color output. Install with pip install san-diego and import with import sd.

Notebook Workflow

There is a starter notebook at notebooks/color_playground.ipynb.

Install notebook tooling:

uv sync --group dev

Launch JupyterLab:

uv run --group dev jupyter lab

Features

• Extract dominant colors from an image.
• Convert between RGB, HEX, and HSL.
• Lighten or darken a color by a percentage.
• Build Plotly colorscales and color sequences.
• Save, load, and reuse named color schemes with consistent roles.
• Use Color and ColorScale classes for structured color handling.

Example

from sd import (
    Color,
    ColorScheme,
    ColorSequence,
    ColorScale,
    build_plotly_colorscale,
    build_plotly_colorscale_from_scheme,
    color_swatches,
    get_color_scheme,
    get_color_sequence,
    extract_dominant_colors,
    extract_dominant_hex_colors,
    list_color_scheme_roles,
    save_color_scheme,
)

brand = Color.from_hex("#1f77b4")

brand.to_rgb()
# (31, 119, 180)

brand.to_hsl()
# (204.6, 0.706161, 0.413725)

brand.lighten(20).to_hex()
# '#4c92c3'

brand.as_plotly_rgb()
# 'rgb(31, 119, 180)'

scale = ColorScale.from_colors(["#0d3b66", "#faf0ca", "#f95738"])
scale.to_plotly()
# [[0.0, '#0d3b66'], [0.5, '#faf0ca'], [1.0, '#f95738']]

build_plotly_colorscale(["#000000", "#ffffff"])
# [[0.0, '#000000'], [1.0, '#ffffff']]

extract_dominant_colors("example.png", count=3)
# [Color(...), Color(...), Color(...)]

extract_dominant_hex_colors("example.png", count=3)
# ['#...', '#...', '#...']

color_swatches(["#1f77b4", "rgb(255, 127, 14)", (44, 160, 44)])
# In Jupyter, renders labeled color swatches.

scheme = get_color_scheme("ocean")
list_color_scheme_roles()
# ['primary', 'secondary', 'accent', 'dark', 'light', 'blue', 'purple', 'red', 'orange', 'yellow', 'green']

scheme.to_hex_map()
# {
#   'primary': '#3a506b',
#   'secondary': '#5bc0be',
#   'accent': '#c5f3f0',
#   'dark': '#0b132b',
#   'light': '#e9fffe',
#   'blue': '#3a6ea5',
#   'purple': '#6a4c93',
#   'red': '#c44536',
#   'orange': '#d97d54',
#   'yellow': '#d8c36a',
#   'green': '#4c956c',
# }

sequence = get_color_sequence("blue")
sequence.to_hex_list()
# ['#ffffff', '#d5e2f0', '#aac5e1', '#80a8d2', '#558bc3', '#3a6ea5', '#2e5884', '#234263', '#172c42', '#0c1621', '#000000']

ColorSequence.from_color("brand-blue", "#336699").to_plotly_sequence()
# ['#ffffff', '#d1e0f0', '#a3c2e0', '#75a3d1', '#4785c2', '#336699', '#29527a', '#1f3d5c', '#14293d', '#0a141f', '#000000']

save_color_scheme(
    "brand",
    {
        "primary": "#112233",
        "secondary": "#445566",
        "accent": "#778899",
        "dark": "#0a0f14",
        "light": "#f5f7fa",
        "blue": "#4f74c8",
        "purple": "#7f5ab6",
        "red": "#bf4b4b",
        "orange": "#d88752",
        "yellow": "#d8c15e",
        "green": "#4d8b68",
    },
    "brand.json",
)

ColorScheme.from_reference("brand.json").to_plotly_colorscale()
# [[0.0, '#112233'], [0.1, '#445566'], [0.2, '#778899'], [0.3, '#0a0f14'], [0.4, '#f5f7fa'], [0.5, '#4f74c8'], [0.6, '#7f5ab6'], [0.7, '#bf4b4b'], [0.8, '#d88752'], [0.9, '#d8c15e'], [1.0, '#4d8b68']]

build_plotly_colorscale_from_scheme("sunset")
# [[0.0, '#e9724c'], [0.1, '#ffc857'], [0.2, '#c5283d'], [0.3, '#1f2041'], [0.4, '#fff1d6'], [0.5, '#4d6cfa'], [0.6, '#7b5ea7'], [0.7, '#c5283d'], [0.8, '#e9724c'], [0.9, '#ffc857'], [1.0, '#7aa67a']]