Skip to content

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

21.9 KB
Raw Blame
//! Define Perspective Grid: the dialog's view of the grid ([`GridDefinition`]: type, units, scale,
//! gridline spacing, viewing angle and distance, horizon height, third vanishing point, gridline
//! colours and opacity), the camera behind it (the [`Station`] point) and the built-in presets.
//!
//! The station point is the viewer: `D` points in front of the picture plane, level with the
//! horizon at the centre of vision `cv`. In two- and three-point perspective the viewing angle θ
//! is the angle between the left plane and the picture plane, so the vanishing points sit at
//! `cv − D·cot θ` and `cv + D·tan θ` (the station point lies on the circle over them). A receding
//! axis foreshortens by the distance from the viewer to its vanishing point, which keeps the grid
//! cells square in the scene whatever the angle.

use serde::{Deserialize, Serialize};
use serde_json::Value;
use vectorcraft_doc::{Document, Unit};
use vectorcraft_geom::Rect;

use super::{PerspectiveGrid, Plane};

/// A Letter page: where presets are fitted without a document.
pub const LETTER: Rect = Rect::new(0.0, 0.0, 612.0, 792.0);

/// The viewing angle of grids made before it was stored, and of the presets.
pub const DEFAULT_ANGLE: f64 = 45.0;

/// The largest length (points) a grid takes, as [`PerspectiveGrid::validate`] allows.
const MAX_LEN: f64 = 4.0e6;

/// The built-in presets: (name, kind, horizon height as a fraction of the artboard height from
/// the top). The ground line sits at 78 % of the height in all of them.
pub const BUILTINS: [(&str, u8, f64); 8] = [
    ("[1P-Normal View]", 1, 0.42),
    ("[1P-Low View]", 1, 0.66),
    ("[1P-High View]", 1, 0.12),
    ("[2P-Normal View]", 2, 0.42),
    ("[2P-Low View]", 2, 0.66),
    ("[2P-High View]", 2, 0.12),
    ("[3P-Normal View]", 3, 0.42),
    ("[3P-Low View]", 3, 0.66),
];

/// Is `name` a built-in preset's (any case)?
pub fn is_builtin(name: &str) -> bool {
    BUILTINS.iter().any(|b| b.0.eq_ignore_ascii_case(name.trim()))
}

/// The first artboard of `doc` (a Letter page without one).
pub fn first_artboard(doc: &Document) -> Rect {
    doc.artboards.first().map_or(LETTER, |a| a.rect)
}

// Serde defaults of the grid's definition fields.
pub(super) fn points() -> String {
    Unit::Points.key().into()
}
pub(super) fn is_points(u: &String) -> bool {
    u == Unit::Points.key()
}
pub(super) fn one_to_one() -> [f64; 2] {
    [1.0, 1.0]
}
pub(super) fn is_one_to_one(s: &[f64; 2]) -> bool {
    *s == one_to_one()
}
pub(super) fn left_rgb() -> Rgb {
    Rgb(Plane::Left.color())
}
pub(super) fn right_rgb() -> Rgb {
    Rgb(Plane::Right.color())
}
pub(super) fn ground_rgb() -> Rgb {
    Rgb(Plane::Ground.color())
}
pub(super) fn half() -> f64 {
    50.0
}

/// A `#rrggbb` colour (gridline colours).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(try_from = "String", into = "String")]
pub struct Rgb(pub [u8; 3]);

impl Rgb {
    /// `#rrggbb` or `rrggbb`.
    pub fn parse(s: &str) -> Option<Self> {
        let h = s.trim();
        let h = h.strip_prefix('#').unwrap_or(h);
        if h.len() != 6 || !h.chars().all(|c| c.is_ascii_hexdigit()) {
            return None;
        }
        let byte = |i: usize| h.get(i..i + 2).and_then(|b| u8::from_str_radix(b, 16).ok());
        Some(Self([byte(0)?, byte(2)?, byte(4)?]))
    }
    /// `#rrggbb`.
    pub fn hex(self) -> String {
        let [r, g, b] = self.0;
        format!("#{r:02x}{g:02x}{b:02x}")
    }
}

