Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

12.5 KB
Raw Blame
//! Drawing views as data (W17a, #4816): which way a view looks, its scale, and the map from the
//! model's millimetres to the paper's. Nothing here draws or measures; the view commands (W07)
//! and the hidden-line and section producers feed it.
//!
//! - A view's **basis** is a [`Plane`]: paper x along `x`, paper y along `y`, and its normal
//!   `x × y` toward the viewer. [`NamedView`] gives the principal views and the four upper
//!   isometric corners exactly, never from a camera, which tilts a top view by its pitch clamp;
//!   [`basis_looking`] gives any other view from its direction and up.
//! - A **[`Scale`]** is a ratio of two numbers from 0.000001 to 1000000, written `"1:2"` (paper :
//!   model), from 1:100000 to 1000:1. [`Scale::fit`] picks the largest of ISO 5455's preset
//!   scales at which a view fits a space.
//! - A **[`ViewFrame`]** places a view on paper: the point of the view's plane at `centre` lands at
//!   `position_mm`, everything scaled by the scale. Its [`ViewFrame::paper_map`] moves the view's
//!   curves ([`Seg2Geom::similar`]) and their accuracy ([`CurveAccuracy::scaled`]) onto paper.

use crate::prelude::*;
use std::fmt;
use std::str::FromStr;

use serde::{Deserialize, Deserializer, Serialize, Serializer};

use crate::paper::MAX_SIDE_MM;
use crate::section::{CurveAccuracy, MAX_NUMBER, validate_plane};
use crate::{Aabb2, Similarity2};
use solidcore_record::{Plane, Seg2, Vec2, Vec3};

/// The smallest scale: one paper millimetre for 100 m of model.
pub const MIN_SCALE: f64 = 1e-5;
/// The largest scale: 1000 paper millimetres for one of model.
pub const MAX_SCALE: f64 = 1000.0;
/// The smallest and largest number either side of a scale may be: `"1:100000"` and `"1000:1"`
/// with room to spare, and never more than about 50 characters written out.
pub const MIN_PART: f64 = 1e-6;
pub const MAX_PART: f64 = 1e6;

#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("drawing view: {0}")]
pub struct Invalid(pub &'static str);

type Result<T> = std::result::Result<T, Invalid>;

fn require(condition: bool, message: &'static str) -> Result<()> {
    if condition { Ok(()) } else { Err(Invalid(message)) }
}

/// Two directions closer to parallel than this (the sine of their angle) give no view.
const PARALLEL: f64 = 1e-9;

/// A view with a name: the six principal views and the isometric views from the four upper
/// corners. Each looks at the model from where its name says; `iso` reads as the front-right one.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NamedView {
    Front,
    Back,
    Top,
    Bottom,
    Left,
    Right,
    #[serde(alias = "iso")]
    IsoFrontRight,
    IsoFrontLeft,
    IsoBackRight,
    IsoBackLeft,
}

impl NamedView {
    pub const ALL: [NamedView; 10] = [
        NamedView::Front,
        NamedView::Back,
        NamedView::Top,
        NamedView::Bottom,
        NamedView::Left,
        NamedView::Right,
        NamedView::IsoFrontRight,
        NamedView::IsoFrontLeft,
        NamedView::IsoBackRight,
        NamedView::IsoBackLeft,
    ];

    /// The view's basis, through the world origin. The principal views' axes are exact unit
    /// vectors, with no -0 to write out, each the front view folded about the edge it shares with
    /// it: the top and bottom views keep paper x along +X (the bottom's y is -Y), and the back and
    /// side views keep paper y along +Z. An isometric view looks from its corner, `(±1, ±1, 1)`,
    /// toward the origin, with paper x horizontal (along the view direction × Z) and paper y up.
    pub fn basis(self) -> Plane {
        let (x, y) = match self {
            NamedView::Front => (Vec3::X, Vec3::Z),
            NamedView::Back => (Vec3::new(-1.0, 0.0, 0.0), Vec3::Z),
            NamedView::Top => (Vec3::X, Vec3::Y),
            NamedView::Bottom => (Vec3::X, Vec3::new(0.0, -1.0, 0.0)),
            NamedView::Left => (Vec3::new(0.0, -1.0, 0.0), Vec3::Z),
            NamedView::Right => (Vec3::Y, Vec3::Z),
            NamedView::IsoFrontRight => iso(1.0, -1.0),
            NamedView::IsoFrontLeft => iso(-1.0, -1.0),
            NamedView::IsoBackRight => iso(1.0, 1.0),
            NamedView::IsoBackLeft => iso(-1.0, 1.0),
        };
        Plane { origin: Vec3::ZERO, x, y }
    }
}

