Skip to content

VectorCraft: An open-source, vector art tool written by scratch in pure Rust

20.2 KB
Raw Blame
//! Colour harmony rules, the variation grid of the Color Guide panel and the five-colour themes of
//! the Color Themes panel (our own colour math).

use serde::{Deserialize, Serialize};

use crate::recolor::Palette;
use crate::{Color, keep_model};

/// A harmony rule: a group of colours built from a base colour, base first.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Harmony {
    Complementary,
    Complementary2,
    SplitComplementary,
    LeftComplement,
    RightComplement,
    Analogous,
    Analogous2,
    Monochromatic,
    Shades,
    Triad,
    Triad2,
    Triad3,
    Tetrad,
    Tetrad2,
    Tetrad3,
    Compound,
    Compound2,
    HighContrast,
    HighContrast2,
    HighContrast3,
    Pentagram,
}

/// One colour of a rule: the base turned by `turn` degrees of hue, its saturation scaled by `sat`
/// and its brightness by `bright` (or flipped to the contrasting brightness).
#[derive(Clone, Copy)]
struct Tone {
    turn: f32,
    sat: f32,
    bright: Bright,
}

#[derive(Clone, Copy)]
enum Bright {
    Times(f32),
    /// Dark for a light base, light for a dark one ([`contrast`]).
    Contrast,
}

const fn sv(turn: f32, sat: f32, bright: f32) -> Tone {
    Tone { turn, sat, bright: Bright::Times(bright) }
}
/// The base's hue turned by `turn`.
const fn t(turn: f32) -> Tone {
    sv(turn, 1.0, 1.0)
}
/// A softer (half as saturated) partner.
const fn soft(turn: f32) -> Tone {
    sv(turn, 0.5, 1.0)
}
/// A deeper (darker) partner.
const fn deep(turn: f32) -> Tone {
    sv(turn, 1.0, 0.6)
}
/// A partner of contrasting brightness.
const fn hc(turn: f32) -> Tone {
    Tone { turn, sat: 1.0, bright: Bright::Contrast }
}

/// The brightness that contrasts with `v`.
fn contrast(v: f32) -> f32 {
    if v >= 0.5 { v * 0.3 } else { 0.7 + 0.3 * v }
}

impl Harmony {
    pub const ALL: [Harmony; 21] = [
        Harmony::Complementary,
        Harmony::Complementary2,
        Harmony::SplitComplementary,
        Harmony::LeftComplement,
        Harmony::RightComplement,
        Harmony::Analogous,
        Harmony::Analogous2,
        Harmony::Monochromatic,
        Harmony::Shades,
        Harmony::Triad,
        Harmony::Triad2,
        Harmony::Triad3,
        Harmony::Tetrad,
        Harmony::Tetrad2,
        Harmony::Tetrad3,
        Harmony::Compound,
        Harmony::Compound2,
        Harmony::HighContrast,
        Harmony::HighContrast2,
        Harmony::HighContrast3,
        Harmony::Pentagram,
    ];