impl TryFrom<String> for Rgb {
    type Error = String;
    fn try_from(s: String) -> Result<Self, String> {
        Self::parse(&s).ok_or_else(|| format!("`{s}` isn't a #rrggbb colour"))
    }
}

impl From<Rgb> for String {
    fn from(c: Rgb) -> String {
        c.hex()
    }
}

/// The viewer: the centre of vision `x` on the horizon and the distance to the picture plane.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Station {
    pub x: f64,
    pub distance: f64,
}

/// Define Perspective Grid's fields: the grid as the dialog shows it. Lengths are real-world
/// lengths in `units`, drawn at `scale` (`[artboard, real world]`).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct GridDefinition {
    /// The preset's name ("" = custom).
    pub name: String,
    /// 1, 2 or 3-point perspective.
    pub kind: u8,
    /// A unit name (`points`, `pixels`, `inches`, `centimeters`…).
    pub units: String,
    /// `[artboard, real world]`: 1:4 draws 4 real-world units as 1.
    pub scale: [f64; 2],
    /// Gridline every (real-world units).
    pub gridline: f64,
    /// Viewing angle (degrees, between 0 and 90; two/three-point).
    pub angle: f64,
    /// Viewing distance: the station point's distance from the picture plane.
    pub distance: f64,
    /// Horizon height above the ground level.
    pub horizon_height: f64,
    /// The third vanishing point (three-point) from the centre of vision: x to the right, y up.
    pub third_vp: [f64; 2],
    pub left_color: Rgb,
    pub right_color: Rgb,
    pub ground_color: Rgb,
    /// Gridline opacity, 0–100 %.
    pub opacity: f64,
}

impl Default for GridDefinition {
    /// [2P-Normal View] on a Letter page.
    fn default() -> Self {
        PerspectiveGrid::normal(2, LETTER).definition()
    }
}

impl GridDefinition {
    /// The unit the lengths are in.
    pub fn unit(&self) -> Unit {
        Unit::named(&self.units).unwrap_or_default()
    }

    /// Artboard points per real-world unit.
    pub fn ratio(&self) -> f64 {
        self.unit().points() * self.scale[0] / self.scale[1]
    }

    /// Merge `patch` (any subset of the fields; other keys are ignored) into this definition.
    pub fn merged(&self, patch: &Value) -> Result<Self, String> {
        let mut v = serde_json::to_value(self).map_err(|e| e.to_string())?;
        if let (Some(o), Some(p)) = (v.as_object_mut(), patch.as_object()) {
            for (k, val) in p {
                if o.contains_key(k) {
                    o.insert(k.clone(), val.clone());
                }
            }
        }
        let mut d: Self = serde_json::from_value(v).map_err(|e| e.to_string())?;
        d.units = Unit::named(&d.units).ok_or_else(|| format!("unknown unit `{}`", d.units))?.key().into();
        d.validate()?;
        Ok(d)
    }

    pub fn validate(&self) -> Result<(), String> {
        if !(1..=3).contains(&self.kind) {
            return Err("kind must be 1, 2 or 3".into());
        }
        if Unit::named(&self.units).is_none() {
            return Err(format!("unknown unit `{}`", self.units));
        }
        if !self.scale.iter().all(|s| s.is_finite() && *s > 0.0 && *s <= 1.0e6) {
            return Err("scale must be two positive numbers [artboard, real world]".into());
        }
        let r = self.ratio();
        let lens = [self.gridline, self.distance, self.horizon_height, self.third_vp[0], self.third_vp[1]];
        if lens.iter().any(|v| !(v * r).is_finite() || (v * r).abs() > MAX_LEN) {
            return Err("grid lengths must be finite".into());
        }
        if self.gridline * r <= 0.0 || self.distance * r <= 0.0 {
            return Err("gridline spacing and viewing distance must be positive".into());
        }
        if (self.horizon_height * r).abs() < 1e-6 {
            return Err("the horizon height can't be 0".into());
        }
        if !(self.angle > 0.0 && self.angle < 90.0) {
            return Err("the viewing angle must be between 0 and 90°".into());
        }
        if !(0.0..=100.0).contains(&self.opacity) {
            return Err("opacity must be 0–100".into());
        }
        Ok(())
    }

