vectorcraft/crates/effects/src/stroke/gradient.rs

//! Gradients laid along or across a stroke ([`StrokeGradientMode::Along`] and
//! [`StrokeGradientMode::Across`]).
//!
//! Each subpath becomes a strip of *ribs*: cross-sections through the flattened path that reach
//! past everything the stroke paints there (its width profile, joins, caps and arrowheads). Between
//! two ribs lies a slice painted with a linear piece of the gradient: along, from the first rib's
//! centre to the next one's (padded beyond, so the outside of a turn keeps the colour of the point
//! it turns at); across, from the stroke's left edge to its right edge. Ribs sit on the bisectors
//! of gentle turns, so neighbouring slices meet where both give the same colour; a sharp corner
//! gets a fan of ribs round its outside, painted in the corner's colour.
//!
//! Clipped to the stroke's outline, the slices paint it: the canvas and the SVG and PDF writers
//! fill them ([`gradient_slices`]); Outline Stroke turns the strip into a gradient mesh
//! ([`gradient_meshes`]).

use kurbo::{BezPath, Point, Shape, Vec2};
use vectorcraft_doc::color::{Gradient, GradientGeom, GradientPaint, Paint};
use vectorcraft_doc::live::{H_DOWN, H_LEFT, H_RIGHT, H_UP};
use vectorcraft_doc::{GradientMesh, LineJoin, MeshPoint, StrokeAlign, StrokeGradientMode, StrokeLayer};
use vectorcraft_geom::FillRule;

use super::width::{flatten, left, length, split_at};
use super::{aligned_width, cap_extent, is_closed, segments, subpaths, unit};

/// Largest stretch of a rib on a turn's bisector (1 / cos of half the turn, about 74°) before the
/// corner gets a fan of ribs round its outside.
const SHARP: f64 = 1.25;
/// Past this stretch (a turn of about 150°) the inside of a corner is not cut on its bisector,
/// which would reach far back along both sides: the slices either side overlap there instead.
const HAIRPIN: f64 = 4.0;
/// Rows of a mesh across the stroke (more where the gradient has stops).
const MESH_ROWS: usize = 16;
/// The most of a subpath one column of a mesh along the stroke spans.
const MESH_STEP: f64 = 1.0 / 32.0;
/// The most of a subpath one slice spans while a width profile shapes the across gradient.
const PROFILE_STEP: f64 = 1.0 / 64.0;
/// Flattening tolerance, cover margin and growth (see [`gradient_slices`]) of meshes and written
/// slices (document points).
const SLICE_TOL: f64 = 0.05;
const SLICE_MARGIN: f64 = 0.5;
const SLICE_GROW: f64 = 0.25;

/// A cross-section of the strip a stroke's gradient is laid on.
#[derive(Clone, Copy, Debug)]
struct Rib {
    /// Where it crosses the path.
    c: Point,
    /// Its left and right ends: the strip runs from `l` through `c` to `r`.
    l: Point,
    r: Point,
    /// How far across the stroke `l` and `r` stand: a point `x` left of the path (negative:
    /// right) lies `x / reach` of the way from `c` to the end on its side.
    reach: (f64, f64),
    /// Fraction of the subpath's length at `c`.
    t: f64,
    /// Where the across gradient starts and ends: this far left and right of the path.
    band: (f64, f64),
}

impl Rib {
    /// A rib square to direction `d`, reaching `r` either side of `c`.
    fn square(c: Point, d: Vec2, r: f64, t: f64, band: (f64, f64)) -> Self {
        let n = left(d);
        Rib { c, l: c + n * r, r: c - n * r, reach: (r, r), t, band }
    }
    /// The point `x` left of the path along the rib (negative: right).
    fn at(&self, x: f64) -> Point {
        if x >= 0.0 {
            self.c + (self.l - self.c) * (x / self.reach.0.max(1e-12))
        } else {
            self.c + (self.r - self.c) * (-x / self.reach.1.max(1e-12))
        }
    }
}

/// What lays out the ribs of one stroke.
struct Lay<'a> {
    st: &'a StrokeLayer,
    /// Half the stroked width ([`aligned_width`]).
    hw: f64,
    /// How far ribs reach either side of the path where nothing wider is near.
    cover: f64,
    margin: f64,
    /// How far a strip runs on past the start and end of an open subpath (caps and heads).
    ext: (f64, f64),
}