    pub fn label(self) -> &'static str {
        match self {
            Harmony::Complementary => "Complementary",
            Harmony::Complementary2 => "Complementary 2",
            Harmony::SplitComplementary => "Split Complementary",
            Harmony::LeftComplement => "Left Complement",
            Harmony::RightComplement => "Right Complement",
            Harmony::Analogous => "Analogous",
            Harmony::Analogous2 => "Analogous 2",
            Harmony::Monochromatic => "Monochromatic",
            Harmony::Shades => "Shades",
            Harmony::Triad => "Triad",
            Harmony::Triad2 => "Triad 2",
            Harmony::Triad3 => "Triad 3",
            Harmony::Tetrad => "Tetrad",
            Harmony::Tetrad2 => "Tetrad 2",
            Harmony::Tetrad3 => "Tetrad 3",
            Harmony::Compound => "Compound",
            Harmony::Compound2 => "Compound 2",
            Harmony::HighContrast => "High Contrast",
            Harmony::HighContrast2 => "High Contrast 2",
            Harmony::HighContrast3 => "High Contrast 3",
            Harmony::Pentagram => "Pentagram",
        }
    }

    /// The rule's id in commands: its label in camelCase ("splitComplementary", "triad2").
    pub fn id(self) -> String {
        let mut out = String::new();
        for (i, w) in self.label().split(' ').enumerate() {
            let mut c = w.chars();
            if let Some(f) = c.next() {
                if i == 0 {
                    out.extend(f.to_lowercase());
                } else {
                    out.extend(f.to_uppercase());
                }
                out.push_str(c.as_str());
            }
        }
        out
    }

    /// A rule from its id or label (case and spaces ignored).
    pub fn parse(s: &str) -> Option<Self> {
        let key = |x: &str| x.chars().filter(|c| !c.is_whitespace()).collect::<String>().to_ascii_lowercase();
        let want = key(s);
        Self::ALL.into_iter().find(|h| key(h.label()) == want)
    }

    fn tones(self) -> &'static [Tone] {
        match self {
            Harmony::Complementary => const { &[t(0.0), t(180.0)] },
            Harmony::Complementary2 => const { &[t(0.0), soft(0.0), t(180.0), soft(180.0)] },
            Harmony::SplitComplementary => const { &[t(0.0), t(150.0), t(210.0)] },
            Harmony::LeftComplement => const { &[t(0.0), t(-30.0), t(150.0)] },
            Harmony::RightComplement => const { &[t(0.0), t(30.0), t(210.0)] },
            Harmony::Analogous => const { &[t(0.0), t(30.0), t(-30.0)] },
            Harmony::Analogous2 => const { &[t(0.0), t(30.0), t(60.0), t(-30.0), t(-60.0)] },
            Harmony::Monochromatic => const { &[t(0.0), sv(0.0, 0.5, 1.0), sv(0.0, 1.0, 0.6), sv(0.0, 0.25, 1.0), sv(0.0, 1.0, 0.35)] },
            Harmony::Shades => const { &[t(0.0), sv(0.0, 1.0, 0.8), sv(0.0, 1.0, 0.6), sv(0.0, 1.0, 0.4), sv(0.0, 1.0, 0.2)] },
            Harmony::Triad => const { &[t(0.0), t(120.0), t(240.0)] },
            Harmony::Triad2 => const { &[t(0.0), t(120.0), soft(120.0), t(240.0), soft(240.0)] },
            Harmony::Triad3 => const { &[t(0.0), t(120.0), deep(120.0), t(240.0), deep(240.0)] },
            Harmony::Tetrad => const { &[t(0.0), t(60.0), t(180.0), t(240.0)] },
            Harmony::Tetrad2 => const { &[t(0.0), t(90.0), t(180.0), t(270.0)] },
            Harmony::Tetrad3 => const { &[t(0.0), t(30.0), t(180.0), t(210.0)] },
            Harmony::Compound => const { &[t(0.0), t(40.0), t(160.0), t(200.0)] },
            Harmony::Compound2 => const { &[t(0.0), t(-40.0), t(160.0), t(200.0)] },
            Harmony::HighContrast => const { &[t(0.0), hc(180.0)] },
            Harmony::HighContrast2 => const { &[t(0.0), hc(0.0), t(180.0), hc(180.0)] },
            Harmony::HighContrast3 => const { &[t(0.0), hc(120.0), hc(240.0)] },
            Harmony::Pentagram => const { &[t(0.0), t(72.0), t(144.0), t(216.0), t(288.0)] },
        }
    }

    /// The rule's colours in the base colour's model, the base colour itself first.
    pub fn apply(self, base: Color) -> Vec<Color> {
        let [h, s, v] = base.to_hsb();
        std::iter::once(base)
            .chain(self.tones()[1..].iter().map(|tone| {
                let b = match tone.bright {
                    Bright::Times(f) => v * f,
                    Bright::Contrast => contrast(v),
                };
                keep_model(base, Color::from_hsb(h + tone.turn, (s * tone.sat).clamp(0.0, 1.0), b.clamp(0.0, 1.0)))
            }))
            .collect()
    }

    /// A [`THEME_SIZE`]-colour theme from `base`: the rule's colours, each followed by the lighter or
    /// darker variations of it that fill the remaining places (the rule's first colours get them
    /// first). The base colour comes first, every colour in its model.
    pub fn theme(self, base: Color) -> Vec<Color> {
        let colors = self.apply(base);
        let n = colors.len();
        let mut rows: Vec<Vec<Color>> = colors.iter().map(|c| vec![*c]).collect();
        let opts = GuideOptions::default();
        for k in 0..THEME_SIZE.saturating_sub(n) {
            let (i, pass) = (k % n, k / n);
            // Alternate lighter and darker along the rule and from one pass to the next.
            let step = if (i + pass) % 2 == 0 { 3 } else { -3 };
            rows[i].push(variation(colors[i], &opts, step));
        }
        rows.into_iter().flatten().take(THEME_SIZE).collect()
    }
}