    /// The same grid (names aside, lengths compared in points)?
    pub fn same(&self, o: &Self) -> bool {
        let (r, s) = (self.ratio(), o.ratio());
        let near = |a: f64, b: f64| (a - b).abs() <= 1e-6 * a.abs().max(b.abs()).max(1.0);
        self.kind == o.kind
            && near(self.gridline * r, o.gridline * s)
            && near(self.distance * r, o.distance * s)
            && near(self.horizon_height * r, o.horizon_height * s)
            && (self.kind != 3 || near(self.third_vp[0] * r, o.third_vp[0] * s) && near(self.third_vp[1] * r, o.third_vp[1] * s))
            && (self.kind == 1 || near(self.angle, o.angle))
            && (self.left_color, self.right_color, self.ground_color) == (o.left_color, o.right_color, o.ground_color)
            && near(self.opacity, o.opacity)
    }
}

impl PerspectiveGrid {
    /// The built-in preset `name` (any case) fitted to `ab`.
    pub fn builtin(name: &str, ab: Rect) -> Option<Self> {
        let &(name, kind, horizon) = BUILTINS.iter().find(|b| b.0.eq_ignore_ascii_case(name.trim()))?;
        let mut g = Self::preset(kind, ab);
        let ground = g.origin[1];
        g.horizon = ab.y0 + horizon * ab.height().max(1.0);
        g.vp_vertical = [g.vp_vertical[0], g.horizon - 3.0 * (ground - g.horizon)];
        g.name = name.into();
        g.set_station(g.station(), DEFAULT_ANGLE);
        Some(g)
    }

    /// The normal view preset of `kind` (1–3) fitted to `ab`.
    pub fn normal(kind: u8, ab: Rect) -> Self {
        let name = BUILTINS.iter().find(|b| b.1 == kind.clamp(1, 3)).map_or("", |b| b.0);
        Self::builtin(name, ab).unwrap_or_else(|| Self::preset(kind, ab))
    }

    /// The viewing angle in degrees.
    pub fn viewing_angle(&self) -> f64 {
        self.angle.unwrap_or(DEFAULT_ANGLE)
    }

    /// The station point: one-point grids look straight at their vanishing point from
    /// `distance`; two/three-point ones stand where the viewing angle puts them (grids without
    /// one: halfway between the vanishing points).
    pub fn station(&self) -> Station {
        let w = self.vp_right - self.vp_left;
        match self.angle {
            _ if self.kind == 1 => Station { x: self.vp_left, distance: self.distance },
            Some(a) if w > 0.0 => {
                let (s, c) = a.to_radians().sin_cos();
                Station { x: self.vp_left + w * c * c, distance: w * s * c }
            }
            _ => Station { x: (self.vp_left + self.vp_right) / 2.0, distance: if w.abs() > 1e-9 { w.abs() / 2.0 } else { self.distance } },
        }
    }

    /// Place the vanishing points for a viewer at `st` looking at `angle` degrees (one-point: the
    /// vanishing point at the centre of vision).
    pub fn set_station(&mut self, st: Station, angle: f64) {
        self.distance = st.distance;
        self.angle = Some(angle);
        if self.kind == 1 {
            self.vp_left = st.x;
        } else {
            let t = angle.to_radians().tan();
            self.vp_left = st.x - st.distance / t;
            self.vp_right = st.x + st.distance * t;
        }
    }

