SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! A Single hole placed by distances from reference edges (#37): up to two straight edges of the
//! face it is drilled into, each with the distance of the hole's centre from that edge's line,
//! measured in the face's plane. The edges are found again by their persistent names, else by
//! their stored points, so the hole follows them when the part changes.
use solidcore_record::Vec3;
use solidcraft_geom::Mesh;
use solidcraft_geom::prelude::*;
use crate::{DocError, ModelBody, ModelState, Result};
/// The most reference edges a hole takes.
pub const MAX_HOLE_REFERENCES: usize = 2;
/// A reference edge's line in the face's plane.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ReferenceLine {
/// A point on the line: the edge's middle, moved into the face's plane.
pub point: Vec3,
/// Along the edge (unit).
pub along: Vec3,
/// In the plane, square to the edge, toward the side the face is on (unit): the way the
/// distance grows.
pub toward: Vec3,
}
impl ReferenceLine {
/// How far `p` is from the line, toward the face's side (negative on the other side).
pub fn distance(&self, p: Vec3) -> f64 {
(p - self.point).dot(self.toward)
}
/// The point of the line nearest `p`.
pub fn foot(&self, p: Vec3) -> Vec3 {
self.point + self.along * (p - self.point).dot(self.along)
}
}
/// The face a referenced hole is drilled into (its plane) and its reference edges' lines.
#[derive(Clone, Debug, PartialEq)]
pub struct ReferenceFrame {
/// The body and the face (its index).
pub body: String,
pub face: usize,
/// A point on the face's plane.
pub origin: Vec3,
/// The face's outward unit normal.
pub normal: Vec3,
pub lines: Vec<ReferenceLine>,
/// The reference edges found (their indices in the body's mesh), one per line.
pub edges: Vec<usize>,
}
impl ReferenceFrame {
/// `p` moved square onto the face's plane.
pub fn onto_plane(&self, p: Vec3) -> Vec3 {
p - self.normal * (p - self.origin).dot(self.normal)
}
/// How far `p` is from each line (see [`ReferenceLine::distance`]).
pub fn distances(&self, p: Vec3) -> Vec<f64> {
let p = self.onto_plane(p);
self.lines.iter().map(|l| l.distance(p)).collect()
}
/// The hole's centre at `distances` (one per line) from the lines, in the face's plane. With
/// one line, `near` moves square to it (it keeps its place along the edge); with two, the
/// centre is where both distances hold.
pub fn place(&self, near: Vec3, distances: &[f64]) -> Result<Vec3> {
if let Some((i, _)) = distances.iter().enumerate().find(|(_, d)| !(d.is_finite() && **d >= 0.0 && **d < 1e9)) {
return Err(DocError::Invalid(format!("reference distance {} must be a length of 0 or more", i + 1)));
}
let p = self.onto_plane(near);
match (self.lines.as_slice(), distances) {
([], []) => Ok(p),
([a], [d]) => Ok(p + a.toward * (d - a.distance(p))),
([a, b], [d1, d2]) => {
// p + r1 * a.toward + s * e2, with e2 square to a in the plane: a's distance is
// then d1, and s gives b's.
let (r1, r2) = (d1 - a.distance(p), d2 - b.distance(p));
let e2 = self.normal.cross(a.toward);
let across = b.toward.dot(e2);
if across.abs() < 1e-6 {
return Err(DocError::Invalid("the reference edges are parallel: pick edges that cross".into()));
}
Ok(p + a.toward * r1 + e2 * ((r2 - r1 * a.toward.dot(b.toward)) / across))
}
_ => Err(DocError::Invalid("a hole takes one distance for each reference edge".into())),
}
}
}
/// The reference frame of a hole placed at `at` (on the surface), drilled along `dir` (into the
/// material), from its reference edges: a point on each edge and, when it has one, the edge's
/// persistent name. A fresh pick (`exact`) must lie on its edge; a stored one is found by its
/// name, else the edge nearest its point. The face is the flat face under `at` that faces the
/// drill, else the one the edges border.
pub fn reference_frame(st: &ModelState, at: Vec3, dir: Vec3, edges: &[(Vec3, Option<&str>)], exact: bool) -> Result<ReferenceFrame> {
if edges.len() > MAX_HOLE_REFERENCES {
return Err(DocError::Invalid(format!("a hole takes at most {MAX_HOLE_REFERENCES} reference edges")));
}
let dir = dir.normalized().ok_or_else(|| DocError::Invalid("hole direction".into()))?;
if !at.is_finite() || edges.iter().any(|(p, _)| !p.is_finite()) {
return Err(DocError::Invalid("reference edges need finite points".into()));
}
let b = body_at(st, at).ok_or_else(|| DocError::Invalid("no body at the hole for its reference edges".into()))?;
let m = b.mesh();
let size = b.body.size().max(1e-9);
let mut found = Vec::with_capacity(edges.len());
for (k, (p, name)) in edges.iter().enumerate() {
found.push(find_edge(b, &m, k, *p, *name, exact)?);
}
let (face, origin, normal) = flat_face(b, &m, at, dir, &found).ok_or_else(|| {
DocError::Invalid("reference edges need the hole on a flat face: no flat face facing the drill at the hole or along its edges".into())
})?;
let mut lines = Vec::with_capacity(found.len());
for (k, (a, z, _)) in found.iter().enumerate() {
let flat = |q: Vec3| q - normal * (q - origin).dot(normal);
let (a, z) = (flat(*a), flat(*z));
let along = (z - a).normalized().ok_or_else(|| DocError::Invalid(format!("reference edge {} is square to the face", k + 1)))?;
let across = normal.cross(along).normalized().ok_or_else(|| DocError::Invalid(format!("reference edge {} is square to the face", k + 1)))?;
let mid = (a + z) * 0.5;
// The side the face is on next to the edge; an edge the face doesn't border (or borders
// on both sides) takes the side the hole is on.
let side = face_side(&m, face, mid, across, normal, size).unwrap_or_else(|| if (at - mid).dot(across) < 0.0 { -1.0 } else { 1.0 });
lines.push(ReferenceLine { point: mid, along, toward: across * side });
}
if let [a, b] = lines.as_slice()
&& a.along.cross(b.along).len() < 1e-6
{
return Err(DocError::Invalid("the reference edges are parallel: pick edges that cross".into()));
}
Ok(ReferenceFrame { body: b.name.clone(), face, origin, normal, lines, edges: found.iter().map(|(_, _, i)| *i).collect() })
}
/// Whether `p` lies on the flat face a reference frame was made for.
pub fn on_reference_face(st: &ModelState, frame: &ReferenceFrame, p: Vec3) -> bool {
let Some(b) = st.bodies.iter().find(|b| b.name == frame.body) else { return false };
let m = b.mesh();
let tol = (b.body.size() * 1e-4).max(1e-6);
m.triangles
.iter()
.zip(&m.tri_face)
.filter(|(_, f)| **f as usize == frame.face)
.any(|(t, _)| m.tri(t).is_some_and(|[a, bb, c]| crate::appearance::closest_on_triangle(p, a, bb, c).dist(p) <= tol))
}
/// The persistent names of the edges at `edges`, on the body the hole at `at` is drilled into
/// (empty where an edge has none).
pub fn reference_edge_names(st: &ModelState, at: Vec3, edges: &[Vec3]) -> Vec<String> {
match body_at(st, at) {
Some(b) => crate::naming::edge_names_at(b, edges),
None => Vec::new(),
}
}
/// The persistent names of a cylinder's reference edges (#6380), on the body it stands on at
/// `base` (its coordinates are numbers when it has reference edges).
pub fn cylinder_edge_names(st: &ModelState, base: &crate::PointExpr, references: &[crate::HoleReference]) -> Vec<String> {
let [x, y, z] = base.clone().map(|c| c.parse::<f64>().unwrap_or(0.0));
let edges: Vec<Vec3> = references.iter().map(|r| r.edge.0).collect();
reference_edge_names(st, Vec3::new(x, y, z), &edges)
}
/// The (non-mesh) body whose surface is nearest `p`.
fn body_at(st: &ModelState, p: Vec3) -> Option<&ModelBody> {
st.bodies
.iter()
.filter(|b| !b.body.is_mesh())
.filter_map(|b| crate::appearance::nearest_face(b, p).map(|(d, _)| (d, b)))
.min_by(|a, b| a.0.total_cmp(&b.0))
.map(|(_, b)| b)
}
/// How far `p` is from an edge's polyline.
fn to_polyline(p: Vec3, e: &[Vec3]) -> f64 {
e.windows(2).map(|w| p.dist_to_segment(w[0], w[1])).fold(f64::INFINITY, f64::min)
}
/// Reference edge `k` (its ends, and its index in the mesh), found by `name` (a name that finds
/// no edge fails, asking for the edge to be picked again), else by the edge nearest `p`: one
/// that runs through `p` for a fresh pick, within a quarter of the body for a stored one. It
/// must be straight.
fn find_edge(b: &ModelBody, m: &Mesh, k: usize, p: Vec3, name: Option<&str>, exact: bool) -> Result<(Vec3, Vec3, usize)> {
let size = b.body.size().max(1e-9);
let by_name = match name.filter(|n| !n.is_empty()) {
Some(n) => Some(crate::naming::locate_edge(b, n, p).map_err(|_| DocError::reselect(n))?.edge),
None => None,
};
let i = match by_name {
Some(i) => i,
None => {
let reach = if exact { (size * 1e-2).max(1e-3) } else { size * 0.25 };
m.edges
.iter()
.enumerate()
.map(|(i, e)| (to_polyline(p, e), i))
.filter(|(d, _)| d.is_finite())
.min_by(|a, b| a.0.total_cmp(&b.0))
.filter(|(d, _)| *d <= reach)
.map(|(_, i)| i)
.ok_or_else(|| {
DocError::Invalid(if exact {
format!("reference edge {}: no edge at [{}, {}, {}]", k + 1, p.x, p.y, p.z)
} else {
format!("reference edge {} no longer exists", k + 1)
})
})?
}
};
let e = m.edges.get(i).ok_or_else(|| DocError::Invalid(format!("reference edge {} no longer exists", k + 1)))?;
let (Some(a), Some(z)) = (e.first().copied(), e.last().copied()) else {
return Err(DocError::Invalid(format!("reference edge {} no longer exists", k + 1)));
};
let len = a.dist(z);
let straight = len > size * 1e-9 && e.iter().all(|q| q.dist_to_segment(a, z) <= 1e-5 * (1.0 + len));
if !straight {
return Err(DocError::Invalid(format!("reference edge {} is not straight: pick a straight edge", k + 1)));
}
Ok((a, z, i))
}
/// The flat face a referenced hole goes into (its index, a point on it and its outward normal):
/// the one under `at` when it faces the drill, else the one the edges border that faces it most.
fn flat_face(b: &ModelBody, m: &Mesh, at: Vec3, dir: Vec3, edges: &[(Vec3, Vec3, usize)]) -> Option<(usize, Vec3, Vec3)> {
let size = b.body.size().max(1e-9);
let plane = |f: usize| match crate::kernel::face_surface(&b.body, f) {
// Outward, so against the drill.
Some(crate::kernel::FaceSurface::Plane { normal, point }) => {
let normal: Vec3 = normal.into();
let n = if normal.dot(dir) > 0.0 { -normal } else { normal };
(n.dot(dir) < -1e-3).then_some((f, point, n))
}
_ => None,
};
if let Some((d, f)) = crate::appearance::nearest_face(b, at)
&& d <= (size * 1e-4).max(1e-6)
&& let Some(hit) = plane(f)
{
return Some(hit);
}
// The faces every edge borders.
let mut faces: Vec<usize> =
edges.first().and_then(|(_, _, i)| m.edge_faces.get(*i)).map(|fs| fs.iter().map(|f| *f as usize).collect()).unwrap_or_default();
for (_, _, i) in edges.iter().skip(1) {
let theirs = m.edge_faces.get(*i).map(Vec::as_slice).unwrap_or(&[]);
faces.retain(|f| theirs.iter().any(|g| *g as usize == *f));
}
faces.into_iter().filter_map(plane).min_by(|x, y| x.2.dot(dir).total_cmp(&y.2.dot(dir)))
}
/// Which side of an edge (through `mid`, square to it in the plane along `across`) face `face`
/// lies on: +1 or −1, or `None` when both sides or neither are that face.
fn face_side(m: &Mesh, face: usize, mid: Vec3, across: Vec3, normal: Vec3, size: f64) -> Option<f64> {
let step = (size * 1e-3).max(1e-6);
let lands = |s: f64| {
let from = mid + across * (s * step) + normal * step;
m.raycast(from, -normal).is_some_and(|(t, tri)| t <= 2.0 * step && m.tri_face.get(tri).is_some_and(|f| *f as usize == face))
};
match (lands(1.0), lands(-1.0)) {
(true, false) => Some(1.0),
(false, true) => Some(-1.0),
_ => None,
}
}