Skip to content

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

16.5 KB
Raw Blame
//! Snap points (#5881): the points a hovered edge or face offers as picks, so a point input
//! (Move's From and To, Measure, …) can take a hole's centre or an edge's middle where no vertex
//! sits. A round edge offers its centre (an arc also its ends and middle), a straight or other
//! edge its ends and middle, a cylinder or cone the centres of its ends, a sphere or torus its
//! centre, a vertex itself. A flat face offers its centre and its whole outline at once (#11476):
//! every corner, the middle of every straight edge and the centre of every round edge, holes
//! included, read from the exact faces and edges. The other shapes are Measure's: exact from the
//! kernel where it knows the curve or surface, fitted to the mesh otherwise. World coordinates,
//! as the viewport shows the model.
//!
//! [`snap_points_from`] also says where each point came from ([`SnapSource`]): the face, its
//! outward normal and the edge, so a tool can keep the point by name and turn a frame to the face.

use serde::Serialize;
use solidcore_record::Vec3;
use solidcore_record::brep::{Brep, Curve, Loop};
use solidcraft_geom::UnitVec3;
use solidcraft_geom::brep::eval::CurveEval;
use solidcraft_geom::prelude::*;
use solidcraft_kernel::{Body, EdgeCircle};

use crate::cmd::Shape;
use crate::{Sel, Session};

/// What a snap point is on its item.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum SnapKind {
    /// The centre of a circle, an arc, a sphere or a torus, or of one end of a cylinder or cone.
    Centre,
    /// The middle of an edge (along its length).
    Middle,
    /// One end of an edge.
    End,
    /// The centre of a flat face (of its area).
    FaceCentre,
    /// A vertex.
    Vertex,
}

/// A point an item offers as a pick.
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct SnapPoint {
    pub at: Vec3,
    pub kind: SnapKind,
    /// The body the item belongs to (empty for the origin and sketch geometry).
    pub body: String,
}

/// Where a snap point came from, in world coordinates: what a tool needs to keep the point by
/// name as the part changes (`joint.create`'s `{"edge", "corner", "on"}`) and to turn a frame to
/// the face it lies on. Empty for a vertex and for sketch geometry.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct SnapSource {
    /// A point on the face that offered the point: where the face was picked.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub face: Option<Vec3>,
    /// Which way the point's face looks, as a unit vector: a flat face's outward normal (out of
    /// the material), or for a cylinder's or cone's end centre the axis pointing out of that end
    /// of the face. That is an axis direction, not always out of the material: at a blind hole's
    /// bottom it points into the material below.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub normal: Option<Vec3>,
    /// A point inside the edge the point belongs to: the edge a corner starts, the straight edge a
    /// middle halves, the round edge a centre is the centre of, or the picked edge itself.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub edge: Option<Vec3>,
}

/// Two round edges' radii closer than this (relative to the radii) are one circle.
const SAME: f64 = 1e-6;

/// Points of one kind closer than this (relative to how far from the origin they are) are one
/// place: well above the rounding of coordinates there and of a circle fitted to an imported
/// edge, so a point found twice is one, and far below any feature, so distinct points stay apart
/// far from the origin too (0.06 µm at 60 m, where `SAME` would be 0.06 mm).
const SAME_PLACE: f64 = 1e-9;

/// The most edges of one face whose points a flat face offers: a face with more (an imported
/// lattice) offers those of its first edges.
const MAX_OUTLINE_EDGES: usize = 4096;

/// A point found on an item, its kind and where it came from.
pub(crate) type Found = (Vec3, SnapKind, SnapSource);

/// The snap points `sel` offers: none for things with no points to offer (a body, a plane).
pub fn snap_points(s: &Session, sel: &Sel) -> Vec<SnapPoint> {
    snap_points_from(s, sel).into_iter().map(|(p, _)| p).collect()
}

/// [`snap_points`], each with where it came from.
pub fn snap_points_from(s: &Session, sel: &Sel) -> Vec<(SnapPoint, SnapSource)> {
    let body = match sel {
        Sel::Edge { body, .. } | Sel::Face { body, .. } | Sel::Vertex { body, .. } => body.clone(),
        _ => String::new(),
    };
    let tagged =
        |points: Vec<(Vec3, SnapKind)>, from: SnapSource| -> Vec<Found> { points.into_iter().map(|(at, kind)| (at, kind, from.clone())).collect() };
    let found = match sel {
        Sel::Vertex { point, .. } => vec![(*point, SnapKind::Vertex, SnapSource::default())],
        Sel::Edge { point, .. } => tagged(edge_points(s, sel), SnapSource { edge: Some(*point), ..SnapSource::default() }),
        Sel::SketchCurve { .. } | Sel::ExternalSketchCurve { .. } => tagged(edge_points(s, sel), SnapSource::default()),
        Sel::Face { .. } => face_points(s, sel),
        _ => Vec::new(),
    };
    merged(found, &body)
}