/// The number of colours in a colour theme.
pub const THEME_SIZE: usize = 5;

/// Move colour `i` of a harmony on the hue and saturation wheel to `hsb` (hue in degrees,
/// saturation and brightness 0..1), keeping its model. With `linked` the other colours keep their
/// relation to it: they turn by the same hue, scale their saturation alike and shift their
/// brightness by as much.
pub fn move_on_wheel(colors: &mut [Color], i: usize, hsb: [f32; 3], linked: bool) {
    let Some(&old) = colors.get(i) else { return };
    let [h0, s0, v0] = old.to_hsb();
    let (dh, ratio, dv) = (hsb[0] - h0, if s0 > 0.01 { hsb[1] / s0 } else { 1.0 }, hsb[2] - v0);
    for (j, c) in colors.iter_mut().enumerate() {
        let new = if j == i {
            hsb
        } else if linked {
            let [h, s, v] = c.to_hsb();
            [h + dh, (s * ratio).clamp(0.0, 1.0), (v + dv).clamp(0.0, 1.0)]
        } else {
            continue;
        };
        *c = keep_model(*c, Color::from_hsb(new[0], new[1], new[2]));
    }
}

/// What the variation grid varies: towards black and white, towards cool and warm, or towards
/// grey and full saturation.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum Variation {
    #[default]
    TintsShades,
    WarmCool,
    VividMuted,
}

impl Variation {
    pub const ALL: [Variation; 3] = [Variation::TintsShades, Variation::WarmCool, Variation::VividMuted];

    pub fn id(self) -> &'static str {
        match self {
            Variation::TintsShades => "tintsShades",
            Variation::WarmCool => "warmCool",
            Variation::VividMuted => "vividMuted",
        }
    }
    pub fn parse(s: &str) -> Option<Self> {
        Self::ALL.into_iter().find(|v| v.id().eq_ignore_ascii_case(s))
    }
    /// The ends of the grid: (left, right).
    pub fn sides(self) -> (&'static str, &'static str) {
        match self {
            Variation::TintsShades => ("Shades", "Tints"),
            Variation::WarmCool => ("Cool", "Warm"),
            Variation::VividMuted => ("Muted", "Vivid"),
        }
    }
}

/// The Color Guide's options: variation kind, steps on each side and how far they reach.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct GuideOptions {
    pub variation: Variation,
    /// Variations on each side of the harmony colour (1..=20).
    pub steps: u32,
    /// How far the outermost variations go, 0..=100 (Less … More).
    pub amount: f32,
}

impl Default for GuideOptions {
    fn default() -> Self {
        Self { variation: Variation::TintsShades, steps: 4, amount: 50.0 }
    }
}

