Color Scales

A color scale is a continuous gradient represented as a list of (position, HSLColor) tuples, where positions are in [0.0, 1.0]. Scales enable smooth color transitions for data visualization.

Creating a color scale

Palette.to_color_scale maps a color sequence to a scale. By default colors are evenly distributed, but an easing function can concentrate them toward the start, end, or both.

from polychromos.color import HSLColor
from polychromos.palette import Palette, HSLColorSequence, HSLColorScale
from polychromos.easing import EasingFunctionId, get_easing_function

danger  = HSLColor.from_abs_hsla(335, 70, 50)
warning = HSLColor.from_abs_hsla(45, 100, 50)
fine    = HSLColor.from_abs_hsla(150, 70, 30)

semaphore = Palette.sequence_from_multiple_cylindrical_interpolation(
    colors=[danger, warning, fine],
    steps=[4, 4],
)

# Even distribution (default)
scale = Palette.to_color_scale(semaphore)

# Ease-in-out: colors concentrate at both ends
scale = Palette.to_color_scale(
    semaphore,
    get_easing_function(EasingFunctionId.EASE_IN_OUT_QUAD),
)

Picking a color from a scale

scale_lerp samples the scale at any position within a given data range. It interpolates linearly within the appropriate scale segment.

# Map data range [10.0, 45.5] to the scale and sample at position 32.6
picked: HSLColor = Palette.scale_lerp(scale, (10.0, 45.5), 32.6)

The range parameter makes it convenient to use directly with raw data values without manual normalization.

Extracting a sequence from a scale

Pick N evenly-spaced colors from a scale to obtain a new discrete sequence:

sequence_4  = Palette.color_scale_to_color_sequence(scale, 4)
sequence_15 = Palette.color_scale_to_color_sequence(scale, 15)

This is the recommended way to change the number of steps in a sequence that was built from multiple sub-sequences with different interpolation methods.