impl Lay<'_> {
    /// The across band at fraction `t` of a subpath whose visible side is `side` (`Some(true)`:
    /// left; `None`: both, a centred stroke).
    fn band(&self, t: f64, side: Option<bool>) -> (f64, f64) {
        let (l, r) = self.st.profile.as_ref().map_or((1.0, 1.0), |p| p.at(t));
        let (l, r) = (self.hw * l.max(0.0), self.hw * r.max(0.0));
        match side {
            None => (l, r),
            Some(true) => (l, 0.0),
            Some(false) => (0.0, r),
        }
    }

    /// The ribs at a turn at `p` from direction `din` to `dout` (unit vectors), reaching `r`
    /// across: one on the bisector, or a fan round the outside of a sharp corner (its miter, or the
    /// box round its round or bevel join).
    fn turn(&self, p: Point, din: Vec2, dout: Vec2, r: f64, t: f64, band: (f64, f64)) -> Vec<Rib> {
        let (nin, nout) = (left(din), left(dout));
        let den = 1.0 + nin.dot(nout);
        let stretch = if den > 1e-12 { (2.0 / den).sqrt() } else { f64::INFINITY };
        if stretch <= SHARP {
            let m = (nin + nout) / den;
            return vec![Rib { c: p, l: p + m * r, r: p - m * r, reach: (r, r), t, band }];
        }
        // `s` is 1 when the outside of the turn is on the left; `out_dir` the outward bisector.
        let s = if dout.dot(nin) > 0.0 { -1.0 } else { 1.0 };
        let sum = nin + nout;
        let out_dir = if sum.hypot() > 1e-9 { unit(sum) * s } else { din };
        let (o1, o2) = (p + nin * (s * r), p + nout * (s * r));
        let mitered = stretch <= std::f64::consts::SQRT_2 || (self.st.join == LineJoin::Miter && stretch <= self.st.miter_limit);
        let outer = if mitered { vec![o1, p + out_dir * (stretch * r), o2] } else { vec![o1, o1 + din * r, o2 - dout * r, o2] };
        let last = outer.len() - 1;
        outer
            .into_iter()
            .enumerate()
            .map(|(k, o)| {
                let (inner, inner_reach) = match k {
                    _ if stretch <= HAIRPIN => (p - out_dir * (stretch * r), r),
                    0 => (p - nin * (s * r), r),
                    _ if k == last => (p - nout * (s * r), r),
                    _ => (p, 0.0),
                };
                let o_reach = o.distance(p);
                if s > 0.0 {
                    Rib { c: p, l: o, r: inner, reach: (o_reach, inner_reach), t, band }
                } else {
                    Rib { c: p, l: inner, r: o, reach: (inner_reach, o_reach), t, band }
                }
            })
            .collect()
    }
}

/// The ribs of each subpath of `bp` (filled with `rule`) under stroke `st`, flattened to `tol`,
/// reaching `margin` past what the stroke paints. Fractions `marks` of each subpath get ribs of
/// their own, and no two are more than `max_dt` of it apart.
fn strips(bp: &BezPath, rule: FillRule, st: &StrokeLayer, tol: f64, margin: f64, marks: &[f64], max_dt: f64) -> Vec<Vec<Rib>> {
    let closed_path = is_closed(bp);
    let hw = aligned_width(st, closed_path) / 2.0;
    if !(hw > 0.0 && hw.is_finite()) {
        return vec![];
    }
    let full = hw * st.profile_max();
    let heads = (st.head_reach(false), st.head_reach(true));
    let cap = cap_extent(st.cap, 2.0 * full);
    let lay = Lay { st, hw, cover: full + margin, margin, ext: (cap.max(heads.0) + margin, cap.max(heads.1) + margin) };
    let subs = subpaths(bp);
    let count = subs.len();
    let mut out = vec![];
    for (k, (range, closed)) in subs.into_iter().enumerate() {
        let (pts, corner) = flatten(&segments(&bp.elements()[range]), closed, tol.max(1e-4));
        let side =
            (st.align != StrokeAlign::Center && closed_path && closed).then(|| band_on_left(bp, rule, &pts, st.align, (4.0 * tol).min(hw / 2.0)));
        // Arrowheads sit on the start of the first subpath and the end of the last one.
        let heads = (if k == 0 { heads.0 } else { 0.0 }, if k + 1 == count { heads.1 } else { 0.0 });
        let ribs = match pts.len() {
            0 => continue,
            // A subpath of no length: a dot (round and projecting caps paint it).
            1 => {
                let (d, b, e) = (Vec2::new(1.0, 0.0), lay.band(0.0, side), lay.ext.0.max(lay.ext.1));
                vec![Rib::square(pts[0] - d * e, d, lay.cover, 0.0, b), Rib::square(pts[0] + d * e, d, lay.cover, 0.0, b)]
            }
            _ => {
                let total = length(&pts, closed);
                if total <= 1e-12 {
                    continue;
                }
                let steps = if max_dt < 1.0 { (1.0 / max_dt).ceil() as usize } else { 1 };
                let profile = st.profile.iter().flat_map(|p| p.points.iter().map(|q| q.0));
                let at: Vec<f64> =
                    marks.iter().copied().chain(profile).chain((1..steps).map(|i| i as f64 / steps as f64)).map(|t| t * total).collect();
                let (pts, _) = split_at(&pts, &corner, closed, &at);
                strip(&lay, &pts, closed, total, side, if closed { (0.0, 0.0) } else { heads })
            }
        };
        out.push(ribs);
    }
    out
}

