Skip to content

Color Sequences

A color sequence is a list[HSLColor]. The Palette class provides two families of sequence factories: those built from a single reference color with deltas, and those built by interpolating between two or more colors.

From a reference color

sequence_from_deltas builds a sequence by repeatedly applying component shifts, starting from the reference color. Each step applies the delta to the previous color.

from polychromos.color import HSLColor
from polychromos.palette import Palette, HSLColorSequence

ref = HSLColor(0.25, 1.0, 0.5)  # hsl(90deg 100% 50%)

sequence = Palette.sequence_from_deltas(
    ref,
    3,      # steps before the reference color
    3,      # steps after the reference color
    0.025,  # 9° hue shift per step
    0.0,    # no saturation shift
    -0.05,  # −5% lightness per step (brighter before, darker after)
)
# Result: 7 colors (3 before + reference + 3 after)

The analogous color harmony scheme is a special case with a small hue delta and no other shifts:

analogous = Palette.sequence_from_deltas(ref, 2, 2, 15.0 / 360.0, 0.0, 0.0)

Interpolation

Two interpolation strategies are available:

Linear interpolation (lerp)

Colors are projected to Cartesian space and interpolated along a straight line. When start and end colors are opposite on the hue wheel, intermediate colors pass through gray.

red  = HSLColor.from_abs_hsla(0, 100, 50)
cyan = HSLColor.from_abs_hsla(180, 100, 50)

Palette.lerp(red, cyan, 0.4)  # reddish gray
Palette.lerp(red, cyan, 0.6)  # cyanish gray

Cylindrical slerp

Each HSLA component is interpolated independently in cylindrical space. Intermediate saturation stays within the range of the two endpoints. Requires a path strategy for the hue direction.

green   = HSLColor.from_abs_hsla(120, 100, 50)
blue    = HSLColor.from_abs_hsla(240, 100, 50)
magenta = HSLColor.from_abs_hsla(300, 100, 50)

Palette.cylindrical_slerp(red, green, 0.5)  # yellow (shortest path)
Palette.cylindrical_slerp(red, blue, 0.5)   # magenta (shortest path)

Path strategies (Palette.CylindricalInterpolationPath):

Strategy Hue direction
FORWARD Always clockwise
BACKWARD Always counter-clockwise
SHORTEST Whichever arc is shorter (default)
LONGEST Whichever arc is longer

Elliptical interpolation

A blend between linear and cylindrical interpolation controlled by a straightening factor: 0.0 is purely cylindrical, 1.0 is purely linear. Useful when linear is too muted and cylindrical is too vivid.

Sequence factory methods

Build a full sequence of N colors between a start and end color:

# Linear: red, reddish-gray, gray, cyanish-gray, cyan
Palette.sequence_from_linear_interpolation(red, cyan, 5)

# Cylindrical (forward): red, yellow, green
Palette.sequence_from_cylindrical_interpolation(
    red, green, 3,
    path_strategy=Palette.CylindricalInterpolationPath.FORWARD,
)

# Cylindrical (backward): red, magenta, blue
Palette.sequence_from_cylindrical_interpolation(
    red, green, 3,
    path_strategy=Palette.CylindricalInterpolationPath.BACKWARD,
)

Open-ended sequences

All factory methods accept open_ended=True to exclude the final color. This allows consecutive sequences to be concatenated without duplicating the joining color.

Multi-segment sequences

The sequence_from_multiple_* variants accept a list of N colors and N−1 step counts, producing a sequence made of N−1 sub-sequences joined together:

yellow = HSLColor.from_abs_hsla(60, 100, 50)

# red → yellow (3 steps) + yellow → blue (4 steps) = red, orange, yellow, green, cyan, blue
Palette.sequence_from_multiple_cylindrical_interpolation(
    colors=[red, yellow, blue],
    steps=[3, 4],
)

# red → green → blue → red, each segment using linear interpolation
Palette.sequence_from_multiple_linear_interpolation(
    colors=[red, green, blue, red],
    steps=[3, 3, 3],
)

Available multi-segment variants:

  • sequence_from_multiple_linear_interpolation
  • sequence_from_multiple_cylindrical_interpolation
  • sequence_from_multiple_elliptical_interpolation