    /// 1 / the measuring distance of the left, right and vertical axes: the viewer's distance to
    /// their vanishing points (grids without a viewing angle: `distance` for all).
    pub(super) fn foreshortening(&self) -> (f64, f64, f64) {
        let uniform = 1.0 / self.distance.max(1e-9);
        if self.kind == 1 || self.angle.is_none() || self.vp_right <= self.vp_left {
            return (uniform, uniform, uniform);
        }
        let st = self.station();
        let to = |x: f64, y: f64| 1.0 / (st.distance.powi(2) + (x - st.x).powi(2) + (y - self.horizon).powi(2)).sqrt().max(1e-9);
        (to(self.vp_left, self.horizon), to(self.vp_right, self.horizon), to(self.vp_vertical[0], self.vp_vertical[1]))
    }

    /// After merging `patch` over `old`: a new viewing angle, viewing distance or type moves the
    /// vanishing points around the old station point (unless the patch places them), and
    /// `distance` reads the station's.
    pub(super) fn reconcile(&mut self, old: &Self, patch: &Value) {
        let has = |k: &str| patch.get(k).is_some();
        let camera = has("angle") || has("distance") && self.kind != 1;
        if !(has("vpLeft") || has("vpRight")) && (camera || self.kind != old.kind) {
            let st = old.station();
            let st = Station { distance: if has("distance") { self.distance } else { st.distance }, ..st };
            self.set_station(st, self.viewing_angle());
        }
        if self.kind != 1 && self.angle.is_some() && self.vp_right > self.vp_left {
            self.distance = self.station().distance;
        }
    }

    /// The definition fields' part of [`PerspectiveGrid::validate`].
    pub(super) fn validate_definition(&self) -> Result<(), String> {
        if self.angle.is_some_and(|a| !(a > 0.0 && a < 90.0)) {
            return Err("the viewing angle must be between 0 and 90°".into());
        }
        if self.kind != 1 && self.angle.is_some() && self.vp_right <= self.vp_left {
            return Err("the right vanishing point must be right of the left one".into());
        }
        if Unit::named(&self.units).is_none() {
            return Err(format!("unknown unit `{}`", self.units));
        }
        if !self.scale.iter().all(|s| s.is_finite() && *s > 0.0 && *s <= 1.0e6) {
            return Err("scale must be two positive numbers [artboard, real world]".into());
        }
        if !(0.0..=100.0).contains(&self.opacity) {
            return Err("opacity must be 0–100".into());
        }
        if self.extent_right.is_some_and(|e| !(e > 0.0 && e <= MAX_LEN)) {
            return Err("extentRight must be positive".into());
        }
        Ok(())
    }

    /// The grid as Define Grid shows it.
    pub fn definition(&self) -> GridDefinition {
        let mut d = GridDefinition {
            name: self.name.clone(),
            kind: self.kind,
            units: self.units.clone(),
            scale: self.scale,
            gridline: 0.0,
            angle: self.viewing_angle(),
            distance: 0.0,
            horizon_height: 0.0,
            third_vp: [0.0; 2],
            left_color: self.left_color,
            right_color: self.right_color,
            ground_color: self.ground_color,
            opacity: self.opacity,
        };
        let r = d.ratio();
        let st = self.station();
        d.gridline = self.cell / r;
        d.distance = st.distance / r;
        d.horizon_height = (self.origin[1] - self.horizon) / r;
        d.third_vp = [(self.vp_vertical[0] - st.x) / r, (self.horizon - self.vp_vertical[1]) / r];
        d
    }