/// Is the visible band of an inside or outside stroke (`align`) on the left of the closed
/// subpath `pts` of `bp`? Probes `off` left of the middle of its longest segment (past where
/// flattening moved it).
fn band_on_left(bp: &BezPath, rule: FillRule, pts: &[Point], align: StrokeAlign, off: f64) -> bool {
    let n = pts.len();
    let Some(i) = (0..n).max_by(|&a, &b| pts[a].distance(pts[(a + 1) % n]).total_cmp(&pts[b].distance(pts[(b + 1) % n]))) else { return true };
    let (a, b) = (pts[i], pts[(i + 1) % n]);
    let probe = a.midpoint(b) + left(unit(b - a)) * off.max(1e-6);
    let w = bp.winding(probe);
    let inside = if rule == FillRule::EvenOdd { w % 2 != 0 } else { w != 0 };
    inside == (align == StrokeAlign::Inside)
}

/// The ribs along one flattened subpath `pts` of length `total` (`heads`: how far arrowheads
/// reach from its start and end).
fn strip(lay: &Lay, pts: &[Point], closed: bool, total: f64, side: Option<bool>, heads: (f64, f64)) -> Vec<Rib> {
    let n = pts.len();
    let seg_count = if closed { n } else { n - 1 };
    let dir: Vec<Vec2> = (0..seg_count).map(|i| unit(pts[(i + 1) % n] - pts[i])).collect();
    // Ribs near an arrowhead reach across it.
    let reach = |s: f64| {
        let mut r = lay.cover;
        if heads.0 > 0.0 && s <= heads.0 {
            r = r.max(heads.0 + lay.margin);
        }
        if heads.1 > 0.0 && total - s <= heads.1 {
            r = r.max(heads.1 + lay.margin);
        }
        r
    };
    let mut out = Vec::with_capacity(n + 4);
    let mut s = 0.0;
    if !closed {
        let (d, b) = (dir[0], lay.band(0.0, side));
        out.push(Rib::square(pts[0] - d * lay.ext.0, d, reach(0.0), 0.0, b));
        out.push(Rib::square(pts[0], d, reach(0.0), 0.0, b));
        s = pts[0].distance(pts[1]);
    }
    let (first, last) = if closed { (0, n) } else { (1, n - 1) };
    for i in first..last {
        let v = i % n;
        let t = s / total;
        let ribs = lay.turn(pts[v], dir[(v + seg_count - 1) % seg_count], dir[v % seg_count], reach(s), t, lay.band(t, side));
        // A closed subpath starts after the fan of its first corner and ends with it.
        let skip = if closed && i == 0 { ribs.len() - 1 } else { 0 };
        out.extend(ribs.into_iter().skip(skip));
        s += pts[v].distance(pts[(v + 1) % n]);
    }
    if closed {
        out.extend(lay.turn(pts[0], dir[seg_count - 1], dir[0], reach(total), 1.0, lay.band(1.0, side)));
    } else {
        let (d, b) = (dir[seg_count - 1], lay.band(1.0, side));
        out.push(Rib::square(pts[n - 1], d, reach(total), 1.0, b));
        out.push(Rib::square(pts[n - 1] + d * lay.ext.1, d, reach(total), 1.0, b));
    }
    out
}

/// A piece of a stroke whose gradient runs along or across it ([`gradient_slices`]).
#[derive(Clone, Debug)]
pub struct Slice {
    /// The area it paints (clipped to the stroke's outline).
    pub shape: BezPath,
    /// Its piece of the gradient runs from position `span.0` at `from` to `span.1` at `to`, and
    /// on unchanged past them; one colour when the span is empty.
    pub from: Point,
    pub to: Point,
    pub span: (f64, f64),
}