impl GuideOptions {
    pub const MAX_STEPS: u32 = 20;

    /// The options with `steps` and `amount` clamped to their ranges.
    pub fn clamped(self) -> Self {
        Self { steps: self.steps.clamp(1, Self::MAX_STEPS), amount: self.amount.clamp(0.0, 100.0), ..self }
    }
    /// The share of the way to the target that the outermost steps reach (10% … 90%).
    fn reach(&self) -> f32 {
        0.1 + 0.8 * self.amount.clamp(0.0, 100.0) / 100.0
    }
}

/// Variation of `c` at `step` (−steps..=steps: negative towards shades/cool/muted, positive towards
/// tints/warm/vivid; 0 is `c` itself), in `c`'s model.
pub fn variation(c: Color, opts: &GuideOptions, step: i32) -> Color {
    if step == 0 {
        return c;
    }
    let f = (step.unsigned_abs() as f32 / opts.steps.max(1) as f32).min(1.0) * opts.reach();
    let v = match opts.variation {
        Variation::TintsShades => c.lerp(if step < 0 { &Color::BLACK } else { &Color::WHITE }, f),
        Variation::WarmCool => {
            let target = if step < 0 { Color::rgb(0.2, 0.45, 1.0) } else { Color::rgb(1.0, 0.55, 0.1) };
            c.lerp(&target, f * 0.6)
        }
        Variation::VividMuted => {
            let [h, s, b] = c.to_hsb();
            let s2 = if step < 0 { s * (1.0 - f) } else { s + (1.0 - s) * f };
            Color::from_hsb(h, s2.clamp(0.0, 1.0), b)
        }
    };
    keep_model(c, v)
}

/// The Color Guide for a base colour: the harmony colours and, per colour, its row of variations
/// from `-steps` to `+steps` (the colour itself in the centre column).
#[derive(Clone, Debug, PartialEq)]
pub struct Guide {
    pub colors: Vec<Color>,
    pub grid: Vec<Vec<Color>>,
}

impl Guide {
    pub fn new(base: Color, rule: Harmony, opts: &GuideOptions) -> Self {
        let opts = opts.clamped();
        let n = opts.steps as i32;
        let colors = rule.apply(base);
        let grid = colors.iter().map(|c| (-n..=n).map(|step| variation(*c, &opts, step)).collect()).collect();
        Self { colors, grid }
    }
    /// Index of the centre column (the harmony colours) in each grid row.
    pub fn centre(&self) -> usize {
        self.grid.first().map_or(0, |r| r.len() / 2)
    }