/// The points found on an item as snap points, a point found twice kept once.
pub(crate) fn merged(found: Vec<Found>, body: &str) -> Vec<(SnapPoint, SnapSource)> {
    // A round edge's centre with the radius its rim has (the rim point is on the circle).
    let radius = |at: Vec3, from: &SnapSource| from.edge.map(|rim| rim.dist(at));
    let mut out: Vec<(SnapPoint, SnapSource)> = Vec::new();
    for (at, kind, from) in found {
        let tol = SAME_PLACE * (1.0 + at.len());
        // Only points of one kind are one point: a hole centred on its face is both the face's
        // centre and the hole's, and only the hole's keeps its rim. Centres are one point only
        // on one circle: a washer's two rims keep a centre each, while the pieces the kernel
        // split one circle into are one.
        let r = radius(at, &from);
        let one_circle = |other: Option<f64>| match (other, r) {
            // By the radii's own size, not the place's: far from the origin two close rims
            // would otherwise count as one.
            (Some(a), Some(b)) => (a - b).abs() <= SAME * (1.0 + a.max(b)),
            (None, None) => true,
            _ => false,
        };
        let same =
            |(p, f): &(SnapPoint, SnapSource)| p.kind == kind && p.at.dist(at) <= tol && (kind != SnapKind::Centre || one_circle(radius(p.at, f)));
        if at.is_finite() && !out.iter().any(same) {
            out.push((SnapPoint { at, kind, body: body.to_string() }, from));
        }
    }
    out
}

/// An edge's or sketch curve's points: a whole circle its centre; an arc its centre, ends and
/// middle; anything else its ends and middle.
fn edge_points(s: &Session, sel: &Sel) -> Vec<(Vec3, SnapKind)> {
    let Some((shape, pts, _)) = crate::cmd::shape_of(s, sel) else { return Vec::new() };
    let ends = |v: &mut Vec<(Vec3, SnapKind)>| {
        v.extend(pts.first().map(|p| (*p, SnapKind::End)));
        v.extend(pts.last().map(|p| (*p, SnapKind::End)));
    };
    let mut v = Vec::new();
    match shape {
        Shape::Round { center, axis, radius, .. } => {
            v.push((center, SnapKind::Centre));
            if !shape.full() {
                // The kernel may split one arc into pieces (at a cylinder's seam): the whole arc.
                let arc = whole_arc(s, sel, center, axis, radius).unwrap_or(pts.clone());
                v.extend(arc.first().map(|p| (*p, SnapKind::End)));
                v.extend(arc.last().map(|p| (*p, SnapKind::End)));
                v.extend(arc_middle(center, axis, &arc).map(|p| (p, SnapKind::Middle)));
            }
        }
        Shape::Line { a, b } => v.extend([(a, SnapKind::End), (b, SnapKind::End), (a.lerp(b, 0.5), SnapKind::Middle)]),
        _ => {
            ends(&mut v);
            v.extend(along(&pts, 0.5).map(|p| (p, SnapKind::Middle)));
        }
    }
    v
}

