nordisk/facett

facett-plotters/src/ramp.rs

//! **Theme-derived colour ramps.** No hardcoded palette: a sequential ramp is
//! built from the theme's `bg` → `accent` → `glow`, and a diverging ramp from
//! `accent` (low) through a neutral midpoint to `glow` (high). Charts call
//! [`Ramp::at`] with a normalised `t ∈ 0..=1` to map a scalar to a colour.
//!
//! Keeping this purely a function of [`facett_core::Theme`] means every chart
//! re-skins automatically when the theme switches — the requirement that no
//! component bakes in its own colours.

use egui::Color32;
use facett_core::Theme;

/// A colour ramp sampled at `t ∈ 0..=1`. Built from theme colours so it follows
/// the active palette.
#[derive(Clone, Copy, Debug)]
pub struct Ramp {
    /// Control colours, low → high. We lerp between the nearest two.
    stops: [Color32; 3],
}

impl Ramp {
    /// **Sequential** low→high ramp: a dim theme ground → `accent` → `glow`.
    /// Good for magnitudes (heatmaps, treemap weights).
    pub fn sequential(th: &Theme) -> Self {
        // Start from a darkened accent so the low end reads as "cool/quiet"
        // rather than the panel background (which would vanish on the canvas).
        let low = lerp_color(th.bg, th.accent, 0.25);
        Self { stops: [low, th.accent, th.glow] }
    }

    /// **Diverging** ramp: `accent` (low) → a neutral mid (theme `text_dim`) →
    /// `glow` (high). Good for signed values around a midpoint.
    pub fn diverging(th: &Theme) -> Self {
        Self { stops: [th.accent, th.text_dim, th.glow] }
    }

    /// Sample the ramp at `t`, clamped to `0..=1`.
    pub fn at(&self, t: f32) -> Color32 {
        let t = t.clamp(0.0, 1.0);
        if t <= 0.5 {
            lerp_color(self.stops[0], self.stops[1], t * 2.0)
        } else {
            lerp_color(self.stops[1], self.stops[2], (t - 0.5) * 2.0)
        }
    }

    /// The control stops, for a legend gradient.
    pub fn stops(&self) -> [Color32; 3] {
        self.stops
    }
}

// Canonical colour lerp lives in `facett_core::look`; re-exported so
// `facett_plotters::ramp::lerp_color` keeps working with no twin implementation.
pub use facett_core::look::color::lerp_color;

/// Normalise `v` into `0..=1` over `[min, max]`. Degenerate ranges map to `0.5`
/// (a flat mid-tone) rather than dividing by zero.
pub fn normalize(v: f64, min: f64, max: f64) -> f32 {
    if max.is_nan() || min.is_nan() || max <= min {
        return 0.5;
    }
    (((v - min) / (max - min)) as f32).clamp(0.0, 1.0)
}

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

    #[test]
    fn lerp_endpoints_and_mid() {
        let a = Color32::from_rgb(0, 0, 0);
        let b = Color32::from_rgb(100, 200, 50);
        assert_eq!(lerp_color(a, b, 0.0), a);
        assert_eq!(lerp_color(a, b, 1.0), b);
        let m = lerp_color(a, b, 0.5);
        assert_eq!((m.r(), m.g(), m.b()), (50, 100, 25));
    }

    #[test]
    fn ramp_hits_its_stops() {
        let r = Ramp::sequential(&Theme::default());
        let [lo, mid, hi] = r.stops();
        assert_eq!(r.at(0.0), lo);
        assert_eq!(r.at(0.5), mid);
        assert_eq!(r.at(1.0), hi);
    }

    #[test]
    fn ramp_clamps_out_of_range() {
        let r = Ramp::diverging(&Theme::sci_fi());
        assert_eq!(r.at(-3.0), r.at(0.0));
        assert_eq!(r.at(9.0), r.at(1.0));
    }

    #[test]
    fn normalize_handles_degenerate_range() {
        assert_eq!(normalize(5.0, 5.0, 5.0), 0.5);
        assert_eq!(normalize(0.0, 0.0, 10.0), 0.0);
        assert_eq!(normalize(10.0, 0.0, 10.0), 1.0);
        assert_eq!(normalize(2.5, 0.0, 10.0), 0.25);
        // out of band clamps
        assert_eq!(normalize(-1.0, 0.0, 10.0), 0.0);
        assert_eq!(normalize(99.0, 0.0, 10.0), 1.0);
    }
}