SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Boolean retries: a candidate whose edges run far outside the operands is discarded unmeshed (#3020) (#3185)
SS-ENac757960dcc2
diff --git a/crates/kernel/src/boolean_diagnostics.rs b/crates/kernel/src/boolean_diagnostics.rsindex dc3e0100e0..b160980fb6 100644--- a/crates/kernel/src/boolean_diagnostics.rs+++ b/crates/kernel/src/boolean_diagnostics.rs@@ -77,6 +77,11 @@ impl BooleanFallback {pub struct BooleanDiagnostics {pub events: Vec<BooleanFallback>,pub truncated: bool,+ /// Why candidates of the retries that led to the result were discarded before they were+ /// measured (#3020: a coarse candidate whose edges run far outside the operands, which+ /// meshing never finished). Left out of the report when there are none.+ #[serde(skip_serializing_if = "Vec::is_empty")]+ pub rejected: Vec<String>,}impl BooleanDiagnostics {@@ -88,6 +93,18 @@ impl BooleanDiagnostics {}}+ fn push_rejected(&mut self, reason: String) {+ // A candidate checked twice (picked, then taken) is noted once.+ if self.rejected.contains(&reason) {+ return;+ }+ if self.rejected.len() < MAX_EVENTS {+ self.rejected.push(reason);+ } else {+ self.truncated = true;+ }+ }+/// Why the result is not verified, when it ignores a place where the bodies seem to pass/// through each other ([`BooleanStrategy::UnverifiedShortcut`]).pub fn unverified(&self) -> Option<String> {@@ -163,10 +180,24 @@ pub(crate) fn record(event: BooleanFallback) {});}+/// Note a candidate discarded before it was measured, and why.+pub(crate) fn reject(reason: String) {+ REPORT.with(|cell| {+ if let Ok(mut report) = cell.try_borrow_mut()+ && let Some(report) = report.as_mut()+ {+ report.push_rejected(reason);+ }+ });+}+pub(crate) fn merge(report: BooleanDiagnostics) {for event in report.events {record(event);}+ for reason in report.rejected {+ reject(reason);+ }if report.truncated {REPORT.with(|cell| {if let Ok(mut report) = cell.try_borrow_mut()@@ -197,6 +228,26 @@ mod tests {assert!(capture_boolean_diagnostics(|| {}).1.events.is_empty());}+ /// Candidates discarded unmeasured (#3020) are reported with the attempt that led to the+ /// result, once each, and not at all when there are none.+ #[test]+ fn rejected_candidates_follow_the_accepted_attempt() {+ let (_, report) = capture_boolean_diagnostics(|| {+ let (_, discarded) = capture_boolean_diagnostics(|| reject("from a discarded attempt".into()));+ assert_eq!(discarded.rejected.len(), 1);+ let (_, accepted) = capture_boolean_diagnostics(|| {+ reject("runaway edge".into());+ reject("runaway edge".into());+ record(BooleanFallback::new(BooleanStrategy::ToolNudge));+ });+ merge(accepted);+ });+ assert_eq!(report.rejected, vec!["runaway edge".to_string()]);+ assert!(serde_json::to_string(&report).unwrap().contains("\"rejected\":[\"runaway edge\"]"));+ let plain = capture_boolean_diagnostics(|| record(BooleanFallback::new(BooleanStrategy::ToolNudge))).1;+ assert!(!serde_json::to_string(&plain).unwrap().contains("rejected"));+ }+/// Only retries whose result can differ from the exact one make a warning; the summary/// lists every retry.#[test]diff --git a/crates/kernel/src/candidate_reach.rs b/crates/kernel/src/candidate_reach.rsnew file mode 100644index 0000000000..75992c4ff2--- /dev/null+++ b/crates/kernel/src/candidate_reach.rs@@ -0,0 +1,127 @@+//! A boolean candidate whose edges run far outside its operands is discarded before it is+//! meshed (#3020).+//!+//! The retries of a boolean mesh every candidate to measure its volume. A candidate made at a+//! coarse tolerance can come out with an edge that leaves the body altogether: in the design of+//! #3020, a face of a revolved dovetail (a cone) got a trim loop several metres long on a part+//! 155 mm across, its points kilometres from the cone, and meshing that face never finished.+//! Its volume (±1e10 mm³) would have failed the check anyway; only measuring it hung.+//!+//! Every edge of a union, a cut or an intersection lies on the operands' faces, within the+//! boolean's tolerance (a small fraction of their size). So a candidate with a point of an edge+//! further outside the box the operands span than [`MARGIN`] of their size is not a result of+//! the operation, whatever its faces are, and it is discarded without meshing it. That needs no+//! search for the edge's points on its faces' surfaces, which is the very thing that runs away+//! on such a face.++use std::collections::HashSet;++use solidcraft_geom::{Aabb3, Mesh, Vec3};+use truck_modeling as mt;++use crate::body::{Body, from_p3};++#[cfg(test)]+#[path = "candidate_reach_tests.rs"]+mod tests;++/// Samples along each edge, ends included: a runaway edge leaves the body over a good part of+/// its length (the loop of #3020 was thousands of times the body's size).+const EDGE_SAMPLES: u32 = 16;++/// How far an edge of a candidate may run outside the box of the operands' meshes, as a fraction+/// of the operands' size: well above any boolean tolerance (2e-3 of the size at the coarsest) and+/// the temporary face shifts of the retries (1.4e-2 of it), well below the metres a runaway edge+/// spans.+pub(crate) const MARGIN: f64 = 0.05;++/// Where a candidate's edges may run when the operands could not be meshed: their edges only+/// bound them loosely (a sphere's seam spans half of it), so the box of those grows by their+/// whole size.+const MARGIN_UNMESHED: f64 = 1.0;++/// The box the operands of a boolean span, grown by the room a result's edges may take.+#[derive(Clone, Copy, Debug)]+pub(crate) struct Reach {+ bounds: Aabb3,+ margin: f64,+}++impl Reach {+ /// The reach of operands `a` and `b` of size `size`, from their meshes where both were made+ /// (`meshes`), else from their edges. `None` when neither gives a finite box.+ pub(crate) fn new(a: &Body, b: &Body, meshes: (Option<&Mesh>, Option<&Mesh>), size: f64) -> Option<Reach> {+ let mut bounds = Aabb3::EMPTY;+ let margin = match meshes {+ (Some(ma), Some(mb)) => {+ ma.positions.iter().chain(&mb.positions).for_each(|p| bounds.add(*p));+ MARGIN * size+ }+ _ => {+ for body in [a, b] {+ edge_points(body, |p| {+ bounds.add(p);+ true+ })?;+ }+ MARGIN_UNMESHED * size+ }+ };+ (!bounds.is_empty() && margin.is_finite() && margin > 0.0).then_some(Reach { bounds, margin })+ }++ /// Why `candidate` cannot be a result of a boolean of these operands: an edge of it runs+ /// further outside them than the margin, or has a point that is not finite. `None` when its+ /// edges stay within reach, and when they could not be sampled (it is then meshed and+ /// checked as before).+ pub(crate) fn runaway(&self, candidate: &Body) -> Option<String> {+ let (lo, hi) = (self.bounds.min, self.bounds.max);+ let mut worst = 0.0f64;+ let mut infinite = false;+ edge_points(candidate, |p| {+ if !p.is_finite() {+ infinite = true;+ return false;+ }+ let outside = Vec3::new(excess(p.x, lo.x, hi.x), excess(p.y, lo.y, hi.y), excess(p.z, lo.z, hi.z)).len();+ worst = worst.max(outside);+ true+ })?;+ if infinite {+ Some("a result whose edge has points that are not finite".into())+ } else if worst > self.margin {+ Some(format!("a result whose edge runs {worst:.4e} mm outside the operands (more than {:.4e} mm), not meshed to measure it", self.margin))+ } else {+ None+ }+ }+}++/// How far `x` lies outside `[lo, hi]`.+fn excess(x: f64, lo: f64, hi: f64) -> f64 {+ (lo - x).max(x - hi).max(0.0)+}++/// Visits [`EDGE_SAMPLES`] points along each edge of `body` (once per edge) until `visit` says+/// stop. `None` when the curves could not be evaluated.+fn edge_points(body: &Body, mut visit: impl FnMut(Vec3) -> bool) -> Option<()> {+ crate::guard("candidate edges", || {+ use mt::{BoundedCurve, ParametricCurve};+ let mut seen = HashSet::new();+ for edge in body.solid.edge_iter() {+ if !seen.insert(edge.id()) {+ continue;+ }+ let curve = edge.curve();+ let (t0, t1) = curve.range_tuple();+ for i in 0..=EDGE_SAMPLES {+ let t = t0 + (t1 - t0) * f64::from(i) / f64::from(EDGE_SAMPLES);+ if !visit(from_p3(curve.subs(t))) {+ return Ok(());+ }+ }+ }+ Ok(())+ })+ .ok()+}diff --git a/crates/kernel/src/candidate_reach_tests.rs b/crates/kernel/src/candidate_reach_tests.rsnew file mode 100644index 0000000000..e237b6b6de--- /dev/null+++ b/crates/kernel/src/candidate_reach_tests.rs@@ -0,0 +1,106 @@+//! A boolean candidate with a trim loop that runs off its surface is discarded fast (#3020).+//!+//! In the design of #3020 a coarse candidate of a nudged union came out with a face on a cone+//! (a revolved line: its profile parameter bounded to [0, 1], its angle periodic) whose trim+//! loop left the cone and ran thousands of profile lengths along its continuation, kilometres+//! from the part. Meshing that face to measure the candidate never finished. Here such a face+//! is made on purpose: the check finds its edge outside the operands without meshing it.++use std::time::{Duration, Instant};++use solidcraft_geom::Vec3;+use truck_modeling::{self as mt, ParametricSurface, builder};++use super::{MARGIN, Reach};+use crate::body::Body;++/// The cone of the report: a profile line 2 mm out and 4 mm up from radius 20 mm (its length,+/// √20 mm, is the |∂S/∂u| measured on the runaway face), turned about Z.+fn cone() -> mt::Surface {+ let profile = mt::Curve::Line(mt::Line(mt::Point3::new(20.0, 0.0, 0.0), mt::Point3::new(22.0, 0.0, 4.0)));+ mt::Surface::RevolutedCurve(mt::Processor::new(mt::RevolutedCurve::by_revolution(profile, mt::Point3::new(0.0, 0.0, 0.0), mt::Vector3::unit_z())))+}++/// A solid of one face of `surface` bounded by straight edges through `corners`, given in the+/// surface's parameters and moved `off` mm off it along its normal.+fn face_body(surface: &mt::Surface, corners: &[(f64, f64, f64)]) -> Body {+ use mt::ParametricSurface3D;+ let vertices: Vec<mt::Vertex> = corners.iter().map(|&(u, v, off)| builder::vertex(surface.subs(u, v) + surface.normal(u, v) * off)).collect();+ let edges: Vec<mt::Edge> = (0..vertices.len()).map(|i| builder::line(&vertices[i], &vertices[(i + 1) % vertices.len()])).collect();+ let face = mt::Face::new(vec![edges.into_iter().collect()], surface.clone());+ let solid = mt::Solid::new_unchecked(vec![vec![face].into()]);+ Body::new(solid).unwrap()+}++/// The operands: a plate and the cone's own patch, which spans u in [0, 1] (radius 20-22 mm,+/// 4 mm high) over a quarter turn.+fn operands() -> (Body, Body) {+ let plate = crate::box_solid(Vec3::new(-30.0, -30.0, -6.0), Vec3::new(30.0, 30.0, 0.0)).unwrap();+ let patch = face_body(&cone(), &[(0.0, 0.0, 0.0), (1.0, 0.0, 0.0), (1.0, 1.5, 0.0), (0.0, 1.5, 0.0)]);+ (plate, patch)+}++fn reach(a: &Body, b: &Body) -> Reach {+ let size = a.size().max(b.size());+ let meshes = (a.tessellate_with(size * 5e-4, true).unwrap(), b.tessellate_with(size * 5e-4, true).unwrap());+ Reach::new(a, b, (Some(&meshes.0), Some(&meshes.1)), size).unwrap()+}++/// The runaway face: on the cone, its loop leaves the patch at u = 0 and follows the cone's+/// continuation out to u = -2450 (as the logged loop did, -2452 … 1349), 1.5 mm off it, and+/// back.+fn runaway() -> Body {+ face_body(&cone(), &[(1.0, 0.2, 0.0), (1.0, 1.3, 0.0), (0.0, 1.3, 0.0), (-2450.0, 0.9, 1.5), (-2450.0, 0.6, 1.5), (0.0, 0.2, 0.0)])+}++#[test]+fn a_candidate_with_a_trim_loop_off_its_surface_is_rejected_fast() {+ let (a, b) = operands();+ let reach = reach(&a, &b);+ let candidate = runaway();+ let start = Instant::now();+ let reason = reach.runaway(&candidate);+ let took = start.elapsed();+ let reason = reason.expect("an edge kilometres outside the operands");+ assert!(reason.contains("outside the operands"), "{reason}");+ assert!(took < Duration::from_secs(1), "{took:?}");+}++#[test]+fn sound_candidates_stay_within_reach() {+ let (a, b) = operands();+ let reach = reach(&a, &b);+ // The operands themselves, and a union of the plate with a cylinder standing on it.+ assert_eq!(reach.runaway(&a), None);+ assert_eq!(reach.runaway(&b), None);+ let post = crate::cylinder(Vec3::new(0.0, 0.0, -1.0), Vec3::Z, 5.0, 20.0).unwrap();+ let reach = self::reach(&a, &post);+ let union = crate::boolean(&a, &post, crate::BoolOp::Union).unwrap().unwrap();+ assert_eq!(reach.runaway(&union), None);+}++#[test]+fn an_edge_just_past_the_margin_is_out_of_reach() {+ let (a, b) = operands();+ let size = a.size().max(b.size());+ let reach = reach(&a, &b);+ // A box reaching past the plate's side by twice the margin, and one within it.+ let top = Vec3::new(30.0, 30.0, 0.0);+ let past = crate::box_solid(Vec3::new(0.0, 0.0, -6.0), top + Vec3::X * (2.0 * MARGIN * size)).unwrap();+ let within = crate::box_solid(Vec3::new(0.0, 0.0, -6.0), top + Vec3::X * (0.5 * MARGIN * size)).unwrap();+ assert!(reach.runaway(&past).is_some());+ assert_eq!(reach.runaway(&within), None);+}++/// The bound on a loop's span is in lengths of a bounded parameter's range: a plane's unit box+/// is only a chart, so a plate thousands of millimetres across (its loops thousands of units+/// wide) still meshes, as does a long cylinder.+#[test]+fn large_faces_still_mesh() {+ let plate = crate::box_solid(Vec3::new(-2500.0, -2500.0, 0.0), Vec3::new(2500.0, 2500.0, 3.0)).unwrap();+ let rod = crate::cylinder(Vec3::ZERO, Vec3::Z, 0.5, 3000.0).unwrap();+ for body in [plate, rod] {+ assert!(!body.tessellate_with(0.05, true).unwrap().triangles.is_empty());+ assert_eq!(body.unmeshed_faces(), 0);+ }+}diff --git a/crates/kernel/src/lib.rs b/crates/kernel/src/lib.rsindex 6f852793df..b688104771 100644--- a/crates/kernel/src/lib.rs+++ b/crates/kernel/src/lib.rs@@ -28,6 +28,7 @@ mod boundary;mod boundary_network;mod bridge;mod build;+mod candidate_reach;#[cfg(test)]mod chamfer_sides_curved_tests;mod clearance;diff --git a/crates/kernel/src/ops.rs b/crates/kernel/src/ops.rsindex 9309b6336f..3339aa851c 100644--- a/crates/kernel/src/ops.rs+++ b/crates/kernel/src/ops.rs@@ -7,7 +7,7 @@ use truck_modeling as mt;use std::collections::HashMap;use crate::body::{Body, Solid, from_p3};-use crate::boolean_diagnostics::{BooleanFallback, BooleanStrategy, capture_boolean_diagnostics, merge, record};+use crate::boolean_diagnostics::{BooleanFallback, BooleanStrategy, capture_boolean_diagnostics, merge, record, reject};use crate::boolean_record::{self as recorded, Traced};use crate::{KernelError, Result, guard, record};@@ -1289,6 +1289,9 @@ where_ => (volume(a), volume(b)),};let slack = 2e-3 * (va + vb) + 1e-9;+ // Where a result's edges can run: a candidate with an edge far outside the operands is+ // discarded before it is meshed (#3020), as meshing such a face may never finish.+ let reach = crate::candidate_reach::Reach::new(a, b, (meshes.0.as_ref(), meshes.1.as_ref()), size);// Volume bounds, then membership against the operands (catches misclassified pieces), on// one mesh of the result. Returns (plausible, volume).// Shells that touch were never fused: coincident back-to-back faces leave the intersection@@ -1306,6 +1309,10 @@ where&& crate::coplanar::faces_touch(a, b)};let check = |r: &Body| -> (bool, f64) {+ if let Some(reason) = reach.as_ref().and_then(|reach| reach.runaway(r)) {+ reject(reason);+ return (false, f64::NAN);+ }let Ok(mr) = r.tessellate_with(tol_m, true) else { return (false, f64::NAN) };let v = mr.measure().volume;let bounds = plausible(v, op, va, vb, slack);diff --git a/docs/robustness.md b/docs/robustness.mdindex 168601ceaa..ebb88d8882 100644--- a/docs/robustness.md+++ b/docs/robustness.md@@ -99,6 +99,11 @@ tolerances and leaves the exact result, so it is recorded but not warned about.`timeline.inspect` and `doc.inspect` expose every retry in the feature's`boolean_diagnostics`, including the strategy and the applied translation,rotation, face offset and tessellation tolerance in millimetres/radians.+Candidates those retries discarded before measuring them are listed in its+`rejected`, with the reason: a candidate with an edge further outside the+operands than 5% of their size cannot be their union, cut or intersection,+and meshing one (a trim loop running metres along a cone's continuation)+could take minutes or never finish (#3020).A common shift of both operands is reversed on the result. Coincident-faceseparation and bore offsets describe temporary working geometry; they are not