impl Slice {
    /// The slice's paint: its piece of `g` as a linear gradient placed from `from` to `to`.
    pub fn paint(&self, g: &Gradient) -> Paint {
        let gradient = g.span(self.span.0 as f32, self.span.1 as f32);
        let end = if self.from.distance(self.to) > 1e-9 { self.to } else { self.from + Vec2::new(1.0, 0.0) };
        let geom = GradientGeom { start: self.from, end, aspect: 1.0, focal: None };
        Paint::Gradient(Box::new(GradientPaint { geom: Some(geom), angle: geom.angle_deg(), ..GradientPaint::new(gradient) }))
    }
}

/// The slices that paint stroke `st` of `bp` (filled with `rule`) when its gradient runs along or
/// across the path (see the module docs): flattened to `tol`, reaching `margin` past the
/// stroke's edge. Clip them to the stroke's outline and fill them in order. With `grow` > 0 each
/// slice reaches that much past its edges into its neighbours, so antialiased edges show no
/// seams: filled so that each replaces what it covers (copy), they paint each point once; filled
/// over each other, only opaque gradients may grow (translucent ones would darken there).
pub fn gradient_slices(bp: &BezPath, rule: FillRule, st: &StrokeLayer, tol: f64, margin: f64, grow: f64) -> Vec<Slice> {
    let across = st.gradient_mode == StrokeGradientMode::Across;
    // A width profile changes the across band along the path: ribs close enough to follow it.
    let max_dt = if across && st.profile.is_some() { PROFILE_STEP } else { 1.0 };
    let mut out = vec![];
    for ribs in strips(bp, rule, st, tol, margin, &[], max_dt) {
        for w in ribs.windows(2) {
            let (a, b) = (&w[0], &w[1]);
            let shape = polygon(&[a.l, b.l, b.c, b.r, a.r, a.c], grow);
            if shape.elements().is_empty() {
                continue;
            }
            let (from, to, span) = if across {
                let axis = b.c - a.c;
                let n = if axis.hypot() > 1e-9 { left(unit(axis)) } else { unit((a.l - a.r) + (b.l - b.r)) };
                let mid = a.c.midpoint(b.c);
                let (l, r) = ((a.band.0 + b.band.0) / 2.0, (a.band.1 + b.band.1) / 2.0);
                (mid + n * l, mid - n * r, (0.0, 1.0))
            } else {
                (a.c, b.c, (a.t, b.t))
            };
            out.push(Slice { shape, from, to, span });
        }
    }
    out
}

/// The closed polygon through `pts`, each edge moved out by `grow` (mitred, at most 4 × `grow`
/// out at a corner). Repeated points and spikes are dropped; empty when no area is left.
fn polygon(pts: &[Point], grow: f64) -> BezPath {
    let mut v: Vec<Point> = pts.to_vec();
    // Drop repeated points and spikes (there and straight back), which have no outward side.
    loop {
        let n = v.len();
        let same = |a: Point, b: Point| a.distance(b) <= 1e-9;
        let Some(i) = (0..n).find(|&i| n > 2 && (same(v[i], v[(i + 1) % n]) || same(v[(i + n - 1) % n], v[(i + 1) % n]))) else { break };
        v.remove(i);
    }
    let mut out = BezPath::new();
    if v.len() < 3 {
        return out;
    }
    let n = v.len();
    if grow > 0.0 {
        let area: f64 = (0..n).map(|i| v[i].to_vec2().cross(v[(i + 1) % n].to_vec2())).sum();
        let side = if area >= 0.0 { 1.0 } else { -1.0 };
        let normal = |i: usize| {
            let d = unit(v[(i + 1) % n] - v[i]);
            Vec2::new(d.y, -d.x) * side
        };
        v = (0..n)
            .map(|i| {
                let (n1, n2) = (normal((i + n - 1) % n), normal(i));
                let den = 1.0 + n1.dot(n2);
                let m = if den > 1e-9 { (n1 + n2) / den } else { n1 };
                let m = if m.hypot() > 4.0 { m * (4.0 / m.hypot()) } else { m };
                v[i] + m * grow
            })
            .collect();
    }
    out.move_to(v[0]);
    for p in &v[1..] {
        out.line_to(*p);
    }
    out.close_path();
    out
}

/// What a writer paints for a stroke whose gradient runs along or across it.
#[derive(Clone, Debug)]
pub struct WrittenSlices {
    /// The outlines the stroke is written as, as one path (non-zero rule) to clip the slices.
    pub clip: BezPath,
    /// The slices in paint order, each with its piece of the gradient.
    pub slices: Vec<(BezPath, Paint)>,
}

