TemperatureCache class

Design utilities using color temperature theory.

Warm/cool queries (warmest, coldest, relativeTemperature) use the Chang-Ou 2026 temperature model. Harmony queries are now delegated to the u'v' vector model: complement is the afterimage complement and analogous walks neighboring u'v' directions. This keeps the historical API while moving complement/analogous off the old warm-cool wheel.

Color science has researched emotion and harmony, which art uses to select colors. See:

  • Li-Chen Ou's Chapter 19 in Handbook of Color Psychology (2015).
  • Josef Albers' Interaction of Color chapters 19 and 21.

The canonical model here is Chang & Ou's chromaticity-based warm-cool model (Color Research & Application, 2026): perceived warmth is the signed distance from the color's CIE 1976 u'v' chromaticity to a neutral line through Illuminant D75 (see rawTemperature). It supersedes the hue-angle models from the same lab — Ou et al. 2004 (used by Material Color Utilities, kept as rawTemperature2004) and the 12-region "universal model" of Ou et al. 2018 (rawTemperature2018) — correlating r ≈ 0.96 with paired-comparison data on both chromatic and near-white stimuli, where the older models were never validated near white.

Material Color Utilities' original implementation evaluated its formula at all 360 hues — 360 invocations of the HCT solver — just to locate the warmest/coolest colors and normalize against them. Besides being slow, the search's answers were dominated by sRGB gamut clamping at high chroma: the "warmest" hue drifted to green-yellow at high chroma and tone, simply because that is where the gamut lets chroma survive.

This implementation instead refits the model in hue space. The Chang-Ou warmth was evaluated on unclamped colors (CAM16 JCH → XYZ and OKLCH → XYZ, no sRGB gamut involved), which shows temperature at fixed chroma and tone is a smooth single-peaked cycle in hue: warmest at red-orange, coolest at blue. Relative temperature is modeled as a "warped cosine" between those two poles, which matches the normalized warmth curve with mean absolute error ≈ 0.06 across chroma and tone — while making every operation here O(1).

Poles per hue space (fit against Chang-Ou 2026, unclamped):

  • CAM16: warm 44, cool 227
  • CAM16 v1.1: warm 40, cool 230
  • OKLCH: warm 43, cool 225

Constructors

TemperatureCache(Hct input)

Properties

coldest → Hct
Coolest color with the same chroma and tone as the input.
no setter
complement → Hct
The color that complements the input, defined physiologically: the afterimage the eye produces after adapting to the input.
no setter
hashCode → int
The hash code for this object.
no setterinherited
input → Hct
final
inputRelativeTemperature → double
Relative temperature of the input color. See relativeTemperature.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
warmest → Hct
Warmest color with the same chroma and tone as the input.
no setter

Methods

analogous({int count = 5, int divisions = 12}) → List<Hct>
A set of colors neighboring the input in u'v' chromatic direction.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
relativeTemperature(Hct hct) → double
Temperature relative to all colors with the same chroma and tone. Value on a scale from 0 to 1.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

coolestHue(ColorModel model) → double
Hue of the coolest color, per hue space of the input's ColorModel.
rawTemperature(Hct color) → double
Perceived warmth of a color: Chang & Ou (2026), the canonical model.
rawTemperature2004(Hct color) → double
Warm-cool per Ou, Woodcock and Wright (2004), in CIELAB — the model Material Color Utilities used. Kept for comparison with newer models.
rawTemperature2018(Hct color) → double
Warm-cool per Ou et al.'s "universal model" (2018), fit to psychophysical data from 12 regions worldwide. Kept for comparison.
warmestHue(ColorModel model) → double
Hue of the warmest color, per hue space of the input's ColorModel.