/// The view through `origin` looking along `direction`, with `up` toward the top of the paper:
/// paper x = direction × up, paper y = x × direction, so the normal points back at the viewer as
/// the named views' do. `up` need not be square to the direction, only not along it.
pub fn basis_looking(direction: Vec3, up: Vec3, origin: Vec3) -> Result<Plane> {
    let d = direction.normalized().ok_or(Invalid("the view direction is zero or not finite"))?;
    let up = up.normalized().ok_or(Invalid("`up` is zero or not finite"))?;
    let across = d.cross(up);
    require(across.len() >= PARALLEL, "`up` lies along the view direction: give another up")?;
    require(
        origin.is_finite() && [origin.x, origin.y, origin.z].iter().all(|v| v.abs() <= MAX_NUMBER),
        "a view's origin is finite and within 1e12 mm of the world's",
    )?;
    // Square to the direction again: near the threshold the cross product's rounding is a large
    // share of its length, which would tilt the normal by up to 1e-8 rad.
    let across = across - d * across.dot(d);
    let x = across * (1.0 / across.len());
    let basis = Plane { origin, x, y: x.cross(d) };
    validate_plane(&basis).map_err(|_| Invalid("a view's basis is finite and orthonormal"))?;
    Ok(basis)
}

/// Paper x and y for an isometric view from the upper corner `(cx, cy, 1)`: x is horizontal, the
/// view direction × Z, and y = x × direction, so the normal points back at the corner.
fn iso(cx: f64, cy: f64) -> (Vec3, Vec3) {
    let toward = Vec3::new(-cx, -cy, -1.0) * (1.0 / 3f64.sqrt());
    let x = Vec3::new(-cy, cx, 0.0) * (1.0 / 2f64.sqrt());
    (x, x.cross(toward))
}

/// A drawing scale, paper : model, as two positive numbers so `"1:3"` stays exactly what was
/// written. Read and written as that text.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Scale {
    paper: f64,
    model: f64,
}

/// ISO 5455's recommended scales, largest first: enlargements, full size, then reductions.
pub const PRESETS: &[Scale] = &[
    Scale { paper: 50.0, model: 1.0 },
    Scale { paper: 20.0, model: 1.0 },
    Scale { paper: 10.0, model: 1.0 },
    Scale { paper: 5.0, model: 1.0 },
    Scale { paper: 2.0, model: 1.0 },
    Scale { paper: 1.0, model: 1.0 },
    Scale { paper: 1.0, model: 2.0 },
    Scale { paper: 1.0, model: 5.0 },
    Scale { paper: 1.0, model: 10.0 },
    Scale { paper: 1.0, model: 20.0 },
    Scale { paper: 1.0, model: 50.0 },
    Scale { paper: 1.0, model: 100.0 },
    Scale { paper: 1.0, model: 200.0 },
    Scale { paper: 1.0, model: 500.0 },
    Scale { paper: 1.0, model: 1000.0 },
    Scale { paper: 1.0, model: 2000.0 },
    Scale { paper: 1.0, model: 5000.0 },
    Scale { paper: 1.0, model: 10000.0 },
];

impl Scale {
    /// `paper : model`, each from [`MIN_PART`] to [`MAX_PART`] (so the text stays short), their
    /// ratio from [`MIN_SCALE`] to [`MAX_SCALE`].
    pub fn new(paper: f64, model: f64) -> Result<Scale> {
        let parts = [paper, model].into_iter().all(|v| (MIN_PART..=MAX_PART).contains(&v));
        let message = "a scale is two numbers from 0.000001 to 1000000, from 1:100000 to 1000:1";
        require(parts && (MIN_SCALE..=MAX_SCALE).contains(&(paper / model)), message)?;
        Ok(Scale { paper, model })
    }

    /// Paper millimetres per model millimetre.
    pub fn factor(self) -> f64 {
        self.paper / self.model
    }

    /// The largest preset at which a view `size_mm` wide and high (in model millimetres) fits
    /// within `room_mm` on paper, if any does. Compared as `size * paper <= room * model`, so an
    /// exact fit at 1:5 isn't lost to 0.2's rounding. A size of 0 sets no limit that way (a view of
    /// a line along the other), so a view of a point fits at the largest preset; a size or room
    /// that is negative or not finite fits none.
    pub fn fit(size_mm: Vec2, room_mm: Vec2) -> Option<Scale> {
        if ![size_mm, room_mm].into_iter().all(|v| v.is_finite() && v.x >= 0.0 && v.y >= 0.0) {
            return None;
        }
        PRESETS.iter().copied().find(|s| size_mm.x * s.paper <= room_mm.x * s.model && size_mm.y * s.paper <= room_mm.y * s.model)
    }
}