    /// The guide limited to `palette` (Limit to Library): every harmony colour and variation snaps
    /// to the palette's nearest colour (CIEDE2000), in that colour's own model.
    pub fn limited(mut self, palette: &Palette) -> Self {
        if palette.is_empty() {
            return self;
        }
        let centre = self.centre();
        for (row, c) in self.grid.iter_mut().zip(&mut self.colors) {
            for v in row.iter_mut() {
                *v = palette.nearest(*v);
            }
            // The centre column is the harmony colour itself.
            *c = row[centre];
        }
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn complementary_red() {
        let c = Harmony::Complementary.apply(Color::rgb(1.0, 0.0, 0.0));
        assert_eq!(c[1].to_hex(), "#00ffff");
        assert_eq!(Harmony::Triad.apply(Color::rgb(1.0, 0.0, 0.0))[1].to_hex(), "#00ff00");
        assert_eq!(Harmony::Pentagram.apply(Color::rgb(1.0, 0.0, 0.0))[1].to_hsb()[0].round(), 72.0);
    }

    #[test]
    fn every_rule_puts_the_base_first() {
        let counts = [2, 4, 3, 3, 3, 3, 5, 5, 5, 3, 5, 5, 4, 4, 4, 4, 4, 2, 4, 3, 5];
        assert_eq!(Harmony::ALL.len(), counts.len());
        for base in [Color::rgb8(230, 120, 40), Color::cmyk(0.1, 0.8, 0.3, 0.05), Color::gray(0.4)] {
            for (h, n) in Harmony::ALL.into_iter().zip(counts) {
                let c = h.apply(base);
                assert_eq!(c.len(), n, "{}", h.label());
                assert_eq!(c[0], base, "{}: the base comes first, in its own model", h.label());
            }
        }
    }

    #[test]
    fn harmonies_keep_the_base_model() {
        let base = Color::cmyk(0.0, 1.0, 1.0, 0.0);
        for h in Harmony::ALL {
            assert!(h.apply(base).iter().all(|c| matches!(c, Color::Cmyk { .. })), "{}", h.label());
        }
        let Color::Cmyk { c, m, y, .. } = Harmony::Complementary.apply(base)[1] else { panic!("a CMYK complement") };
        assert!(c > m && c > y, "the complement of red is a cyan: {c} {m} {y}");
        let g = Guide::new(Color::gray(0.4), Harmony::Triad, &GuideOptions::default());
        assert!(g.grid.iter().flatten().all(|c| matches!(c, Color::Gray { .. })));
    }

    #[test]
    fn rules_parse_by_id_and_label() {
        for h in Harmony::ALL {
            assert_eq!(Harmony::parse(&h.id()), Some(h));
            assert_eq!(Harmony::parse(h.label()), Some(h));
        }
        assert_eq!(Harmony::SplitComplementary.id(), "splitComplementary");
        assert_eq!(Harmony::HighContrast3.id(), "highContrast3");
        assert_eq!(Harmony::parse("square"), None);
    }

    #[test]
    fn high_contrast_flips_brightness() {
        let light = Harmony::HighContrast.apply(Color::rgb(0.9, 0.8, 0.2));
        assert!(light[1].to_hsb()[2] < 0.5);
        let dark = Harmony::HighContrast.apply(Color::rgb(0.2, 0.1, 0.05));
        assert!(dark[1].to_hsb()[2] > 0.5);
    }

    #[test]
    fn variations_step_out_from_the_colour() {
        let c = Color::rgb(0.5, 0.5, 0.5);
        let o = GuideOptions::default();
        assert_eq!(variation(c, &o, 0), c, "step 0 is the colour");
        assert!(variation(c, &o, 4).to_rgb()[0] > variation(c, &o, 2).to_rgb()[0]);
        assert!(variation(c, &o, -4).to_rgb()[0] < 0.5);
        let red = Color::rgb(1.0, 0.2, 0.2);
        let vm = GuideOptions { variation: Variation::VividMuted, ..o };
        assert!(variation(red, &vm, -2).to_hsb()[1] < red.to_hsb()[1]);
        let warm = variation(c, &GuideOptions { variation: Variation::WarmCool, ..o }, 2).to_rgb();
        assert!(warm[0] > warm[2]);
        // More variation reaches further.
        let more = GuideOptions { amount: 100.0, ..o };
        assert!(variation(c, &more, -4).to_rgb()[0] < variation(c, &o, -4).to_rgb()[0]);
    }

    #[test]
    fn guide_rows_hold_the_colour_in_the_centre() {
        let base = Color::rgb8(30, 120, 200);
        let g = Guide::new(base, Harmony::Triad, &GuideOptions { steps: 3, ..Default::default() });
        assert_eq!(g.colors.len(), 3);
        assert!(g.grid.iter().all(|r| r.len() == 7));
        assert_eq!(g.centre(), 3);
        for (row, c) in g.grid.iter().zip(&g.colors) {
            assert_eq!(row[3], *c);
        }
        // Steps are clamped to 1..=20.
        let g = Guide::new(base, Harmony::Triad, &GuideOptions { steps: 99, ..Default::default() });
        assert_eq!(g.grid[0].len(), 41);
    }

    #[test]
    fn a_limited_guide_only_holds_palette_colours() {
        let lib =
            [Color::rgb(1.0, 0.0, 0.0), Color::cmyk(1.0, 0.0, 0.0, 0.0), Color::gray(0.5), Color::rgb8(250, 240, 200), Color::lab(30.0, 10.0, -40.0)];
        let palette = Palette::new(lib);
        for rule in Harmony::ALL {
            let g = Guide::new(Color::rgb8(200, 60, 40), rule, &GuideOptions::default()).limited(&palette);
            assert!(g.grid.iter().flatten().chain(&g.colors).all(|c| lib.contains(c)), "{}", rule.label());
            for (row, c) in g.grid.iter().zip(&g.colors) {
                assert_eq!(row[g.centre()], *c, "{}: the harmony colour stays in the centre", rule.label());
            }
        }
        // The nearest colour wins: a pale yellow snaps to the cream and its darkest shade to the grey.
        let g = Guide::new(Color::rgb(0.95, 0.9, 0.75), Harmony::Complementary, &GuideOptions::default()).limited(&palette);
        assert_eq!(g.colors[0], lib[3]);
        assert_eq!(g.grid[0][0], lib[2]);
        // An empty palette limits nothing.
        let free = Guide::new(Color::rgb(0.8, 0.1, 0.1), Harmony::Triad, &GuideOptions::default());
        assert_eq!(free.clone().limited(&Palette::default()), free);
    }

    #[test]
    fn themes_have_five_colours_base_first() {
        for base in [Color::rgb8(230, 120, 40), Color::cmyk(0.1, 0.8, 0.3, 0.05)] {
            for rule in Harmony::ALL {
                let t = rule.theme(base);
                assert_eq!(t.len(), THEME_SIZE, "{}", rule.label());
                assert_eq!(t[0], base, "{}", rule.label());
                assert!(t.iter().all(|c| c.model() == base.model()), "{}: colours keep the base model", rule.label());
            }
        }
        // A two-colour rule fills in variations next to the colour they vary.
        let red = Color::rgb(1.0, 0.0, 0.0);
        let t = Harmony::Complementary.theme(red);
        assert_eq!(t[3].to_hex(), "#00ffff", "the complement follows the base's variations");
        let l = |c: &Color| c.to_lab().l;
        assert!(l(&t[1]) > l(&t[0]) && l(&t[2]) < l(&t[0]), "the base, a lighter and a darker red");
        assert!(l(&t[4]) < l(&t[3]));
        for (i, a) in t.iter().enumerate() {
            assert!(t[i + 1..].iter().all(|b| b.to_hex() != a.to_hex()), "{} repeats", a.to_hex());
        }
        // Five-colour rules are themes as they are.
        assert_eq!(Harmony::Pentagram.theme(red), Harmony::Pentagram.apply(red));
    }

    #[test]
    fn moving_a_linked_colour_moves_the_others_alike() {
        let mut c = [Color::rgb(1.0, 0.0, 0.0), Color::rgb(1.0, 1.0, 0.0), Color::cmyk(0.0, 1.0, 0.0, 0.0)];
        move_on_wheel(&mut c, 0, [120.0, 1.0, 1.0], false);
        assert_eq!(c[0].to_hex(), "#00ff00");
        assert_eq!(c[1].to_hex(), "#ffff00", "unlinked: only that colour moves");
        move_on_wheel(&mut c, 0, [240.0, 0.5, 1.0], true);
        assert_eq!(c[0].to_hex(), "#8080ff");
        let [h, s, v] = c[1].to_hsb();
        assert!((h - 180.0).abs() < 0.5 && (s - 0.5).abs() < 0.01 && v > 0.99, "it turned and paled as much: {h} {s} {v}");
        assert!(matches!(c[2], Color::Cmyk { .. }), "colours keep their model");
        // An index past the end moves nothing.
        let before = c;
        move_on_wheel(&mut c, 5, [0.0, 0.0, 0.0], true);
        assert_eq!(c, before);
    }
}