/// The polyline of a picked edge joined with the neighbouring edges that continue it on the
/// same circle, in order: the whole arc when the kernel split it.
fn whole_arc(s: &Session, sel: &Sel, center: Vec3, axis: UnitVec3, radius: f64) -> Option<Vec<Vec3>> {
    let Sel::Edge { body, index, .. } = sel else { return None };
    let st = s.world_state().ok()?;
    let m = st.body(body)?.mesh();
    let tol = (radius * 1e-6).max(1e-9);
    let on = |e: &Vec<Vec3>| e.iter().all(|p| (p.dist(center) - radius).abs() <= tol * 10.0 && (*p - center).dot(axis).abs() <= tol * 10.0);
    let mut left: Vec<usize> =
        m.tangent_chain(*index, 2f64.to_radians()).into_iter().filter(|&i| i != *index && m.edges.get(i).is_some_and(on)).collect();
    let mut arc = m.edges.get(*index).filter(|e| on(e))?.clone();
    // Add pieces at either end while one starts or ends there (capped by the pieces there are).
    while let Some((k, at_end, rev)) = left.iter().enumerate().find_map(|(k, &i)| {
        let e = m.edges.get(i)?;
        let (first, last, a, z) = (*e.first()?, *e.last()?, *arc.first()?, *arc.last()?);
        [(z, first, true, false), (z, last, true, true), (a, last, false, false), (a, first, false, true)]
            .into_iter()
            .find(|(p, q, _, _)| p.dist(*q) <= tol * 10.0)
            .map(|(_, _, at_end, rev)| (k, at_end, rev))
    }) {
        let i = left.swap_remove(k);
        let mut piece = m.edges.get(i)?.clone();
        if rev {
            piece.reverse();
        }
        if at_end {
            arc.extend(piece.into_iter().skip(1));
        } else {
            piece.pop();
            piece.extend(arc);
            arc = piece;
        }
    }
    Some(arc)
}

/// The exact middle of an arc through `pts` (first to last): on the circle, halfway round
/// from one end to the other on the side the polyline runs.
fn arc_middle(center: Vec3, axis: UnitVec3, pts: &[Vec3]) -> Option<Vec3> {
    let (a, z) = (*pts.first()? - center, *pts.last()? - center);
    let near = along(pts, 0.5)? - center;
    let radius = a.len();
    // Along the bisector of the ends, or square to them across a half circle.
    let dir = (a + z).normalized().or_else(|| axis.cross(a).normalized())?;
    let dir = if dir.dot(near) < 0.0 { -dir } else { dir };
    Some(center + dir * radius)
}

/// The point a fraction `f` of the way along a polyline (by length).
fn along(pts: &[Vec3], f: f64) -> Option<Vec3> {
    let total: f64 = pts.windows(2).map(|w| w[0].dist(w[1])).sum();
    let mut left = total * f;
    for w in pts.windows(2) {
        let d = w[0].dist(w[1]);
        if left <= d && d > 0.0 {
            return Some(w[0].lerp(w[1], left / d));
        }
        left -= d;
    }
    pts.last().copied()
}

/// A face's points: a flat face its area's centre and its outline ([`outline_points`]); a
/// cylinder or cone the centres of its two ends on the axis; a sphere or torus its centre.
fn face_points(s: &Session, sel: &Sel) -> Vec<Found> {
    let Sel::Face { body, index, point } = sel else { return Vec::new() };
    let Ok(st) = s.world_state() else { return Vec::new() };
    let Some(b) = st.body(body) else { return Vec::new() };
    let Some((shape, _, tris)) = crate::cmd::shape_of(s, sel) else { return Vec::new() };
    let verts: Vec<Vec3> = tris.iter().flat_map(|t| t.iter().copied()).collect();
    let on = SnapSource { face: Some(*point), ..SnapSource::default() };
    let tagged = |points: Vec<(Vec3, SnapKind)>| -> Vec<Found> { points.into_iter().map(|(at, kind)| (at, kind, on.clone())).collect() };
    match solidcraft_kernel::face_surface(&b.body, *index) {
        Some(solidcraft_kernel::FaceSurface::Sphere { center, .. } | solidcraft_kernel::FaceSurface::Torus { center, .. }) => {
            return tagged(vec![(center, SnapKind::Centre)]);
        }
        Some(solidcraft_kernel::FaceSurface::Cone { apex, axis, .. }) => return ends_out(axis_ends(apex, axis, &verts), axis, &on),
        _ => {}
    }
    match shape {
        Shape::Round { center, axis, .. } => ends_out(axis_ends(center, axis, &verts), axis, &on),
        Shape::Plane { .. } => {
            let flat = SnapSource { normal: b.body.planar_face(*index).and_then(|p| p.normal().normalized()), ..on.clone() };
            let mut v: Vec<Found> = area_centre(&tris).map(|p| vec![(p, SnapKind::FaceCentre, flat.clone())]).unwrap_or_default();
            v.extend(outline_points(&b.body, *index).into_iter().map(|(at, kind, edge)| (at, kind, SnapSource { edge: Some(edge), ..flat.clone() })));
            v
        }
        _ => Vec::new(),
    }
}