impl fmt::Display for Scale {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}:{}", self.paper, self.model)
    }
}

/// Plain decimal numbers only (`2`, `2.5`): digits, then at most one point with digits after it;
/// no sign, exponent or space.
fn decimal(text: &str) -> Option<f64> {
    let digits = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit());
    let plain = match text.split_once('.') {
        Some((whole, fraction)) => digits(whole) && digits(fraction),
        None => digits(text),
    };
    plain.then(|| text.parse().ok()).flatten()
}

impl FromStr for Scale {
    type Err = Invalid;

    fn from_str(text: &str) -> Result<Scale> {
        let parts = text.split_once(':').and_then(|(p, m)| Some((decimal(p)?, decimal(m)?)));
        let (paper, model) = parts.ok_or(Invalid("a scale is written paper:model, such as 1:2"))?;
        Scale::new(paper, model)
    }
}

impl Serialize for Scale {
    fn serialize<S: Serializer>(&self, s: S) -> std::result::Result<S::Ok, S::Error> {
        s.collect_str(self)
    }
}

impl<'de> Deserialize<'de> for Scale {
    fn deserialize<D: Deserializer<'de>>(d: D) -> std::result::Result<Scale, D::Error> {
        String::deserialize(d)?.parse().map_err(serde::de::Error::custom)
    }
}

/// A view placed on paper: its basis, its scale, and where it sits.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ViewFrame {
    basis: Plane,
    scale: Scale,
    map: Similarity2,
}

impl ViewFrame {
    /// The view through `basis` at `scale`, with the point `centre` of the view's plane (in its
    /// own coordinates, [`Plane::to_local`]) at `position_mm` on paper.
    pub fn new(basis: Plane, scale: Scale, centre: Vec2, position_mm: Vec2) -> Result<ViewFrame> {
        validate_plane(&basis).map_err(|_| Invalid("a view's basis is finite and orthonormal"))?;
        require(centre.is_finite() && centre.x.abs() <= MAX_NUMBER && centre.y.abs() <= MAX_NUMBER, "a view's centre is finite")?;
        let on_paper = position_mm.is_finite() && position_mm.x.abs() <= MAX_SIDE_MM && position_mm.y.abs() <= MAX_SIDE_MM;
        require(on_paper, "a view's position is finite and at most 5000 mm from the sheet's origin")?;
        let factor = scale.factor();
        let map = Similarity2::new(factor, 0.0, position_mm - centre * factor).ok_or(Invalid("a view's position is finite"))?;
        Ok(ViewFrame { basis, scale, map })
    }

    pub fn basis(&self) -> Plane {
        self.basis
    }

    pub fn scale(&self) -> Scale {
        self.scale
    }

    /// The map from the view's plane coordinates to paper millimetres, for its curves. Plane
    /// coordinates are the plane's own ([`Plane::to_local`]: from the basis's origin along its x
    /// and y), as section curves are. Points measured along x and y from the world origin (as the
    /// hidden-line output is planned to be) first lose the origin's own `(origin · x, origin · y)`;
    /// a named view's origin is the world origin, so for it the two are the same.
    pub fn paper_map(&self) -> Similarity2 {
        self.map
    }

    /// Where a model point appears on paper.
    pub fn to_paper(&self, p: Vec3) -> Vec2 {
        self.map.apply(self.basis.to_local(p))
    }

    /// A box of the view's plane (in plane coordinates, as [`Self::paper_map`]'s) on paper: the box
    /// around its four corners, mapped. A box that is inside out, or not finite on paper, has none.
    pub fn boundary(&self, model: &Aabb2) -> Result<Aabb2> {
        let corners = [model.min, Vec2::new(model.max.x, model.min.y), model.max, Vec2::new(model.min.x, model.max.y)].map(|c| self.map.apply(c));
        require(!model.is_empty() && corners.iter().all(|c| c.is_finite()), "a view's box is not inside out and is finite on paper")?;
        Ok(corners.into_iter().collect())
    }

    /// A curve of the view's plane (in plane coordinates, as [`Self::paper_map`]'s), on paper.
    pub fn seg_to_paper(&self, seg: &Seg2) -> Seg2 {
        seg.similar(&self.map)
    }

    /// A curve's accuracy on paper: its deviation scaled as the curve is.
    pub fn accuracy_on_paper(&self, accuracy: CurveAccuracy) -> CurveAccuracy {
        accuracy.scaled(self.map.scale())
    }
}

#[cfg(test)]
#[path = "drawing_view_tests.rs"]
mod tests;