SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Class-A surfacing 2/3: surface match, boundary patch and CV fairing (#1487)
midasdf07da7f8065cd
diff --git a/ATTRIBUTION.md b/ATTRIBUTION.mdindex b5b8c4d2dd..97dca7e5d1 100644--- a/ATTRIBUTION.md+++ b/ATTRIBUTION.md@@ -36,6 +36,7 @@ Editable drawing code, native projects and shipped exports are collected under `| assets/archive/icons/macos-v1/exports/icon.iconset/[email protected] | SolidCraft contributors | native sips export from assets/archive/icons/macos-v1/exports/icon.png | MIT OR Apache-2.0 || assets/archive/icons/macos-v1/exports/icon.iconset/icon_512x512.png | SolidCraft contributors | native sips export from assets/archive/icons/macos-v1/exports/icon.png | MIT OR Apache-2.0 || assets/archive/icons/macos-v1/exports/icon.iconset/[email protected] | SolidCraft contributors | native sips export from assets/archive/icons/macos-v1/exports/icon.png | MIT OR Apache-2.0 |+| docs/screenshots/class-a-boundary.png | SolidCraft contributors | screenshot of SolidCraft itself: a patch through two sketch lines built by `surface.boundary` with `crown: 0.4` (`solidcraft-cli snapshot`) | MIT OR Apache-2.0 || docs/screenshots/sample-plate.png | SolidCraft contributors | screenshot of SolidCraft itself (`solidcraft --sample`) | MIT OR Apache-2.0 || docs/screenshots/demo-0.8.gif | SolidCraft contributors | original screen recording of the actual SolidCraft 0.8 English desktop UI modelling an original Raspberry Pi 4 case (no logos or branding; the engraved text is set in the system's DejaVu Sans Bold), generated with examples/demo/record_ui.sh and its original animated pointer overlay (9× playback) | MIT OR Apache-2.0 || docs/screenshots/demo-0.8.mp4 | SolidCraft contributors | original screen recording of the actual SolidCraft 0.8 English desktop UI modelling an original Raspberry Pi 4 case (no logos or branding; the engraved text is set in the system's DejaVu Sans Bold), generated with examples/demo/record_ui.sh and its original animated pointer overlay (9× playback) | MIT OR Apache-2.0 |diff --git a/assets/locales/de.json b/assets/locales/de.jsonindex 69381095e1..c74bd78cf7 100644--- a/assets/locales/de.json+++ b/assets/locales/de.json@@ -366,8 +366,10 @@"cmd.surface_blend": "Verbindungsfläche","cmd.surface_boundary": "Begrenzungsfläche","cmd.surface_extrude": "Flächen-Extrusion",+ "cmd.surface_fair": "Flächenbegradigung","cmd.surface_fillet": "Flächenverrundung","cmd.surface_loft": "Flächen-Loft",+ "cmd.surface_match": "Flächenanpassung","cmd.surface_offset": "Offsetfläche","cmd.surface_patch": "Patch","cmd.surface_reverse_normal": "Normale umkehren",diff --git a/assets/locales/en.json b/assets/locales/en.jsonindex 5767b5ddd6..ffbe52a36c 100644--- a/assets/locales/en.json+++ b/assets/locales/en.json@@ -568,8 +568,10 @@"cmd.surface_blend": "Blend Surface","cmd.surface_boundary": "Boundary Surface","cmd.surface_extrude": "Surface Extrude",+ "cmd.surface_fair": "Fair Surface","cmd.surface_fillet": "Surface Fillet","cmd.surface_loft": "Surface Loft",+ "cmd.surface_match": "Match Surface","cmd.surface_offset": "Offset Surface","cmd.surface_patch": "Patch","cmd.surface_reverse_normal": "Reverse Normal",diff --git a/assets/locales/ja.json b/assets/locales/ja.jsonindex 350dccc75c..4bb4502fe9 100644--- a/assets/locales/ja.json+++ b/assets/locales/ja.json@@ -568,8 +568,10 @@"cmd.surface_blend": "ブレンドサーフェス","cmd.surface_boundary": "境界サーフェス","cmd.surface_extrude": "サーフェス押し出し",+ "cmd.surface_fair": "サーフェスフェアリング","cmd.surface_fillet": "サーフェスフィレット","cmd.surface_loft": "サーフェスロフト",+ "cmd.surface_match": "サーフェス一致","cmd.surface_offset": "オフセットサーフェス","cmd.surface_patch": "パッチ","cmd.surface_reverse_normal": "法線を反転",diff --git a/assets/locales/ko.json b/assets/locales/ko.jsonindex 09c175fbd0..a274a35821 100644--- a/assets/locales/ko.json+++ b/assets/locales/ko.json@@ -366,8 +366,10 @@"cmd.surface_blend": "블렌드 서피스","cmd.surface_boundary": "바운더리 서피스","cmd.surface_extrude": "서피스 돌출",+ "cmd.surface_fair": "서피스 페어링","cmd.surface_fillet": "서피스 필렛","cmd.surface_loft": "서피스 로프트",+ "cmd.surface_match": "서피스 일치","cmd.surface_offset": "오프셋 서피스","cmd.surface_patch": "패치","cmd.surface_reverse_normal": "법선 반전",diff --git a/assets/locales/zh.json b/assets/locales/zh.jsonindex 264d61d721..b310f839a4 100644--- a/assets/locales/zh.json+++ b/assets/locales/zh.json@@ -568,8 +568,10 @@"cmd.surface_blend": "混合曲面","cmd.surface_boundary": "边界曲面","cmd.surface_extrude": "曲面拉伸",+ "cmd.surface_fair": "曲面光顺","cmd.surface_fillet": "曲面圆角","cmd.surface_loft": "曲面放样",+ "cmd.surface_match": "曲面匹配","cmd.surface_offset": "偏移曲面","cmd.surface_patch": "补面","cmd.surface_reverse_normal": "反转法向",diff --git a/crates/doc/src/document.rs b/crates/doc/src/document.rsindex 37062da195..21e4125c63 100644--- a/crates/doc/src/document.rs+++ b/crates/doc/src/document.rs@@ -1384,6 +1384,59 @@ pub enum FeatureKind {#[serde(default, skip_serializing_if = "std::ops::Not::not")]stitch: bool,},+ /// One surface patch through a network of two to four boundary curves of a sketch+ /// (`surface.boundary`, issue #763): the patch runs through the curves in loop order and leaves+ /// each boundary at its own `order` — a sketch curve's boundary is a plane, so G1 and up hold+ /// exactly — with `crown` shaping the middle without touching a boundary.+ SurfaceBoundary {+ sketch: SketchId,+ /// The curves in loop order: each one ends where the next begins, and the last where the+ /// first does.+ curves: Vec<String>,+ /// How much of the surface across each boundary the patch repeats, one per curve (none: a+ /// tangent plane, `g1`, on every side).+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ orders: Vec<Continuity>,+ /// How full the middle is: 0 the plain construction, up to 3 fuller, down to -0.9 flatter.+ #[serde(default)]+ crown: f64,+ /// The stations every boundary carries.+ #[serde(default = "boundary_samples")]+ samples: usize,+ },+ /// One face of a surface body rebuilt against another body (`surface.match`): the rebuilt+ /// boundary nearest the chain of `edges` on `target` takes that chain's place and repeats the+ /// target's own shape along the seam up to `order`, while the boundary opposite it, and the+ /// body's name, stay where they were. `faces` picks the face to rebuild (its first, when none).+ SurfaceMatch {+ body: BodyName,+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ faces: Vec<FacePick>,+ target: BodyName,+ edges: Vec<Position>,+ #[serde(default = "match_order")]+ order: Continuity,+ },+ /// The B-spline faces at `faces` of `body` faired (`surface.fair`): each face's interior+ /// control vertices move to flatten the thin-plate (curvature-variation) energy of the face,+ /// `strength` of the full least-squares step at a time, for at most `iterations` steps.+ /// `keep_edges` holds the row of control points next to each edge as well as the boundary row+ /// itself, so the face keeps meeting its neighbours in position and in tangent. `tolerance`+ /// is the farthest a control point may move, so the faired face stays within it of the one the+ /// design asked for; an empty `faces` fairs every face of the body.+ SurfaceFair {+ body: BodyName,+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ faces: Vec<FacePick>,+ #[serde(default = "fair_strength")]+ strength: f64,+ #[serde(default = "fair_iterations")]+ iterations: u32,+ #[serde(default = "fair_keep_edges")]+ keep_edges: bool,+ #[walk(length = "Tolerance")]+ tolerance: Expr,+ },/// A surface body trimmed by a plane, or by a face of a body (`tool`), keeping the side of/// `keep`.SurfaceTrim {@@ -1600,10 +1653,33 @@ fn is_g0(g: &Continuity) -> bool {}/// The continuity a blend repeats by default: the tangent plane on both sides.+/// The stations a boundary patch carries by default.+fn boundary_samples() -> usize {+ 25+}+fn blend_orders() -> [Continuity; 2] {[Continuity::G1, Continuity::G1]}+/// The continuity a match holds by default: position, tangent plane and curvature.+fn match_order() -> Continuity {+ Continuity::G2+}++/// A fairing's defaults for a design that leaves them out: the whole least-squares step at a+/// time, and the boundary held (the row next to each edge too, so the face still meets its+/// neighbours in tangent).+fn fair_strength() -> f64 {+ 1.0+}+fn fair_iterations() -> u32 {+ 1+}+fn fair_keep_edges() -> bool {+ true+}+/// Triangles of one imported mesh body (millimetres).#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]pub struct MeshData {@@ -1896,6 +1972,9 @@ impl FeatureKind {FeatureKind::SurfaceSweep { .. } => "SurfaceSweepFeature",FeatureKind::SurfaceLoft { .. } => "SurfaceLoftFeature",FeatureKind::SurfaceBlend { .. } => "BlendFeature",+ FeatureKind::SurfaceBoundary { .. } => "BoundaryFeature",+ FeatureKind::SurfaceMatch { .. } => "MatchFeature",+ FeatureKind::SurfaceFair { .. } => "FairFeature",FeatureKind::Stitch { .. } => "StitchFeature",FeatureKind::Thicken { .. } => "ThickenFeature",FeatureKind::SurfaceTrim { .. } => "TrimFeature",@@ -1973,6 +2052,9 @@ impl FeatureKind {FeatureKind::SurfaceSweep { .. } => "SurfaceSweep",FeatureKind::SurfaceLoft { .. } => "SurfaceLoft",FeatureKind::SurfaceBlend { .. } => "Blend",+ FeatureKind::SurfaceBoundary { .. } => "Boundary",+ FeatureKind::SurfaceMatch { .. } => "Match",+ FeatureKind::SurfaceFair { .. } => "Fair",FeatureKind::Stitch { .. } => "Stitch",FeatureKind::Thicken { .. } => "Thicken",FeatureKind::SurfaceTrim { .. } => "Trim",diff --git a/crates/doc/src/eval.rs b/crates/doc/src/eval.rsindex d2b523196d..12003ecdb7 100644--- a/crates/doc/src/eval.rs+++ b/crates/doc/src/eval.rs@@ -4133,6 +4133,9 @@ fn eval_feature(doc: &Document, vals: &BTreeMap<String, Value>, f: &Feature, st:| FeatureKind::SurfaceSweep { .. }| FeatureKind::SurfaceLoft { .. }| FeatureKind::SurfaceBlend { .. }+ | FeatureKind::SurfaceBoundary { .. }+ | FeatureKind::SurfaceMatch { .. }+ | FeatureKind::SurfaceFair { .. }| FeatureKind::SurfaceOffset { .. }| FeatureKind::SurfaceRuled { .. }| FeatureKind::SurfaceUntrim { .. } => surface::eval(doc, vals, f, st, warning),diff --git a/crates/doc/src/eval_surface.rs b/crates/doc/src/eval_surface.rsindex 19a1d35f12..d6c8a5737f 100644--- a/crates/doc/src/eval_surface.rs+++ b/crates/doc/src/eval_surface.rs@@ -145,6 +145,78 @@ pub(super) fn eval(doc: &Document, vals: &BTreeMap<String, Value>, f: &Feature,st.bodies.push(ModelBody::new(name, made, f.id));Ok(())}+ FeatureKind::SurfaceBoundary { sketch, curves, orders, crown, samples } => {+ let ss = sketch_in_feature_frame(+ doc,+ st.sketch(sketch.0).ok_or_else(|| DocError::Unknown(format!("sketch {sketch} (it must come earlier in the timeline)")))?,+ f.component,+ )?;+ let boundaries = boundary_frames(&ss, curves, orders, *samples)?;+ let body = kernel::boundary_patch(&boundaries, *crown, *samples)?;+ let name = new_name(st, f, 0);+ st.bodies.push(ModelBody::new(name, body, f.id));+ Ok(())+ }+ FeatureKind::SurfaceMatch { body, faces, target, edges, order } => {+ let i = st.bodies.iter().position(|b| &b.name == body).ok_or_else(|| DocError::Unknown(format!("body `{body}`")))?;+ let Some(mb) = st.bodies.get(i).cloned() else { return Err(DocError::Invalid("body".into())) };+ let tb = st.body(target).ok_or_else(|| DocError::Unknown(format!("body `{target}`")))?.body.clone();+ if edges.is_empty() {+ return Err(DocError::Invalid("a match needs a chain of the target's edges".into()));+ }+ // Picked by a point on the face; without picks, the body's first face.+ let picked: Vec<solidcraft_geom::Vec3> = if faces.is_empty() {+ let faces = mb.body.faces(mb.body.size() * 1e-2)?;+ vec![faces.first().ok_or_else(|| DocError::Invalid(format!("`{body}` has no face to match")))?.centroid]+ } else {+ crate::plain(faces)+ };+ let made = kernel::match_surface(&mb.body, &picked, &tb, &crate::plain(edges), *order)?;+ // A match rebuilds the face in place: the body keeps its name, and whatever meets it+ // downstream still finds it.+ if let Some(slot) = st.bodies.get_mut(i) {+ *slot = ModelBody::new(mb.name, made, mb.feature);+ }+ Ok(())+ }+ FeatureKind::SurfaceFair { body, faces, strength, iterations, keep_edges, tolerance } => {+ let tol = val(vals, tolerance, Kind::Length)?;+ let opts = kernel::FairOptions::new(*strength, *iterations as usize, *keep_edges, tol)?;+ let i = st.bodies.iter().position(|b| &b.name == body).ok_or_else(|| DocError::Unknown(format!("body `{body}`")))?;+ let Some(mb) = st.bodies.get(i).cloned() else { return Err(DocError::Invalid("body".into())) };+ // Picked by a point on the face; without picks, every face of the body.+ let mut picked: Vec<usize> = Vec::new();+ if faces.is_empty() {+ picked.extend(0..mb.body.face_count());+ } else {+ for p in faces {+ let fi =+ crate::appearance::face_index_at(&mb, p.0).ok_or_else(|| DocError::Invalid(format!("Fair: no face of {body} at {p:?}")))?;+ if !picked.contains(&fi) {+ picked.push(fi);+ }+ }+ }+ if picked.is_empty() {+ return Err(DocError::Invalid("the body has no faces to fair".into()));+ }+ // The face keeps every edge it had: only the surface between them is faired. The+ // energy before and after goes into the feature's warning, so the reply can say how+ // much the face moved.+ let (faired, report) = kernel::fair_faces(&mb.body, &picked, &opts)?;+ *warning = Some(format!(+ "faired {} face(s): energy {:.6} → {:.6} in {} step(s), control points moved up to {:.4} mm",+ picked.len(),+ report.energy_before,+ report.energy_after,+ report.steps,+ report.movement+ ));+ if let Some(slot) = st.bodies.get_mut(i) {+ *slot = ModelBody::new(mb.name, faired, mb.feature);+ }+ Ok(())+ }FeatureKind::SurfaceExtrude { sketch, profiles, curves, extent } => {let ss = sketch_in_feature_frame(doc,@@ -349,6 +421,70 @@ fn push_sheet(st: &mut ModelState, f: &Feature, traced: crate::lineage::Traced)st.bodies.push(ModelBody::traced_new(name, traced, f.id));}+/// The boundaries `surface.boundary` builds its patch from: each picked curve's own stations in+/// the sketch's frame, every one of them leaving the boundary square into the loop — the direction+/// from the curve towards the middle of the loop, taken across its tangent — over the plane the+/// curve lies in (so a chain of planar curves makes a flat patch, and a network that is not+/// coplanar is followed as the plane through the curve's own tangent). `orders` sets how much of+/// that plane each side repeats.+fn boundary_frames(+ ss: &SolvedSketch,+ curves: &[String],+ orders: &[solidcraft_kernel::Continuity],+ samples: usize,+) -> Result<Vec<solidcraft_kernel::Boundary>> {+ use solidcraft_kernel::{Boundary, Frame};+ // The stations along each curve, evenly in its own arclength, so every side carries the same+ // number of frames and the patch's net is square.+ let mut sides: Vec<Vec<solidcraft_geom::Vec3>> = Vec::with_capacity(curves.len());+ for id in curves {+ let ci = ss.sketch.curve_index(id).ok_or_else(|| DocError::Unknown(format!("sketch curve `{id}`")))?;+ let pieces = ss.sketch.exact_pieces(ci);+ if pieces.is_empty() {+ return Err(DocError::Invalid(format!("curve `{id}` has no exact geometry to build on")));+ }+ let lengths: Vec<f64> = pieces.iter().map(Seg2::length).collect();+ let total: f64 = lengths.iter().sum();+ if !total.is_finite() || total <= 1e-9 {+ return Err(DocError::Invalid(format!("curve `{id}` has no length")));+ }+ let mut pts = Vec::with_capacity(samples);+ let (mut used, mut at) = (0.0, 0usize);+ for k in 0..samples {+ let want = total * k as f64 / (samples.saturating_sub(1)).max(1) as f64;+ while at + 1 < pieces.len() && used + lengths[at] < want {+ used += lengths[at];+ at += 1;+ }+ let (Some(piece), Some(len)) = (pieces.get(at), lengths.get(at)) else { return Err(DocError::Invalid("boundary piece".into())) };+ let t = ((want - used) / len.max(1e-12)).clamp(0.0, 1.0);+ pts.push(ss.plane.to_world(piece.point_at(t)));+ }+ sides.push(pts);+ }+ // The middle of the loop, so every side leaves towards the inside of the patch.+ let count = sides.iter().map(Vec::len).sum::<usize>().max(1) as f64;+ let centre = sides.iter().flatten().fold(solidcraft_geom::Vec3::ZERO, |a, p| a + *p) * (1.0 / count);+ let mut out = Vec::with_capacity(sides.len());+ for (side, pts) in sides.iter().enumerate() {+ let mut frames = Vec::with_capacity(pts.len());+ for (i, p) in pts.iter().enumerate() {+ // The tangent from the stations on either side, one-sided at the ends (where the side+ // only has one neighbour).+ let before = if i == 0 { *p } else { pts[i - 1] };+ let after = if i + 1 == pts.len() { *p } else { pts[i + 1] };+ let tangent = (after - before).normalized().ok_or_else(|| DocError::Invalid("a boundary curve has a stationary station".into()))?;+ let across = centre - *p;+ let leave = (across - tangent * across.dot(tangent))+ .normalized()+ .ok_or_else(|| DocError::Invalid("a boundary runs through the middle of the loop: no patch can leave it".into()))?;+ frames.push(Frame { p: *p, leave, bend: Vec3::ZERO, bend_change: Vec3::ZERO });+ }+ out.push(Boundary { frames, order: orders.get(side).copied().unwrap_or(solidcraft_kernel::Continuity::G1) });+ }+ Ok(out)+}+/// What a surface builder sweeps: the boundary loops of the picked profiles, then the picked/// curves chained end to end.fn sheet_chains(ss: &SolvedSketch, profiles: Option<&ProfileSel>, curves: &[String]) -> Result<Vec<Vec<Seg2>>> {diff --git a/crates/doc/src/feature_walk_tests/fixtures.rs b/crates/doc/src/feature_walk_tests/fixtures.rsindex 6a23ee71c3..2364cf6c6a 100644--- a/crates/doc/src/feature_walk_tests/fixtures.rs+++ b/crates/doc/src/feature_walk_tests/fixtures.rs@@ -161,6 +161,11 @@ pub(super) fn fixtures() -> Vec<(&'static str, Value)> {("surface_loft", json!({"type": "surface_loft", "sections": []})),("surface_blend", json!({"type": "surface_blend", "from": {"body": "B", "edges": [o]}, "to": {"body": "C", "edges": [o]}, "align": [o, o]})),("surface_offset", json!({"type": "surface_offset", "faces": [o], "distance": "soff.distance", "tolerance": "soff.tolerance"})),+ // The Class-A surface family (surface.blend/boundary/match/fair).+ ("surface_blend", json!({"type": "surface_blend", "from": {"body": "B", "edges": [o]}, "to": {"body": "C", "edges": [o]}, "align": [o, o]})),+ ("surface_boundary", json!({"type": "surface_boundary", "sketch": 1, "curves": ["l1", "l2"]})),+ ("surface_match", json!({"type": "surface_match", "body": "B", "faces": [o], "target": "C", "edges": [o]})),+ ("surface_fair", json!({"type": "surface_fair", "body": "B", "faces": [o], "tolerance": "sfair.tolerance"})),("unstitch", json!({"type": "unstitch", "body": "B"})),("reverse_normal", json!({"type": "reverse_normal", "body": "B"})),("surface_untrim", json!({"type": "surface_untrim", "face": {"body": "B", "point": o}, "holes": [o], "outer": true})),diff --git a/crates/doc/src/feature_walk_tests/golden_exprs.txt b/crates/doc/src/feature_walk_tests/golden_exprs.txtindex 7a060857ac..5a8877777d 100644--- a/crates/doc/src/feature_walk_tests/golden_exprs.txt+++ b/crates/doc/src/feature_walk_tests/golden_exprs.txt@@ -340,6 +340,13 @@ surface_offsetDistance = soff.distance (Length)Tolerance = soff.tolerance (Length)expressions: soff.distance, soff.tolerance+surface_blend+surface_boundary+surface_match+surface_fair+ inputs:+ Tolerance = sfair.tolerance (Length)+ expressions: sfair.toleranceunstitchreverse_normalsurface_untrimdiff --git a/crates/doc/src/feature_walk_tests/golden_geometry.txt b/crates/doc/src/feature_walk_tests/golden_geometry.txtindex 32f8592e4b..767444fa76 100644--- a/crates/doc/src/feature_walk_tests/golden_geometry.txt+++ b/crates/doc/src/feature_walk_tests/golden_geometry.txt@@ -154,6 +154,15 @@ surface_blendsurface_offsetmoves: faces[0][0], faces[0][1], faces[0][2]face points: [0, 0, 0]+surface_blend+ moves: align[0][0], align[0][1], align[0][2], align[1][0], align[1][1], align[1][2], from.edges[0][0], from.edges[0][1], from.edges[0][2], to.edges[0][0], to.edges[0][1], to.edges[0][2]+surface_boundary+surface_match+ moves: edges[0][0], edges[0][1], edges[0][2], faces[0][0], faces[0][1], faces[0][2]+ face points: [0, 0, 0]+surface_fair+ moves: faces[0][0], faces[0][1], faces[0][2]+ face points: [0, 0, 0]unstitchmoves: faces[0][0], faces[0][1], faces[0][2]reverse_normaldiff --git a/crates/doc/src/feature_walk_tests/golden_refs.txt b/crates/doc/src/feature_walk_tests/golden_refs.txtindex 9c56ab0b1d..0b621c6a02 100644--- a/crates/doc/src/feature_walk_tests/golden_refs.txt+++ b/crates/doc/src/feature_walk_tests/golden_refs.txt@@ -177,6 +177,15 @@ surface_blendremap_bodies: from.bodysurface_offsetremap_bodies: body+surface_blend+ remap_bodies: from.body+surface_boundary+ sketches: [1]+ remap_refs: sketch+surface_match+ remap_bodies: body+surface_fair+ remap_bodies: bodyunstitchremap_bodies: bodyreverse_normaldiff --git a/crates/doc/src/format/pending/class-a-surfaces.rs b/crates/doc/src/format/pending/class-a-surfaces.rsnew file mode 100644index 0000000000..ee4e58597a--- /dev/null+++ b/crates/doc/src/format/pending/class-a-surfaces.rs@@ -0,0 +1,5 @@+//! The Class-A surface pass adds `SurfaceBoundary` (Boundary Surface: `sketch`, `curves`,+//! optional `orders`, `crown`, `samples`), `SurfaceMatch` (Match Surface: `body`, optional+//! `faces`, `target`, `edges`, optional `order`) and `SurfaceFair` (Fair Surface: `body`, optional+//! `faces`, `strength`, `iterations`, `keep_edges`, `tolerance`). Older designs need no+//! transformation; 0.13.x asks for an update instead of meeting a feature it can't read.diff --git a/crates/doc/src/walk.rs b/crates/doc/src/walk.rsindex 64073b3110..7c571a1bb8 100644--- a/crates/doc/src/walk.rs+++ b/crates/doc/src/walk.rs@@ -40,6 +40,8 @@ impl Walk for bool {}impl Walk for u64 {}impl Walk for i8 {}impl Walk for f64 {}+impl Walk for usize {}+impl Walk for u32 {}impl Walk for ProfileSel {}impl Walk for solidcraft_sketch::Sketch {}impl Walk for solidcraft_sketch::PatternAlignment {}diff --git a/crates/engine/src/cmd/mod.rs b/crates/engine/src/cmd/mod.rsindex db7fa5c3fd..a37f226a78 100644--- a/crates/engine/src/cmd/mod.rs+++ b/crates/engine/src/cmd/mod.rs@@ -74,6 +74,7 @@ mod sketch_modify;mod sketch_project;mod surface;mod surface_analysis;+mod surface_match;mod view_dxf;mod view_navigation;@@ -236,6 +237,7 @@ pub fn command_specs() -> Vec<&'static CommandSpec> {v.extend(sketch_3d::COMMANDS.iter());v.extend(surface_analysis::COMMANDS.iter());v.extend(surface::COMMANDS.iter());+ v.extend(surface_match::COMMANDS.iter());v.extend(sketch_modify::COMMANDS.iter());v.extend(sketch_project::COMMANDS.iter());v.extend(features::COMMANDS.iter());diff --git a/crates/engine/src/cmd/surface.rs b/crates/engine/src/cmd/surface.rsindex 93d7a19af0..4e76e0d465 100644--- a/crates/engine/src/cmd/surface.rs+++ b/crates/engine/src/cmd/surface.rs@@ -3,7 +3,8 @@use serde_json::Value;use solidcraft_doc::{- BlendSide, EdgeContinuity, ExtendMode, ExtendTo, FaceAt, FeatureKind, PatchContinuity, PlaneRef, ProfileSel, RuledCorners, RuledMode, expr::Kind,+ BlendSide, EdgeContinuity, Expr, ExtendMode, ExtendTo, FaceAt, FeatureKind, PatchContinuity, PlaneRef, ProfileSel, RuledCorners, RuledMode,+ expr::Kind,};use solidcraft_doc::{BodyName, SketchId};use solidcraft_doc::{Dir, FacePick, Position};@@ -11,7 +12,7 @@ use solidcraft_kernel::Continuity;use super::CommandSpec;use super::features::{add_feature, axis_param, check_expr, extent_param, feature_sketch, operation, plane_param, profiles, sketch_id};-use crate::params::{bad, bool_, expr, str_, string_list, vec3};+use crate::params::{bad, bool_, expr, num, str_, string_list, vec3};use crate::{Result, Session};pub static COMMANDS: &[CommandSpec] = &[@@ -59,10 +60,6 @@ pub static COMMANDS: &[CommandSpec] = &[.at("SURFACE", "CREATE").icon("ruled").params("body; edges: [[x,y,z]] (points on a chain of its edges, open or closed); distance: expr (how far the strip reaches); mode?: normal|tangent|angle|direction (default normal: along the normal of the face beside each edge; tangent: continuing it); angle?: expr (angle mode: from `direction`, else from the face's normal, turned away from the face; 90 deg from the normal is tangent); direction?: [x,y,z] (direction mode: the rulings; angle mode: the reference, e.g. a pull direction for a draft); face?: [x,y,z] (a point on the face the directions come from; default: the face beside the most picked edges); flip?: bool (the other side); corners?: mitre|round (sharp corners of the chain; inside corners are always cut back). Lines and arcs give exact planes, cylinders and cones, other edges a fitted ruled B-spline. A new surface body"),- planned!("surface.boundary", "Boundary Surface", "763")- .at("SURFACE", "CREATE")- .icon("boundary")- .params("planned: u: [curves], v?: [curves] (sketch curves, 3D sketch wires or {body, point} edges; 2–4 boundaries, more make a network); continuity?: [{curve, g: 0|1|2}] for edge boundaries; operation?: new|join"),CommandSpec::new("surface.blend", "Blend Surface", blend).at("SURFACE", "CREATE").icon("surface_blend")@@ -79,6 +76,10 @@ pub static COMMANDS: &[CommandSpec] = &[.at("SURFACE", "MODIFY").icon("reverse_normal").params("body (a surface); faces?: [[x,y,z]] (points on the faces to turn over; default: all of them)"),+ CommandSpec::new("surface.fair", "Fair Surface", fair)+ .at("SURFACE", "MODIFY")+ .icon("spline_cv")+ .params("body: surface name; faces?: [[x,y,z]] points on the faces to fair (default: every face); strength?: number (0..1 of the full fairing step, default 1); iterations?: number (1..1000 steps, default 1); keep_edges?: bool (default true: hold the boundary row and the row next to it, so a face keeps meeting its neighbours in position and in tangent); tolerance?: expr mm (how far a control vertex may move, default 0.001 of the body's size). Moves the interior control vertices of each B-spline face to flatten its curvature variation while the boundary stays put: the face keeps its edges and the body its shape within the tolerance, and the warning in the reply carries the energy before and after; name?"),planned!("surface.fillet", "Surface Fillet", "769").at("SURFACE", "MODIFY").icon("surface_fillet")@@ -558,6 +559,39 @@ fn trim(s: &mut Session, p: &Value) -> Result<Value> {add_feature(s, p, FeatureKind::SurfaceTrim { body: BodyName(body), plane, tool, keep: Position(keep) })}+/// `surface.fair`: the B-spline faces of a body faired in place. The tolerance a caller leaves+/// out is a thousandth of the body's own size, so a fairing run can never make a design jump by+/// more than a hair of itself.+fn fair(s: &mut Session, p: &Value) -> Result<Value> {+ let cmd = "surface.fair";+ let (body, faces) = body_faces(s, p, cmd)?;+ let size = {+ let state = s.model.state();+ let Some(mb) = state.body(&body) else { return Err(bad(cmd, format!("no body `{body}`"))) };+ mb.body.size()+ };+ let strength = num(p, "strength").unwrap_or(1.0);+ if !(strength.is_finite() && strength > 0.0 && strength <= 1.0) {+ return Err(bad(cmd, "`strength` must be greater than 0 and at most 1 (the whole fairing step)"));+ }+ let steps = num(p, "iterations").unwrap_or(1.0);+ if !(steps.is_finite() && (1.0..=1000.0).contains(&steps)) {+ return Err(bad(cmd, "`iterations` must be 1 to 1000"));+ }+ let keep_edges = bool_(p, "keep_edges").unwrap_or(true);+ let tolerance = expr(p, "tolerance").unwrap_or_else(|| Expr::new(format!("{:.6}", (size * 1e-3).max(1e-6))));+ check_expr(s, tolerance.as_str(), Kind::Length, cmd, "tolerance")?;+ let kind = FeatureKind::SurfaceFair {+ body: BodyName::from(body),+ faces: faces.into_iter().map(FacePick).collect(),+ strength,+ iterations: steps as u32,+ keep_edges,+ tolerance,+ };+ add_feature(s, p, kind)+}+#[cfg(test)]mod tests {use super::*;@@ -1178,7 +1212,7 @@ mod tests {/// as it was.#[test]fn planned_commands_refuse_and_leave_the_design_alone() {- let planned = ["surface.boundary", "surface.fillet", "inspect.continuity"];+ let planned = ["surface.fillet", "inspect.continuity"];let mut s = Session::default();run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "body_name": "B"}));let before = s.doc.features.len();@@ -1500,4 +1534,58 @@ mod tests {let sketch_patch = json!({"sketch": 1, "continuity": "g1"});assert!(s.execute("surface.patch", &sketch_patch).is_err(), "continuity on a sketch patch");}+ /// The energies the reply's warning carries: the fairness energy before and after.+ fn energies(reply: &Value) -> (f64, f64) {+ let warning = reply["warning"].as_str().unwrap_or_else(|| panic!("no warning in {reply}"));+ let after = warning.split("energy ").nth(1).unwrap_or_else(|| panic!("no energies in `{warning}`"));+ let numbers: Vec<f64> = after+ .split(|c: char| !(c.is_ascii_digit() || c == '.' || c == 'e' || c == '-' || c == '+'))+ .filter_map(|w| w.parse::<f64>().ok())+ .collect();+ assert!(numbers.len() >= 2, "no energies in `{warning}`");+ (numbers[0], numbers[1])+ }++ /// Surface Fair on the fitted B-spline face of an offset sphere: the face is smoothed in+ /// place, its edges do not move at all, the reply carries the energy before and after, undo,+ /// redo and a cold reopen keep it, and hostile inputs are refused.+ #[test]+ fn fairing_a_b_spline_face_keeps_its_edges_and_reports_its_energy() {+ let mut s = Session::default();+ run(&mut s, "solid.sphere", json!({"radius": 20, "body_name": "Ball"}));+ // A sphere is neither a plane nor a cylinder, so its offset is a fitted B-spline face.+ run(&mut s, "surface.offset", json!({"faces": [[0, 0, 20]], "body": "Ball", "distance": 2, "body_name": "Shell"}));+ let st = s.world_state();+ assert!(st.body("Shell").unwrap().body.is_surface(), "an offset sphere face is a sheet");+ let before: Vec<solidcraft_geom::Vec3> = st.body("Shell").unwrap().body.edges(0.1).unwrap().iter().flat_map(|e| e.points.clone()).collect();+ assert!(!before.is_empty());+ let area_before = area(&s, "Shell");+ // The fairing reports both energies, the second no larger than the first.+ let reply = run(&mut s, "surface.fair", json!({"body": "Shell", "tolerance": 1.0, "iterations": 3}));+ let (energy_before, energy_after) = energies(&reply);+ let area_after = area(&s, "Shell");+ eprintln!("surface.fair: {reply}\nenergies {energy_before:e} → {energy_after:e}, area {area_before} → {area_after}");+ assert!(energy_before > 0.0 && energy_after <= energy_before, "{energy_before:e} → {energy_after:e}");+ // The face moved (the fit is not the flattest surface on its own rim), but not its edges:+ // every boundary point of the body is where it was, bit for bit.+ assert!((area_after - area_before).abs() > 0.0 || energy_after < energy_before);+ let after: Vec<solidcraft_geom::Vec3> = st.body("Shell").unwrap().body.edges(0.1).unwrap().iter().flat_map(|e| e.points.clone()).collect();+ assert_eq!(after, before, "fairing must not move the face's edges");+ assert_eq!(st.body("Shell").unwrap().body.face_count(), 1);+ // Undo takes the fairing back, redo puts it back, and a cold reopen rebuilds the same.+ run(&mut s, "edit.undo", json!({}));+ assert!((area(&s, "Shell") - area_before).abs() < 1e-9, "undo did not take the fairing back");+ run(&mut s, "edit.redo", json!({}));+ assert!((area(&s, "Shell") - area_after).abs() < 1e-9, "redo did not put the fairing back");+ let cold = Session::new(solidcraft_doc::Document::from_json(&s.doc.to_json()).unwrap());+ assert!((area(&cold, "Shell") - area_after).abs() < 1e-9, "a cold reopen did not rebuild the same sheet");+ // Refusals: an unknown body, a body whose faces are all planes, an out-of-range strength+ // or step count, and a missing tolerance expression.+ assert!(s.execute("surface.fair", &json!({"body": "Nope", "tolerance": 1.0})).is_err());+ run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "body_name": "Box"}));+ assert!(s.execute("surface.fair", &json!({"body": "Box", "tolerance": 1.0})).is_err());+ assert!(s.execute("surface.fair", &json!({"body": "Shell", "strength": 2, "tolerance": 1.0})).is_err());+ assert!(s.execute("surface.fair", &json!({"body": "Shell", "iterations": 0, "tolerance": 1.0})).is_err());+ assert!(s.execute("surface.fair", &json!({"body": "Shell", "tolerance": 0})).is_err());+ }}diff --git a/crates/engine/src/cmd/surface_boundary.rs b/crates/engine/src/cmd/surface_boundary.rsnew file mode 100644index 0000000000..6bbc3f1a41--- /dev/null+++ b/crates/engine/src/cmd/surface_boundary.rs@@ -0,0 +1,197 @@+//! Boundary surfaces: one patch through a network of two to four sketch curves (`surface.boundary`,+//! issue #763). The kernel builds the face from the curves' own frames; this is the command's+//! parameters and its checks, so that a loop it cannot hold is refused before anything is built.++use serde_json::Value;+use solidcraft_doc::{FeatureKind, SketchId};+use solidcraft_kernel::Continuity;++use super::CommandSpec;+use super::features::{add_feature, feature_sketch};+use crate::params::{bad, string_list};+use crate::{Result, Session};++/// The stations a boundary carries by default (the patch's resolution along the loop).+const DEFAULT_SAMPLES: usize = 25;+/// The fewest stations a patch can hold the widest continuity pair with: a G3 side needs four rows+/// at each of two opposite sides, so eight.+const MIN_SAMPLES: usize = 8;+/// The most stations a boundary may carry (the kernel's own cap).+const MAX_SAMPLES: usize = 512;++pub static COMMANDS: &[CommandSpec] = &[CommandSpec::new("surface.boundary", "Boundary Surface", boundary)+ .at("SURFACE", "CREATE")+ .icon("boundary")+ .params(+ "sketch?: id|name (default: the sketch being edited); curves: [2 to 4 sketch curve ids in loop order] (each one ends where the next begins and the last where the first does; the patch runs through them and leaves each boundary along the tangent across it); continuity?: g0|g1|g2|g3 | [one per curve] (default g1: how much of the surface across each boundary the patch repeats — a sketch curve's own plane, so g1 and up hold exactly and g0 lets the middle bow); crown?: number -0.9…3 (default 0: how full the middle is, without touching a boundary); samples?: 8…512 stations per boundary (default 25); name?, body_name? (a surface body)",+ )];++/// `surface.boundary`: one patch through a network of two to four sketch curves.+fn boundary(s: &mut Session, p: &Value) -> Result<Value> {+ let cmd = "surface.boundary";+ let sketch = feature_sketch(s, p, cmd)?;+ let curves = string_list(p, "curves");+ if !(2..=4).contains(&curves.len()) {+ return Err(bad(cmd, "`curves` must list 2 to 4 sketch curves in loop order"));+ }+ // The curves must be the sketch's own, and they must run on into one another: the last station+ // of each is the first of the next, and the last boundary's end is the first one's start.+ let state = s.model.state();+ let sk = state.sketch(sketch).ok_or_else(|| bad(cmd, "the sketch has not been solved"))?;+ let mut ends: Vec<(solidcraft_geom::Vec2, solidcraft_geom::Vec2)> = Vec::with_capacity(curves.len());+ for id in &curves {+ let ci = sk.sketch.curve_index(id).ok_or_else(|| bad(cmd, format!("no sketch curve `{id}`")))?;+ let pieces = sk.sketch.exact_pieces(ci);+ let (Some(first), Some(last)) = (pieces.first(), pieces.last()) else {+ return Err(bad(cmd, format!("curve `{id}` has no exact geometry to build on")));+ };+ if last.end().dist(first.start()) < 1e-9 {+ return Err(bad(cmd, format!("curve `{id}` is closed: a boundary must be one side of the loop")));+ }+ ends.push((first.start(), last.end()));+ }+ // Two boundaries are the two sides of a bridge, which do not meet; three or four run round a+ // loop, so each has to end where the next begins.+ let scale = ends.iter().map(|(a, b)| a.dist(*b)).fold(1.0_f64, f64::max);+ let tol = scale * 1e-4 + 1e-9;+ for i in 0..if curves.len() >= 3 { ends.len() } else { 0 } {+ let next = (i + 1) % ends.len();+ let (Some(end), Some(start)) = (ends.get(i).map(|e| e.1), ends.get(next).map(|e| e.0)) else {+ return Err(bad(cmd, "a curve is missing its ends"));+ };+ let gap = end.dist(start);+ if gap > tol {+ return Err(bad(+ cmd,+ format!("curve `{}` ends {gap:.4} mm from where `{}` starts: list the curves in loop order", curves[i], curves[next]),+ ));+ }+ }+ drop(state);+ let orders = match p.get("continuity") {+ None | Some(Value::Null) => vec![Continuity::G1; curves.len()],+ Some(Value::String(w)) => {+ let one = Continuity::parse(w).ok_or_else(|| bad(cmd, "`continuity` must be g0, g1, g2 or g3"))?;+ vec![one; curves.len()]+ }+ Some(v) => {+ let list = v.as_array().filter(|a| a.len() == curves.len()).ok_or_else(|| bad(cmd, "`continuity` must be one word, or one per curve"))?;+ let mut out = Vec::with_capacity(list.len());+ for x in list {+ out.push(x.as_str().and_then(Continuity::parse).ok_or_else(|| bad(cmd, "`continuity` entries must be g0, g1, g2 or g3"))?);+ }+ out+ }+ };+ let crown = match p.get("crown") {+ None | Some(Value::Null) => 0.0,+ Some(v) => v+ .as_f64()+ .filter(|x| x.is_finite() && (solidcraft_geom::fill::MIN_CROWN..=solidcraft_geom::fill::MAX_CROWN).contains(x))+ .ok_or_else(|| bad(cmd, "`crown` must be a number between -0.9 and 3"))?,+ };+ let samples = match p.get("samples") {+ None | Some(Value::Null) => DEFAULT_SAMPLES,+ Some(v) => {+ let n = v.as_f64().filter(|x| x.is_finite() && x.fract() == 0.0).map(|x| x as usize);+ n.filter(|x| (MIN_SAMPLES..=MAX_SAMPLES).contains(x))+ .ok_or_else(|| bad(cmd, format!("`samples` must be a whole number of stations between {MIN_SAMPLES} and {MAX_SAMPLES}")))?+ }+ };+ add_feature(s, p, FeatureKind::SurfaceBoundary { sketch: SketchId(sketch), curves, orders, crown, samples })+}++#[cfg(test)]+mod tests {+ use serde_json::{Value, json};++ use crate::Session;++ fn run(s: &mut Session, id: &str, p: Value) -> Value {+ match s.execute(id, &p) {+ Ok(v) => v,+ Err(e) => panic!("{id} {p}: {e}"),+ }+ }++ fn ids(v: &Value) -> Vec<String> {+ v.as_array().map(|a| a.iter().filter_map(|x| x.as_str().map(str::to_string)).collect()).unwrap_or_default()+ }++ fn new_sketch() -> Session {+ let mut s = Session::default();+ run(&mut s, "sketch.create", json!({"plane": "XY"}));+ s+ }++ /// Two parallel 20 mm lines 10 mm apart, and the patch between them.+ fn two_walls(s: &mut Session) -> Vec<String> {+ let a = ids(&run(s, "sketch.line", json!({"points": [[0, 0], [20, 0]]}))["created"]["curves"])[0].clone();+ let b = ids(&run(s, "sketch.line", json!({"points": [[0, 10], [20, 10]]}))["created"]["curves"])[0].clone();+ vec![a, b]+ }++ #[test]+ fn a_boundary_patch_between_two_sketch_curves_is_the_sheet_they_span() {+ for continuity in [json!("g0"), json!("g1"), json!("g2"), json!(["g1", "g2"])] {+ let mut s = new_sketch();+ let curves = two_walls(&mut s);+ let r = run(&mut s, "surface.boundary", json!({"curves": curves, "continuity": continuity}));+ let body = ids(&r["created_bodies"])[0].clone();+ // It is one face, its boundary is the two lines themselves, and it covers exactly the+ // 20 × 10 sheet between them — all four frames lie in the sketch's plane.+ let f = run(&mut s, "model.faces", json!({"body": body}));+ let faces = f["faces"].as_array().cloned().unwrap_or_default();+ assert_eq!(faces.len(), 1, "{continuity}: {f}");+ assert!((faces[0]["area"].as_f64().unwrap_or(f64::NAN) - 200.0).abs() < 1e-4, "{continuity}: {f}");+ let normal = faces[0]["plane_normal"].as_array().cloned().unwrap_or_default();+ assert_eq!(normal.len(), 3, "{continuity}: the patch is planar: {f}");+ assert!(normal[2].as_f64().unwrap_or(0.0).abs() > 1.0 - 1e-9, "{continuity}: it lies in the sketch's plane: {f}");+ let m = run(&mut s, "inspect.measure", json!({}));+ let area = m["total"]["area_mm2"].as_f64().unwrap_or(f64::NAN);+ assert!((area - 200.0).abs() < 1e-4, "{continuity}: {area}");+ }+ }++ #[test]+ fn a_boundary_patch_refuses_a_loop_and_values_it_cannot_hold() {+ let mut s = new_sketch();+ let curves = two_walls(&mut s);+ let extra = ids(&run(&mut s, "sketch.line", json!({"points": [[30, 30], [40, 40]]}))["created"]["curves"])[0].clone();+ // A loop of three or four: the kernel refuses it with its own reason (a tensor-product patch+ // cannot hold two sides' data at a corner, issue #763) rather than building it approximately.+ let triangle = ["l1", "l2", "l3"].map(|id| {+ let _ = id;+ String::new()+ });+ let _ = triangle;+ let a = ids(&run(&mut s, "sketch.line", json!({"points": [[0, 0], [20, 0]]}))["created"]["curves"])[0].clone();+ let b = ids(&run(&mut s, "sketch.line", json!({"points": [[20, 0], [10, 15]]}))["created"]["curves"])[0].clone();+ let c = ids(&run(&mut s, "sketch.line", json!({"points": [[10, 15], [0, 0]]}))["created"]["curves"])[0].clone();+ let e = s.execute("surface.boundary", &json!({"curves": [a, b, c], "continuity": "g2"})).unwrap_err().to_string();+ assert!(e.contains("not supported yet") && e.contains("#763"), "three boundaries: {e}");+ // A closed square of four lines, in loop order.+ let sq = [[[0, 0], [10, 0]], [[10, 0], [10, 10]], [[10, 10], [0, 10]], [[0, 10], [0, 0]]];+ let square: Vec<String> = sq.iter().map(|p| ids(&run(&mut s, "sketch.line", json!({"points": p}))["created"]["curves"])[0].clone()).collect();+ let e = s.execute("surface.boundary", &json!({"curves": square})).unwrap_err().to_string();+ assert!(e.contains("not supported yet") && e.contains("#763"), "four boundaries: {e}");+ // Parameters and curves that make no sense.+ let cases: Vec<(Value, &str)> = vec![+ (json!({"curves": [curves[0]]}), "2 to 4"),+ (json!({"curves": [curves[0], curves[1], extra.clone(), extra.clone(), extra.clone()]}), "2 to 4"),+ (json!({"curves": [curves[0], "nope"]}), "no sketch curve"),+ (json!({"curves": curves, "continuity": "g9"}), "continuity"),+ (json!({"curves": curves, "continuity": ["g1", "g2", "g3"]}), "continuity"),+ (json!({"curves": curves, "crown": 5}), "crown"),+ (json!({"curves": curves, "crown": "full"}), "crown"),+ (json!({"curves": curves, "samples": 3}), "samples"),+ (json!({"curves": curves, "samples": 2.5}), "samples"),+ ];+ for (params, want) in cases {+ let e = s.execute("surface.boundary", ¶ms).unwrap_err().to_string();+ assert!(e.contains(want), "{params}: {e}");+ }+ // Nothing was built by any of them.+ assert!(s.model.state().bodies.is_empty(), "a refused patch left a body behind");+ }+}diff --git a/crates/engine/src/cmd/surface_match.rs b/crates/engine/src/cmd/surface_match.rsnew file mode 100644index 0000000000..78f5b8ec89--- /dev/null+++ b/crates/engine/src/cmd/surface_match.rs@@ -0,0 +1,160 @@+//! `surface.match`: rebuild a surface body's face so that one of its boundaries takes the place of+//! a picked edge chain of another body, repeating that body's shape along the seam up to a+//! requested continuity, while the boundary opposite it keeps its place. The body keeps its name:+//! a match is a modify, like Trim, Extend and Fair.++use serde_json::Value;+use solidcraft_doc::{BodyName, FacePick, FeatureKind, Position};+use solidcraft_kernel::Continuity;++use super::CommandSpec;+use super::features::add_feature;+use crate::params::{bad, str_, vec3};+use crate::{Result, Session};++pub static COMMANDS: &[CommandSpec] = &[+ CommandSpec::new("surface.match", "Match Surface", match_surface)+ .at("SURFACE", "MODIFY")+ .icon("continuity")+ .params(+ "body: surface name (the body whose face is rebuilt); faces?: [[x,y,z]] (points on that face, default: the body's first); target: body name (the body the seam must meet); edges: [[x,y,z]] (points on one edge chain of the target: the rebuilt boundary takes its place); order?: g1|g2|g3 (default g2: position and tangent plane, the curvature too, or how that curvature changes along the seam). The far boundary stays where it was and the body keeps its name",+ ),+];++/// `surface.match`: one face of `body` is rebuilt so that its boundary nearest the picked chain of+/// `target` lies on that chain and repeats the target's own shape there up to `order`.+fn match_surface(s: &mut Session, p: &Value) -> Result<Value> {+ let cmd = "surface.match";+ let body = str_(p, "body").ok_or_else(|| bad(cmd, "`body` is required"))?.to_string();+ if s.model.state().body(&body).is_none() {+ return Err(bad(cmd, format!("no body `{body}`")));+ }+ let target = str_(p, "target").ok_or_else(|| bad(cmd, "`target` is required"))?.to_string();+ if s.model.state().body(&target).is_none() {+ return Err(bad(cmd, format!("no body `{target}`")));+ }+ let faces: Vec<solidcraft_geom::Vec3> = p.get("faces").and_then(Value::as_array).map(|a| a.iter().filter_map(vec3).collect()).unwrap_or_default();+ if faces.len() > 64 {+ return Err(bad(cmd, "too many points on the face to rebuild"));+ }+ let edges: Vec<solidcraft_geom::Vec3> = p.get("edges").and_then(Value::as_array).map(|a| a.iter().filter_map(vec3).collect()).unwrap_or_default();+ if edges.is_empty() || edges.len() > 10_000 {+ return Err(bad(cmd, "`edges` must list 1 to 10000 points on the target's edge chain"));+ }+ let order = match p.get("order") {+ None => Continuity::G2,+ Some(v) => v.as_str().and_then(Continuity::parse).filter(|o| *o != Continuity::G0).ok_or_else(|| bad(cmd, "`order` must be g1, g2 or g3"))?,+ };+ add_feature(+ s,+ p,+ FeatureKind::SurfaceMatch {+ body: BodyName::from(body),+ faces: faces.into_iter().map(FacePick).collect(),+ target: BodyName::from(target),+ edges: edges.into_iter().map(Position).collect(),+ order,+ },+ )+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::Session;+ use serde_json::json;+ use solidcraft_geom::Vec3;++ fn run(s: &mut Session, c: &str, p: Value) -> Value {+ s.execute(c, &p).unwrap_or_else(|e| panic!("{c}: {e}"))+ }++ /// The picked chain: two points of the cylinder's own vertical wall seam, clear of the corners+ /// at either end. The seam is where `solid.extrude` starts the circle, so it is read off the+ /// body rather than assumed.+ fn picks(s: &Session) -> Vec<Vec3> {+ let boss = s.world_state().body("Boss").unwrap().body.clone();+ let e = boss+ .edges(boss.size() * 1e-2)+ .unwrap()+ .into_iter()+ .find(|e| e.length > 25.0 && (e.mid.x.hypot(e.mid.y) - 10.0).abs() < 0.05 && e.mid.z > 5.0 && e.mid.z < 25.0)+ .expect("the cylinder has a straight vertical wall seam");+ let (a, b) = (e.points.first().copied(), e.points.last().copied());+ let (a, b) = (a.unwrap_or(e.mid), b.unwrap_or(e.mid));+ vec![a + (b - a) * 0.25, a + (b - a) * 0.75]+ }++ /// A cylinder of radius 10, 30 high, and a cylindrical skirt of radius 11 from the cylinder's+ /// own wall seam round 60 degrees: the skirt's near boundary is 1 mm off the seam line.+ fn boss_and_skirt(s: &mut Session) {+ run(s, "sketch.create", json!({"plane": "XY", "name": "Round"}));+ run(s, "sketch.circle.center", json!({"center": [0, 0], "radius": 10}));+ run(s, "sketch.finish", json!({}));+ run(s, "solid.extrude", json!({"sketch": "Round", "distance": 30, "body_name": "Boss"}));+ let seam = picks(s)[0];+ let a = seam.y.atan2(seam.x);+ let at = |t: f64| json!([11.0 * t.cos(), 11.0 * t.sin()]);+ run(s, "sketch.create", json!({"plane": "XY", "name": "Skirt sketch"}));+ let arc = run(s, "sketch.arc.three_point", json!({"start": at(a), "end": at(a + 60f64.to_radians()), "through": at(a + 30f64.to_radians())}))+ ["created"]["curves"][0]+ .as_str()+ .unwrap()+ .to_string();+ run(s, "sketch.finish", json!({}));+ run(s, "surface.extrude", json!({"sketch": "Skirt sketch", "curves": [arc], "distance": 30, "body_name": "Skirt"}));+ }++ /// The seam of a matched skirt, measured back off the two bodies: how far the rebuilt boundary+ /// is from the picked seam line, the angle between the two surfaces' normals across it, and+ /// the continuity it holds.+ fn seam(s: &Session) -> (f64, f64, Continuity) {+ let st = s.world_state();+ let made = st.body("Skirt").unwrap().body.clone();+ let target = st.body("Boss").unwrap().body.clone();+ solidcraft_kernel::seam_continuity(&made, &target, &picks(s)).unwrap()+ }++ /// `surface.match`: a skirt meets a cylinder's wall seam at g2; the body keeps its name, undo+ /// and redo move it back and forth, a cold reopen gives the same seam, and what cannot be+ /// matched is refused.+ #[test]+ fn surface_match_rebuilds_a_skirt_onto_a_cylinder() {+ let mut s = Session::default();+ boss_and_skirt(&mut s);+ // Before the match the skirt's boundary is the 1 mm-wider line it was extruded at.+ let (gap, _, _) = seam(&s);+ assert!((gap - 1.0).abs() < 0.05, "the skirt starts a millimetre off the seam: {gap}");+ let chain = picks(&s);+ run(&mut s, "surface.match", json!({"body": "Skirt", "target": "Boss", "edges": chain, "order": "g2"}));+ let st = s.world_state();+ assert!(st.body("Skirt").is_some(), "the matched body keeps its name");+ assert!(st.body("Boss").is_some(), "the body it was matched to stays too");+ assert!(st.body("Skirt").unwrap().body.is_surface(), "a match stays a surface");+ let (gap, deg, order) = seam(&s);+ println!("engine: gap {gap:e} mm, normal {deg:e} deg, order {order:?}");+ assert!(gap < 1e-6, "the seam is on the picked line: {gap:e} mm");+ assert!(deg < 0.05, "the seam holds the wall's tangent plane: {deg} deg");+ assert!(order.conditions() >= Continuity::G1.conditions(), "{order:?}");+ // Undo puts the boundary back, redo matches it again, and a cold reopen agrees.+ run(&mut s, "edit.undo", json!({}));+ assert!(seam(&s).0 > 0.5, "undo restores the original skirt");+ run(&mut s, "edit.redo", json!({}));+ assert!(seam(&s).1 < 0.05, "redo matches it again");+ let cold = Session::new(solidcraft_doc::Document::from_json(&s.doc.to_json()).unwrap());+ assert!(seam(&cold).1 < 0.05, "a reopened design matches the same");+ // Refusals: an unknown body, no target, no picks on the target, a word that is no order,+ // and a body that is not a surface.+ assert!(s.execute("surface.match", &json!({"body": "Nope", "target": "Boss", "edges": picks(&s)})).is_err());+ assert!(s.execute("surface.match", &json!({"body": "Skirt", "edges": picks(&s)})).is_err());+ assert!(s.execute("surface.match", &json!({"body": "Skirt", "target": "Boss", "edges": []})).is_err());+ assert!(s.execute("surface.match", &json!({"body": "Skirt", "target": "Nope", "edges": picks(&s)})).is_err());+ assert!(s.execute("surface.match", &json!({"body": "Skirt", "target": "Boss", "edges": picks(&s), "order": "g5"})).is_err());+ assert!(s.execute("surface.match", &json!({"body": "Skirt", "target": "Boss", "edges": [[100, 0, 0]]})).is_err());+ run(&mut s, "sketch.create", json!({"plane": "XY", "name": "B"}));+ run(&mut s, "sketch.rectangle.two_point", json!({"p0": [0, 0], "p1": [4, 4]}));+ run(&mut s, "sketch.finish", json!({}));+ run(&mut s, "solid.extrude", json!({"sketch": "B", "distance": 4, "body_name": "Block"}));+ assert!(s.execute("surface.match", &json!({"body": "Block", "target": "Boss", "edges": picks(&s)})).is_err(), "a solid is not a surface");+ }+}diff --git a/crates/kernel/src/boundary.rs b/crates/kernel/src/boundary.rsnew file mode 100644index 0000000000..c0825f2efb--- /dev/null+++ b/crates/kernel/src/boundary.rs@@ -0,0 +1,123 @@+//! Boundary patches: one face through the boundary curves of a sketch, each side meeting the+//! surface it was taken from at a requested continuity (G0 up to G3).+//!+//! Two boundaries are the two sides of a [`crate::bridge`]: the patch is the Hermite surface that+//! leaves each boundary along the direction its frames state and repeats as much of that support+//! surface — its tangent plane, its curvature, the change of that curvature — as the side's order+//! asks for, with `crown` shaping the middle without touching a boundary condition.+//!+//! A patch through *three or four* boundaries is refused rather than built approximately. At a+//! corner two sides prescribe the same entries of the control net from two different surfaces, and+//! a tensor-product patch can hold both only where those two prescriptions already agree (one wall+//! carrying every side, say). Where they do not — the general case — the requested order would+//! silently drop near the corner, or the boundary curve would visibly leave its stations, and a+//! Gregory-type corner (a rational blend of the sides' own data) is needed to hold them instead+//! (issue #763). Everything this module refuses is an error, never a quietly worse surface.++use solidcraft_geom::Vec3;++use crate::body::Body;+use crate::bridge::{Continuity, Frame, bridge};+use crate::{KernelError, Result};++/// The most stations a boundary of a patch may carry.+const MAX_SAMPLES: usize = 512;++/// One boundary of a patch: the stations along it, and how much of the surface it was taken from+/// the patch repeats there.+#[derive(Clone, Debug)]+pub struct Boundary {+ /// The stations along the boundary, in the order they run: the end of one boundary meets the+ /// start of the next, and the last meets the first.+ pub frames: Vec<Frame>,+ /// How much of the neighbouring surface the patch repeats at this boundary.+ pub order: Continuity,+}++/// A two-sided patch: one face that meets boundary `i` at the continuity its `order` asks for (G0 up+/// to G3), with `samples` stations every boundary must carry and `crown` shaping the middle of the+/// patch without touching any boundary condition (0 the plain blend, up to 3 fuller, down to -0.9+/// flatter). Three or four boundaries are refused: see the module docs.+pub fn boundary_patch(boundaries: &[Boundary], crown: f64, samples: usize) -> Result<Body> {+ check_input(boundaries, crown, samples)?;+ if boundaries.len() > 2 {+ return Err(KernelError::Invalid(format!(+ "not supported yet: a patch through {} boundaries — a three- or four-sided patch needs a Gregory-type corner (issue #763); \+ give two boundaries, which is the bridge this builds exactly",+ boundaries.len()+ )));+ }+ let (Some(a), Some(b)) = (boundaries.first(), boundaries.get(1)) else {+ return Err(KernelError::Invalid("a boundary patch joins 2 boundaries: one of them is missing".into()));+ };+ bridge(&a.frames, &b.frames, [a.order, b.order], [crown, crown])+}++/// Everything a patch refuses, before any geometry is built.+fn check_input(boundaries: &[Boundary], crown: f64, samples: usize) -> Result<()> {+ let n = boundaries.len();+ if !(2..=4).contains(&n) {+ return Err(KernelError::Invalid(format!("a boundary patch joins 2 to 4 boundaries, {n} given")));+ }+ if !(2..=MAX_SAMPLES).contains(&samples) {+ return Err(KernelError::Invalid(format!("a boundary patch needs 2 to {MAX_SAMPLES} stations per boundary, {samples} given")));+ }+ if !crown.is_finite() || !(-0.9..=3.0).contains(&crown) {+ return Err(KernelError::Invalid("a boundary patch's crown must be between -0.9 and 3".into()));+ }+ for (i, b) in boundaries.iter().enumerate() {+ if b.frames.len() != samples {+ return Err(KernelError::Invalid(format!(+ "boundary {i} carries {} stations, not the {samples} every boundary of a patch needs",+ b.frames.len()+ )));+ }+ for f in &b.frames {+ if ![f.p, f.leave, f.bend, f.bend_change].into_iter().all(Vec3::is_finite) {+ return Err(KernelError::Invalid(format!("boundary {i} has a station that is not finite")));+ }+ if f.leave.normalized().is_none() {+ return Err(KernelError::Invalid(format!("boundary {i} has a station with no leave direction")));+ }+ }+ if boundary_length(&b.frames) <= 1e-9 {+ return Err(KernelError::Invalid(format!("boundary {i} has no length: a patch needs a curve, not a single point")));+ }+ }+ // Two boundaries are the two sides of a bridge, which do not meet; three or four would run round+ // a loop, so each one would have to end where the next one begins.+ if n >= 3 {+ let mut scale: f64 = 1.0;+ for b in boundaries {+ scale = scale.max(boundary_length(&b.frames));+ }+ let tol = scale * 1e-4 + 1e-9;+ for i in 0..n {+ let (Some(a), Some(b)) = (boundaries.get(i), boundaries.get((i + 1) % n)) else { continue };+ let (Some(end), Some(start)) = (a.frames.last(), b.frames.first()) else { continue };+ let gap = end.p.dist(start.p);+ if gap > tol {+ return Err(KernelError::Invalid(format!(+ "boundary {i} ends and boundary {} starts {gap:.6} mm apart: the boundaries of a loop must run on into one another",+ (i + 1) % n+ )));+ }+ }+ }+ Ok(())+}++/// The length of a run of stations.+fn boundary_length(frames: &[Frame]) -> f64 {+ let mut length: f64 = 0.0;+ for w in frames.windows(2) {+ if let (Some(a), Some(b)) = (w.first(), w.get(1)) {+ length += a.p.dist(b.p);+ }+ }+ length+}++#[cfg(test)]+#[path = "boundary_tests.rs"]+mod tests;diff --git a/crates/kernel/src/boundary_tests.rs b/crates/kernel/src/boundary_tests.rsnew file mode 100644index 0000000000..ce7abfcb03--- /dev/null+++ b/crates/kernel/src/boundary_tests.rs@@ -0,0 +1,276 @@+//! Tests of boundary patches: the bridge this builds is measured back off the face it made — not+//! from the construction — and everything it cannot hold is an error rather than a quiet+//! approximation.++use super::*;+use crate::body::from_p3;+use truck_modeling::ParametricSurface;++/// The angle between two vectors, in degrees.+fn angle_deg(a: Vec3, b: Vec3) -> f64 {+ (a.normalized().unwrap().dot(b.normalized().unwrap())).clamp(-1.0, 1.0).acos().to_degrees()+}++/// The geometric shape of a surface curve from its first three derivatives along it: the unit+/// tangent, the curvature vector and the arclength derivative of that curvature vector — the same+/// reading `bridge` states its conditions with.+fn shape_of(d1: Vec3, d2: Vec3, d3: Vec3) -> (Vec3, Vec3, Vec3) {+ let sigma = d1.len();+ let t = d1 * (1.0 / sigma);+ let tp = d2 * (1.0 / sigma) - d1 * (d1.dot(d2) / (sigma * sigma * sigma));+ let nn = d2 - t * d2.dot(t);+ let np = d3 - t * d3.dot(t) - tp * d2.dot(t) - t * d2.dot(tp);+ let kappa = np * (sigma * sigma) - nn * (2.0 * d1.dot(d2));+ (t, nn * (1.0 / (sigma * sigma)), kappa * (1.0 / (sigma.powi(5))))+}++/// Across a boundary: five samples a step `h` apart, `into` the patch from the parameter `(u, v)`,+/// read back as the position, the unit tangent, the curvature vector and the change of curvature+/// along that inward direction.+fn across(body: &Body, uv: (f64, f64), into: (f64, f64), h: f64) -> (Vec3, Vec3, Vec3, Vec3) {+ let face = body.solid.face_iter().next().unwrap();+ let surf = face.surface();+ let q: Vec<Vec3> = (0..5).map(|k| from_p3(surf.subs(uv.0 + k as f64 * h * into.0, uv.1 + k as f64 * h * into.1))).collect();+ let (f0, f1, f2, f3, f4) = (q[0], q[1], q[2], q[3], q[4]);+ let d1 = (f0 * -25.0 + f1 * 48.0 + f2 * -36.0 + f3 * 16.0 + f4 * -3.0) * (1.0 / (12.0 * h));+ let d2 = (f0 * 35.0 + f1 * -104.0 + f2 * 114.0 + f3 * -56.0 + f4 * 11.0) * (1.0 / (12.0 * h * h));+ let d3 = (f0 * -5.0 + f1 * 18.0 + f2 * -24.0 + f3 * 14.0 + f4 * -3.0) * (1.0 / (2.0 * h * h * h));+ let (t, bend, change) = shape_of(d1, d2, d3);+ (f0, t, bend, change)+}++/// The stations' parameters: `n` of them, evenly spread over the patch.+fn stations(n: usize) -> Vec<f64> {+ (0..n).map(|i| i as f64 / (n - 1) as f64).collect()+}++/// The normal angle a side may be off by.+const ANGLE_TOL: f64 = 0.01;+/// How much of the supporting wall's own curvature a side must repeat, relative to it.+const CURV_TOL: f64 = 1e-3;+/// The normal part of the change of curvature a G3 side may leave over, relative to 1/r² (the+/// finite differences that read the third derivative off the face amplify round-off by 1/h³, so+/// this is a noise floor rather than a geometric tolerance).+const CHANGE_TOL: f64 = 1e-4;++/// Measure one side of a built patch at every station of `frames`, and check what its order asks+/// for: the boundary curve itself always, the tangent plane from G1 on, the curvature vector from+/// G2 on and its change along the leave direction at G3.+fn check_side(body: &Body, frames: &[Frame], order: Continuity, at: impl Fn(usize) -> ((f64, f64), (f64, f64)), r: f64) {+ for (i, f) in frames.iter().enumerate() {+ let (uv, into) = at(i);+ let (p, t, bend, change) = across(body, uv, into, 1e-3);+ let gap = p.dist(f.p);+ assert!(gap < 1e-9, "station {i} sits on its boundary: {p:?} vs {:?} ({gap:.2e} mm)", f.p);+ if order == Continuity::G0 {+ continue;+ }+ assert!(angle_deg(t, f.leave) < ANGLE_TOL, "station {i} leaves along the tangent: {t:?} vs {:?}", f.leave);+ if order == Continuity::G1 {+ continue;+ }+ if f.bend.len() > 1e-9 {+ assert!(bend.dist(f.bend) / f.bend.len() < CURV_TOL, "station {i}: curvature {bend:?} vs the wall's {:?}", f.bend);+ if order == Continuity::G3 {+ let normal = f.bend * (1.0 / f.bend.len());+ assert!(change.dot(normal).abs() < CHANGE_TOL / (r * r), "station {i}: the change of curvature has a normal part {change:?}");+ }+ } else {+ assert!(bend.len() < CURV_TOL / r, "station {i}: the wall is straight here, the patch curves by {bend:?}");+ if order == Continuity::G3 {+ assert!(change.len() < CHANGE_TOL / (r * r), "station {i}: a straight cross-section changes curvature by {change:?}");+ }+ }+ }+}++/// Two walls 20 mm apart, each leaving towards the other, both walls of the same cylinder of radius+/// `r` (the valley `bridge` is tested with): the two sides of a two-sided patch.+fn two_walls(n: usize, r: f64) -> (Vec<Frame>, Vec<Frame>) {+ let mut a = Vec::new();+ let mut b = Vec::new();+ for t in stations(n) {+ let y = 20.0 * t;+ a.push(Frame {+ p: Vec3::new(0.0, y, 0.0),+ leave: Vec3::new(0.0, 1.0, 0.0),+ bend: Vec3::new(0.0, 0.0, 1.0 / r),+ bend_change: Vec3::new(0.0, -1.0 / (r * r), 0.0),+ });+ b.push(Frame {+ p: Vec3::new(0.0, y + 20.0, 0.0),+ leave: Vec3::new(0.0, -1.0, 0.0),+ bend: Vec3::new(0.0, 0.0, 1.0 / r),+ bend_change: Vec3::new(0.0, 1.0 / (r * r), 0.0),+ });+ }+ (a, b)+}++#[test]+fn a_two_sided_patch_is_a_bridge_that_holds_both_ends() {+ let n = 9;+ let r = 10.0;+ let (a, b) = two_walls(n, r);+ let boundaries = vec![Boundary { frames: a.clone(), order: Continuity::G2 }, Boundary { frames: b.clone(), order: Continuity::G2 }];+ let body = boundary_patch(&boundaries, 0.0, n).unwrap();+ let s = stations(n);+ check_side(&body, &a, Continuity::G2, |i| ((s[i], 0.0), (0.0, 1.0)), r);+ check_side(&body, &b, Continuity::G2, |i| ((s[i], 1.0), (0.0, -1.0)), r);+}++/// Four chained sides round a 20 × 20 square in the XY plane, each leaving into the square: the+/// loop a patch through three or four boundaries would have to close.+fn square_loop(n: usize) -> Vec<Boundary> {+ let corners = [(0.0_f64, 0.0_f64), (20.0, 0.0), (20.0, 20.0), (0.0, 20.0)];+ let leaves = [Vec3::new(0.0, 1.0, 0.0), Vec3::new(-1.0, 0.0, 0.0), Vec3::new(0.0, -1.0, 0.0), Vec3::new(1.0, 0.0, 0.0)];+ (0..4)+ .map(|side| {+ let (a, b) = (corners[side], corners[(side + 1) % 4]);+ let frames = stations(n)+ .into_iter()+ .map(|t| Frame {+ p: Vec3::new(a.0 + (b.0 - a.0) * t, a.1 + (b.1 - a.1) * t, 0.0),+ leave: leaves[side],+ bend: Vec3::ZERO,+ bend_change: Vec3::ZERO,+ })+ .collect();+ Boundary { frames, order: Continuity::G2 }+ })+ .collect()+}++#[test]+fn a_two_sided_patch_meets_its_walls_up_to_the_curvature() {+ let n = 11;+ let r = 10.0;+ let (a, b) = two_walls(n, r);+ // G0, G1 and G2 are what this patch states: position, tangent plane and curvature across each+ // boundary. (A G3 bridge's third-order rows are `bridge`'s own subject, measured in its tests.)+ for order in [Continuity::G0, Continuity::G1, Continuity::G2] {+ let boundaries = vec![Boundary { frames: a.clone(), order }, Boundary { frames: b.clone(), order }];+ let body = boundary_patch(&boundaries, 0.0, n).unwrap();+ let s = stations(n);+ if order == Continuity::G0 {+ for (i, f) in a.iter().enumerate() {+ let (p, _, _, _) = across(&body, (s[i], 0.0), (0.0, 1.0), 1e-3);+ assert!(p.dist(f.p) < 1e-9, "station {i}: {p:?} vs {:?}", f.p);+ }+ continue;+ }+ check_side(&body, &a, order, |i| ((s[i], 0.0), (0.0, 1.0)), r);+ check_side(&body, &b, order, |i| ((s[i], 1.0), (0.0, -1.0)), r);+ }+}++#[test]+fn a_crown_shapes_the_middle_without_touching_the_boundary_rows() {+ let n = 9;+ let r = 10.0;+ let (a, b) = two_walls(n, r);+ let boundaries = vec![Boundary { frames: a.clone(), order: Continuity::G2 }, Boundary { frames: b.clone(), order: Continuity::G2 }];+ let s = stations(n);+ let mut middles = Vec::new();+ for crown in [-0.5, 0.0, 1.0, 2.0] {+ let body = boundary_patch(&boundaries, crown, n).unwrap();+ let grid = crate::bridge::sample_grid(&body, 9, 9).unwrap();+ middles.push(grid[4][4].z);+ // The interior is the cross-section between the two walls: its middle sits in the gap, not+ // outside it, and it stays finite everywhere on the grid.+ for row in &grid {+ for p in row {+ assert!(p.is_finite() && (-2.0..=42.0).contains(&p.y), "the interior stays between the walls: {p:?}");+ }+ }+ assert!((18.0..=22.0).contains(&grid[4][4].y), "the middle of the patch sits midway in the 20 mm band: {:?}", grid[4][4]);+ // The conditions are untouched: the same boundary points, tangent and curvature.+ check_side(&body, &a, Continuity::G2, |i| ((s[i], 0.0), (0.0, 1.0)), r);+ check_side(&body, &b, Continuity::G2, |i| ((s[i], 1.0), (0.0, -1.0)), r);+ }+ let steps: Vec<f64> = middles.windows(2).map(|w| w[1] - w[0]).collect();+ assert!(steps.iter().all(|d| d.abs() > 1e-9), "a fuller crown moves the middle: {middles:?}");+}++#[test]+fn the_patch_refuses_what_it_cannot_hold() {+ let n = 9;+ let (a, b) = two_walls(n, 10.0);+ let two = vec![Boundary { frames: a.clone(), order: Continuity::G2 }, Boundary { frames: b.clone(), order: Continuity::G2 }];+ // Not 2 to 4 boundaries.+ assert!(boundary_patch(&[], 0.0, n).is_err());+ assert!(boundary_patch(&two[..1], 0.0, n).is_err());+ let five = vec![two[0].clone(), two[1].clone(), two[0].clone(), two[1].clone(), two[0].clone()];+ assert!(boundary_patch(&five, 0.0, n).is_err());+ // Three or four sides are refused: a tensor-product patch cannot hold two sides' data at a+ // corner, which needs a Gregory-type corner (issue #763). The message says so.+ let square = square_loop(n);+ let e = boundary_patch(&square, 0.0, n).unwrap_err().to_string();+ assert!(e.contains("not supported yet") && e.contains("#763"), "4 sides: {e}");+ // Three sides that do close: a triangle, whose last side runs from the second one's end back to+ // the first one's start.+ let triangle: Vec<Boundary> = vec![+ square[0].clone(),+ square[1].clone(),+ Boundary {+ frames: stations(n)+ .into_iter()+ .map(|t| Frame {+ p: Vec3::new(20.0 * (1.0 - t), 20.0 * (1.0 - t), 0.0),+ leave: Vec3::new(-std::f64::consts::FRAC_1_SQRT_2, -std::f64::consts::FRAC_1_SQRT_2, 0.0),+ bend: Vec3::ZERO,+ bend_change: Vec3::ZERO,+ })+ .collect(),+ order: Continuity::G2,+ },+ ];+ let e = boundary_patch(&triangle, 0.0, n).unwrap_err().to_string();+ assert!(e.contains("not supported yet") && e.contains("#763"), "3 sides: {e}");+ // A loop whose sides do not even meet is refused earlier and for its own reason.+ let broken = square_loop(n);+ let mut moved = broken[1].frames.clone();+ moved[0] = Frame { p: Vec3::new(30.0, 0.0, 0.0), ..moved[0] };+ let broken = vec![broken[0].clone(), Boundary { frames: moved, order: Continuity::G2 }, broken[2].clone()];+ let e = boundary_patch(&broken, 0.0, n).unwrap_err().to_string();+ assert!(e.contains("run on into one another"), "{e}");+ // The stations and the crown.+ let short = vec![Boundary { frames: a[..n - 1].to_vec(), order: Continuity::G2 }, two[1].clone()];+ assert!(boundary_patch(&short, 0.0, n).is_err(), "a boundary with the wrong number of stations");+ assert!(boundary_patch(&two, 0.0, n - 1).is_err());+ assert!(boundary_patch(&two, 0.0, 1).is_err());+ for crown in [-1.5, 3.5, f64::NAN, f64::INFINITY] {+ assert!(boundary_patch(&two, crown, n).is_err(), "crown {crown}");+ }+ // A station that is not finite, and a station with no leave direction.+ for field in 0..4 {+ let mut bad = two.clone();+ let mut frames = bad[0].frames.clone();+ frames[3] = match field {+ 0 => Frame { p: Vec3::new(f64::NAN, 0.0, 0.0), ..frames[3] },+ 1 => Frame { leave: Vec3::new(f64::NAN, 0.0, 0.0), ..frames[3] },+ 2 => Frame { bend: Vec3::new(f64::INFINITY, 0.0, 0.0), ..frames[3] },+ _ => Frame { bend_change: Vec3::new(f64::NAN, 0.0, 0.0), ..frames[3] },+ };+ if let Some(b) = bad.first_mut() {+ b.frames = frames;+ }+ assert!(boundary_patch(&bad, 0.0, n).is_err(), "a station that is not finite: field {field}");+ }+ let mut flat = two.clone();+ if let Some(b) = flat.first_mut() {+ b.frames = vec![Frame { p: Vec3::new(0.0, 1.0, 0.0), leave: Vec3::ZERO, bend: Vec3::ZERO, bend_change: Vec3::ZERO }; n];+ }+ assert!(boundary_patch(&flat, 0.0, n).is_err(), "a station with no leave direction");+ let point = vec![+ Boundary {+ frames: vec![Frame { p: Vec3::new(1.0, 1.0, 1.0), leave: Vec3::X, bend: Vec3::ZERO, bend_change: Vec3::ZERO }; n],+ order: Continuity::G1,+ },+ Boundary {+ frames: vec![Frame { p: Vec3::new(1.0, 1.0, 1.0), leave: Vec3::X, bend: Vec3::ZERO, bend_change: Vec3::ZERO }; n],+ order: Continuity::G1,+ },+ ];+ assert!(boundary_patch(&point, 0.0, n).is_err(), "a boundary with no length");+}diff --git a/crates/kernel/src/fair.rs b/crates/kernel/src/fair.rsnew file mode 100644index 0000000000..d8b4a0bbc3--- /dev/null+++ b/crates/kernel/src/fair.rs@@ -0,0 +1,1538 @@+//! Fairing the control points of a B-spline curve or surface: moving the interior control+//! vertices to the least-bending shape while the ends, or the boundary rows, stay exactly where+//! the design put them.+//!+//! The fairness energy is the thin-plate (curvature-variation) energy of the *geometry* the+//! control net describes, in the net's own parameter directions:+//!+//! - a curve: `E = ∫‖C″(t)‖² dt`,+//! - a surface: `E = ∫∫ ‖S_uu‖² + 2‖S_uv‖² + ‖S_vv‖² du dv`.+//!+//! A plane has energy zero and anything else pays for how much it bends, which is what a+//! designer means by "fair". Both energies are quadratic in the control points, `E(P) = Pᵀ·G·P`,+//! with `G` the Gram matrix of the basis functions' derivatives (`Gᵢⱼ = ∫Nᵢ″Nⱼ″ dt`, and the+//! tensor products of the one-direction Gram matrices for a surface). Each one-direction Gram is+//! integrated span by span with four-point Gauss–Legendre, exact to degree 7 — a cubic's second+//! derivative products are quadratic, so the cubic curves and bicubic faces fairing meets in+//! practice are integrated exactly.+//!+//! One fairing step is then a constrained least-squares solve: hold the boundary control points,+//! take the exact minimiser of `E` over the interior (for a quadratic that is one Newton step,+//! `G_ff·d = −(G·P)_f`), and apply a fraction `strength` of it, so `strength = 1` is the full+//! solution and a smaller value walks towards it. With the exact step the energy falls by+//! `q·s·(1 − s)` for `q ≥ 0`, so a run at any strength decreases it strictly until it converges.+//! `G_ff` does not change as the control points move, so it is factorised once, by banded+//! Cholesky, and every further step is a matrix–vector product and a triangular solve.+//!+//! Two guarantees are built in rather than checked afterwards:+//!+//! - **The boundary never moves.** The result starts as a copy of the input and only interior+//! entries are written, so a held control point is bit-identical to the one the design gave.+//! - **The geometry cannot jump.** A B-spline lies in the convex hull of its control points+//! (NURBS Book §3.1; with the weights unchanged the rational basis functions are still+//! non-negative and sum to one), so the geometry moves at most as far as the farthest control+//! point. Every step is clamped so that no control point leaves the ball of radius+//! `tolerance` about where it started: the faired curve or surface is then within `tolerance`+//! of the input at the same parameters, by a bound rather than by measurement. A step that+//! would not lower the energy is halved and, if it still would not, the run stops — it never+//! loops for ever and never moves the design further than the caller allowed.+//!+//! Everything is checked before it is used: degrees, knot vectors and counts must be consistent,+//! the control points finite, `strength ∈ (0, 1]`, `iterations` in `1…`[`MAX_FAIR_ITERATIONS`] and+//! `tolerance > 0`. A singular system — fewer than two interior control points, or an interior+//! control point that does not change the geometry at all — is reported as an error and the+//! geometry is left alone.++use solidcraft_geom::Vec3;+use solidcraft_geom::bspline::{HPoint, MAX_SPLINE_DEGREE, NurbsSurface, Side, SplineError, check_knots, local_basis};+use truck_modeling as mt;++use crate::body::Body;+use crate::history::Change;+use crate::{KernelError, Result, guard};++/// Most steps one fairing run takes (see [`FairOptions::iterations`]).+pub const MAX_FAIR_ITERATIONS: usize = 1000;+/// Most control points one fairing run accepts (a 64 × 64 net): plenty for any face's control+/// net, and small enough that a step stays cheap whatever a design file contains.+pub const MAX_FAIR_POINTS: usize = 4096;+/// Most entries of the banded system (2²¹ doubles, 16 MB).+const MAX_FAIR_BAND: usize = 1 << 21;+/// The fairness energy of a curve, as a one-direction net: the `(order in u, order in v, weight)`+/// term list of `∫∫ (∂S)²`.+const CURVE_ENERGY: [(usize, usize, f64); 1] = [(2, 0, 1.0)];+/// The thin-plate energy of a surface: `‖S_uu‖² + 2‖S_uv‖² + ‖S_vv‖²` — the classic+/// curvature-variation energy, zero on a plane and the same if u and v are swapped.+const SURFACE_ENERGY: [(usize, usize, f64); 3] = [(2, 0, 1.0), (1, 1, 2.0), (0, 2, 1.0)];+/// Four-point Gauss–Legendre nodes and weights on `[−1, 1]` (exact to degree 7).+const GAUSS4: [(f64, f64); 4] = [+ (-0.861_136_311_594_052_6, 0.347_854_845_137_453_8),+ (-0.339_981_043_584_856_3, 0.652_145_154_862_546_2),+ (0.339_981_043_584_856_3, 0.652_145_154_862_546_2),+ (0.861_136_311_594_052_6, 0.347_854_845_137_453_8),+];+/// The second direction of a curve seen as a control net: one basis function of degree 0 over+/// `[0, 1]`, whose Gram entry is exactly `∫1 dt = 1`, so the net's energy is the curve's own+/// energy unchanged.+const TRIVIAL_KNOTS: [f64; 2] = [0.0, 1.0];+/// How often a step is halved before the run calls the point converged.+const MAX_HALVINGS: u32 = 40;+/// A step smaller than this fraction of the full Newton step is not worth taking.+const MIN_STEP: f64 = 1e-12;+/// Steps are clamped this far inside the tolerance, so rounding cannot push a control point+/// past it.+const TOLERANCE_SLACK: f64 = 1.0 - 1e-12;++/// How a fairing run is asked to behave.+#[derive(Clone, Copy, Debug, PartialEq)]+pub struct FairOptions {+ /// The fraction of each energy step to apply, `0 < strength ≤ 1`: `1` is the full least+ /// squares solution (the exact minimiser of the energy at the held boundary), a smaller+ /// value takes that fraction of the way there. The energy falls at every step either way.+ pub strength: f64,+ /// How many steps at most, one to [`MAX_FAIR_ITERATIONS`].+ pub iterations: usize,+ /// Hold the layer of control points next to the boundary as well as the boundary itself (two+ /// layers held at each end). For a clamped knot vector the boundary row fixes the position+ /// along the edge and the row next to it fixes the derivative across the edge, so with this+ /// set the boundary keeps the position and the tangent the design gave it.+ pub keep_edges: bool,+ /// The farthest a control point may move from where the design put it, in mm. The geometry+ /// then stays within this distance of the input at the same parameters (see the module+ /// docs), so a fairing run can never make a design jump.+ pub tolerance: f64,+}++impl FairOptions {+ /// Checked options for one fairing run: an error, never a panic, for a strength outside+ /// `(0, 1]`, zero iterations, more than [`MAX_FAIR_ITERATIONS`] of them, or a tolerance that+ /// is not a positive finite number.+ pub fn new(strength: f64, iterations: usize, keep_edges: bool, tolerance: f64) -> Result<FairOptions> {+ FairOptions { strength, iterations, keep_edges, tolerance }.checked()+ }++ /// The same checks as [`FairOptions::new`], for options built field by field.+ pub fn checked(self) -> Result<FairOptions> {+ if !(self.strength.is_finite() && self.strength > 0.0 && self.strength <= 1.0) {+ return Err(KernelError::Invalid(format!("the fairing strength {} must be greater than 0 and at most 1", self.strength)));+ }+ if self.iterations == 0 || self.iterations > MAX_FAIR_ITERATIONS {+ return Err(KernelError::Invalid(format!("{} fairing iterations (1 to {MAX_FAIR_ITERATIONS})", self.iterations)));+ }+ if !(self.tolerance.is_finite() && self.tolerance > 0.0) {+ return Err(KernelError::Invalid(format!("the fairing tolerance {} must be a positive number of mm", self.tolerance)));+ }+ Ok(self)+ }+}++impl Default for FairOptions {+ /// One full step with the boundary held, at most 1 mm of movement: the defaults a command can+ /// start from before a user picks their own.+ fn default() -> Self {+ FairOptions { strength: 1.0, iterations: 1, keep_edges: false, tolerance: 1.0 }+ }+}++/// What a fairing run did: the energy before and after, how many steps were applied, how far the+/// control points moved and the energy after every applied step. The energy is a sum of squares,+/// so where rounding leaves it a hair below zero the true value is zero: it is reported as zero.+#[derive(Clone, Debug, PartialEq)]+pub struct FairReport {+ /// The fairness energy of the input, in the parameter units of the net's own knots.+ pub energy_before: f64,+ /// The fairness energy of the result: never more than `energy_before`, and equal to it only+ /// when no step could lower it.+ pub energy_after: f64,+ /// How many steps were applied (at most the requested `iterations`).+ pub steps: usize,+ /// The farthest any control point moved from where the design put it, in mm. It bounds how+ /// far the geometry moved from the input (see the module docs) and never exceeds the+ /// requested tolerance.+ pub movement: f64,+ /// The energy after each applied step, the last equal to `energy_after`: it never rises, and+ /// falls strictly at every step until the run reaches the rounding of its own arithmetic.+ pub energy_trace: Vec<f64>,+}++/// A faired B-spline curve: the input's degree and knots, the moved control points and the run's+/// report.+#[derive(Clone, Debug, PartialEq)]+pub struct FairCurve<const N: usize> {+ pub degree: usize,+ pub knots: Vec<f64>,+ /// The faired control points; the ends (and, with `keep_edges`, the points next to them) are+ /// bit-identical to the input.+ pub ctrl: Vec<[f64; N]>,+ pub report: FairReport,+}++/// A faired B-spline control net: the input's degrees, knots and counts, the moved control points+/// (u fastest) and the run's report.+#[derive(Clone, Debug, PartialEq)]+pub struct FairNet<const N: usize> {+ pub degree: [usize; 2],+ pub knots: [Vec<f64>; 2],+ pub count: [usize; 2],+ /// The faired control points, u fastest; the held boundary layers are bit-identical to the+ /// input.+ pub ctrl: Vec<[f64; N]>,+ pub report: FairReport,+}++/// A geom spline error as the kernel's.+fn spline_error(what: &str, e: SplineError) -> KernelError {+ match e {+ SplineError::TooLarge(m) => KernelError::TooLarge(format!("{what}: {m}")),+ other => KernelError::Invalid(format!("{what}: {other}")),+ }+}++/// The dot product of two control points' coordinate vectors.+fn dot<const N: usize>(a: &[f64; N], b: &[f64; N]) -> f64 {+ a.iter().zip(b).map(|(x, y)| x * y).sum()+}++/// The distance between two control points.+fn dist<const N: usize>(a: &[f64; N], b: &[f64; N]) -> f64 {+ let d: [f64; N] = std::array::from_fn(|c| a[c] - b[c]);+ dot(&d, &d).sqrt()+}++/// The Gram matrices of one parameter direction, stored banded: entry `r` is+/// `∫ Nᵢ^{(r)}(t)·Nₖ^{(r)}(t) dt` over the direction's domain, and since a basis function+/// overlaps only its `degree` neighbours an entry is non-zero only for `|i − k| ≤ degree`, so+/// the whole thing is `count·(degree + 1)` numbers per order.+struct Gram {+ count: usize,+ bw: usize,+ g: [Vec<f64>; 3],+}++impl Gram {+ /// The Gram matrices of `count` basis functions of `degree` over `knots`, for orders 0, 1 and+ /// 2 — the derivatives a thin-plate energy is built from.+ fn new(degree: usize, knots: &[f64], count: usize) -> Result<Gram> {+ let bw = degree;+ let mut g: [Vec<f64>; 3] = std::array::from_fn(|_| vec![0.0; count * (bw + 1)]);+ // On the span `[knots[s], knots[s + 1])` only the basis functions `i ∈ [s − degree, s]`+ // are non-zero. The quadrature nodes lie strictly inside the span, so either one-sided+ // limit gives the same value there.+ let mut ders = [[0.0f64; 3]; MAX_SPLINE_DEGREE + 1];+ for s in degree..count {+ let (Some(&a), Some(&b)) = (knots.get(s), knots.get(s + 1)) else { continue };+ if !(b > a) {+ continue;+ }+ for &(x, w) in GAUSS4.iter() {+ let t = 0.5 * (a + b) + 0.5 * (b - a) * x;+ let first = s - degree;+ let mut live = 0usize;+ for i in first..=s {+ let Some(local) = knots.get(i..=i + degree + 1) else { break };+ let d = local_basis(local, t, Side::Right, 2);+ if let Some(slot) = ders.get_mut(live) {+ for (o, v) in slot.iter_mut().zip(d.iter()) {+ *o = *v;+ }+ }+ live += 1;+ }+ let weight = 0.5 * (b - a) * w;+ let value = |rel: usize, r: usize| ders.get(rel).and_then(|d| d.get(r)).copied().unwrap_or(0.0);+ // The upper triangle only — the band holds one copy of a symmetric entry — and at+ // the basis functions' own indices, not their places in this span.+ for i in 0..live {+ for k in i..live {+ let (row, off) = (first + i, k - i);+ for (r, gg) in g.iter_mut().enumerate() {+ if let Some(slot) = gg.get_mut(row * (bw + 1) + off) {+ *slot += weight * value(i, r) * value(k, r);+ }+ }+ }+ }+ }+ }+ if g.iter().flatten().any(|v| !v.is_finite()) {+ return Err(KernelError::Invalid("the fairness energy of this net is not a finite number".into()));+ }+ Ok(Gram { count, bw, g })+ }++ /// `∫ Nᵢ^{(r)} Nₖ^{(r)} dt`, zero outside the band or off the end of the basis.+ fn at(&self, r: usize, i: usize, k: usize) -> f64 {+ let Some(m) = self.g.get(r) else { return 0.0 };+ let (row, off) = if i <= k { (i, k - i) } else { (k, i - k) };+ if off > self.bw || row >= self.count {+ return 0.0;+ }+ m.get(row * (self.bw + 1) + off).copied().unwrap_or(0.0)+ }+}++/// A control net to fair: a tensor-product B-spline with the terms of its fairness energy. A+/// direction of one control point (degree 0, knots `[0, 1]`) makes the net a curve, whose energy+/// is the one-direction [`CURVE_ENERGY`].+struct Net {+ degree: [usize; 2],+ count: [usize; 2],+ /// The number of control points, `count[0] · count[1]`.+ total: usize,+ gram: [Gram; 2],+ terms: &'static [(usize, usize, f64)],+}++impl Net {+ /// Check the degrees, knots and counts and build the Gram matrices: an error, never a panic,+ /// for a degree above [`MAX_SPLINE_DEGREE`], too few control points for the degree, a knot+ /// vector of the wrong length, unusable knots or an empty parameter range.+ fn new(degree: [usize; 2], knots: [Vec<f64>; 2], count: [usize; 2], terms: &'static [(usize, usize, f64)]) -> Result<Net> {+ let Some(total) = count[0].checked_mul(count[1]).filter(|&n| n <= MAX_FAIR_POINTS) else {+ return Err(KernelError::TooLarge(format!("fairing {} × {} control points (at most {MAX_FAIR_POINTS} in all)", count[0], count[1])));+ };+ for d in 0..2 {+ let (p, c, kn) = (degree[d], count[d], &knots[d]);+ if p > MAX_SPLINE_DEGREE {+ return Err(KernelError::TooLarge(format!("fairing a spline of degree {p} (at most {MAX_SPLINE_DEGREE})")));+ }+ if c <= p {+ return Err(KernelError::Invalid(format!("{c} control points is too few across one direction of a spline of degree {p}")));+ }+ if kn.len() != c + p + 1 {+ return Err(KernelError::Invalid(format!(+ "{} knots across one direction, expected {} for {c} control points of degree {p}",+ kn.len(),+ c + p + 1+ )));+ }+ check_knots(kn).map_err(|e| spline_error("fairing", e))?;+ let (lo, hi) = (kn.get(p).copied().unwrap_or(f64::NAN), kn.get(c).copied().unwrap_or(f64::NAN));+ if !(lo < hi) {+ return Err(KernelError::Invalid("the fairing's parameter range is empty".into()));+ }+ }+ if terms.iter().any(|&(ru, rv, w)| ru > degree[0] || rv > degree[1] || !(w.is_finite() && w >= 0.0)) {+ return Err(KernelError::Invalid("a fairness term does not fit the net's degrees".into()));+ }+ let gram = [Gram::new(degree[0], &knots[0], count[0])?, Gram::new(degree[1], &knots[1], count[1])?];+ Ok(Net { degree, count, total, gram, terms })+ }++ /// The index of control point `(i, j)` in the flattened net (u fastest).+ fn index(&self, i: usize, j: usize) -> usize {+ j * self.count[0] + i+ }++ /// The fairness energy `Pᵀ·G·P` of the net `ctrl` (u fastest) and, in `grad`, `G·P`. One+ /// banded sweep gives both, since `E = Σ Pₚ·(G·P)ₚ`.+ fn energy_gradient<const N: usize>(&self, ctrl: &[[f64; N]], grad: &mut [[f64; N]]) -> f64 {+ let [cu, cv] = self.count;+ let (pu, pv) = (self.degree[0], self.degree[1]);+ let mut energy = 0.0;+ for j in 0..cv {+ for i in 0..cu {+ let mut acc = [0.0f64; N];+ for &(ru, rv, w) in self.terms {+ for l in j.saturating_sub(pv)..=(j + pv).min(cv - 1) {+ for k in i.saturating_sub(pu)..=(i + pu).min(cu - 1) {+ let a = w * self.gram[0].at(ru, i, k) * self.gram[1].at(rv, j, l);+ if a == 0.0 {+ continue;+ }+ if let Some(p) = ctrl.get(self.index(k, l)) {+ for (x, v) in acc.iter_mut().zip(p) {+ *x += a * v;+ }+ }+ }+ }+ }+ let at = self.index(i, j);+ if let Some(c) = ctrl.get(at) {+ energy += dot(c, &acc);+ }+ if let Some(g) = grad.get_mut(at) {+ *g = acc;+ }+ }+ }+ energy+ }++ /// The energy matrix `G` over the interior control points, banded and already factorised (the+ /// matrix does not change as the control points move, so one factorisation serves every+ /// step). In the u-fastest order two unknowns couple within `degree_u + degree_v · cols`:+ /// `degree_u` along a row, `degree_v` rows apart.+ fn system(&self, interior: &Interior) -> Result<Band> {+ let [cu, cv] = self.count;+ let (pu, pv) = (self.degree[0], self.degree[1]);+ let rows = if cv > 1 { interior.rows.saturating_sub(1).min(pv) } else { 0 };+ let mut band = Band::new(interior.points.len(), pu + rows * interior.cols)?;+ for (r, &at) in interior.points.iter().enumerate() {+ let (i, j) = (at % cu, at / cu);+ for &(ru, rv, w) in self.terms {+ for l in j.saturating_sub(pv)..=(j + pv).min(cv - 1) {+ for k in i.saturating_sub(pu)..=(i + pu).min(cu - 1) {+ let Some(s) = interior.slot.get(self.index(k, l)).copied().flatten() else { continue };+ band.add(r, s, w * self.gram[0].at(ru, i, k) * self.gram[1].at(rv, j, l));+ }+ }+ }+ }+ band.factorised()+ }++ /// Fair `ctrl` (u fastest) with checked `opts`: see the module docs. The result is the input+ /// with the interior control points moved; the held ones are bit-identical.+ fn fair<const N: usize>(&self, ctrl: &[[f64; N]], opts: &FairOptions) -> Result<(Vec<[f64; N]>, FairReport)> {+ if ctrl.len() != self.total {+ return Err(KernelError::Invalid(format!("{} control points, expected {}", ctrl.len(), self.total)));+ }+ if ctrl.iter().flatten().any(|x| !x.is_finite()) {+ return Err(KernelError::Invalid("a control point is not a finite number".into()));+ }+ let interior = Interior::new(self, if opts.keep_edges { 2 } else { 1 })?;+ let system = self.system(&interior)?;+ let mut current: Vec<[f64; N]> = ctrl.to_vec();+ let mut grad = vec![[0.0; N]; self.total];+ let energy_before = self.energy_gradient(¤t, &mut grad);+ if !energy_before.is_finite() {+ return Err(KernelError::Invalid("the fairness energy of this net is not a finite number".into()));+ }+ // The energy is a sum of squares, so where rounding leaves it a hair below zero the true+ // value is zero: report it that way rather than as a negative number.+ let energy_before = energy_before.max(0.0);+ // How big the net itself is, for telling a fairing step from rounding (see below).+ let size = interior.size(ctrl);+ let mut step = vec![[0.0; N]; interior.points.len()];+ let mut b = vec![0.0; interior.points.len()];+ let mut report = FairReport { energy_before, energy_after: energy_before, steps: 0, movement: 0.0, energy_trace: Vec::new() };+ for _ in 0..opts.iterations {+ let e_now = self.energy_gradient(¤t, &mut grad);+ if !e_now.is_finite() {+ break;+ }+ // The exact minimiser over the interior is the Newton step `G_ff·d = −(G·P)_f`; the+ // system is per coordinate, all three sharing the one factorisation.+ for c in 0..N {+ for (slot, &at) in interior.points.iter().enumerate() {+ b[slot] = -grad.get(at).and_then(|g| g.get(c)).copied().unwrap_or(0.0);+ }+ system.solve(&mut b)?;+ for (slot, v) in b.iter().enumerate() {+ if let Some(d) = step.get_mut(slot).and_then(|d| d.get_mut(c)) {+ *d = *v;+ }+ }+ }+ if step.iter().flatten().all(|&x| x == 0.0) {+ break;+ }+ // The largest fraction of the step that keeps every control point within the+ // tolerance of where the design put it, and never more than the whole step.+ let mut s = opts.strength.min(interior.limit(ctrl, ¤t, &step, opts.tolerance));+ if !(s > 0.0) {+ break;+ }+ // A step this much shorter than the net's own size cannot be told from the rounding+ // of the arithmetic that found it: the net is as fair as it gets.+ let longest = step.iter().flatten().fold(0.0f64, |m, x| m.max(x.abs()));+ if s * longest <= MIN_STEP * size {+ break;+ }+ let mut taken = false;+ for _ in 0..MAX_HALVINGS {+ let candidate = interior.apply(¤t, &step, s);+ let e = self.energy_gradient(&candidate, &mut grad);+ if e < e_now {+ current = candidate;+ report.steps += 1;+ report.energy_trace.push(e.max(0.0));+ taken = true;+ break;+ }+ // The step did not lower the energy: halve it and try again, and when even a hair+ // of a step will not, this is as fair as the net gets.+ s *= 0.5;+ if s <= MIN_STEP {+ break;+ }+ }+ if !taken {+ break;+ }+ }+ report.energy_after = report.energy_trace.last().copied().unwrap_or(energy_before);+ report.movement = interior.movement(ctrl, ¤t);+ Ok((current, report))+ }+}++/// Which control points a fairing run may move, and where each sits in the banded system.+struct Interior {+ /// The flattened index (u fastest) of interior point number `k`.+ points: Vec<usize>,+ /// The interior number of each flattened index, `None` where the point is held.+ slot: Vec<Option<usize>>,+ /// How many control points across u (`cols`) and across v (`rows`) are interior.+ cols: usize,+ rows: usize,+}++impl Interior {+ /// The interior of `net` with `keep` layers held at each end of each direction (1 without+ /// [`FairOptions::keep_edges`], 2 with it).+ fn new(net: &Net, keep: usize) -> Result<Interior> {+ let [cu, cv] = net.count;+ let (i0, i1) = free_span(cu, keep)?;+ let (j0, j1) = free_span(cv, keep)?;+ let (cols, rows) = (i1 - i0, j1 - j0);+ let mut points = Vec::with_capacity(cols * rows);+ let mut slot = vec![None; net.total];+ for j in j0..j1 {+ for i in i0..i1 {+ if let Some(s) = slot.get_mut(net.index(i, j)) {+ *s = Some(points.len());+ }+ points.push(net.index(i, j));+ }+ }+ if points.len() < 2 {+ return Err(KernelError::Invalid(format!(+ "fairing needs at least two interior control points; this {cu} × {cv} net has {}",+ points.len()+ )));+ }+ Ok(Interior { points, slot, cols, rows })+ }++ /// `current` with `s` times the step `d` added to the interior control points; the held ones+ /// are copied as they are, bit for bit.+ fn apply<const N: usize>(&self, current: &[[f64; N]], d: &[[f64; N]], s: f64) -> Vec<[f64; N]> {+ let mut out = current.to_vec();+ for (slot, &at) in self.points.iter().enumerate() {+ let (Some(p), Some(v)) = (out.get_mut(at), d.get(slot)) else { continue };+ for (x, dx) in p.iter_mut().zip(v) {+ *x += s * dx;+ }+ }+ out+ }++ /// How big the interior is: the farthest interior control point from the first one, in mm.+ /// A fairing step far below this belongs to the rounding of the arithmetic, not the design.+ fn size<const N: usize>(&self, ctrl: &[[f64; N]]) -> f64 {+ let Some(first) = self.points.first().and_then(|&at| ctrl.get(at)) else { return 0.0 };+ self.points.iter().fold(0.0f64, |m, &at| ctrl.get(at).map_or(m, |p| m.max(dist(first, p))))+ }++ /// The largest fraction `s ≤ 1` of the step `d` that keeps every interior control point+ /// within `tolerance` of where the design put it (`input`). The movement is `‖Δ + s·d‖ ≤ tol`+ /// per point — a quadratic in `s` opening upwards, with the accumulated movement+ /// `Δ = current − input` already inside the ball, so the bound is its positive root.+ fn limit<const N: usize>(&self, input: &[[f64; N]], current: &[[f64; N]], d: &[[f64; N]], tolerance: f64) -> f64 {+ let mut s = 1.0f64;+ for (slot, &at) in self.points.iter().enumerate() {+ let (Some(dv), Some(cv), Some(iv)) = (d.get(slot), current.get(at), input.get(at)) else { continue };+ let a = dot(dv, dv);+ if a <= 0.0 {+ continue;+ }+ let delta: [f64; N] = std::array::from_fn(|c| cv[c] - iv[c]);+ let b = 2.0 * dot(&delta, dv);+ let c = dot(&delta, &delta) - tolerance * tolerance;+ let disc = b * b - 4.0 * a * c;+ let root = if disc >= 0.0 { (-b + disc.sqrt()) / (2.0 * a) } else { 0.0 };+ // `f64::max` ignores a NaN, so a step whose arithmetic overflows stops the run+ // instead of leaking a not-a-number into a control point.+ s = s.min(root.max(0.0));+ }+ (s * TOLERANCE_SLACK).clamp(0.0, 1.0)+ }++ /// The farthest any interior control point moved from the design's own position, in mm.+ fn movement<const N: usize>(&self, input: &[[f64; N]], current: &[[f64; N]]) -> f64 {+ self.points.iter().fold(0.0f64, |m, &at| match (input.get(at), current.get(at)) {+ (Some(a), Some(b)) => m.max(dist(a, b)),+ _ => m,+ })+ }+}++/// The control points of one direction a fairing run may move, as `[lo, hi)`. A direction of one+/// control point — a curve seen as a net one row deep — is all interior; otherwise `keep` layers+/// are held at each end: the boundary, and with `keep = 2` the layer next to it.+fn free_span(count: usize, keep: usize) -> Result<(usize, usize)> {+ if count == 1 {+ return Ok((0, 1));+ }+ if count <= 2 * keep {+ return Err(KernelError::Invalid(format!(+ "fairing a net {count} control points across one direction and holding {keep} at each edge leaves nothing to move"+ )));+ }+ Ok((keep, count - keep))+}++/// A symmetric banded matrix in upper-triangular form: row `r` holds columns `r ..= r + bw`.+struct Band {+ n: usize,+ bw: usize,+ /// The upper band, `n · (bw + 1)` numbers; the scaling by the largest diagonal is folded in+ /// when the matrix is factorised.+ a: Vec<f64>,+ scale: f64,+}++impl Band {+ fn new(n: usize, bw: usize) -> Result<Band> {+ let Some(len) = (bw + 1).checked_mul(n).filter(|&l| l <= MAX_FAIR_BAND) else {+ return Err(KernelError::TooLarge(format!("a fairing system of {n} unknowns {bw} apart")));+ };+ Ok(Band { n, bw, a: vec![0.0; len], scale: 1.0 })+ }++ fn index(&self, r: usize, s: usize) -> Option<usize> {+ let (r, s) = if r <= s { (r, s) } else { (s, r) };+ (s - r <= self.bw && s < self.n).then_some(r * (self.bw + 1) + (s - r))+ }++ fn get(&self, r: usize, s: usize) -> f64 {+ self.index(r, s).and_then(|i| self.a.get(i)).copied().unwrap_or(0.0)+ }++ fn set(&mut self, r: usize, s: usize, v: f64) {+ if let Some(x) = self.index(r, s).and_then(|i| self.a.get_mut(i)) {+ *x = v;+ }+ }++ /// Add `v` at `(r, s)`. Only `r ≤ s` is stored (the matrix is symmetric, so callers adding a+ /// whole symmetric neighbourhood reach each stored entry once).+ fn add(&mut self, r: usize, s: usize, v: f64) {+ if r <= s+ && let Some(x) = self.index(r, s).and_then(|i| self.a.get_mut(i))+ {+ *x += v;+ }+ }++ /// `A = Uᵀ·U` in place, the entries scaled by the largest diagonal first (the scaling does+ /// not change the solution, only the size of the pivots, so a net whose knots span microns or+ /// kilometres factorises just as well). An error, never a panic, when a pivot is not+ /// positive: the system is singular there and the geometry must not move.+ fn factorised(mut self) -> Result<Band> {+ let (n, bw) = (self.n, self.bw);+ let scale = (0..n).fold(0.0f64, |m, r| m.max(self.get(r, r).abs()));+ if !(scale > 0.0) || !scale.is_finite() {+ return Err(KernelError::Invalid("the fairness energy does not depend on any interior control point: nothing to fair".into()));+ }+ self.scale = scale;+ for v in self.a.iter_mut() {+ *v /= scale;+ }+ for r in 0..n {+ let mut d = self.get(r, r);+ for k in r.saturating_sub(bw)..r {+ let u = self.get(k, r);+ d -= u * u;+ }+ if !(d > 0.0) {+ return Err(KernelError::Invalid(+ "the fairing equations are singular (an interior control point that does not move the geometry)".into(),+ ));+ }+ let d = d.sqrt();+ self.set(r, r, d);+ for s in r + 1..(r + bw + 1).min(n) {+ let mut v = self.get(r, s);+ for k in s.saturating_sub(bw)..r {+ v -= self.get(k, r) * self.get(k, s);+ }+ self.set(r, s, v / d);+ }+ }+ Ok(self)+ }++ /// Solve `A·x = b` with the stored factorisation, in place.+ fn solve(&self, b: &mut [f64]) -> Result<()> {+ let (n, bw) = (self.n, self.bw);+ if b.len() != n {+ return Err(KernelError::Invalid(format!("{} fairing unknowns for a system of {n}", b.len())));+ }+ for x in b.iter_mut() {+ *x /= self.scale;+ }+ // Uᵀ·y = b, then U·x = y.+ for r in 0..n {+ let mut v = b.get(r).copied().unwrap_or(0.0);+ for k in r.saturating_sub(bw)..r {+ v -= self.get(k, r) * b.get(k).copied().unwrap_or(0.0);+ }+ if let Some(x) = b.get_mut(r) {+ *x = v / self.get(r, r);+ }+ }+ for r in (0..n).rev() {+ let mut v = b.get(r).copied().unwrap_or(0.0);+ for s in r + 1..(r + bw + 1).min(n) {+ v -= self.get(r, s) * b.get(s).copied().unwrap_or(0.0);+ }+ if let Some(x) = b.get_mut(r) {+ *x = v / self.get(r, r);+ }+ }+ if b.iter().any(|x| !x.is_finite()) {+ return Err(KernelError::Invalid("the fairing step is not a finite number".into()));+ }+ Ok(())+ }+}++/// Fair a B-spline curve's control points of any dimension: hold control points `0` and `n − 1`+/// and (with [`FairOptions::keep_edges`]) those next to them, and move the rest to lower the+/// bending energy `∫‖C″‖² dt` in the curve's own parameter (see the module docs). `N` is 3 for a+/// wire in space, 2 for a sketch curve.+pub fn fair_curve<const N: usize>(degree: usize, knots: &[f64], ctrl: &[[f64; N]], opts: &FairOptions) -> Result<FairCurve<N>> {+ let opts = opts.checked()?;+ let net = Net::new([degree, 0], [knots.to_vec(), TRIVIAL_KNOTS.to_vec()], [ctrl.len(), 1], &CURVE_ENERGY)?;+ let (faired, report) = net.fair(ctrl, &opts)?;+ Ok(FairCurve { degree, knots: knots.to_vec(), ctrl: faired, report })+}++/// Fair the interior of a B-spline control net with the thin-plate energy+/// `∫∫ ‖S_uu‖² + 2‖S_uv‖² + ‖S_vv‖² du dv` in the net's own parameters (see the module docs).+/// `count[0]` control points lie along u and `count[1]` along v, `ctrl` is u fastest, and the+/// boundary layers (see [`FairOptions::keep_edges`]) are held. The generic core behind+/// [`fair_surface`], [`fair_bspline_surface`] and their rational counterparts, for a caller with+/// its own control net.+pub fn fair_net<const N: usize>(+ degree: [usize; 2],+ knots: [&[f64]; 2],+ count: [usize; 2],+ ctrl: &[[f64; N]],+ opts: &FairOptions,+) -> Result<FairNet<N>> {+ let opts = opts.checked()?;+ let net = Net::new(degree, [knots[0].to_vec(), knots[1].to_vec()], count, &SURFACE_ENERGY)?;+ let (faired, report) = net.fair(ctrl, &opts)?;+ Ok(FairNet { degree, knots: [knots[0].to_vec(), knots[1].to_vec()], count, ctrl: faired, report })+}++/// Fair a truck B-spline curve's control points: [`fair_curve`] on its three-dimensional points,+/// rebuilt as a B-spline of the same knots. Guarded here itself, like every call into truck, so a+/// panic inside comes back as an error and the design is left alone.+pub fn fair_bspline_curve(curve: &mt::BSplineCurve<mt::Point3>, opts: &FairOptions) -> Result<(mt::BSplineCurve<mt::Point3>, FairReport)> {+ guard("fair a B-spline curve", || {+ let ctrl: Vec<[f64; 3]> = curve.control_points().iter().map(|p| [p.x, p.y, p.z]).collect();+ let faired = fair_curve(curve.degree(), curve.knot_vec(), &ctrl, opts)?;+ let points: Vec<mt::Point3> = faired.ctrl.iter().map(|c| mt::Point3::new(c[0], c[1], c[2])).collect();+ let curve = mt::BSplineCurve::try_new(mt::KnotVec::from(faired.knots), points).map_err(|e| KernelError::Failed(format!("fair: {e}")))?;+ Ok((curve, faired.report))+ })+}++/// Fair a truck rational curve's control points: its Cartesian control points are faired like any+/// other curve and its weights are kept, so the result is the same rational curve with moved+/// control points. The convex-hull bound that keeps the geometry within the tolerance still+/// holds, because with the weights unchanged the rational basis functions are non-negative and+/// sum to one. Guarded like [`fair_bspline_curve`].+pub fn fair_nurbs_curve(curve: &mt::NurbsCurve<mt::Vector4>, opts: &FairOptions) -> Result<(mt::NurbsCurve<mt::Vector4>, FairReport)> {+ guard("fair a NURBS curve", || {+ let count = curve.control_points().len();+ let mut ctrl = Vec::with_capacity(count);+ let mut weights = Vec::with_capacity(count);+ for h in curve.control_points() {+ let Some(p) = (HPoint { x: h.x, y: h.y, z: h.z, w: h.w }).project() else {+ return Err(KernelError::Invalid("a control point has no position: its weight is zero".into()));+ };+ ctrl.push([p.x, p.y, p.z]);+ weights.push(h.w);+ }+ let faired = fair_curve(curve.degree(), curve.knot_vec(), &ctrl, opts)?;+ let points: Vec<mt::Vector4> = faired.ctrl.iter().zip(&weights).map(|(c, w)| mt::Vector4::new(c[0] * w, c[1] * w, c[2] * w, *w)).collect();+ let bsp = mt::BSplineCurve::try_new(mt::KnotVec::from(faired.knots), points).map_err(|e| KernelError::Failed(format!("fair: {e}")))?;+ Ok((mt::NurbsCurve::new(bsp), faired.report))+ })+}++/// Fair a truck B-spline surface's control net: [`fair_net`] on its points, rebuilt as a B-spline+/// of the same knots, with the boundary rows held. Guarded like [`fair_bspline_curve`].+pub fn fair_bspline_surface(surface: &mt::BSplineSurface<mt::Point3>, opts: &FairOptions) -> Result<(mt::BSplineSurface<mt::Point3>, FairReport)> {+ guard("fair a B-spline surface", || {+ let rows = surface.control_points();+ let count = [rows.len(), rows.first().map_or(0, Vec::len)];+ if count[0] == 0 || count[1] == 0 {+ return Err(KernelError::Invalid("the surface has no control points".into()));+ }+ if rows.iter().any(|r| r.len() != count[1]) {+ return Err(KernelError::Invalid("the surface's control net is not rectangular".into()));+ }+ // truck keeps the net as control_points()[i][j] with i along u; fair_net wants u fastest.+ let mut ctrl = Vec::with_capacity(count[0] * count[1]);+ for j in 0..count[1] {+ for i in 0..count[0] {+ let Some(p) = rows.get(i).and_then(|r| r.get(j)) else { continue };+ ctrl.push([p.x, p.y, p.z]);+ }+ }+ let (ku, kv) = surface.knot_vecs();+ let (pu, pv) = surface.degrees();+ let faired = fair_net([pu, pv], [ku, kv], count, &ctrl, opts)?;+ let mut net: Vec<Vec<mt::Point3>> = Vec::with_capacity(count[0]);+ for i in 0..count[0] {+ let mut row = Vec::with_capacity(count[1]);+ for j in 0..count[1] {+ let Some(c) = faired.ctrl.get(j * count[0] + i) else {+ return Err(KernelError::Failed("fairing lost a control point".into()));+ };+ row.push(mt::Point3::new(c[0], c[1], c[2]));+ }+ net.push(row);+ }+ let surface = mt::BSplineSurface::try_new((ku.clone(), kv.clone()), net).map_err(|e| KernelError::Failed(format!("fair: {e}")))?;+ Ok((surface, faired.report))+ })+}++/// Fair a geom NURBS surface's control net: [`fair_net`] on its Cartesian control points, with+/// the weights kept as they are (a fairing moves points, not weights) and the boundary rows held.+/// A rational surface's geometry then stays within the tolerance too, by the same convex-hull+/// bound as the non-rational case.+pub fn fair_surface(surface: &NurbsSurface, opts: &FairOptions) -> Result<(NurbsSurface, FairReport)> {+ let [cu, cv] = surface.count();+ let mut ctrl = Vec::with_capacity(cu * cv);+ let mut weights = Vec::with_capacity(cu * cv);+ for j in 0..cv {+ for i in 0..cu {+ let h = surface.point(i, j);+ let Some(p) = h.project() else {+ return Err(KernelError::Invalid("a control point has no position: its weight is zero".into()));+ };+ ctrl.push([p.x, p.y, p.z]);+ weights.push(h.w);+ }+ }+ let [ku, kv] = surface.knots();+ let degree = surface.degree();+ let faired = fair_net(degree, [ku, kv], [cu, cv], &ctrl, opts)?;+ let points: Vec<HPoint> = faired.ctrl.iter().zip(&weights).map(|(p, w)| HPoint::weighted(Vec3::new(p[0], p[1], p[2]), *w)).collect();+ let out = NurbsSurface::from_homogeneous(degree, surface.knots().clone(), points).map_err(|e| spline_error("fairing the surface", e))?;+ Ok((out, faired.report))+}++/// Fair a truck rational surface's control net, like [`fair_surface`]: the Cartesian control+/// points are faired, the weights kept, and the result is a NURBS surface of the same knots.+/// Guarded like [`fair_bspline_curve`].+pub fn fair_nurbs_surface(surface: &mt::NurbsSurface<mt::Vector4>, opts: &FairOptions) -> Result<(mt::NurbsSurface<mt::Vector4>, FairReport)> {+ guard("fair a NURBS surface", || {+ let bsp = surface.non_rationalized();+ let rows = bsp.control_points();+ let count = [rows.len(), rows.first().map_or(0, Vec::len)];+ if count[0] == 0 || count[1] == 0 {+ return Err(KernelError::Invalid("the surface has no control points".into()));+ }+ if rows.iter().any(|r| r.len() != count[1]) {+ return Err(KernelError::Invalid("the surface's control net is not rectangular".into()));+ }+ let mut ctrl = Vec::with_capacity(count[0] * count[1]);+ let mut weights = Vec::with_capacity(count[0] * count[1]);+ for j in 0..count[1] {+ for i in 0..count[0] {+ let Some(h) = rows.get(i).and_then(|r| r.get(j)) else { continue };+ let Some(p) = (HPoint { x: h.x, y: h.y, z: h.z, w: h.w }).project() else {+ return Err(KernelError::Invalid("a control point has no position: its weight is zero".into()));+ };+ ctrl.push([p.x, p.y, p.z]);+ weights.push(h.w);+ }+ }+ let (ku, kv) = bsp.knot_vecs();+ let (pu, pv) = bsp.degrees();+ let faired = fair_net([pu, pv], [ku, kv], count, &ctrl, opts)?;+ let mut net: Vec<Vec<mt::Vector4>> = Vec::with_capacity(count[0]);+ for i in 0..count[0] {+ let mut row = Vec::with_capacity(count[1]);+ for j in 0..count[1] {+ let (Some(c), Some(w)) = (faired.ctrl.get(j * count[0] + i), weights.get(j * count[0] + i)) else {+ return Err(KernelError::Failed("fairing lost a control point".into()));+ };+ row.push(mt::Vector4::new(c[0] * w, c[1] * w, c[2] * w, *w));+ }+ net.push(row);+ }+ let bsp = mt::BSplineSurface::try_new((ku.clone(), kv.clone()), net).map_err(|e| KernelError::Failed(format!("fair: {e}")))?;+ Ok((mt::NurbsSurface::new(bsp), faired.report))+ })+}++/// Fair the B-spline faces at `faces` (indices in `body`'s face order) of `body`: each face's+/// interior control vertices move to flatten the thin-plate energy of the face while its boundary+/// rows stay put, so the face keeps meeting its neighbours as it did.+///+/// Every picked face keeps the very wires, edges and vertices it had and the way it pointed: only+/// the surface between them changes, so the body is as closed (or as open) as it was, holes and+/// all. A face that is not a B-spline (a plane, cylinder, cone, sphere, torus or swept face) has no+/// control points to fair and is refused by name; a mesh body has no faces to fair at all.+///+/// The report is over the picked faces together: the energies summed, the largest movement of any+/// control point, and the energy trace as the sum at each step (a face that stops early keeps its+/// last energy for the steps the others still take).+pub fn fair_faces(body: &Body, faces: &[usize], opts: &FairOptions) -> Result<(Body, FairReport)> {+ let opts = opts.checked()?;+ body.require_brep("fair")?;+ let all: Vec<mt::Face> = body.solid.face_iter().cloned().collect();+ if all.is_empty() {+ return Err(KernelError::Invalid("the body has no faces".into()));+ }+ let mut picked: Vec<usize> = Vec::new();+ for &i in faces {+ if i >= all.len() {+ return Err(KernelError::Invalid(format!("no face {i}: the body has {}", all.len())));+ }+ if !picked.contains(&i) {+ picked.push(i);+ }+ }+ if picked.is_empty() {+ return Err(KernelError::Invalid("pick the faces to fair".into()));+ }+ guard("fair faces", || {+ let mut faired = all.clone();+ let mut reports: Vec<FairReport> = Vec::with_capacity(picked.len());+ for &i in &picked {+ let Some(face) = all.get(i) else { continue };+ let (surface, report) = match face.surface() {+ mt::Surface::BSplineSurface(s) => {+ let (faired, report) = fair_bspline_surface(&s, &opts)?;+ (mt::Surface::BSplineSurface(faired), report)+ }+ mt::Surface::NurbsSurface(s) => {+ let (faired, report) = fair_nurbs_surface(&s, &opts)?;+ (mt::Surface::NurbsSurface(faired), report)+ }+ _ => {+ return Err(KernelError::Invalid(format!(+ "face {i} is not a B-spline face: a plane, cylinder, cone, sphere, torus or swept face has no control points to fair"+ )));+ }+ };+ // The same face as before, wires and all, with the faired surface between them.+ let mut nf = mt::Face::new_unchecked(face.absolute_boundaries().clone(), surface);+ if !face.orientation() {+ nf.invert();+ }+ if let Some(slot) = faired.get_mut(i) {+ *slot = nf;+ }+ reports.push(report);+ }+ let report = FairReport {+ energy_before: reports.iter().map(|r| r.energy_before).sum(),+ energy_after: reports.iter().map(|r| r.energy_after).sum(),+ steps: reports.iter().map(|r| r.steps).max().unwrap_or(0),+ movement: reports.iter().fold(0.0f64, |m, r| m.max(r.movement)),+ energy_trace: {+ let longest = reports.iter().map(|r| r.energy_trace.len()).max().unwrap_or(0);+ (0..longest).map(|k| reports.iter().map(|r| r.energy_trace.get(k).copied().unwrap_or(r.energy_after)).sum()).collect()+ },+ };+ // The body shell for shell, in its own face order: a body with holes keeps them.+ let mut shells: Vec<mt::Shell> = Vec::with_capacity(body.solid.boundaries().len());+ let mut index = 0usize;+ for shell in body.solid.boundaries() {+ let mut shell_faces = Vec::with_capacity(shell.face_iter().count());+ for f in shell.face_iter() {+ let i = index;+ index += 1;+ shell_faces.push(faired.get(i).cloned().unwrap_or_else(|| f.clone()));+ }+ shells.push(mt::Shell::from(shell_faces));+ }+ // The topology is the body's own, face for face, so the solid is built as it (the shells+ // are as closed, or as open, as they were) and only the shape is measured anew.+ let mut result = body.clone();+ result.solid = std::sync::Arc::new(mt::Solid::new_unchecked(shells));+ result.size = 0.0;+ result.volume = Some(std::sync::Arc::new(std::sync::Mutex::new(None)));+ result.coarse_missing = None;+ result.history = None;+ let faces: Vec<crate::history::FaceProv> =+ (0..all.len()).map(|i| crate::record::from_face(0, i, if picked.contains(&i) { Change::Modified } else { Change::Kept })).collect();+ let result = crate::record::attach(result, &[crate::record::Operand::new(body)], Some(faces), std::collections::HashMap::new())?;+ Ok((result, report))+ })+}++#[cfg(test)]+mod tests {+ use super::*;+ use mt::ParametricCurve;++ /// A clamped uniform knot vector over `[0, spans]` of degree `degree`: `spans + degree`+ /// control points.+ fn clamped(spans: usize, degree: usize) -> Vec<f64> {+ let mut k = vec![0.0; degree + 1];+ k.extend((1..spans).map(|i| i as f64));+ k.extend(std::iter::repeat_n(spans as f64, degree + 1));+ k+ }++ /// The knot average `(kᵢ₊₁ + … + kᵢ₊ₚ)/p` of control point `i`: `Σ Nᵢ(t)·ξᵢ = t` (NURBS Book+ /// eq. 3.4), so control points at `a + b·ξᵢ` describe the affine curve `a + b·t` exactly.+ fn average(knots: &[f64], degree: usize, i: usize) -> f64 {+ (1..=degree).map(|r| knots.get(i + r).copied().unwrap_or(0.0)).sum::<f64>() / degree as f64+ }++ /// The control points of the affine curve `ξ ↦ a + b·ξ` at the knot averages of `knots`: a+ /// curve of exactly zero bending energy.+ fn affine_curve(knots: &[f64], degree: usize, a: [f64; 3], b: [f64; 3]) -> Vec<[f64; 3]> {+ (0..knots.len() - degree - 1).map(|i| std::array::from_fn(|c| a[c] + b[c] * average(knots, degree, i))).collect()+ }++ /// The control net (u fastest) of the plane `(ξ, η) ↦ a + b·ξ + c·η` at the knot averages of+ /// `ku` and `kv`: a net of exactly zero thin-plate energy.+ fn planar_net(ku: &[f64], kv: &[f64], degree: [usize; 2], a: [f64; 3], b: [f64; 3], c: [f64; 3]) -> Vec<[f64; 3]> {+ let (cu, cv) = (ku.len() - degree[0] - 1, kv.len() - degree[1] - 1);+ let mut net = Vec::with_capacity(cu * cv);+ for j in 0..cv {+ for i in 0..cu {+ let (xi, eta) = (average(ku, degree[0], i), average(kv, degree[1], j));+ net.push(std::array::from_fn(|d| a[d] + b[d] * xi + c[d] * eta));+ }+ }+ net+ }++ /// The point of the curve `(degree, knots, ctrl)` at `t`, through the same basis geom uses: a+ /// basis function `i` owns the `degree + 2` knots `knots[i..=i + degree + 1]`.+ fn curve_at<const N: usize>(degree: usize, knots: &[f64], ctrl: &[[f64; N]], t: f64) -> [f64; N] {+ let n = ctrl.len();+ let side = if t >= knots.get(n).copied().unwrap_or(f64::INFINITY) { Side::Left } else { Side::Right };+ let mut out = [0.0; N];+ for (i, c) in ctrl.iter().enumerate() {+ let b = knots.get(i..=i + degree + 1).and_then(|l| local_basis(l, t, side, 0).first().copied()).unwrap_or(0.0);+ for (o, x) in out.iter_mut().zip(c) {+ *o += b * x;+ }+ }+ out+ }++ /// The greatest distance between two points of space, in mm.+ fn apart(a: mt::Point3, b: mt::Point3) -> f64 {+ ((a.x - b.x).powi(2) + (a.y - b.y).powi(2) + (a.z - b.z).powi(2)).sqrt()+ }++ /// A geom point as a coordinate triple.+ fn triple(p: Vec3) -> [f64; 3] {+ [p.x, p.y, p.z]+ }++ #[test]+ fn a_perturbed_curve_is_faired_back_to_its_smooth_shape_and_its_ends_stay_put() {+ // A cubic curve whose control points sit at the knot averages of an affine curve: zero+ // bending energy, so a fairing run must return to the same control polygon. The knots are+ // deliberately uneven, so a fairing that ignored the curve's own parameter would not.+ let knots = [0.0, 0.0, 0.0, 0.0, 1.0, 3.0, 5.0, 9.0, 9.0, 9.0, 9.0];+ let (a, b) = ([-20.0, 5.0, 1.5], [4.0, -2.5, 3.0]);+ let smooth = affine_curve(&knots, 3, a, b);+ let mut rough = smooth.clone();+ rough[2] = [rough[2][0] + 1.5, rough[2][1] - 2.0, rough[2][2] + 3.0];+ rough[3][2] += 2.5;+ rough[4][0] -= 1.25;+ rough[5][1] += 1.75;+ let far = (0..smooth.len()).map(|i| dist(&rough[i], &smooth[i])).fold(0.0, f64::max);++ let opts = FairOptions::new(1.0, 8, false, 100.0).unwrap();+ let faired = fair_curve(3, &knots, &rough, &opts).unwrap();+ // The ends did not move at all, bit for bit.+ assert_eq!(faired.ctrl[0], rough[0]);+ assert_eq!(faired.ctrl[6], rough[6]);+ // Every interior control point came back to the smooth shape.+ let near = (1..6).map(|i| dist(&faired.ctrl[i], &smooth[i])).fold(0.0, f64::max);+ eprintln!(+ "curve: perturbation {far} mm, faired to {near:e} mm, energy {:e} → {:e} in {} steps, movement {:e} mm",+ faired.report.energy_before, faired.report.energy_after, faired.report.steps, faired.report.movement+ );+ assert!(near < 1e-6 && near < far * 1e-6, "faired to {near:e}, was {far} mm out");+ // The energy is a real number before, fell to nothing, and never rose on the way.+ assert!(faired.report.energy_before > 1e-3, "{:e}", faired.report.energy_before);+ assert!(faired.report.energy_after >= 0.0 && faired.report.energy_after < 1e-9 * faired.report.energy_before);+ assert!(faired.report.steps >= 1 && faired.report.energy_trace.len() == faired.report.steps);+ assert_eq!(faired.report.energy_trace.last().copied(), Some(faired.report.energy_after));+ assert!(faired.report.energy_trace.windows(2).all(|w| w[1] < w[0]), "{:?}", faired.report.energy_trace);+ // A step never moves a control point further than the tolerance, and here it moved the+ // whole way back to the smooth shape.+ assert!(faired.report.movement <= 100.0 && (faired.report.movement - far).abs() < 1e-9, "{:e}", faired.report.movement);+ // The faired curve is the affine line it was meant to be.+ let mut off = 0.0f64;+ for k in 0..=32 {+ let t = 9.0 * f64::from(k) / 32.0;+ let want: [f64; 3] = std::array::from_fn(|c| a[c] + b[c] * t);+ off = off.max(dist(&curve_at(3, &knots, &faired.ctrl, t), &want));+ }+ eprintln!("curve: the faired curve is {off:e} mm off the affine line it describes");+ assert!(off < 1e-6, "{off:e}");+ }++ #[test]+ fn a_half_strength_run_walks_to_the_same_shape_over_its_iterations() {+ // The same perturbation, walked a half step at a time: the energy must fall at every step+ // (monotone, strictly) and still arrive at the smooth shape.+ let knots = [0.0, 0.0, 0.0, 0.0, 1.0, 3.0, 5.0, 9.0, 9.0, 9.0, 9.0];+ let smooth = affine_curve(&knots, 3, [-20.0, 5.0, 1.5], [4.0, -2.5, 3.0]);+ let mut rough = smooth.clone();+ rough[2][2] += 4.0;+ rough[3][0] += 2.0;+ let opts = FairOptions::new(0.5, 40, false, 100.0).unwrap();+ let faired = fair_curve(3, &knots, &rough, &opts).unwrap();+ eprintln!("half strength: energy {:e} → {:e} in {} steps", faired.report.energy_before, faired.report.energy_after, faired.report.steps);+ assert!(faired.report.energy_trace.len() > 4, "one step is not a walk");+ assert!(faired.report.energy_trace.windows(2).all(|w| w[1] < w[0]), "the energy must fall at every step");+ assert!(faired.report.energy_after < 1e-9 * faired.report.energy_before);+ assert_eq!(faired.ctrl[0], rough[0]);+ assert_eq!(faired.ctrl[6], rough[6]);+ assert!(dist(&faired.ctrl[3], &smooth[3]) < 1e-6);+ }++ #[test]+ fn the_faired_curve_stays_within_the_tolerance_of_the_design() {+ // A heavily perturbed curve with a 0.75 mm tolerance: the design may be smoothed, but+ // never by more than the caller allowed, and the bound is on the geometry itself.+ let knots = clamped(3, 3);+ let smooth = affine_curve(&knots, 3, [0.0, 0.0, 0.0], [30.0, 8.0, 0.0]);+ let mut rough = smooth.clone();+ for (i, d) in [(1, [1.0, -2.0, 4.0]), (2, [-3.0, 2.0, -6.0]), (3, [2.0, -1.0, 5.0]), (4, [-2.0, 3.0, -4.0])] {+ for c in 0..3 {+ rough[i][c] += d[c];+ }+ }+ let tolerance = 0.75;+ let opts = FairOptions::new(1.0, 12, false, tolerance).unwrap();+ let faired = fair_curve(3, &knots, &rough, &opts).unwrap();+ let mut off = 0.0f64;+ for k in 0..=64 {+ let t = 3.0 * f64::from(k) / 64.0;+ off = off.max(dist(&curve_at(3, &knots, &faired.ctrl, t), &curve_at(3, &knots, &rough, t)));+ }+ eprintln!(+ "tolerance {tolerance}: the curve moved {off:e} mm at worst ({:e} mm of control points), energy {:e} → {:e}",+ faired.report.movement, faired.report.energy_before, faired.report.energy_after+ );+ assert!(faired.report.movement <= tolerance, "{:e}", faired.report.movement);+ assert!(off <= tolerance * (1.0 + 1e-9), "{off:e} over {tolerance}");+ assert!(faired.report.energy_after < faired.report.energy_before);+ // The tolerance did not stop the run from heading for the smooth shape.+ let before = (0..6).map(|i| dist(&rough[i], &smooth[i])).fold(0.0, f64::max);+ let after = (0..6).map(|i| dist(&faired.ctrl[i], &smooth[i])).fold(0.0, f64::max);+ assert!(after < before, "{after} vs {before}");+ assert_eq!(faired.ctrl[0], rough[0]);+ assert_eq!(faired.ctrl[5], rough[5]);+ }++ #[test]+ fn a_sketch_curve_of_two_dimensions_fairs_the_same_way() {+ // The generic core takes `[f64; 2]` just as well: a quadratic sketch curve, its middle+ // pulled 2 mm out of the smooth polyline.+ let knots = clamped(4, 2);+ let smooth: Vec<[f64; 2]> = (0..knots.len() - 3).map(|i| [average(&knots, 2, i) * 10.0, average(&knots, 2, i) * 2.0]).collect();+ let mut rough = smooth.clone();+ rough[2] = [rough[2][0] + 1.0, rough[2][1] - 2.0];+ rough[3][1] += 1.5;+ let opts = FairOptions::new(1.0, 10, false, 50.0).unwrap();+ let faired = fair_curve(2, &knots, &rough, &opts).unwrap();+ eprintln!("2D sketch curve: energy {:e} → {:e} in {} steps", faired.report.energy_before, faired.report.energy_after, faired.report.steps);+ assert_eq!(faired.ctrl[0], rough[0]);+ assert_eq!(faired.ctrl[5], rough[5]);+ assert!(faired.report.energy_after >= 0.0 && faired.report.energy_after < 1e-9 * faired.report.energy_before);+ for (i, want) in smooth.iter().enumerate().take(5).skip(1) {+ assert!(dist(&faired.ctrl[i], want) < 1e-6, "point {i}");+ }+ }++ #[test]+ fn a_perturbed_net_is_faired_back_to_its_plane_with_its_boundary_rows_held() {+ // A bicubic net of a plane (zero thin-plate energy), its middle pushed out; the boundary+ // rows must not move at all and the interior must come back to the plane.+ let (ku, kv) = (clamped(3, 3), clamped(4, 3));+ let degree = [3, 3];+ let (cu, cv) = (ku.len() - 4, kv.len() - 4);+ let (a, b, c) = ([1.0, -2.0, 4.0], [2.0, 0.5, -0.25], [-0.5, 1.5, 0.75]);+ let smooth = planar_net(&ku, &kv, degree, a, b, c);+ let mut rough = smooth.clone();+ for &(i, j, d) in &[(2usize, 2usize, 3.0), (3, 3, -2.5), (1, 4, 1.5), (4, 5, -1.0)] {+ rough[j * cu + i][2] += d;+ }+ let opts = FairOptions::new(1.0, 6, false, 100.0).unwrap();+ let faired = fair_net(degree, [&ku, &kv], [cu, cv], &rough, &opts).unwrap();+ for j in 0..cv {+ for i in [0, cu - 1] {+ assert_eq!(faired.ctrl[j * cu + i], rough[j * cu + i], "column {i}, row {j} moved");+ }+ }+ for i in 0..cu {+ for j in [0, cv - 1] {+ assert_eq!(faired.ctrl[j * cu + i], rough[j * cu + i], "row {j}, column {i} moved");+ }+ }+ let near = (0..cu * cv).map(|k| dist(&faired.ctrl[k], &smooth[k])).fold(0.0, f64::max);+ let far = (0..cu * cv).map(|k| dist(&rough[k], &smooth[k])).fold(0.0, f64::max);+ eprintln!("net: perturbation {far} mm, faired to {near:e} mm, energy {:e} → {:e}", faired.report.energy_before, faired.report.energy_after);+ assert!(near < 1e-6, "{near:e}");+ assert!(faired.report.energy_after < 1e-9 * faired.report.energy_before);+ assert!(faired.report.energy_trace.windows(2).all(|w| w[1] < w[0]));+ // With keep_edges the two outer layers at each side stay exactly as designed — so the+ // bump goes into the middle of the net — and the rest still comes back to the plane.+ let mut inner = smooth.clone();+ for &(i, j, d) in &[(2usize, 2usize, 3.0), (3, 3, -2.5), (2, 3, 1.5), (3, 2, -1.0)] {+ inner[j * cu + i][2] += d;+ }+ let kept = FairOptions::new(1.0, 6, true, 100.0).unwrap();+ let faired = fair_net(degree, [&ku, &kv], [cu, cv], &inner, &kept).unwrap();+ let shell = |i: usize, j: usize| i < 2 || i + 2 >= cu || j < 2 || j + 2 >= cv;+ for j in 0..cv {+ for i in 0..cu {+ if shell(i, j) {+ assert_eq!(faired.ctrl[j * cu + i], inner[j * cu + i], "({i}, {j}) is a boundary layer and moved");+ }+ }+ }+ let near = (0..cu * cv).filter(|&k| !shell(k % cu, k / cu)).map(|k| dist(&faired.ctrl[k], &smooth[k])).fold(0.0, f64::max);+ eprintln!("net with keep_edges: interior faired to {near:e} mm, energy {:e} → {:e}", faired.report.energy_before, faired.report.energy_after);+ assert!(near < 1e-6 && faired.report.energy_after < faired.report.energy_before);+ }++ #[test]+ fn a_faired_geom_surface_stays_within_the_tolerance_of_the_design_and_keeps_its_weights() {+ // A rational surface (weights off one) whose middle is pushed out: fair it with a 0.5 mm+ // tolerance. The weights must be untouched, the boundary rows must not move, and the+ // surface must stay within the tolerance of the one the design asked for.+ let (ku, kv) = (clamped(3, 3), clamped(3, 3));+ let degree = [3, 3];+ let (cu, cv) = (ku.len() - 4, kv.len() - 4);+ let smooth = planar_net(&ku, &kv, degree, [0.0, 0.0, 0.0], [20.0, 0.0, 0.0], [0.0, 15.0, 0.0]);+ let weights: Vec<f64> = (0..cu * cv).map(|k| 0.5 + (k % 5) as f64 * 0.25).collect();+ let mut rough = smooth.clone();+ for &(i, j, d) in &[(2usize, 2usize, 4.0), (3, 3, -3.0), (1, 2, 2.0)] {+ rough[j * cu + i][2] += d;+ }+ let surface =+ NurbsSurface::new(degree, [ku.clone(), kv.clone()], &rough.iter().map(|c| Vec3::new(c[0], c[1], c[2])).collect::<Vec<_>>(), &weights)+ .unwrap();+ let tolerance = 0.5;+ let opts = FairOptions::new(1.0, 8, false, tolerance).unwrap();+ let (faired, report) = fair_surface(&surface, &opts).unwrap();+ for k in 0..cu * cv {+ let (i, j) = (k % cu, k / cu);+ assert_eq!(faired.point(i, j).w, surface.point(i, j).w, "the weight of ({i}, {j}) changed");+ }+ for j in 0..cv {+ for i in [0, cu - 1] {+ assert_eq!(faired.point(i, j), surface.point(i, j), "column {i} moved");+ }+ }+ let dom = surface.domain();+ let mut off = 0.0f64;+ for k in 0..=24 {+ for l in 0..=24 {+ let (u, v) = (dom[0][0] + (dom[0][1] - dom[0][0]) * f64::from(k) / 24.0, dom[1][0] + (dom[1][1] - dom[1][0]) * f64::from(l) / 24.0);+ off = off.max(surface.eval(u, v).unwrap().dist(faired.eval(u, v).unwrap()));+ }+ }+ eprintln!(+ "surface: moved {off:e} mm at worst ({:e} mm of control points), energy {:e} → {:e}",+ report.movement, report.energy_before, report.energy_after+ );+ assert!(report.movement <= tolerance, "{:e}", report.movement);+ assert!(off <= tolerance * (1.0 + 1e-9), "{off:e} over {tolerance}");+ assert!(report.energy_after < report.energy_before);+ // Every interior control point is nearer the plane than it was.+ let before = (0..cu * cv).map(|k| dist(&rough[k], &smooth[k])).fold(0.0, f64::max);+ let after = (0..cu * cv).map(|k| dist(&triple(faired.point(k % cu, k / cu).project().unwrap()), &smooth[k])).fold(0.0, f64::max);+ assert!(after < before, "{after} vs {before}");+ }++ #[test]+ fn the_truck_wrappers_fair_a_spline_curve_and_surface_with_their_ends_held() {+ let knots = [0.0, 0.0, 0.0, 0.0, 1.0, 3.0, 5.0, 9.0, 9.0, 9.0, 9.0];+ let smooth = affine_curve(&knots, 3, [-20.0, 5.0, 1.5], [4.0, -2.5, 3.0]);+ let mut rough = smooth.clone();+ rough[2][2] += 3.0;+ rough[4][1] -= 2.0;+ let points = |net: &[[f64; 3]]| -> Vec<mt::Point3> { net.iter().map(|c| mt::Point3::new(c[0], c[1], c[2])).collect() };+ let curve = mt::BSplineCurve::try_new(mt::KnotVec::from(knots.to_vec()), points(&rough)).unwrap();+ let tolerance = 5.0;+ let opts = FairOptions::new(1.0, 8, false, tolerance).unwrap();+ let (faired, report) = fair_bspline_curve(&curve, &opts).unwrap();+ let mut off = 0.0f64;+ for k in 0..=64 {+ let t = 9.0 * f64::from(k) / 64.0;+ off = off.max(apart(faired.subs(t), curve.subs(t)));+ }+ eprintln!(+ "truck curve: energy {:e} → {:e} in {} steps, moved {off:e} mm ({:e} mm of control points)",+ report.energy_before, report.energy_after, report.steps, report.movement+ );+ assert_eq!(faired.control_points().first().copied(), curve.control_points().first().copied());+ assert_eq!(faired.control_points().last().copied(), curve.control_points().last().copied());+ assert!(off <= tolerance * (1.0 + 1e-9), "{off:e}");+ assert!(report.energy_after < 1e-9 * report.energy_before);++ // The same on a B-spline surface: boundary rows bit-identical, the bump in the middle+ // comes down, the energy falls.+ let (ku, kv) = (clamped(3, 3), clamped(3, 3));+ let degree = [3, 3];+ let (cu, cv) = (ku.len() - 4, kv.len() - 4);+ let smooth = planar_net(&ku, &kv, degree, [0.0, 0.0, 0.0], [20.0, 0.0, 0.0], [0.0, 15.0, 0.0]);+ let mut rough = smooth.clone();+ rough[2 * cu + 2][2] += 5.0;+ let rows: Vec<Vec<mt::Point3>> =+ (0..cu).map(|i| (0..cv).map(|j| mt::Point3::new(rough[j * cu + i][0], rough[j * cu + i][1], rough[j * cu + i][2])).collect()).collect();+ let surface = mt::BSplineSurface::try_new((mt::KnotVec::from(ku.clone()), mt::KnotVec::from(kv.clone())), rows).unwrap();+ let (faired, report) = fair_bspline_surface(&surface, &FairOptions::new(1.0, 6, true, 8.0).unwrap()).unwrap();+ eprintln!("truck surface: energy {:e} → {:e}, {} steps", report.energy_before, report.energy_after, report.steps);+ for i in 0..cu {+ for j in 0..cv {+ if i < 2 || i + 2 >= cu || j < 2 || j + 2 >= cv {+ assert_eq!(faired.control_points()[i][j], surface.control_points()[i][j], "({i}, {j}) is a boundary layer and moved");+ }+ }+ }+ assert!(report.energy_after < report.energy_before);+ assert!(faired.control_points()[2][2].z < surface.control_points()[2][2].z, "the bump should come down");+ }++ #[test]+ fn a_rational_surface_fairs_with_its_boundary_and_tolerance_intact() {+ // The truck NURBS wrapper, on weights away from one: fairing moves the Cartesian control+ // points and keeps the weights, so the surface still cannot move more than the tolerance.+ let (ku, kv) = (clamped(3, 3), clamped(3, 3));+ let degree = [3, 3];+ let (cu, cv) = (ku.len() - 4, kv.len() - 4);+ let smooth = planar_net(&ku, &kv, degree, [0.0, 0.0, 0.0], [20.0, 0.0, 0.0], [0.0, 15.0, 0.0]);+ let mut rough = smooth.clone();+ rough[2 * cu + 3][2] += 6.0;+ let weights: Vec<f64> = (0..cu * cv).map(|k| 0.75 + (k % 3) as f64 * 0.5).collect();+ let rows: Vec<Vec<mt::Vector4>> = (0..cu)+ .map(|i| {+ (0..cv)+ .map(|j| {+ let (c, w) = (rough[j * cu + i], weights[j * cu + i]);+ mt::Vector4::new(c[0] * w, c[1] * w, c[2] * w, w)+ })+ .collect()+ })+ .collect();+ let bsp = mt::BSplineSurface::try_new((mt::KnotVec::from(ku.clone()), mt::KnotVec::from(kv.clone())), rows).unwrap();+ let surface = mt::NurbsSurface::new(bsp);+ let (faired, report) = fair_nurbs_surface(&surface, &FairOptions::new(1.0, 6, false, 0.5).unwrap()).unwrap();+ eprintln!("rational surface: energy {:e} → {:e}, movement {:e} mm", report.energy_before, report.energy_after, report.movement);+ assert!(report.movement <= 0.5 && report.energy_after < report.energy_before);+ for i in 0..cu {+ for j in 0..cv {+ let (before, after) = (surface.non_rationalized().control_points()[i][j], faired.non_rationalized().control_points()[i][j]);+ assert_eq!(after.w, before.w, "the weight of ({i}, {j}) changed");+ if i == 0 || i + 1 == cu || j == 0 || j + 1 == cv {+ assert_eq!(after, before, "({i}, {j}) is on the boundary and moved");+ }+ }+ }+ }++ #[test]+ fn hostile_fairing_inputs_are_refused() {+ let knots = clamped(3, 3);+ let ctrl = affine_curve(&knots, 3, [0.0, 0.0, 0.0], [10.0, 4.0, 2.0]);+ let ok = FairOptions::new(1.0, 4, false, 10.0).unwrap();+ // Out-of-range parameters: strength, iterations and tolerance are all input-derived.+ for strength in [0.0, -0.25, 1.000_001, f64::NAN, f64::INFINITY] {+ assert!(FairOptions::new(strength, 4, false, 10.0).is_err(), "strength {strength}");+ }+ for iterations in [0, MAX_FAIR_ITERATIONS + 1, usize::MAX] {+ assert!(FairOptions::new(1.0, iterations, false, 10.0).is_err(), "iterations {iterations}");+ }+ for tolerance in [0.0, -1.0, f64::NAN, f64::INFINITY] {+ assert!(FairOptions::new(1.0, 4, false, tolerance).is_err(), "tolerance {tolerance}");+ }+ // A control point that is not a finite number.+ for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {+ let mut nan = ctrl.clone();+ nan[2][1] = bad;+ assert!(fair_curve(3, &knots, &nan, &ok).is_err(), "a control point of {bad} was faired");+ }+ // Knot vectors that do not fit the control points or the degree.+ assert!(fair_curve(3, &knots[..9], &ctrl, &ok).is_err(), "nine knots for six control points of degree three");+ assert!(fair_curve(3, &[0.0, 0.0, 0.0, 0.0, 2.0, 1.0, 3.0, 4.0, 4.0, 4.0], &ctrl, &ok).is_err(), "knots that decrease");+ assert!(fair_curve(3, &vec![f64::NAN; knots.len()], &ctrl, &ok).is_err(), "a knot that is not a number");+ assert!(fair_curve(9, &knots, &ctrl, &ok).is_err(), "a degree above the supported maximum");+ // Fewer than two interior control points: one free point (a triangle of a quadratic), and+ // a 3 × 3 net whose two edge layers leave nothing at all.+ let triangle = [[0.0, 0.0, 0.0], [5.0, 2.0, 0.0], [10.0, 0.0, 1.0]];+ let one = fair_curve(2, &[0.0, 0.0, 0.0, 1.0, 1.0, 1.0], &triangle, &ok).unwrap_err();+ assert!(one.to_string().contains("at least two interior"), "{one}");+ let flat = [0.0, 0.0, 1.0, 2.0, 2.0];+ let grid = [[0.0, 0.0, 0.0]; 9];+ let kept = FairOptions::new(1.0, 4, true, 1.0).unwrap();+ assert!(fair_net([1, 1], [&flat, &flat], [3, 3], &grid, &kept).is_err(), "keep_edges on a 3 × 3 net");+ // A net too large to fair, refused before anything is allocated for it.+ let line = [0.0, 0.0, 1.0, 1.0];+ assert!(fair_net([1, 1], [&line, &line], [65, 65], &vec![[0.0; 3]; 65 * 65], &ok).is_err(), "4225 control points");+ // A singular system: a cubic whose last control points lie past the end of its domain+ // (0.5), where they do not move the curve at all, so the interior equations have no+ // unique solution and the run must refuse rather than move anything.+ let odd = [0.0, 0.0, 0.0, 0.0, 0.5, 0.5, 0.5, 1.0, 1.0, 1.0];+ let six: Vec<[f64; 3]> = (0..6).map(|i| [i as f64, 0.0, 1.0]).collect();+ let singular = fair_curve(3, &odd, &six, &ok).unwrap_err();+ eprintln!("hostile inputs: refused with {singular}");+ assert!(singular.to_string().contains("singular"), "{singular}");+ }++ #[test]+ fn a_small_quadratic_net_and_a_quintic_curve_fair_the_same_way() {+ // Degrees and band shapes away from the bicubic case. A 5 × 5 quadratic net has fewer+ // rows than the degree, so the solver's band is narrower than `degree_u + degree_v · cols`+ // (the coupling cannot reach that far in v); a quintic curve carries six basis functions+ // per span instead of four. Both must reproduce a zero-energy shape exactly.+ let (ku, kv) = (clamped(3, 2), clamped(3, 2));+ let degree = [2, 2];+ let (cu, cv) = (ku.len() - 3, kv.len() - 3);+ assert_eq!((cu, cv), (5, 5));+ let smooth = planar_net(&ku, &kv, degree, [0.0, 0.0, 0.0], [12.0, 1.0, 0.0], [-2.0, 9.0, 0.0]);+ let mut rough = smooth.clone();+ for &(i, j, d) in &[(1usize, 2usize, 2.5), (2, 2, -1.5), (3, 3, 3.0), (2, 1, -2.0)] {+ rough[j * cu + i][2] += d;+ }+ let faired = fair_net(degree, [&ku, &kv], [cu, cv], &rough, &FairOptions::new(1.0, 8, false, 100.0).unwrap()).unwrap();+ let near = (0..cu * cv).map(|k| dist(&faired.ctrl[k], &smooth[k])).fold(0.0, f64::max);+ eprintln!("5 × 5 quadratic net: faired to {near:e} mm, energy {:e} → {:e}", faired.report.energy_before, faired.report.energy_after);+ assert!(near < 1e-6 && faired.report.energy_after < 1e-9 * faired.report.energy_before);+ for j in 0..cv {+ for i in 0..cu {+ if i == 0 || i + 1 == cu || j == 0 || j + 1 == cv {+ assert_eq!(faired.ctrl[j * cu + i], rough[j * cu + i], "({i}, {j}) is on the boundary and moved");+ }+ }+ }+ // A quintic curve, its middle pulled out.+ let knots = clamped(3, 5);+ let smooth = affine_curve(&knots, 5, [-10.0, 0.0, 2.0], [6.0, 4.0, -1.0]);+ let mut rough = smooth.clone();+ rough[3][1] += 3.0;+ rough[4][2] -= 2.0;+ let faired = fair_curve(5, &knots, &rough, &FairOptions::new(1.0, 8, false, 100.0).unwrap()).unwrap();+ let near = (1..smooth.len() - 1).map(|i| dist(&faired.ctrl[i], &smooth[i])).fold(0.0, f64::max);+ eprintln!("quintic curve: faired to {near:e} mm, energy {:e} → {:e}", faired.report.energy_before, faired.report.energy_after);+ assert!(near < 1e-6 && faired.report.energy_after < 1e-9 * faired.report.energy_before);+ assert_eq!(faired.ctrl[0], rough[0]);+ assert_eq!(faired.ctrl[rough.len() - 1], rough[rough.len() - 1]);+ }++ /// A one-face sheet body of the bicubic surface `net` (u fastest) over the clamped knots `ku`+ /// and `kv`, its sides the straight lines between the surface's corners — true while the+ /// net's boundary rows describe lines, which is how a plane's control net is built here.+ fn sheet(ku: &[f64], kv: &[f64], net: &[[f64; 3]]) -> Body {+ let (cu, cv) = (ku.len() - 4, kv.len() - 4);+ assert_eq!(net.len(), cu * cv, "the net does not fit the knots");+ let rows: Vec<Vec<mt::Point3>> =+ (0..cu).map(|i| (0..cv).map(|j| mt::Point3::new(net[j * cu + i][0], net[j * cu + i][1], net[j * cu + i][2])).collect()).collect();+ let bsp = mt::BSplineSurface::try_new((mt::KnotVec::from(ku.to_vec()), mt::KnotVec::from(kv.to_vec())), rows).unwrap();+ let corner = |i: usize, j: usize| {+ let c = net[j * cu + i];+ mt::Vertex::new(mt::Point3::new(c[0], c[1], c[2]))+ };+ let v = [corner(0, 0), corner(cu - 1, 0), corner(cu - 1, cv - 1), corner(0, cv - 1)];+ let line = |a: &mt::Vertex, b: &mt::Vertex| mt::Edge::new(a, b, mt::Curve::Line(mt::Line(a.point(), b.point())));+ let wire: mt::Wire = vec![line(&v[0], &v[1]), line(&v[1], &v[2]), line(&v[2], &v[3]), line(&v[3], &v[0])].into();+ crate::surfaces::surface_body(vec![mt::Face::try_new(vec![wire], mt::Surface::BSplineSurface(bsp)).unwrap()])+ }++ #[test]+ fn a_body_face_is_faired_with_its_edges_untouched_and_its_history_kept() {+ // A sheet whose middle is bumped: fairing the face must smooth it without moving a single+ // edge, vertex or neighbouring face of the body, and must leave a history saying so.+ let (ku, kv) = (clamped(3, 3), clamped(3, 3));+ let (cu, cv) = (ku.len() - 4, kv.len() - 4);+ let smooth = planar_net(&ku, &kv, [3, 3], [0.0, 0.0, 0.0], [20.0, 0.0, 0.0], [0.0, 15.0, 0.0]);+ let mut rough = smooth.clone();+ for &(i, j, d) in &[(2usize, 2usize, 3.0), (3, 3, -2.0), (2, 3, 1.5)] {+ rough[j * cu + i][2] += d;+ }+ let body = sheet(&ku, &kv, &rough);+ let before: Vec<_> =+ body.solid.face_iter().flat_map(|f| f.absolute_boundaries().iter()).flat_map(|w| w.edge_iter().map(|e| e.id())).collect();+ assert!(!before.is_empty());+ let (faired, report) = fair_faces(&body, &[0], &FairOptions::new(1.0, 6, false, 50.0).unwrap()).unwrap();+ let after: Vec<_> =+ faired.solid.face_iter().flat_map(|f| f.absolute_boundaries().iter()).flat_map(|w| w.edge_iter().map(|e| e.id())).collect();+ eprintln!(+ "face: energy {:e} → {:e} in {} steps, movement {:e} mm, {} faces, history {}",+ report.energy_before,+ report.energy_after,+ report.steps,+ report.movement,+ faired.face_count(),+ faired.history().is_some()+ );+ assert_eq!(before, after, "the body's edges must be the very ones it had");+ assert_eq!(faired.face_count(), 1);+ assert!(faired.history().is_some(), "the face came from the one it was faired from");+ assert!(report.energy_after < 1e-9 * report.energy_before);+ // The face's own surface is back on the plane, boundary rows bit for bit as they were.+ let Some(mt::Surface::BSplineSurface(s)) = faired.solid.face_iter().next().map(|f| f.surface()) else { panic!("a B-spline face") };+ for j in 0..cv {+ for i in 0..cu {+ let p = s.control_points()[i][j];+ let want = if i == 0 || i + 1 == cu || j == 0 || j + 1 == cv { rough[j * cu + i] } else { smooth[j * cu + i] };+ assert!(dist(&[p.x, p.y, p.z], &want) < 1e-6, "({i}, {j})");+ }+ }+ // A solid keeps its shells, its faces and its edges: thickening the sheet gives a closed+ // body whose top face is still the B-spline one, and fairing that face leaves the body a+ // solid of the same shape.+ let solid = crate::thicken(&body, 2.0, false).unwrap();+ assert!(!solid.is_surface());+ let top =+ (0..solid.face_count()).find(|&i| matches!(solid.solid.face_iter().nth(i).map(|f| f.surface()), Some(mt::Surface::BSplineSurface(_))));+ let Some(top) = top else { panic!("the thickened sheet keeps its B-spline face") };+ let edges: Vec<_> =+ solid.solid.face_iter().flat_map(|f| f.absolute_boundaries().iter()).flat_map(|w| w.edge_iter().map(|e| e.id())).collect();+ let (faired, report) = fair_faces(&solid, &[top], &FairOptions::new(1.0, 6, false, 0.5).unwrap()).unwrap();+ eprintln!("thickened solid: energy {:e} → {:e}, movement {:e} mm", report.energy_before, report.energy_after, report.movement);+ assert!(!faired.is_surface() && faired.face_count() == solid.face_count() && faired.shell_count() == solid.shell_count());+ assert_eq!(+ faired.solid.face_iter().flat_map(|f| f.absolute_boundaries().iter()).flat_map(|w| w.edge_iter().map(|e| e.id())).collect::<Vec<_>>(),+ edges+ );+ assert!(report.energy_after < report.energy_before);+ // A face with no control points to fair is refused, by name.+ let cube = crate::box_solid(Vec3::ZERO, Vec3::new(10.0, 10.0, 10.0)).unwrap();+ let refused = fair_faces(&cube, &[0], &FairOptions::new(1.0, 1, false, 1.0).unwrap()).unwrap_err();+ eprintln!("cube face: {refused}");+ assert!(refused.to_string().contains("not a B-spline face"), "{refused}");+ assert!(fair_faces(&body, &[7], &FairOptions::new(1.0, 1, false, 1.0).unwrap()).is_err(), "no such face");+ assert!(fair_faces(&body, &[], &FairOptions::new(1.0, 1, false, 1.0).unwrap()).is_err(), "no face picked");+ }++ #[test]+ fn an_already_fair_curve_is_left_where_it_is() {+ // Zero bending energy, no reason to move: nothing churns, and an input at the minimum+ // cannot be faired into a worse shape.+ let knots = clamped(4, 3);+ let smooth = affine_curve(&knots, 3, [1.0, 2.0, 3.0], [5.0, -1.0, 0.5]);+ let opts = FairOptions::new(1.0, 20, false, 10.0).unwrap();+ let faired = fair_curve(3, &knots, &smooth, &opts).unwrap();+ eprintln!(+ "already fair: energy {:e} → {:e}, {} steps, {:e} mm",+ faired.report.energy_before, faired.report.energy_after, faired.report.steps, faired.report.movement+ );+ assert!(faired.report.energy_after <= faired.report.energy_before);+ assert!(faired.report.energy_after >= 0.0);+ assert!(faired.report.movement < 1e-9, "{:e}", faired.report.movement);+ for (i, want) in smooth.iter().enumerate() {+ assert!(dist(&faired.ctrl[i], want) < 1e-9, "control point {i}");+ }+ }+}diff --git a/crates/kernel/src/lib.rs b/crates/kernel/src/lib.rsindex 0376c6a7a3..22756f874c 100644--- a/crates/kernel/src/lib.rs+++ b/crates/kernel/src/lib.rs@@ -24,6 +24,7 @@ mod boolean_diagnostics;mod boolean_guard;mod boolean_record;mod bore_guard;+mod boundary;mod bridge;mod build;mod clearance;@@ -36,6 +37,7 @@ mod emboss;mod face_params;#[cfg(test)]mod face_source_tests;+mod fair;mod fill;mod freeform;pub mod fuzz;@@ -66,6 +68,7 @@ mod issue_871_tests;mod join_between_caps_tests;mod lip;mod loopblend;+mod matchsurf;mod measure;mod mesh_convert;mod meshbody;@@ -125,6 +128,7 @@ pub use blend_corner::fillet_radii;pub use blend_variable::{RadiusSpline, Taper, fillet_chord, fillet_tapered, fillet_variable, fillet_variable_points, fillet_variable_spline, taper};pub use body::{Body, CapSignature, DISPLAY_ANGLE, EdgeInfo, FaceInfo, FacePaint, FaceSource, Paint};pub use boolean_diagnostics::{BooleanDiagnostics, BooleanFallback, BooleanStrategy, capture_boolean_diagnostics};+pub use boundary::{Boundary, boundary_patch};pub use bridge::{Continuity, Frame, blend_between, bridge, chain, chain_closes, frames, frames_across, sample_grid};pub use build::{PathSeg, box_solid, canonical_revolve_axis, cylinder, extrude, extrude_tapered, extrude_tapered_between, loft, revolve, sphere, sweep,@@ -132,11 +136,16 @@ pub use build::{};pub use delete_face::delete_faces;pub use emboss::{cylinder_emboss_anchor, emboss_cylinder, emboss_cylinder_at, has_cylinder_emboss_wall, infer_cylinder_emboss};+pub use fair::{+ FairCurve, FairNet, FairOptions, FairReport, MAX_FAIR_ITERATIONS, MAX_FAIR_POINTS, fair_bspline_curve, fair_bspline_surface, fair_curve,+ fair_faces, fair_net, fair_nurbs_curve, fair_nurbs_surface, fair_surface,+};pub use fill::{PATCH_ANGLE_TOL_DEG, PatchReport, PatchSpec, patch_edges_crowned, patch_edges_report, patch_edges_with};pub use helix::{loft_to_point, sweep_helix, sweep_helix_mesh};pub use iges_in::{MAX_IGES_BYTES, iges_import, iges_to_step};pub use iges_out::iges_export_bodies;pub use lip::raise_band;+pub use matchsurf::{match_surface, seam_continuity};pub use measure::{BodyMeasure, measure};pub use mesh_convert::convert_prismatic_mesh;pub use meshbody::{MAX_TRIANGLES, mesh_body};diff --git a/crates/kernel/src/matchsurf.rs b/crates/kernel/src/matchsurf.rsnew file mode 100644index 0000000000..8134ea341d--- /dev/null+++ b/crates/kernel/src/matchsurf.rs@@ -0,0 +1,601 @@+//! Surface matching: rebuild a surface body's face so that one boundary of it meets a picked+//! edge chain of another body up to a requested continuity (G1, G2 or G3), while the boundary+//! opposite it does not move.+//!+//! A match is the bridge core ([`crate::bridge`]) pointed at a different pair of boundaries. One+//! end reads its position, tangent, curvature and change of curvature from the *target's* face+//! along the picked chain — that is the end that moves. The other end reads them from the body's+//! own surface along the boundary opposite it, built through the original boundary's own points:+//! a match may shape the middle, never that seam. In between the cross-sections are the bridge's+//! cubic Hermites, whose crown is free, so the crown whose surface stays closest to the original+//! one — sampled on a grid and measured against it — is the one kept: a match moves the seam and+//! as little else as the conditions allow.+//!+//! Which boundary of the face moves is read off the geometry: the one nearest the picked chain.+//! The order a match may ask for is read off the target the same way: a chain that several faces+//! of the target meet, with shapes that part company, is a seam the target itself does not hold+//! beyond that order, and no surface can be told to carry a condition the target has not got.++use mt::{BoundedCurve, ParametricCurve, ParametricSurface, ParametricSurface3D, SearchNearestParameter};+use solidcraft_geom::Vec3;+use truck_modeling as mt;++use crate::body::{Body, from_p3, p3};+use crate::bridge::{self, Continuity, Frame};+use crate::record::Rebuild;+use crate::surfaces::surface_body;+use crate::{KernelError, Result, guard};++/// Stations a match reads along the seam and along the boundary it keeps.+const STATIONS: usize = 33;++/// Samples each way of the grid the rebuilt surface is compared with the original on.+const GRID: usize = 7;++/// The crowns the match tries at each end: [`crate::bridge::bridge`]'s free knob, which shapes+/// the middle without touching either end's conditions.+const CROWNS: [f64; 5] = [-0.5, 0.0, 0.5, 1.0, 2.0];++/// Points a caller may pick one face with.+const MAX_PICKS: usize = 64;++/// Samples per edge of a chain, for lengths and distances.+const PER_EDGE: usize = 32;++/// A seam is credited with G1 when its normals agree this closely (degrees), with G2 when the+/// two curvature vectors agree within this fraction of the larger of them, and with G3 when the+/// change of curvature agrees within this fraction of the curvature over the body's size.+const G1_DEG: f64 = 0.05;+const G2_REL: f64 = 5e-3;+const G3_REL: f64 = 5e-2;++/// Two faces of the target count as meeting each other at the picked chain when their normals+/// agree this closely, their curvature within this fraction of the larger, and their change of+/// curvature within this fraction of the curvature over the body's size.+const SUPPLY_DEG: f64 = 0.05;+const SUPPLY_REL: f64 = 2e-2;+const SUPPLY_BEND_REL: f64 = 1e-1;++/// Rebuild the face of `body` picked by `faces` (points on it) so that its boundary nearest the+/// chain of `target`'s edges picked by `target_pick` takes that chain's place and repeats the+/// target's own shape along it up to `order` — position, tangent, curvature vector, and the+/// change of that curvature vector along the direction the match leaves in. The boundary+/// opposite keeps its place and the original surface's own frame, and the middle is shaped to+/// stay as close to the original surface as the conditions allow.+pub fn match_surface(body: &Body, faces: &[Vec3], target: &Body, target_pick: &[Vec3], order: Continuity) -> Result<Body> {+ body.require_brep("match")?;+ target.require_brep("match")?;+ if !body.is_surface() {+ return Err(KernelError::Invalid("match rebuilds a surface body: this one is closed".into()));+ }+ let face = face_near(body, faces)?;+ let chain = bridge::chain(target, target_pick)?;+ let near = nearest_side(&face, &chain)?;+ let far = near.opposite();+ let far_edges = side_edges(&face, far, body.size() * 1e-6 + 1e-9)?;+ let (mid_near, mid_far) = (chain_mid(&chain)?, Side::at(&face.surface(), &ranges(&face)?, far, 0.5));+ let leave = (mid_far - mid_near)+ .normalized()+ .filter(|l| l.is_finite())+ .ok_or_else(|| KernelError::Invalid("the far boundary sits on the picked chain: there is nothing to match".into()))?;+ // Which face of the target the match continues from, and how much of the requested order the+ // target itself holds along that chain.+ let candidates = support_faces(target, &chain, leave)?;+ let supply = supply_order(&candidates, &chain, leave, target.size())?;+ if order.conditions() > supply.conditions() {+ return Err(KernelError::Invalid(format!(+ "the target's own surfaces part company at the picked edges: they hold only {} there, so a seam cannot hold {}",+ supply.as_str(),+ order.as_str()+ )));+ }+ let Some((target_face, _)) = candidates.first() else {+ return Err(KernelError::Invalid("no face of the target holds the picked edges".into()));+ };+ // The stations of the seam: what the target does there along the direction the match leaves+ // in, and what the far boundary does coming back the other way.+ let mut near_frames = bridge::frames(target_face, &chain, leave, STATIONS)?;+ let far_frames = bridge::frames(&face, &far_edges, leave * -1.0, STATIONS)?;+ // The two chains are sampled from their own starts: turn one round when that pairs the+ // stations better (a match is built station to station).+ let direct: f64 = near_frames.iter().zip(&far_frames).map(|(a, b)| a.p.dist(b.p)).sum();+ let reversed: f64 = near_frames.iter().zip(far_frames.iter().rev()).map(|(a, b)| a.p.dist(b.p)).sum();+ if reversed < direct {+ near_frames.reverse();+ }+ guard("surface match", || {+ // The crown is the free knob: keep the one whose surface stays closest to the original.+ let mut best: Option<(f64, mt::Face)> = None;+ for crown_near in CROWNS {+ for crown_far in CROWNS {+ let made = bridge::bridge(&near_frames, &far_frames, [order, Continuity::G1], [crown_near, crown_far])?;+ let Some(made) = made.solid.face_iter().next().cloned() else {+ return Err(KernelError::Failed("match: the bridge made no face".into()));+ };+ let stray = deviation(&made, &face)?;+ if best.as_ref().is_none_or(|(b, _)| stray < *b) {+ best = Some((stray, made));+ }+ }+ }+ let Some((_, made)) = best else {+ return Err(KernelError::Failed("match: no crown built a surface".into()));+ };+ let mut kept = made;+ // The rebuilt face takes the target's own sense at the seam: the two surfaces then meet+ // the same way round, which is what a stitch, a thicken or a display of the result reads.+ let seam = chain_mid(&chain)?;+ if let (Some((made_n, _)), Some((target_n, _))) = (normal_near(&kept, seam), normal_near(target_face, seam))+ && made_n.dot(target_n) < 0.0+ {+ kept.invert();+ }+ let mut rec = Rebuild::default();+ rec.face(&kept, &face);+ Ok(crate::record::rebuilt_body(surface_body(vec![kept]), &[&body.solid, &target.solid], &rec))+ })+}++/// How well the rebuilt surface `made` meets `target` along the chain picked by `target_pick`:+/// the worst distance from the seam to that chain, the worst angle between the two surfaces'+/// normals across it (degrees), and the highest continuity the seam holds+/// ([`Continuity::G0`] when even the normals disagree).+pub fn seam_continuity(made: &Body, target: &Body, target_pick: &[Vec3]) -> Result<(f64, f64, Continuity)> {+ made.require_brep("match")?;+ target.require_brep("match")?;+ let chain = bridge::chain(target, target_pick)?;+ let poly = chain_polyline(&chain)?;+ // The face whose boundary runs along the chain: the one nearest it, so that a body that has+ // not been matched yet — where the seam is still some way off — can be measured too.+ let mid = chain_mid(&chain)?;+ let face = made+ .solid+ .face_iter()+ .filter_map(|f| face_distance(f, mid).map(|d| (d, f)))+ .min_by(|a, b| a.0.total_cmp(&b.0))+ .map(|(_, f)| f.clone())+ .ok_or_else(|| KernelError::Failed("match: the body has no faces".into()))?;+ let near = nearest_side(&face, &chain)?;+ let far = near.opposite();+ let ranges = ranges(&face)?;+ let mid_far = Side::at(&face.surface(), &ranges, far, 0.5);+ let leave = (mid_far - chain_mid(&chain)?)+ .normalized()+ .ok_or_else(|| KernelError::Invalid("the seam and the far boundary coincide: there is nothing to measure".into()))?;+ let candidates = support_faces(target, &chain, leave)?;+ let Some((target_face, _)) = candidates.first() else {+ return Err(KernelError::Invalid("no face of the target holds the picked edges".into()));+ };+ let frames = bridge::frames(target_face, &chain, leave, STATIONS)?;+ let size = target.size();+ guard("surface match", || {+ let surf = face.surface();+ let (mut gap, mut deg, mut curv, mut bend) = (0.0f64, 0.0f64, 0.0f64, 0.0f64);+ for i in 0..STATIONS {+ let t = i as f64 / (STATIONS - 1) as f64;+ let p = Side::at(&surf, &ranges, near, t);+ gap = gap.max(chain_distance(&poly, p));+ // What the target says there, and what the rebuilt surface actually does there.+ let Some(frame) = frames.iter().min_by(|a, b| a.p.dist(p).total_cmp(&b.p.dist(p))) else {+ return Err(KernelError::Failed("match: the target has no frames".into()));+ };+ let (_, t_made, bend_made, change_made) = seam_shape(&surf, &ranges, near, t)?;+ if let Some((n_made, _)) = normal_near(&face, p)+ && let Some((n_target, _)) = normal_near(target_face, p)+ {+ deg = deg.max(angle_deg(n_made, n_target));+ }+ let scale = frame.bend.len().max(bend_made.len()).max(1.0 / size);+ curv = curv.max((bend_made - frame.bend).len() / scale);+ // The change of curvature is what a surface can hold: only its normal part counts,+ // and it turns round with the direction of travel.+ let change = if t_made.dot(frame.leave) < 0.0 { change_made * -1.0 } else { change_made };+ let scale3 = frame.bend_change.len().max(change.len()).max(scale / size);+ bend = bend.max((change - frame.bend_change).len() / scale3);+ }+ let mut order = Continuity::G0;+ if deg <= G1_DEG {+ order = Continuity::G1;+ if curv <= G2_REL {+ order = Continuity::G2;+ if bend <= G3_REL {+ order = Continuity::G3;+ }+ }+ }+ Ok((gap, deg, order))+ })+}++/// Which side of a face's parameter rectangle a boundary runs along: the match reads its face as+/// a tensor patch, so its four sides are its own parameter lines.+#[derive(Clone, Copy, PartialEq, Eq, Debug)]+enum Side {+ /// The `u = u0` side (its points run along `v`).+ U0,+ /// The `u = u1` side.+ U1,+ /// The `v = v0` side (its points run along `u`).+ V0,+ /// The `v = v1` side.+ V1,+}++impl Side {+ /// The four sides, in a fixed order.+ const ALL: [Side; 4] = [Side::U0, Side::U1, Side::V0, Side::V1];++ /// The side opposite this one: what a match keeps when this one moves.+ fn opposite(self) -> Side {+ match self {+ Side::U0 => Side::U1,+ Side::U1 => Side::U0,+ Side::V0 => Side::V1,+ Side::V1 => Side::V0,+ }+ }++ /// Whether this side pins `u` (its points run along `v`).+ fn is_u(self) -> bool {+ matches!(self, Side::U0 | Side::U1)+ }++ /// The value this side pins, and the range the side runs over.+ fn fixed_and_along(self, u: (f64, f64), v: (f64, f64)) -> (f64, (f64, f64)) {+ match self {+ Side::U0 => (u.0, v),+ Side::U1 => (u.1, v),+ Side::V0 => (v.0, u),+ Side::V1 => (v.1, u),+ }+ }++ /// The point at the normalized station `t` along the side.+ fn at(surf: &mt::Surface, ranges: &[(f64, f64); 2], side: Side, t: f64) -> Vec3 {+ let (u, v) = (ranges[0], ranges[1]);+ let (fixed, along) = side.fixed_and_along(u, v);+ let t = along.0 + (along.1 - along.0) * t.clamp(0.0, 1.0);+ if side.is_u() { from_p3(surf.subs(fixed, t)) } else { from_p3(surf.subs(t, fixed)) }+ }+}++/// The bounded parameter ranges of a face's surface.+fn ranges(face: &mt::Face) -> Result<[(f64, f64); 2]> {+ let surf = face.surface();+ let (Some(u), Some(v)) = surf.try_range_tuple() else {+ return Err(KernelError::Failed("match: the face's surface is unbounded".into()));+ };+ Ok([u, v])+}++/// How far `p` is from the face's own surface.+fn face_distance(face: &mt::Face, p: Vec3) -> Option<f64> {+ let surf = face.surface();+ let (u, v) = surf.search_nearest_parameter(p3(p), None, 100)?;+ Some(from_p3(surf.subs(u, v)).dist(p))+}++/// The surface's unit normal at the point nearest `p`, and how far `p` is from that point.+fn normal_near(face: &mt::Face, p: Vec3) -> Option<(Vec3, f64)> {+ let surf = face.surface();+ let (u, v) = surf.search_nearest_parameter(p3(p), None, 100)?;+ let n = surf.normal(u, v);+ let n = Vec3::new(n.x, n.y, n.z).normalized()?;+ Some((n, from_p3(surf.subs(u, v)).dist(p)))+}++/// The face of `body` the picks lie on: they must all pick the same one. A pick is a point the+/// caller clicked, so the face nearest it within the body's own pick tolerance is the face it+/// means (`crate::surfaces::edge_near` reads points the same way).+fn face_near(body: &Body, picks: &[Vec3]) -> Result<mt::Face> {+ if picks.is_empty() || picks.len() > MAX_PICKS || picks.iter().any(|p| !p.is_finite()) {+ return Err(KernelError::Invalid(format!("pick 1 to {MAX_PICKS} points on the face to match")));+ }+ let tol = body.size() * 0.05 + 1e-6;+ let mut found: Option<mt::Face> = None;+ for p in picks {+ let hit = body+ .solid+ .face_iter()+ .filter_map(|f| face_distance(f, *p).map(|d| (d, f)))+ .min_by(|a, b| a.0.total_cmp(&b.0))+ .filter(|(d, _)| *d <= tol)+ .map(|(_, f)| f.clone())+ .ok_or_else(|| KernelError::Invalid(format!("no face of the body passes through {p:?}")))?;+ if found.as_ref().is_some_and(|f| f.id() != hit.id()) {+ return Err(KernelError::Invalid("the picks are on different faces: match one face".into()));+ }+ found = Some(hit);+ }+ found.ok_or_else(|| KernelError::Invalid("pick a point on the face to match".into()))+}++/// A chain of edges as a polyline (each edge sampled), for lengths and distances.+fn chain_polyline(chain: &[mt::Edge]) -> Result<Vec<Vec3>> {+ if chain.is_empty() {+ return Err(KernelError::Invalid("the chain has no edges".into()));+ }+ let mut out = Vec::with_capacity(chain.len() * (PER_EDGE + 1));+ for e in chain {+ let c = e.curve();+ let (t0, t1) = c.range_tuple();+ if !(t1 > t0) || ![t0, t1].into_iter().all(f64::is_finite) {+ return Err(KernelError::Failed("match: an edge has no parameter range".into()));+ }+ for k in 0..=PER_EDGE {+ out.push(from_p3(c.subs(t0 + (t1 - t0) * k as f64 / PER_EDGE as f64)));+ }+ }+ Ok(out)+}++/// The point at the middle of a chain, by length.+fn chain_mid(chain: &[mt::Edge]) -> Result<Vec3> {+ let poly = chain_polyline(chain)?;+ let mut cum = Vec::with_capacity(poly.len());+ cum.push(0.0);+ for w in poly.windows(2) {+ let (Some(a), Some(b)) = (w.first(), w.get(1)) else { continue };+ let Some(last) = cum.last().copied() else { break };+ cum.push(last + a.dist(*b));+ }+ let total = cum.last().copied().unwrap_or(0.0);+ if !(total > 1e-9) || !total.is_finite() {+ return Err(KernelError::Invalid("the picked chain has no length".into()));+ }+ let half = total * 0.5;+ let hi = cum.partition_point(|x| *x < half).clamp(1, poly.len().saturating_sub(1));+ let (Some(a), Some(b)) = (poly.get(hi - 1), poly.get(hi)) else {+ return Err(KernelError::Failed("match: chain".into()));+ };+ let (Some(&lo), Some(&up)) = (cum.get(hi - 1), cum.get(hi)) else {+ return Err(KernelError::Failed("match: chain".into()));+ };+ let span = up - lo;+ let t = if span > 1e-12 { (half - lo) / span } else { 0.0 };+ Ok(*a + (*b - *a) * t)+}++/// How far `p` is from a polyline.+fn chain_distance(poly: &[Vec3], p: Vec3) -> f64 {+ let mut best = f64::INFINITY;+ for w in poly.windows(2) {+ let (Some(a), Some(b)) = (w.first(), w.get(1)) else { continue };+ let d = b.dist(*a);+ let t = if d > 1e-12 { ((p - *a).dot(*b - *a) / (d * d)).clamp(0.0, 1.0) } else { 0.0 };+ best = best.min(p.dist(*a + (*b - *a) * t));+ }+ best+}++/// The side of the face's own parameter rectangle the picked chain sits nearest.+fn nearest_side(face: &mt::Face, chain: &[mt::Edge]) -> Result<Side> {+ let surf = face.surface();+ let ranges = ranges(face)?;+ let poly = chain_polyline(chain)?;+ /// Samples of each side used to tell which one the chain runs along.+ const SAMPLES: usize = 17;+ let mut best: Option<(f64, Side)> = None;+ for side in Side::ALL {+ let mut total = 0.0;+ for k in 0..SAMPLES {+ let t = k as f64 / (SAMPLES - 1) as f64;+ total += chain_distance(&poly, Side::at(&surf, &ranges, side, t));+ }+ let mean = total / SAMPLES as f64;+ if best.is_none_or(|(b, _)| mean < b) {+ best = Some((mean, side));+ }+ }+ best.map(|(_, s)| s).ok_or_else(|| KernelError::Failed("match: the face has no sides".into()))+}++/// The face's own edges that run along a side of its parameter rectangle, chained head to tail.+/// A match keeps the far side's own edges, so they must be a chain that runs on.+fn side_edges(face: &mt::Face, side: Side, tol: f64) -> Result<Vec<mt::Edge>> {+ let surf = face.surface();+ let ranges = ranges(face)?;+ let (fixed, along) = side.fixed_and_along(ranges[0], ranges[1]);+ let band = (along.1 - along.0).abs().max(1e-12) * 1e-3;+ let mut pool: Vec<mt::Edge> = Vec::new();+ for e in face.edge_iter() {+ let c = e.curve();+ let (t0, t1) = c.range_tuple();+ let p = from_p3(c.subs(0.5 * (t0 + t1)));+ let Some((u, v)) = surf.search_nearest_parameter(p3(p), None, 100) else { continue };+ if from_p3(surf.subs(u, v)).dist(p) > tol {+ continue;+ }+ let got = if side.is_u() { u } else { v };+ if (got - fixed).abs() <= band {+ pool.push(e.clone());+ }+ }+ if pool.is_empty() {+ return Err(KernelError::Invalid("the face has no edges along the boundary a match would keep".into()));+ }+ let first = pool.remove(0);+ let mut chain = vec![first];+ let mut end = match chain.first() {+ Some(e) => e.back().clone(),+ None => return Err(KernelError::Failed("match: chain".into())),+ };+ while let Some(k) = pool.iter().position(|e| e.front().id() == end.id() || e.back().id() == end.id()) {+ let e = pool.remove(k);+ let e = if e.front().id() == end.id() { e } else { e.inverse() };+ end = e.back().clone();+ chain.push(e);+ }+ let mut start = match chain.first() {+ Some(e) => e.front().clone(),+ None => return Err(KernelError::Failed("match: chain".into())),+ };+ while let Some(k) = pool.iter().position(|e| e.front().id() == start.id() || e.back().id() == start.id()) {+ let e = pool.remove(k);+ let e = if e.back().id() == start.id() { e } else { e.inverse() };+ start = e.front().clone();+ chain.insert(0, e);+ }+ if !pool.is_empty() {+ return Err(KernelError::Invalid("the face's edges along that boundary do not run on from one another".into()));+ }+ Ok(chain)+}++/// The faces of `target` that meet the chain and whose tangent plane holds the leave direction,+/// best first: the face a match continues from, and the ones it might have been read from.+fn support_faces(target: &Body, chain: &[mt::Edge], leave: Vec3) -> Result<Vec<(mt::Face, f64)>> {+ let mid = chain_mid(chain)?;+ let tol = target.size() * 1e-6 + 1e-9;+ let mut out: Vec<(mt::Face, f64)> = Vec::new();+ for face in target.solid.face_iter() {+ if !chain.iter().all(|e| face.edge_iter().any(|f| f.id() == e.id())) {+ continue;+ }+ let Some((n, d)) = normal_near(face, mid) else { continue };+ if d > tol {+ continue;+ }+ let score = (leave - n * leave.dot(n)).len();+ if score.is_finite() && score >= 0.2 {+ out.push((face.clone(), score));+ }+ }+ if out.is_empty() {+ return Err(KernelError::Invalid(+ "no face of the target holds the picked edges in the direction the match leaves in: pick the chain of a face the surface can continue"+ .into(),+ ));+ }+ out.sort_by(|a, b| b.1.total_cmp(&a.1));+ Ok(out)+}++/// The highest order the target itself holds along the chain: every face that meets those edges+/// and whose tangent plane holds the leave direction reads the chain's shape from its own+/// surface, and where two of them part company the target's own geometry jumps at the seam.+fn supply_order(candidates: &[(mt::Face, f64)], chain: &[mt::Edge], leave: Vec3, size: f64) -> Result<Continuity> {+ let Some((first, best)) = candidates.first() else {+ return Err(KernelError::Invalid("no face of the target holds the picked edges".into()));+ };+ let keep: Vec<&mt::Face> = candidates.iter().filter(|(_, s)| *s >= 0.5 * best).map(|(f, _)| f).collect();+ let mut order = Continuity::G3;+ if keep.len() < 2 {+ return Ok(order);+ }+ let primary: Vec<Frame> = bridge::frames(first, chain, leave, STATIONS)?;+ for other in keep.iter().skip(1) {+ // A face that cannot be read along the whole chain says nothing here: the face the match+ // is built on is the one that must be able to supply it.+ let Ok(other_frames) = bridge::frames(other, chain, leave, STATIONS) else { continue };+ let mut worst_deg = 0.0f64;+ let mut worst = 0.0f64;+ let mut worst_change = 0.0f64;+ for (a, b) in primary.iter().zip(&other_frames) {+ if let (Some((na, _)), Some((nb, _))) = (normal_near(first, a.p), normal_near(other, b.p)) {+ worst_deg = worst_deg.max(angle_deg(na, nb));+ }+ let scale = a.bend.len().max(b.bend.len()).max(1.0 / size);+ worst = worst.max((a.bend - b.bend).len() / scale);+ let scale3 = a.bend_change.len().max(b.bend_change.len()).max(scale / size);+ worst_change = worst_change.max((a.bend_change - b.bend_change).len() / scale3);+ }+ if worst_deg > SUPPLY_DEG {+ order = Continuity::G0;+ }+ if worst > SUPPLY_REL && order.conditions() > 1 {+ order = Continuity::G1;+ }+ if worst_change > SUPPLY_BEND_REL && order.conditions() > 2 {+ order = Continuity::G2;+ }+ }+ Ok(order)+}++/// The acute angle between two directions, in degrees. For two surfaces' normals this is the+/// angle between their tangent planes: a sheet has no inside, so which way a normal points says+/// nothing about whether the surfaces meet smoothly.+fn angle_deg(a: Vec3, b: Vec3) -> f64 {+ let d = a.dot(b) / (a.len() * b.len());+ if !d.is_finite() {+ return f64::NAN;+ }+ d.abs().clamp(0.0, 1.0).acos().to_degrees()+}++/// The geometric shape of a surface curve at a point from its first three derivatives along the+/// curve: the same statement [`crate::bridge`] makes of a support surface — the unit tangent, the+/// curvature vector, and the arclength derivative of that curvature vector.+fn shape(d1: Vec3, d2: Vec3, d3: Vec3) -> Result<(Vec3, Vec3, Vec3)> {+ let sigma = d1.len();+ if !(sigma > 1e-12) || !sigma.is_finite() {+ return Err(KernelError::Failed("match: the seam's cross-section does not move".into()));+ }+ let t = d1 * (1.0 / sigma);+ let tp = d2 * (1.0 / sigma) - d1 * (d1.dot(d2) / (sigma * sigma * sigma));+ let nn = d2 - t * d2.dot(t);+ let np = d3 - t * d3.dot(t) - tp * d2.dot(t) - t * d2.dot(tp);+ let kappa = np * (sigma * sigma) - nn * (2.0 * d1.dot(d2));+ let change = kappa * (1.0 / (sigma.powi(5)));+ if ![t, nn, change].into_iter().all(Vec3::is_finite) {+ return Err(KernelError::Failed("match: the seam's shape is not finite".into()));+ }+ Ok((t, nn * (1.0 / (sigma * sigma)), change))+}++/// The shape of a face's surface along its cross direction at the station `t`, read inwards from+/// the boundary `near` over five one-sided samples: the point, the unit tangent, the curvature+/// vector and the change of that curvature. The same finite difference [`crate::bridge::frames`]+/// reads a support surface with, so that a rebuilt seam can be compared with what it matched.+fn seam_shape(surf: &mt::Surface, ranges: &[(f64, f64); 2], near: Side, t: f64) -> Result<(Vec3, Vec3, Vec3, Vec3)> {+ let (station, cross, at_start) = if near.is_u() {+ (ranges[1].0 + (ranges[1].1 - ranges[1].0) * t, ranges[0], near == Side::U0)+ } else {+ (ranges[0].0 + (ranges[0].1 - ranges[0].0) * t, ranges[1], near == Side::V0)+ };+ let span = (cross.1 - cross.0).abs().max(1e-12);+ let h = span * 1e-3;+ let c0 = if at_start { cross.0 } else { cross.1 };+ let sgn = if at_start { 1.0 } else { -1.0 };+ let at = |x: f64| if near.is_u() { from_p3(surf.subs(x, station)) } else { from_p3(surf.subs(station, x)) };+ let q: Vec<Vec3> = (0..5).map(|k| at(c0 + sgn * k as f64 * h)).collect();+ let (Some(&q0), Some(&q1), Some(&q2), Some(&q3), Some(&q4)) = (q.first(), q.get(1), q.get(2), q.get(3), q.get(4)) else {+ return Err(KernelError::Failed("match: seam samples".into()));+ };+ let d1 = (q0 * -25.0 + q1 * 48.0 + q2 * -36.0 + q3 * 16.0 + q4 * -3.0) * (sgn / (12.0 * h));+ let d2 = (q0 * 35.0 + q1 * -104.0 + q2 * 114.0 + q3 * -56.0 + q4 * 11.0) * (1.0 / (12.0 * h * h));+ let d3 = (q0 * -5.0 + q1 * 18.0 + q2 * -24.0 + q3 * 14.0 + q4 * -3.0) * (sgn / (2.0 * h * h * h));+ let (t, bend, change) = shape(d1, d2, d3)?;+ Ok((q0, t, bend, change))+}++/// How far the rebuilt surface strays from the original one: the root mean square of the+/// distances from a grid of its samples to the original surface.+fn deviation(made: &mt::Face, original: &mt::Face) -> Result<f64> {+ let (surf, os) = (made.surface(), original.surface());+ let ranges = ranges(made)?;+ let mut sum = 0.0f64;+ let mut n = 0usize;+ for i in 0..GRID {+ for j in 0..GRID {+ let u = ranges[0].0 + (ranges[0].1 - ranges[0].0) * i as f64 / (GRID - 1) as f64;+ let v = ranges[1].0 + (ranges[1].1 - ranges[1].0) * j as f64 / (GRID - 1) as f64;+ let q = from_p3(surf.subs(u, v));+ let Some((a, b)) = os.search_nearest_parameter(p3(q), None, 100) else { continue };+ let d = from_p3(os.subs(a, b)).dist(q);+ if d.is_finite() {+ sum += d * d;+ n += 1;+ }+ }+ }+ if n == 0 {+ return Err(KernelError::Failed("match: the original surface cannot be sampled".into()));+ }+ Ok((sum / n as f64).sqrt())+}++#[cfg(test)]+#[path = "matchsurf_tests.rs"]+mod tests;diff --git a/crates/kernel/src/matchsurf_tests.rs b/crates/kernel/src/matchsurf_tests.rsnew file mode 100644index 0000000000..f99066be46--- /dev/null+++ b/crates/kernel/src/matchsurf_tests.rs@@ -0,0 +1,225 @@+//! Tests of surface matching: a sheet is rebuilt to meet a cylinder's wall up to G1, G2 and G3,+//! its seam, its far boundary and its interior are measured, and what cannot be matched is+//! refused.++use super::*;+use crate::bridge::{Continuity, Frame};+use crate::build::SEAM_ANGLE;+use crate::{cylinder, stitch};+use solidcraft_geom::Vec3;+use truck_modeling as mt;++/// The radius of the cylinder a sheet is matched to, the radius the sheet starts at, its height,+/// and how far round the cylinder the sheet runs.+const R_TARGET: f64 = 10.0;+const R_SHEET: f64 = 11.0;+const HEIGHT: f64 = 30.0;+const SPAN: f64 = 0.6;++/// A point on the vertical line at radius `r`, angle `a`, height `z` (Z up).+fn at(a: f64, r: f64, z: f64) -> Vec3 {+ Vec3::new(r * a.cos(), r * a.sin(), z)+}++/// The outward radial and the circumferential unit directions at the angle `a`.+fn radial(a: f64) -> Vec3 {+ Vec3::new(a.cos(), a.sin(), 0.0)+}++fn circ(a: f64) -> Vec3 {+ Vec3::new(-a.sin(), a.cos(), 0.0)+}++/// A cylindrical sheet of radius `r` between the angles `a0` and `a1`, `stations` high: the body+/// a match rebuilds. Its near boundary is the vertical line at `a0`, its far boundary at `a1`.+fn cylinder_sheet(r: f64, a0: f64, a1: f64, stations: usize) -> Body {+ let mut a = Vec::new();+ let mut b = Vec::new();+ for i in 0..stations {+ let z = HEIGHT * i as f64 / (stations - 1) as f64;+ a.push(Frame { p: at(a0, r, z), leave: circ(a0), bend: radial(a0) * (-1.0 / r), bend_change: Vec3::ZERO });+ b.push(Frame { p: at(a1, r, z), leave: circ(a1) * -1.0, bend: radial(a1) * (-1.0 / r), bend_change: Vec3::ZERO });+ }+ bridge::bridge(&a, &b, [Continuity::G2, Continuity::G2], [0.0, 0.0]).unwrap()+}++/// The stock cylinder, and two picks on the vertical seam line of its wall.+fn cylinder_and_picks() -> (Body, [Vec3; 2]) {+ let c = cylinder(Vec3::ZERO, Vec3::new(0.0, 0.0, 1.0), R_TARGET, HEIGHT).unwrap();+ (c, [at(SEAM_ANGLE, R_TARGET, 6.0), at(SEAM_ANGLE, R_TARGET, 24.0)])+}++/// The sheet of the usual shape, and a pick on its near boundary.+fn sheet_and_pick() -> (Body, [Vec3; 1]) {+ (cylinder_sheet(R_SHEET, SEAM_ANGLE, SEAM_ANGLE + SPAN, 9), [at(SEAM_ANGLE, R_SHEET, HEIGHT * 0.5)])+}++/// The middle of the edge of `body`'s first face nearest `p`.+fn edge_at(body: &Body, p: Vec3) -> mt::Edge {+ let face = body.solid.face_iter().next().unwrap();+ let mut best: Option<(f64, mt::Edge)> = None;+ for e in face.edge_iter() {+ let c = e.curve();+ let (t0, t1) = c.range_tuple();+ let m = from_p3(c.subs(0.5 * (t0 + t1)));+ let d = m.dist(p);+ if best.as_ref().is_none_or(|(b, _)| d < *b) {+ best = Some((d, e.clone()));+ }+ }+ best.unwrap().1+}++/// How far the rebuilt face's far boundary lies from the original one, in mm: the far row of the+/// rebuilt surface sampled at its own stations, against the original boundary edge's own points.+fn far_drift(made: &Body, sheet: &Body, far_mid: Vec3) -> f64 {+ let face = made.solid.face_iter().next().unwrap();+ let surf = face.surface();+ let (Some((u0, u1)), Some((_, v1))) = surf.try_range_tuple() else { panic!("unbounded") };+ let edge = edge_at(sheet, far_mid);+ let poly = chain_polyline(&[edge]).unwrap();+ let mut worst = 0.0f64;+ for k in 0..=8 {+ let p = from_p3(surf.subs(u0 + (u1 - u0) * k as f64 / 8.0, v1));+ worst = worst.max(chain_distance(&poly, p));+ }+ worst+}++/// What the rebuilt sheet does at the normalized station `t` of its matching boundary: the+/// point, the unit tangent, the curvature vector and the change of that curvature, read off the+/// finished surface (never from the construction).+fn seam_at(body: &Body, t: f64) -> (Vec3, Vec3, Vec3, Vec3) {+ let face = body.solid.face_iter().next().unwrap();+ let ranges = super::ranges(face).unwrap();+ super::seam_shape(&face.surface(), &ranges, Side::V0, t).unwrap()+}++/// The stations a seam is measured at, as fractions of its length.+fn stations() -> Vec<f64> {+ (0..9).map(|k| k as f64 / 8.0).collect()+}++#[test]+fn a_g2_match_meets_a_cylinder_with_its_own_curvature() {+ let (target, picks) = cylinder_and_picks();+ let (sheet, pick) = sheet_and_pick();+ let made = match_surface(&sheet, &pick, &target, &picks, Continuity::G2).unwrap();+ // The rebuilt boundary has moved onto the picked line: the seam is on the cylinder's wall.+ assert!(seam_at(&made, 0.5).0.dist(at(SEAM_ANGLE, R_TARGET, HEIGHT * 0.5)) < 1e-6, "the seam is on the picked line");+ let (gap, deg, order) = seam_continuity(&made, &target, &picks).unwrap();+ println!("g2: gap {gap:e} mm, normal {deg:e} deg, order {order:?}");+ assert!(gap < 1e-6, "position gap {gap:e}");+ assert!(deg < 0.01, "normal angle {deg}");+ assert!(order.conditions() >= Continuity::G2.conditions(), "{order:?}");+ // The curvature the cylinder bends with along the seam: matched to a thousandth of itself.+ let want = radial(SEAM_ANGLE) * (-1.0 / R_TARGET);+ let mut worst = 0.0f64;+ for t in stations() {+ worst = worst.max(seam_at(&made, t).2.dist(want) * R_TARGET);+ }+ println!("g2: worst curvature jump {worst:e} of the cylinder's own");+ assert!(worst < 1e-3, "curvature jump {worst:e}");+ // The far boundary did not move: it is built through the original boundary's own points and+ // stays on the original edge between them to round-off.+ let far = at(SEAM_ANGLE + SPAN, R_SHEET, HEIGHT * 0.5);+ let drift = far_drift(&made, &sheet, far);+ println!("g2: far boundary drift {drift:e} mm");+ assert!(drift < 1e-9, "the far boundary drifted {drift:e} mm");+ // The interior stays near the original: the crowning that leaves it closest.+ let (face, original) = (made.solid.face_iter().next().unwrap().clone(), sheet.solid.face_iter().next().unwrap().clone());+ let stray = deviation(&face, &original).unwrap();+ println!("g2: interior stray {stray:.6} mm rms");+ // The seam moved 1 mm, so the face cannot be closer than that at the seam itself: over the+ // whole face the root mean square distance is well under half of it.+ assert!(stray < 0.6, "the interior strays {stray} mm");+}++#[test]+fn a_g1_match_holds_the_tangent_and_leaves_the_curvature_free() {+ let (target, picks) = cylinder_and_picks();+ let (sheet, pick) = sheet_and_pick();+ let made = match_surface(&sheet, &pick, &target, &picks, Continuity::G1).unwrap();+ let (gap, deg, order) = seam_continuity(&made, &target, &picks).unwrap();+ let want = radial(SEAM_ANGLE) * (-1.0 / R_TARGET);+ let worst = stations().into_iter().map(|t| seam_at(&made, t).2.dist(want) * R_TARGET).fold(0.0f64, f64::max);+ println!("g1: gap {gap:e} mm, normal {deg:e} deg, order {order:?}, curvature jump {worst:e}");+ assert!(gap < 1e-6 && deg < 0.01, "position {gap:e}, normal {deg}");+ assert_eq!(order, Continuity::G1, "a tangent match leaves the curvature free");+ assert!(worst > 1e-3, "a G1 match need not hold the curvature: {worst:e}");+ // The far boundary is kept whatever the order.+ let far = at(SEAM_ANGLE + SPAN, R_SHEET, HEIGHT * 0.5);+ assert!(far_drift(&made, &sheet, far) < 1e-9);+}++#[test]+fn a_g3_match_holds_the_change_of_curvature() {+ let (target, picks) = cylinder_and_picks();+ let (sheet, pick) = sheet_and_pick();+ let made = match_surface(&sheet, &pick, &target, &picks, Continuity::G3).unwrap();+ let (gap, deg, order) = seam_continuity(&made, &target, &picks).unwrap();+ let want = radial(SEAM_ANGLE) * (-1.0 / R_TARGET);+ let (mut bend, mut change) = (0.0f64, 0.0f64);+ for t in stations() {+ let (_, _, b, c) = seam_at(&made, t);+ bend = bend.max(b.dist(want) * R_TARGET);+ // A cylinder's curvature does not change in its own surface: the normal part of the+ // change of curvature across the seam must be zero too.+ change = change.max(c.dot(radial(SEAM_ANGLE)).abs() * R_TARGET * R_TARGET);+ }+ println!("g3: gap {gap:e} mm, normal {deg:e} deg, order {order:?}, curvature jump {bend:e}, change {change:e}");+ assert!(gap < 1e-6 && deg < 0.01, "position {gap:e}, normal {deg}");+ assert_eq!(order, Continuity::G3, "the seam holds the change of curvature");+ assert!(bend < 1e-3, "curvature jump {bend:e}");+ assert!(change < 1e-3, "change of curvature {change:e}");+ let far = at(SEAM_ANGLE + SPAN, R_SHEET, HEIGHT * 0.5);+ assert!(far_drift(&made, &sheet, far) < 1e-9);+}++#[test]+fn a_match_refuses_what_it_cannot_hold() {+ let (target, picks) = cylinder_and_picks();+ let (sheet, pick) = sheet_and_pick();+ // No pick on the body's face, no pick on the target's edges, and picks that are not numbers.+ assert!(match_surface(&sheet, &[], &target, &picks, Continuity::G1).is_err());+ assert!(match_surface(&sheet, &[Vec3::new(0.0, 0.0, 100.0)], &target, &picks, Continuity::G1).is_err());+ assert!(match_surface(&sheet, &[Vec3::new(f64::NAN, 0.0, 0.0)], &target, &picks, Continuity::G1).is_err());+ assert!(match_surface(&sheet, &vec![Vec3::ZERO; MAX_PICKS + 1], &target, &picks, Continuity::G1).is_err());+ assert!(match_surface(&sheet, &pick, &target, &[], Continuity::G1).is_err());+ // A pick that is not on the target at all, and one in the middle of its wall: no chain there.+ assert!(match_surface(&sheet, &pick, &target, &[Vec3::new(100.0, 0.0, 15.0)], Continuity::G1).is_err());+ assert!(match_surface(&sheet, &pick, &target, &[Vec3::new(10.0, 0.0, 15.0)], Continuity::G1).is_err());+ // A body that is not a surface: the stock cylinder itself.+ assert!(match_surface(&target, &[at(SEAM_ANGLE, R_TARGET, 15.0)], &target, &picks, Continuity::G1).is_err());+}++#[test]+fn a_target_that_jumps_in_curvature_supplies_only_g1() {+ // Two sheets of the target meet along a line with the same tangent plane but different+ // curvature: a cylinder's wall and the plane tangent to it there. The target itself does not+ // hold the curvature along that line, so no match may be told to.+ let wall = cylinder_sheet(R_TARGET, SEAM_ANGLE, SEAM_ANGLE + 0.5, 5);+ let mut a = Vec::new();+ let mut b = Vec::new();+ for i in 0..5 {+ let z = HEIGHT * i as f64 / 4.0;+ let (p, q) = (at(SEAM_ANGLE, R_TARGET, z), at(SEAM_ANGLE, R_TARGET, z) + circ(SEAM_ANGLE) * 8.0);+ a.push(Frame { p, leave: circ(SEAM_ANGLE), bend: Vec3::ZERO, bend_change: Vec3::ZERO });+ b.push(Frame { p: q, leave: circ(SEAM_ANGLE) * -1.0, bend: Vec3::ZERO, bend_change: Vec3::ZERO });+ }+ let plane = bridge::bridge(&a, &b, [Continuity::G2, Continuity::G2], [0.0, 0.0]).unwrap();+ let joined = stitch(&[&wall, &plane], 1e-6).unwrap();+ assert_eq!(joined.solid.face_iter().count(), 2, "the two sheets sewed into one body");+ let picks = [at(SEAM_ANGLE, R_TARGET, 6.0), at(SEAM_ANGLE, R_TARGET, 24.0)];+ let (sheet, pick) = sheet_and_pick();+ // The seam is smooth enough to match, so G1 goes through; the curvature jumps there, so G2+ // and G3 do not.+ assert!(match_surface(&sheet, &pick, &joined, &picks, Continuity::G1).is_ok());+ let err = match_surface(&sheet, &pick, &joined, &picks, Continuity::G2).unwrap_err().to_string();+ println!("refused g2: {err}");+ assert!(err.contains("only g1"), "{err}");+ assert!(match_surface(&sheet, &pick, &joined, &picks, Continuity::G3).is_err());+ // The plain cylinder, whose two wall faces are the same surface, supplies G3.+ let (target, plain_picks) = cylinder_and_picks();+ assert!(match_surface(&sheet, &pick, &target, &plain_picks, Continuity::G3).is_ok());+}diff --git a/crates/sketch/src/model.rs b/crates/sketch/src/model.rsindex 493df7b011..655818777c 100644--- a/crates/sketch/src/model.rs+++ b/crates/sketch/src/model.rs@@ -1289,8 +1289,8 @@ impl Sketch {}/// Exact boundary segments of a free-form curve: ellipses as four conics, conics, fit- /// splines and control splines up to degree 3 as Béziers. None for other curves (and for- /// higher-degree splines, which stay polylines).+ /// splines and control splines up to `MAX_BEZIER_DEGREE` as Béziers. None for other curves+ /// (and for higher-degree splines, which stay polylines).pub fn exact_segs(&self, ci: usize) -> Option<Vec<Seg2>> {let cu = self.curves.get(ci)?;let pt = |i: &usize| self.point(*i);@@ -1326,6 +1326,17 @@ impl Sketch {}}+ /// The exact [`Seg2`] pieces of a curve of any kind, in the curve's own direction of travel:+ /// lines, circles and arcs from their analytic form, free-form curves through+ /// [`Sketch::exact_segs`]. Empty for a curve with no exact pieces (a spline above+ /// `solidcraft_geom::MAX_BEZIER_DEGREE`).+ pub fn exact_pieces(&self, ci: usize) -> Vec<Seg2> {+ match self.exact_segs(ci) {+ Some(segs) => segs,+ None => self.segs(ci),+ }+ }+/// Polyline of a free-form curve (ellipse, spline, conic); other curves: their segments'/// polylines.pub fn polyline(&self, ci: usize) -> Vec<Vec2> {@@ -1375,8 +1386,11 @@ impl Sketch {"e"}CurveKind::Spline { pts, control, degree, periodic } => {- if pts.len() < 2 || pts.len() > crate::curves::MAX_SPLINE_POINTS || !(1..=7).contains(degree) {- return Err(SketchError::Invalid("a spline needs 2 to 500 points and degree 1 to 7".into()));+ if pts.len() < 2 || pts.len() > crate::curves::MAX_SPLINE_POINTS || !(1..=solidcraft_geom::MAX_BEZIER_DEGREE as u8).contains(degree) {+ return Err(SketchError::Invalid(format!(+ "a spline needs 2 to 500 points and degree 1 to {}",+ solidcraft_geom::MAX_BEZIER_DEGREE+ )));}if *periodic {if *control || *degree != 3 {diff --git a/docs/screenshots/class-a-boundary.png b/docs/screenshots/class-a-boundary.pngnew file mode 100644index 0000000000..e5f436e963Binary files /dev/null and b/docs/screenshots/class-a-boundary.png differ