/// A flat face's outline from the exact record: every corner (where one edge ends and another
/// begins, but not where a round edge runs on into the next piece of its circle, nor on a closed
/// circle's seam), the middle of every straight edge and the centre of every round edge, holes
/// included. Each comes with a point inside the edge it belongs to, which finds that edge again.
fn outline_points(body: &Body, face: usize) -> Vec<(Vec3, SnapKind, Vec3)> {
    let record = body.record();
    let Some(f) = record.faces.get(face) else { return Vec::new() };
    let tol = (body.size() * 1e-7).max(1e-9) * 100.0;
    let mut out = Vec::new();
    let mut left = MAX_OUTLINE_EDGES;
    for l in &f.loops {
        let Loop::Edges { edges } = l else { continue };
        let edges = &edges[..edges.len().min(left)];
        left -= edges.len();
        let circles: Vec<Option<EdgeCircle>> = edges.iter().map(|oe| solidcraft_kernel::edge_circle(body, oe.edge as usize)).collect();
        for (i, oe) in edges.iter().enumerate() {
            let Some(e) = record.edges.get(oe.edge as usize) else { continue };
            let Some(c) = CurveEval::new(e.parameters()).ok() else { continue };
            let [t0, t1] = e.interval;
            let Some(inside) = c.point((t0 + t1) * 0.5) else { continue };
            match (circles.get(i).and_then(Option::as_ref), &e.curve) {
                (Some(circle), _) => out.push((circle.center, SnapKind::Centre, inside)),
                (None, Curve::Line { .. }) => {
                    if let (Some(a), Some(b)) = (c.point(t0), c.point(t1)) {
                        out.push((a.lerp(b, 0.5), SnapKind::Middle, inside));
                    }
                }
                _ => {}
            }
            // The corner this edge starts from in the loop.
            if e.vertices[0] == e.vertices[1] {
                continue;
            }
            let previous = i.checked_sub(1).unwrap_or(edges.len().saturating_sub(1));
            let runs_on = match (circles.get(previous).and_then(Option::as_ref), circles.get(i).and_then(Option::as_ref)) {
                (Some(a), Some(b)) if previous != i => same_circle(a, b, tol),
                _ => false,
            };
            let start = if oe.forward { e.vertices[0] } else { e.vertices[1] };
            if let (false, Some(p)) = (runs_on, vertex(record, start)) {
                out.push((p, SnapKind::End, inside));
            }
        }
        if left == 0 {
            break;
        }
    }
    out
}

/// Whether two round edges lie on one circle: one circle the kernel split into pieces.
fn same_circle(a: &EdgeCircle, b: &EdgeCircle, tol: f64) -> bool {
    a.center.dist(b.center) <= tol && (a.radius - b.radius).abs() <= tol && a.axis.dot(b.axis).abs() >= 1.0 - 1e-9
}

/// Vertex `i`'s point.
fn vertex(record: &Brep, i: u32) -> Option<Vec3> {
    record.vertices.get(i as usize).map(|v| Vec3::from(v.point)).filter(|p| p.is_finite())
}

/// A round face's two end centres (lower along `axis` first), each with the axis pointing out of
/// its end as the normal: the normal of the face a hole opens onto, or of a pin's end.
fn ends_out(ends: Vec<(Vec3, SnapKind)>, axis: UnitVec3, on: &SnapSource) -> Vec<Found> {
    ends.into_iter().zip([-axis.vec(), axis.vec()]).map(|((at, kind), out)| (at, kind, SnapSource { normal: Some(out), ..on.clone() })).collect()
}

/// The points of the axis through `origin` along `axis` level with the face's two ends.
fn axis_ends(origin: Vec3, axis: UnitVec3, verts: &[Vec3]) -> Vec<(Vec3, SnapKind)> {
    let along = || verts.iter().map(|p| (*p - origin).dot(axis));
    let (lo, hi) = (along().fold(f64::INFINITY, f64::min), along().fold(f64::NEG_INFINITY, f64::max));
    if !(lo.is_finite() && hi.is_finite()) {
        return Vec::new();
    }
    vec![(origin + axis * lo, SnapKind::Centre), (origin + axis * hi, SnapKind::Centre)]
}

/// The centre of the area of some triangles.
fn area_centre(tris: &[[Vec3; 3]]) -> Option<Vec3> {
    let (mut sum, mut area) = (Vec3::ZERO, 0.0);
    for [a, b, c] in tris {
        let w = (*b - *a).cross(*c - *a).len() * 0.5;
        sum += (*a + *b + *c) * (w / 3.0);
        area += w;
    }
    (area > 0.0).then(|| sum * (1.0 / area))
}