Skip to content

Color Fundamentals

Colors in Polychromos are defined through the HSLA components: hue, saturation, lightness, and alpha/opacity. This model is more intuitive for artists and designers than RGB.

Colors exist in a cylindrical coordinate space:

  • Hue — the angle on the color wheel (0–360°). This component is cyclical: values past 360° wrap back to 0°.
  • Saturation — the distance from the cylinder axis. A saturation of 0% means no chroma (gray).
  • Lightness — position along the cylinder axis. 50% is the pure chroma; 100% is white, 0% is black.
  • Alpha — opacity, defined outside the cylindrical system.

Constructing colors

from polychromos.color import HSLColor

# Default format: each component in [0.0, 1.0]
color = HSLColor(0.25, 0.85, 0.45)       # hsl(90deg 85% 45%)
color = HSLColor(0.25, 0.85, 0.45, 0.6)  # hsla(90deg 85% 45% / 60%)

# From absolute HSLA: hue [0, 360], sat/light/alpha [0, 100]
color = HSLColor.from_abs_hsla(90, 85, 45)
color = HSLColor.from_abs_hsla(90, 85, 45, 60)

# From RGBA: each component in [0.0, 1.0]
color = HSLColor.from_rgba(0.51, 0.75, 0.1)
color = HSLColor.from_rgba(0.51, 0.75, 0.1, 1.0)

# From absolute RGBA: each component in [0, 255]
color = HSLColor.from_abs_rgba(0x78, 0xac, 0x19)
color = HSLColor.from_abs_rgba(0x78, 0xac, 0x19, 0xff)

# From CSS hexadecimal notation: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
color = HSLColor.from_hex('#78ac19')
color = HSLColor.from_hex('#78ac19ff')

Accessing and modifying components

All components are in the [0.0, 1.0] range and can be read and written directly:

color.hue        = 0.7
color.saturation = 0.95
color.lightness  = 0.5
color.opacity    = 0.35
color.alpha      = 0.35  # alias for opacity

A new color shifted relative to an existing one:

# Shift hue 7.2°, muted 10%, brightened 5%
new_color = color.delta(0.02, -0.1, 0.05)

CSS output

color = HSLColor(0.25, 0.85, 0.45)
color.to_css_hsl()             # hsl(90deg 85% 45%)
color.to_css_hsl(legacy=True)  # hsl(90, 85%, 45%)  — for tools like Plotly
color.to_css_rgb()

Web colors

Standard CSS named colors are available by name (case-insensitive):

from polychromos.color.web import get_web_color

color = get_web_color('Crimson')
color = get_web_color('steelblue')