use crossterm::style::Color;
#[derive(Debug, Clone, PartialEq)]
pub struct Palette {
stops: Vec<Color>,
}
impl Palette {
pub fn new(stops: Vec<Color>) -> Self {
let stops = if stops.is_empty() {
vec![Color::White]
} else {
stops
};
Self { stops }
}
pub fn from_rgb(stops: Vec<[f32; 3]>) -> Self {
Self::new(
stops
.into_iter()
.map(|rgb| Color::Rgb {
r: (rgb[0].clamp(0.0, 1.0) * 255.0).round() as u8,
g: (rgb[1].clamp(0.0, 1.0) * 255.0).round() as u8,
b: (rgb[2].clamp(0.0, 1.0) * 255.0).round() as u8,
})
.collect(),
)
}
pub fn len(&self) -> usize {
self.stops.len()
}
pub fn is_empty(&self) -> bool {
self.stops.is_empty()
}
pub fn sample(&self, t: f32) -> Color {
let t = if t.is_nan() { 0.0 } else { t.clamp(0.0, 1.0) };
if self.stops.len() == 1 {
return self.stops[0];
}
let scaled = t * (self.stops.len() - 1) as f32;
let index = scaled.floor() as usize;
let index = index.min(self.stops.len() - 2);
let fraction = scaled - index as f32;
lerp(self.stops[index], self.stops[index + 1], fraction)
}
pub fn sample_index(&self, index: usize) -> Color {
self.stops[index % self.stops.len()]
}
pub fn sample_rgb(&self, t: f32) -> [f32; 3] {
match self.sample(t) {
Color::Rgb { r, g, b } => {
[r as f32 / 255.0, g as f32 / 255.0, b as f32 / 255.0]
}
_ => [1.0, 1.0, 1.0],
}
}
pub fn sample_wrapped(&self, t: f32) -> Color {
let t = if t.is_nan() { 0.0 } else { t.rem_euclid(1.0) };
self.sample(t)
}
pub fn sample_rgb_wrapped(&self, t: f32) -> [f32; 3] {
match self.sample_wrapped(t) {
Color::Rgb { r, g, b } => {
[r as f32 / 255.0, g as f32 / 255.0, b as f32 / 255.0]
}
_ => [1.0, 1.0, 1.0],
}
}
pub fn named(name: &str) -> Option<Palette> {
presets::by_name(name).map(|stops| Palette::new(stops.to_vec()))
}
pub fn preset_names() -> Vec<&'static str> {
presets::ALL.iter().map(|(name, _)| *name).collect()
}
pub fn truncated_at_peak(&self) -> Palette {
let mut peak = 0usize;
let mut best = f32::NEG_INFINITY;
for (i, color) in self.stops.iter().enumerate() {
let luma = luminance(*color);
if luma > best {
best = luma;
peak = i;
}
}
Palette::new(self.stops[..=peak].to_vec())
}
pub fn stops(&self) -> &[Color] {
&self.stops
}
pub fn expand(&self, n: usize) -> Vec<Color> {
let n = n.max(2);
(0..n)
.map(|i| self.sample(i as f32 / (n - 1) as f32))
.collect()
}
}
pub fn lerp(a: Color, b: Color, t: f32) -> Color {
let t = if t.is_nan() { 0.0 } else { t.clamp(0.0, 1.0) };
match (a, b) {
(
Color::Rgb {
r: r0,
g: g0,
b: b0,
},
Color::Rgb {
r: r1,
g: g1,
b: b1,
},
) => Color::Rgb {
r: lerp_u8(r0, r1, t),
g: lerp_u8(g0, g1, t),
b: lerp_u8(b0, b1, t),
},
(a, b) => match (named_rgb(a), named_rgb(b)) {
(Some((r0, g0, b0)), Some((r1, g1, b1))) => Color::Rgb {
r: lerp_u8(r0, r1, t),
g: lerp_u8(g0, g1, t),
b: lerp_u8(b0, b1, t),
},
_ => {
if t < 0.5 {
a
} else {
b
}
}
},
}
}
fn named_rgb(color: Color) -> Option<(u8, u8, u8)> {
Some(match color {
Color::Rgb { r, g, b } => (r, g, b),
Color::Black => (0, 0, 0),
Color::DarkGrey => (128, 128, 128),
Color::Red => (170, 0, 0),
Color::DarkRed => (170, 0, 0),
Color::Green => (0, 170, 0),
Color::DarkGreen => (0, 170, 0),
Color::Yellow => (170, 170, 0),
Color::DarkYellow => (170, 170, 0),
Color::Blue => (0, 0, 170),
Color::DarkBlue => (0, 0, 170),
Color::Magenta => (170, 0, 170),
Color::DarkMagenta => (170, 0, 170),
Color::Cyan => (0, 170, 170),
Color::DarkCyan => (0, 170, 170),
Color::Grey => (170, 170, 170),
Color::White => (255, 255, 255),
_ => return None,
})
}
#[inline]
fn lerp_u8(a: u8, b: u8, t: f32) -> u8 {
(a as f32 + (b as f32 - a as f32) * t)
.round()
.clamp(0.0, 255.0) as u8
}
pub fn luminance(color: Color) -> f32 {
let (r, g, b) = named_rgb(color).unwrap_or((0, 0, 0));
(0.2126 * r as f32 + 0.7152 * g as f32 + 0.0722 * b as f32) / 255.0
}
pub fn oklab_hue(lightness: f32, chroma: f32, hue: f32) -> Color {
let lightness = if lightness.is_nan() {
0.75
} else {
lightness.clamp(0.0, 1.0)
};
let chroma = if chroma.is_nan() {
0.0
} else {
chroma.max(0.0)
};
let hue = if hue.is_nan() { 0.0 } else { hue } * std::f32::consts::TAU;
let (r, g, b) =
oklab_to_srgb(lightness, chroma * hue.cos(), chroma * hue.sin());
Color::Rgb { r, g, b }
}
fn oklab_to_srgb(l: f32, a: f32, b: f32) -> (u8, u8, u8) {
let l_ = l + 0.396_337_8 * a + 0.215_803_8 * b;
let m_ = l - 0.105_561_3 * a - 0.063_854_2 * b;
let s_ = l - 0.089_484_2 * a - 1.291_485_5 * b;
let (l3, m3, s3) = (l_.powi(3), m_.powi(3), s_.powi(3));
let r = 4.076_742 * l3 - 3.307_711_6 * m3 + 0.230_969_9 * s3;
let g = -1.268_438 * l3 + 2.609_757_4 * m3 - 0.341_319_38 * s3;
let b = -0.004_196_1 * l3 - 0.703_418_6 * m3 + 1.707_614_7 * s3;
let encode = |v: f32| -> u8 {
let v = v.clamp(0.0, 1.0);
let s = if v <= 0.0031308 {
v * 12.92
} else {
1.055 * v.powf(1.0 / 2.4) - 0.055
};
(s * 255.0).round() as u8
};
(encode(r), encode(g), encode(b))
}
pub fn shade(color: Color, value: f32) -> Color {
match color {
Color::Rgb { r, g, b } => {
let k = if value.is_nan() {
1.0
} else {
value.clamp(0.0, 1.0)
};
Color::Rgb {
r: (r as f32 * k).round() as u8,
g: (g as f32 * k).round() as u8,
b: (b as f32 * k).round() as u8,
}
}
other => other,
}
}
pub fn perceptual_distance(a: Color, b: Color) -> f32 {
let (ar, ag, ab) = named_rgb(a).unwrap_or((0, 0, 0));
let (br, bg, bb) = named_rgb(b).unwrap_or((0, 0, 0));
let (al, aa, ac) = oklab((ar, ag, ab));
let (bl, ba, bc) = oklab((br, bg, bb));
let (dl, da, dc) = (al - bl, aa - ba, ac - bc);
(dl * dl + da * da + dc * dc).sqrt()
}
fn oklab((r, g, b): (u8, u8, u8)) -> (f32, f32, f32) {
fn lin(v: u8) -> f32 {
let v = v as f32 / 255.0;
if v <= 0.04045 {
v / 12.92
} else {
((v + 0.055) / 1.055).powf(2.4)
}
}
let (r, g, b) = (lin(r), lin(g), lin(b));
let l = 0.412_221_5 * r + 0.536_332_5 * g + 0.051_446 * b;
let m = 0.211_903_5 * r + 0.680_699_5 * g + 0.107_397 * b;
let s = 0.088_302_5 * r + 0.281_718_8 * g + 0.629_978_7 * b;
let (l_, m_, s_) = (l.cbrt(), m.cbrt(), s.cbrt());
(
0.210_454_3 * l_ + 0.793_617_8 * m_ - 0.004_072_047 * s_,
1.977_998_5 * l_ - 2.428_592_2 * m_ + 0.450_593_7 * s_,
0.025_904 * l_ + 0.782_771_8 * m_ - 0.808_675_8 * s_,
)
}
pub fn greyscale() -> Palette {
Palette::from_rgb(vec![[0.0, 0.0, 0.0], [1.0, 1.0, 1.0]])
}
pub mod presets {
use crossterm::style::Color::{self, Rgb};
pub const DEPTH: &[Color] = &[
Rgb { r: 0, g: 7, b: 100 },
Rgb {
r: 32,
g: 107,
b: 203,
},
Rgb {
r: 237,
g: 255,
b: 255,
},
Rgb {
r: 255,
g: 170,
b: 0,
},
Rgb { r: 204, g: 0, b: 0 },
Rgb { r: 16, g: 8, b: 40 },
];
pub const EMBER: &[Color] = &[
Rgb { r: 0, g: 0, b: 0 },
Rgb { r: 120, g: 0, b: 0 },
Rgb {
r: 200,
g: 60,
b: 0,
},
Rgb {
r: 255,
g: 160,
b: 0,
},
Rgb {
r: 255,
g: 240,
b: 160,
},
Rgb {
r: 255,
g: 255,
b: 255,
},
Rgb {
r: 255,
g: 160,
b: 0,
},
Rgb {
r: 200,
g: 60,
b: 0,
},
Rgb { r: 120, g: 0, b: 0 },
];
pub const OCEAN: &[Color] = &[
Rgb { r: 0, g: 0, b: 20 },
Rgb {
r: 0,
g: 40,
b: 120,
},
Rgb {
r: 0,
g: 130,
b: 190,
},
Rgb {
r: 60,
g: 210,
b: 220,
},
Rgb {
r: 220,
g: 250,
b: 255,
},
Rgb {
r: 60,
g: 210,
b: 220,
},
Rgb {
r: 0,
g: 130,
b: 190,
},
Rgb {
r: 0,
g: 40,
b: 120,
},
Rgb { r: 0, g: 10, b: 50 },
];
pub const MAGMA: &[Color] = &[
Rgb { r: 0, g: 0, b: 4 },
Rgb {
r: 81,
g: 18,
b: 124,
},
Rgb {
r: 183,
g: 55,
b: 121,
},
Rgb {
r: 252,
g: 137,
b: 97,
},
Rgb {
r: 254,
g: 224,
b: 181,
},
Rgb {
r: 252,
g: 253,
b: 191,
},
Rgb {
r: 254,
g: 224,
b: 181,
},
Rgb {
r: 252,
g: 137,
b: 97,
},
Rgb {
r: 183,
g: 55,
b: 121,
},
Rgb {
r: 81,
g: 18,
b: 124,
},
];
pub const CONTRAST: &[Color] = &[
Rgb { r: 0, g: 0, b: 0 },
Rgb {
r: 255,
g: 255,
b: 255,
},
];
pub const ALL: &[(&str, &[Color])] = &[
("depth", DEPTH),
("ember", EMBER),
("ocean", OCEAN),
("magma", MAGMA),
("contrast", CONTRAST),
];
pub fn by_name(name: &str) -> Option<&'static [Color]> {
ALL.iter()
.find(|(preset, _)| preset.eq_ignore_ascii_case(name))
.map(|(_, stops)| *stops)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn rgb(r: u8, g: u8, b: u8) -> Color {
Color::Rgb { r, g, b }
}
#[test]
fn the_endpoints_are_exact() {
let palette = Palette::new(vec![rgb(0, 0, 0), rgb(255, 255, 255)]);
assert_eq!(palette.sample(0.0), rgb(0, 0, 0));
assert_eq!(palette.sample(1.0), rgb(255, 255, 255));
}
#[test]
fn the_middle_is_the_middle() {
let palette = Palette::new(vec![rgb(0, 0, 0), rgb(200, 100, 50)]);
assert_eq!(palette.sample(0.5), rgb(100, 50, 25));
}
#[test]
fn an_overshoot_saturates_rather_than_wrapping() {
let palette = Palette::new(vec![rgb(255, 0, 0), rgb(0, 0, 255)]);
assert_eq!(palette.sample(1.5), rgb(0, 0, 255));
assert_eq!(palette.sample(-0.5), rgb(255, 0, 0));
assert_eq!(palette.sample(f32::NAN), rgb(255, 0, 0));
}
#[test]
fn a_single_stop_is_flat() {
let palette = Palette::new(vec![rgb(10, 20, 30)]);
assert_eq!(palette.sample(0.0), rgb(10, 20, 30));
assert_eq!(palette.sample(0.7), rgb(10, 20, 30));
assert_eq!(palette.sample(1.0), rgb(10, 20, 30));
}
#[test]
fn an_empty_ramp_is_white_rather_than_a_panic() {
let palette = Palette::new(Vec::new());
assert_eq!(palette.len(), 1);
assert_eq!(palette.sample(0.5), Color::White);
}
#[test]
fn intermediate_stops_are_evenly_spaced() {
let palette =
Palette::new(vec![rgb(0, 0, 0), rgb(255, 0, 0), rgb(255, 255, 255)]);
assert_eq!(palette.sample(0.5), rgb(255, 0, 0));
assert_eq!(palette.sample(0.25), rgb(128, 0, 0));
assert_eq!(palette.sample(0.75), rgb(255, 128, 128));
}
#[test]
fn index_sampling_wraps_but_does_not_panic() {
let palette = Palette::new(vec![rgb(1, 1, 1), rgb(2, 2, 2)]);
assert_eq!(palette.sample_index(0), rgb(1, 1, 1));
assert_eq!(palette.sample_index(1), rgb(2, 2, 2));
assert_eq!(palette.sample_index(2), rgb(1, 1, 1));
assert_eq!(palette.sample_index(99), rgb(2, 2, 2));
}
#[test]
fn expand_produces_the_requested_count_with_exact_endpoints() {
let palette = Palette::new(vec![rgb(0, 0, 0), rgb(255, 0, 0)]);
let table = palette.expand(5);
assert_eq!(table.len(), 5);
assert_eq!(table[0], rgb(0, 0, 0));
assert_eq!(table[4], rgb(255, 0, 0));
}
#[test]
fn expand_never_returns_a_single_entry() {
let table = Palette::new(vec![rgb(0, 0, 0), rgb(1, 1, 1)]).expand(1);
assert_eq!(table.len(), 2);
}
#[test]
fn fading_from_black_is_a_fade_and_not_a_step() {
let ink = Color::Rgb {
r: 200,
g: 100,
b: 50,
};
let mut previous = lerp(Color::Black, ink, 0.9);
for step in 1..=20 {
let t = step as f32 / 20.0;
let blended = lerp(Color::Black, ink, t);
assert_ne!(
blended, previous,
"at t = {t} the colour did not change, so this is a step"
);
previous = blended;
}
assert_eq!(
lerp(Color::Black, ink, 0.0),
Color::Rgb { r: 0, g: 0, b: 0 }
);
assert_eq!(lerp(Color::Black, ink, 1.0), ink);
assert_eq!(lerp(ink, Color::Black, 0.0), ink);
assert_eq!(
lerp(ink, Color::Black, 1.0),
Color::Rgb { r: 0, g: 0, b: 0 }
);
}
#[test]
fn every_named_colour_blends_with_a_truecolor() {
let ink = Color::Rgb {
r: 200,
g: 100,
b: 50,
};
let named = [
Color::Black,
Color::DarkGrey,
Color::Red,
Color::Green,
Color::Blue,
Color::Magenta,
Color::Cyan,
Color::Yellow,
Color::Grey,
Color::White,
];
for color in named {
for (a, b) in [(color, ink), (ink, color)] {
let middle = lerp(a, b, 0.5);
assert_ne!(
middle, a,
"{color:?} did not blend towards {ink:?} at the halfway point"
);
assert_ne!(
middle, b,
"{ink:?} did not blend towards {color:?} at the halfway point"
);
}
}
}
#[test]
fn unresolvable_endpoints_still_pick_an_endpoint() {
let ink = Color::Rgb {
r: 200,
g: 100,
b: 50,
};
for unresolvable in [Color::Reset, Color::AnsiValue(42)] {
assert_eq!(lerp(unresolvable, ink, 0.0), unresolvable);
assert_eq!(lerp(unresolvable, ink, 0.49), unresolvable);
assert_eq!(lerp(unresolvable, ink, 0.5), ink);
assert_eq!(lerp(unresolvable, ink, 1.0), ink);
}
}
#[test]
fn a_ramp_starting_at_black_is_monotonic() {
let ramp = Palette::new(vec![Color::Black, ink_colour()]);
assert_eq!(ramp.sample(0.0), Color::Rgb { r: 0, g: 0, b: 0 });
assert_eq!(ramp.sample(1.0), ink_colour());
let mut previous = 0u8;
for step in 1..=20 {
let Color::Rgb { r, .. } = ramp.sample(step as f32 / 20.0) else {
panic!("a two-stop black ramp stopped being truecolor");
};
assert!(r >= previous, "the ramp went backwards at step {step}");
previous = r;
}
}
fn ink_colour() -> Color {
Color::Rgb {
r: 200,
g: 100,
b: 50,
}
}
#[test]
fn from_rgb_clamps_and_rounds() {
let palette = Palette::from_rgb(vec![[-1.0, 0.5, 2.0]]);
assert_eq!(palette.stops()[0], rgb(0, 128, 255));
}
#[test]
fn lerp_across_colour_kinds_picks_an_endpoint() {
assert_eq!(lerp(Color::Reset, rgb(9, 9, 9), 0.2), Color::Reset);
assert_eq!(lerp(Color::Reset, rgb(9, 9, 9), 0.8), rgb(9, 9, 9));
}
#[test]
fn greyscale_runs_black_to_white() {
let palette = greyscale();
assert_eq!(palette.sample(0.0), rgb(0, 0, 0));
assert_eq!(palette.sample(1.0), rgb(255, 255, 255));
assert_eq!(palette.sample(0.5), rgb(128, 128, 128));
}
#[test]
fn a_brightness_ramp_puts_its_brightest_colour_at_the_top() {
for (name, stops) in presets::ALL {
let brightest = stops
.iter()
.copied()
.max_by(|a, b| {
luminance(*a)
.partial_cmp(&luminance(*b))
.unwrap_or(std::cmp::Ordering::Equal)
})
.expect("a preset with no stops");
let truncated = Palette::new(stops.to_vec()).truncated_at_peak();
assert_eq!(
truncated.sample(1.0),
brightest,
"{name}: the truncated ramp does not end on its brightest stop"
);
let untruncated = Palette::new(stops.to_vec());
if stops.len() > 2 {
assert_ne!(
untruncated.sample(1.0),
brightest,
"{name} is no longer mirrored, so truncated_at_peak is a \
no-op for it and the call sites should stop calling it"
);
}
}
}
#[test]
fn a_truncated_ramp_is_monotonic_in_luminance() {
for (name, stops) in presets::ALL {
let ramp = Palette::new(stops.to_vec()).truncated_at_peak();
let mut previous = f32::NEG_INFINITY;
for step in 0..=32 {
let t = step as f32 / 32.0;
let luma = luminance(ramp.sample(t));
assert!(
luma >= previous - 1e-4,
"{name} went backwards in luminance at t = {t}: \
{luma} after {previous}"
);
previous = luma;
}
}
}
#[test]
fn the_peak_is_found_by_luminance_and_not_by_channel_maximum() {
let ramp = Palette::new(presets::DEPTH.to_vec()).truncated_at_peak();
assert_eq!(ramp.len(), 3, "DEPTH peaks at index 2, so three stops");
assert_eq!(ramp.sample(1.0), rgb(237, 255, 255));
assert!(!ramp.stops().contains(&rgb(204, 0, 0)));
}
#[test]
fn a_ramp_that_never_climbs_truncates_to_itself() {
let flat = Palette::new(vec![rgb(10, 20, 30), rgb(9, 19, 29)]);
let truncated = flat.truncated_at_peak();
assert_eq!(truncated.len(), 1);
assert_eq!(truncated.sample(0.0), rgb(10, 20, 30));
assert_eq!(truncated.sample(1.0), rgb(10, 20, 30));
}
#[test]
fn luminance_says_a_saturated_blue_is_dark() {
let blue = rgb(0, 0, 255);
let red = rgb(255, 0, 0);
assert!(
luminance(blue) < luminance(red),
"a channel maximum would have called blue the brighter colour"
);
assert!((luminance(rgb(255, 255, 255)) - 1.0).abs() < 1e-6);
assert!((luminance(rgb(0, 0, 0))).abs() < 1e-6);
assert!(luminance(Color::White) > luminance(Color::DarkGrey));
assert_eq!(luminance(Color::Reset), 0.0);
}
}