/// How a file writer paints stroke `st` of `bp` (filled with `rule`) when its gradient runs along
/// or across it ([`StrokeLayer::path_gradient`]), given the filled outlines it writes for the
/// stroke ([`for_writer`](super::for_writer)): [`gradient_slices`] clipped to them. Where the
/// gradient is opaque the slices overlap a little, so viewers that antialias every shape show no
/// seams. `None` without such a gradient.
pub fn written_slices(bp: &BezPath, rule: FillRule, st: &StrokeLayer, outlines: &[BezPath]) -> Option<WrittenSlices> {
    let g = &st.path_gradient()?.gradient;
    let clip = match outlines {
        [one] => one.clone(),
        _ => vectorcraft_pathops::stroke_region(outlines).to_bezpath(),
    };
    let grow = if g.stops.iter().all(|s| s.opacity >= 1.0) { SLICE_GROW } else { 0.0 };
    let slices = gradient_slices(bp, rule, st, SLICE_TOL, SLICE_MARGIN, grow)
        .into_iter()
        .map(|s| {
            let paint = s.paint(g);
            (s.shape, paint)
        })
        .collect();
    Some(WrittenSlices { clip, slices })
}

/// Outline Stroke of stroke `st` of `bp` (filled with `rule`) whose gradient `g` runs along or
/// across it: a gradient mesh per subpath over all the stroke can paint there (clip it to the
/// stroke's outline), coloured as [`gradient_slices`] paint it.
pub fn gradient_meshes(bp: &BezPath, rule: FillRule, st: &StrokeLayer, g: &Gradient) -> Vec<GradientMesh> {
    let across = st.gradient_mode == StrokeGradientMode::Across;
    let color = |t: f64| g.sample_keep_model(t.clamp(0.0, 1.0) as f32);
    // Along: a column at each stop (colours are linear between columns), close enough to look smooth.
    let marks: Vec<f64> = if across { vec![] } else { g.expanded_stops().iter().map(|s| s.0 as f64).collect() };
    let max_dt = match (across, st.profile.is_some()) {
        (false, _) => MESH_STEP,
        (true, true) => PROFILE_STEP,
        (true, false) => 1.0,
    };
    // Rows across: the strip's edges, then (across) the band's left edge to its right edge with a row at each stop.
    let mut us: Vec<f64> = if across {
        (0..=MESH_ROWS).map(|i| i as f64 / MESH_ROWS as f64).chain(g.expanded_stops().iter().map(|s| s.0 as f64)).collect()
    } else {
        vec![0.5]
    };
    us.sort_by(f64::total_cmp);
    us.dedup_by(|a, b| (*a - *b).abs() < 1e-6);
    strips(bp, rule, st, SLICE_TOL, SLICE_MARGIN, &marks, max_dt)
        .into_iter()
        .filter(|ribs| ribs.len() > 1)
        .map(|ribs| {
            let (rows, cols) = (us.len() + 1, ribs.len() - 1);
            // Each level across: a point on each rib and the gradient position there.
            let level = |row: usize, rib: &Rib| -> (Point, f64) {
                let t = |u: f64| if across { u } else { rib.t };
                match row {
                    0 => (rib.l, t(0.0)),
                    _ if row == rows => (rib.r, t(1.0)),
                    _ if across => {
                        let (l, r) = rib.band;
                        (rib.at(l - us[row - 1] * (l + r)), us[row - 1])
                    }
                    _ => (rib.c, rib.t),
                }
            };
            let level = &level;
            let pos: Vec<Point> = (0..=rows).flat_map(|row| ribs.iter().map(move |rib| level(row, rib).0)).collect();
            let at = |row: usize, col: usize| pos[row * (cols + 1) + col];
            let mut points = Vec::with_capacity(pos.len());
            for row in 0..=rows {
                for (col, rib) in ribs.iter().enumerate() {
                    let p = at(row, col);
                    let toward = |o: Option<Point>| o.map_or(Vec2::ZERO, |o| (o - p) / 3.0);
                    let mut handles = [Vec2::ZERO; 4];
                    handles[H_RIGHT] = toward((col < cols).then(|| at(row, col + 1)));
                    handles[H_LEFT] = toward(col.checked_sub(1).map(|c| at(row, c)));
                    handles[H_DOWN] = toward((row < rows).then(|| at(row + 1, col)));
                    handles[H_UP] = toward(row.checked_sub(1).map(|r| at(r, col)));
                    let (color, opacity) = color(level(row, rib).1);
                    points.push(MeshPoint { p, color, opacity, handles });
                }
            }
            GradientMesh { rows: rows as u32, cols: cols as u32, points }
        })
        .collect()
}