    /// This grid redefined by `def`: only what differs from [`Self::definition`] changes, so the
    /// unchanged fields leave the grid exactly as it was. A new type, viewing angle or distance
    /// moves the vanishing points around the station point.
    pub fn with_definition(&self, def: &GridDefinition) -> Result<Self, String> {
        def.validate()?;
        let cur = self.definition();
        let r = def.ratio();
        let near = |a: f64, b: f64| (a - b).abs() <= 1e-6 * a.abs().max(b.abs()).max(1.0);
        let cr = cur.ratio();
        let mut g = self.clone();
        g.name = def.name.clone();
        g.units = def.unit().key().into();
        g.scale = def.scale;
        (g.left_color, g.right_color, g.ground_color, g.opacity) = (def.left_color, def.right_color, def.ground_color, def.opacity);
        g.kind = def.kind;
        if !near(def.gridline * r, cur.gridline * cr) {
            g.cell = def.gridline * r;
        }
        if !near(def.horizon_height * r, cur.horizon_height * cr) {
            g.horizon = g.origin[1] - def.horizon_height * r;
        }
        if def.kind != self.kind || !near(def.distance * r, cur.distance * cr) || def.kind != 1 && !near(def.angle, cur.angle) {
            let st = Station { distance: def.distance * r, ..self.station() };
            g.set_station(st, def.angle);
        }
        if !(near(def.third_vp[0] * r, cur.third_vp[0] * cr) && near(def.third_vp[1] * r, cur.third_vp[1] * cr)) || g.horizon != self.horizon {
            let x = g.station().x;
            g.vp_vertical = [x + def.third_vp[0] * r, g.horizon - def.third_vp[1] * r];
        }
        g.validate()?;
        Ok(g)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    use vectorcraft_geom::Point;

    const AB: Rect = Rect::new(0.0, 0.0, 800.0, 600.0);

    #[test]
    fn rgb_rejects_repeated_hash() {
        assert!(Rgb::parse("##ff0000").is_none());
        assert!(Rgb::parse("####00ff00").is_none());
        assert!(Rgb::try_from(String::from("##ff0000")).is_err());
        assert_eq!(Rgb::parse("#ff0000"), Some(Rgb([255, 0, 0])));
        assert_eq!(Rgb::parse("ff0000"), Some(Rgb([255, 0, 0])));
    }

    #[test]
    fn the_station_point_places_the_vanishing_points() {
        let mut g = PerspectiveGrid::normal(2, AB);
        let st = g.station();
        assert!((st.x - g.origin[0]).abs() < 1e-9, "the normal view looks at the corner");
        // At 30° the left plane turns toward the picture plane: its vanishing point recedes.
        g.set_station(st, 30.0);
        assert!((st.x - g.vp_left - st.distance * 3f64.sqrt()).abs() < 1e-9);
        assert!((g.vp_right - st.x - st.distance / 3f64.sqrt()).abs() < 1e-9);
        let back = g.station();
        assert!((back.x - st.x).abs() < 1e-9 && (back.distance - st.distance).abs() < 1e-9);
        // The station point sees the vanishing points at a right angle.
        let (a, b) = (Point::new(g.vp_left - st.x, st.distance), Point::new(g.vp_right - st.x, st.distance));
        assert!((a.x * b.x + a.y * b.y).abs() < 1e-6 * st.distance * st.distance);
    }

    #[test]
    fn receding_axes_keep_true_lengths_at_the_picture_plane() {
        // A true camera: at the picture plane a step along a receding axis spans its true width
        // (cos θ of it on the left, sin θ on the right), whatever the viewing angle.
        for angle in [20.0, 45.0, 70.0] {
            let mut g = PerspectiveGrid::normal(2, AB);
            g.set_station(g.station(), angle);
            g.origin[0] = g.station().x;
            for pl in [Plane::Left, Plane::Right] {
                let h = g.homography(pl).unwrap();
                let (o, e) = (h.apply(Point::new(0.0, 0.0)).unwrap(), h.apply(Point::new(1e-3, 0.0)).unwrap());
                let s = angle.to_radians();
                let dx = if pl == Plane::Left { s.cos() } else { s.sin() };
                assert!(((e.x - o.x).abs() / 1e-3 - dx).abs() < 1e-3, "{angle} {pl:?}");
            }
        }
    }

    #[test]
    fn definition_round_trips_and_unchanged_fields_change_nothing() {
        for kind in [1u8, 2, 3] {
            let g = PerspectiveGrid::normal(kind, AB);
            let d = g.definition();
            assert_eq!(g.with_definition(&d).unwrap(), g);
            // In inches at 1:4 the same grid reads differently but is the same.
            let inches = GridDefinition { units: "inches".into(), scale: [1.0, 4.0], ..d.clone() };
            let r = inches.ratio() / d.ratio();
            let inches = GridDefinition {
                gridline: d.gridline / r,
                distance: d.distance / r,
                horizon_height: d.horizon_height / r,
                third_vp: d.third_vp.map(|v| v / r),
                ..inches
            };
            let g2 = g.with_definition(&inches).unwrap();
            assert_eq!((g2.origin, g2.horizon, g2.vp_left, g2.vp_right, g2.cell), (g.origin, g.horizon, g.vp_left, g.vp_right, g.cell));
            assert!(g2.definition().same(&d));
        }
        // A grid from before the viewing angle keeps its foreshortening through an unchanged OK.
        let legacy = PerspectiveGrid::preset(2, AB);
        let d = legacy.definition();
        assert_eq!(legacy.with_definition(&GridDefinition { opacity: 80.0, ..d.clone() }).unwrap().angle, None);
        assert!(legacy.with_definition(&GridDefinition { angle: 30.0, ..d }).unwrap().angle.is_some());
    }

    #[test]
    fn definition_fields_map_to_the_grid() {
        let g = PerspectiveGrid::normal(3, AB);
        let d = GridDefinition {
            gridline: 2.0,
            angle: 30.0,
            distance: 5.0,
            horizon_height: 3.0,
            third_vp: [1.0, 8.0],
            units: "inches".into(),
            ..g.definition()
        };
        let n = g.with_definition(&d).unwrap();
        let st = n.station();
        assert!((n.cell - 144.0).abs() < 1e-9);
        assert!((st.distance - 360.0).abs() < 1e-6 && (st.x - g.station().x).abs() < 1e-6, "the viewer stays put");
        assert!((n.viewing_angle() - 30.0).abs() < 1e-9);
        assert!((n.origin[1] - n.horizon - 216.0).abs() < 1e-9);
        assert!((n.vp_vertical[0] - st.x - 72.0).abs() < 1e-6 && (n.horizon - n.vp_vertical[1] - 576.0).abs() < 1e-6);
        assert_eq!(n.units, "inches");
        // Bad values are refused.
        for bad in [
            json!({"angle": 90}),
            json!({"distance": 0}),
            json!({"units": "furlongs"}),
            json!({"scale": [1, 0]}),
            json!({"opacity": 120}),
            json!({"kind": 4}),
        ] {
            assert!(d.merged(&bad).is_err(), "{bad}");
        }
        assert_eq!(d.merged(&json!({"units": "mm", "leftColor": "#00ff00"})).unwrap().units, "millimeters");
        assert!(d.merged(&json!({"leftColor": "green"})).is_err());
    }

    #[test]
    fn set_moves_the_vanishing_points_for_a_new_angle_or_distance() {
        let g = PerspectiveGrid::normal(2, AB);
        let st = g.station();
        let n = g.merged(&json!({"angle": 60})).unwrap();
        assert!((n.station().x - st.x).abs() < 1e-6 && (n.station().distance - st.distance).abs() < 1e-6);
        let n = g.merged(&json!({"distance": 100})).unwrap();
        assert!((n.vp_right - n.vp_left - 200.0).abs() < 1e-6);
        // Moving a vanishing point keeps the angle; `distance` follows.
        let n = g.merged(&json!({"vpLeft": g.vp_left - 100.0})).unwrap();
        assert_eq!(n.angle, Some(45.0));
        assert!((n.distance - (n.vp_right - n.vp_left) / 2.0).abs() < 1e-6);
        assert!(g.merged(&json!({"vpRight": g.vp_left - 10.0})).is_err());
    }

    #[test]
    fn rgb_parses_hex() {
        assert_eq!(Rgb::parse("#3366ff"), Some(Rgb([0x33, 0x66, 0xff])));
        assert_eq!(Rgb::parse("ff8C1A").map(Rgb::hex).as_deref(), Some("#ff8c1a"));
        for bad in ["", "#12345", "#gg0000", "é12345", "#1234567", "+f+f+f"] {
            assert_eq!(Rgb::parse(bad), None, "{bad}");
        }
    }
}