Skip to content

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

Wave 267/509: geom: fill_matched, a height field G1/G2 to the faces beside its loop (and 2 more)

jyviko57b4ce645360
diff --git a/crates/engine/src/schema/diagnostics_tests.rs b/crates/engine/src/schema/diagnostics_tests.rs
index df0f343bc5..23cbef048f 100644
--- a/crates/engine/src/schema/diagnostics_tests.rs
+++ b/crates/engine/src/schema/diagnostics_tests.rs
@@ -45,13 +45,18 @@ fn diagnostics_profile_reports_commands_features_and_the_kernel() {
let dir = std::env::temp_dir().join(format!("solidcraft-profile-trace-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("trace.json").to_string_lossy().to_string();
+ let since_trace = std::time::Instant::now();
let t = s.execute("diagnostics.profile", &json!({"trace": path, "enabled": false, "reset": true})).unwrap();
assert_eq!((t["trace"].as_str(), t["enabled"].as_bool()), (Some(path.as_str()), Some(false)));
let trace: serde_json::Value = serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap();
assert!(trace["traceEvents"].as_array().unwrap().iter().any(|e| e["ph"] == "X" && e["name"] == "solid.box"), "{trace}");
- // Only the call that reset it (its own span ends after the reset).
+ // Other tests run commands (this one among them) while it records, so the rows after the
+ // reset can hold theirs too. The wall time shows the reset: it starts again at the call that
+ // reset it, whose own span ends after the reset and is the one row certain to be there.
let after = s.execute("diagnostics.profile", &json!({})).unwrap();
- let names: Vec<&str> = after["rows"].as_array().unwrap().iter().filter_map(|r| r["name"].as_str()).collect();
- assert_eq!(names, ["diagnostics.profile"], "{after}");
+ assert!(after["wall_ms"].as_f64().unwrap() <= since_trace.elapsed().as_secs_f64() * 1000.0 + 0.001, "{after}");
+ let rows = after["rows"].as_array().unwrap();
+ assert!(rows.iter().any(|x| x["category"] == "command" && x["name"] == "diagnostics.profile"), "{after}");
+ assert_eq!(after["enabled"], json!(false), "{after}");
let _ = std::fs::remove_dir_all(&dir);
}
diff --git a/crates/geom/src/fill.rs b/crates/geom/src/fill.rs
index 1ce368fa0e..5590ec400e 100644
--- a/crates/geom/src/fill.rs
+++ b/crates/geom/src/fill.rs
@@ -166,10 +166,25 @@ enum Fit {
Exhausted(f64),
}
-/// One round of [`fill_loop`]: fit the points `fit`, check every point of `all` (the loop in
-/// order, `fit` among them).
-fn fit_once(fit: &[Vec3], all: &[Vec3], tol: f64, crown: f64) -> SplineResult<Fit> {
+/// The plane a loop's height field stands on (see [`fill_loop`]): through the fitted points'
+/// centroid `o`, normal `n` by Newell's method turned so that its largest component is positive,
+/// first axis `x` towards the fitted point farthest from the centroid in the plane, `y = n × x`;
+/// and whether the points run counter-clockwise about `n`.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct LoopFrame {
+ pub(crate) o: Vec3,
+ pub(crate) x: Vec3,
+ pub(crate) y: Vec3,
+ pub(crate) n: Vec3,
+ pub(crate) counter_clockwise: bool,
+}
+
+/// The [`LoopFrame`] of the loop of points `fit`.
+pub(crate) fn loop_frame(fit: &[Vec3]) -> SplineResult<LoopFrame> {
let m = fit.len();
+ if m < 3 {
+ return invalid("a loop needs three points");
+ }
let o = fit.iter().fold(Vec3::ZERO, |a, p| a + *p) / m as f64;
let at = |k: usize| fit.get(k % m).copied().unwrap_or(Vec3::ZERO);
let area = (0..m).fold(Vec3::ZERO, |a, k| a + (at(k) - o).cross(at(k + 1) - o));
@@ -206,6 +221,14 @@ fn fit_once(fit: &[Vec3], all: &[Vec3], tol: f64, crown: f64) -> SplineResult<Fi
let far = far.map(flat).unwrap_or(Vec3::ZERO);
let x = far.normalized().ok_or_else(|| SplineError::Invalid("the loop has no extent in its plane".into()))?;
let y = n.cross(x);
+ Ok(LoopFrame { o, x, y, n, counter_clockwise })
+}
+
+/// One round of [`fill_loop`]: fit the points `fit`, check every point of `all` (the loop in
+/// order, `fit` among them).
+fn fit_once(fit: &[Vec3], all: &[Vec3], tol: f64, crown: f64) -> SplineResult<Fit> {
+ let m = fit.len();
+ let LoopFrame { o, x, y, n, counter_clockwise } = loop_frame(fit)?;
let project = |pts: &[Vec3]| -> (Vec<[f64; 2]>, Vec<f64>) {
(pts.iter().map(|p| [(*p - o).dot(x), (*p - o).dot(y)]).collect(), pts.iter().map(|p| (*p - o).dot(n)).collect())
};
@@ -495,7 +518,7 @@ fn segment_meets_rect(p: [f64; 2], q: [f64; 2], lo: [f64; 2], hi: [f64; 2]) -> b
}
/// Refuse a loop that does not bound a height field over its plane (see [`fill_loop`]).
-fn check_projectable(points: &[Vec3], uv: &[[f64; 2]]) -> SplineResult<()> {
+pub(crate) fn check_projectable(points: &[Vec3], uv: &[[f64; 2]]) -> SplineResult<()> {
let m = uv.len();
let q = |k: usize| uv.get(k % m).copied().unwrap_or([0.0; 2]);
let p = |k: usize| points.get(k % m).copied().unwrap_or(Vec3::ZERO);
@@ -707,7 +730,7 @@ impl Grid {
/// The surface of the net `heights` over the plane `o`, `x`, `y`, `n`: control point `(i, j)`
/// at the knot averages `(ξᵢ, ηⱼ)` in the plane, `heights[j·count[0] + i]` along `n`.
- fn surface(&self, heights: &[f64], o: Vec3, x: Vec3, y: Vec3, n: Vec3) -> SplineResult<NurbsSurface> {
+ pub(crate) fn surface(&self, heights: &[f64], o: Vec3, x: Vec3, y: Vec3, n: Vec3) -> SplineResult<NurbsSurface> {
let [cu, cv] = self.count;
let mut ctrl = Vec::with_capacity(cu * cv);
for j in 0..cv {
@@ -755,7 +778,7 @@ impl Band {
}
/// Solve `A·x = b` by banded Cholesky factorisation `A = Uᵀ·U`; an error when `A` is not
/// positive definite.
- fn solve(self, b: Vec<f64>) -> SplineResult<Vec<f64>> {
+ pub(crate) fn solve(self, b: Vec<f64>) -> SplineResult<Vec<f64>> {
self.factor()?.substitute(b)
}
diff --git a/crates/geom/src/fill_matched.rs b/crates/geom/src/fill_matched.rs
new file mode 100644
index 0000000000..a8b6e8c745
--- /dev/null
+++ b/crates/geom/src/fill_matched.rs
@@ -0,0 +1,504 @@
+//! Filling a closed loop with one height field that meets the faces beside the loop with G1 or
+//! G2: the surface of [`crate::fill::fill_loop`] (a bicubic B-spline height field over the loop's
+//! plane, so its parameters are plane coordinates and every edge's pcurve is the edge projected
+//! onto that plane, exactly), fitted to the faces' derivatives as well as to the loop.
+//!
+//! The formulation (Piegl & Tiller, *The NURBS Book*, §9.4.1 least squares; do Carmo,
+//! *Differential Geometry of Curves and Surfaces*, §3-3 for the second fundamental form of a
+//! graph):
+//!
+//! - **The plane and grid** are [`crate::fill::fill_loop`]'s: the surface is
+//! `S(u, v) = o + u·x + v·y + h(u, v)·n` with `h` a bicubic B-spline on a uniform grid over the
+//! projected loop's box, the heights its unknowns.
+//! - **The conditions** at each station (a point of the loop with the face beside it) are linear
+//! in the heights, since every quantity of a graph is a derivative of `h`:
+//! - G0: `h(u, v)` is the station's height.
+//! - G1: the face's unit normal `N` (turned to `n`'s side) is the graph's when
+//! `h_u = −N·x / N·n` and `h_v = −N·y / N·n`.
+//! - G2: with G1, the surfaces share the curve and its tangent plane, so they agree to the
+//! second order exactly when their normal curvatures across the curve agree: along the
+//! direction `w` the face leaves the loop in (`a = w·x`, `b = w·y`),
+//! `(a² h_uu + 2ab h_uv + b² h_vv) · N·n = κ`, `κ` the face's normal curvature along `w`
+//! (its curvature vector `bend` against `N`).
+//!
+//! Each row is weighed to a length on the grid's scale (the G1 rows times a cell, the G2 rows
+//! times a cell squared), and the heights minimise their squared misfit plus a small multiple
+//! of the thin-plate energy ([`FAIRNESS`]), which decides what the conditions leave free.
+//! - **At a corner** of the loop the two faces' conditions meet, and where their curvatures
+//! across the corner differ (a round ending on a plane: the round's section has the round's
+//! curvature where it reaches the plane, which is flat across its own curve) no surface is G2
+//! to both there: the surface's curvature is continuous, and has to pass from one face's to the
+//! other's. A plane's G2 with G1 makes the surface flat to the second order all along its
+//! curve, so the passage is a stiff one, and asked over a few cells it pulls the surface off
+//! the loop along the whole side. The corner's own station holds the position only; the G2
+//! rows fade in over [`FADE_SHARE`] of the run from each corner to the next (a smoothstep of
+//! the distance along the loop), a stretch of the loop's own, which finer grids then resolve,
+//! and hold everywhere else. G1 rows fade likewise from a corner whose faces' tangent planes
+//! disagree (`clash`), where no surface is G1 to both.
+//! - **Grids** of 4 to [`MAX_MATCHED_SPANS`] spans across the box's longer side are tried in turn,
+//! with denser sampling when a grid's cells are finer than twice the stations' step: the first
+//! whose surface is within `tol` of every station, whose normal is within `angle_tol` of the
+//! face's at every G1/G2 station clear of clashing corners, and whose normal curvature across
+//! the loop is within `curvature_tol` of the face's at every G2 station clear of the corners'
+//! fades, is the fill. Otherwise "not supported yet", with how close the best grid came.
+//!
+//! A loop that is not the boundary of a height field over its plane, or a face beside it that
+//! stands along the plane's normal, is refused, never filled with wrong geometry. Input is
+//! hostile: sizes are capped and every evaluation checked; nothing here panics.
+
+use crate::Vec3;
+use crate::bspline::{SplineError, SplineResult, invalid};
+use crate::fill::{Band, Grid, LoopFill, LoopFrame, MAX_LOOP_POINTS, SMOOTHNESS, check_projectable, loop_frame};
+use crate::fill_general::Station;
+
+/// Most spans of the height field across the box's longer side.
+pub const MAX_MATCHED_SPANS: usize = 128;
+/// Fewest spans (the first grid tried).
+const MIN_SPANS: usize = 4;
+/// The share of the run from a corner to the next over which the conditions the corner cannot
+/// hold fade in.
+pub const FADE_SHARE: f64 = 0.15;
+/// The thin-plate energy's weight per fitted station: a thousand times
+/// [`crate::fill::fill_loop`]'s. Its fill only passes through points, which leave the inside to
+/// the energy alone; here the slope and curvature rows also act a little way inside the loop,
+/// and with the weaker energy they pull the surface up past a plane it is G2 to, a millimetre or
+/// two in from the plane's curve (by 0.06 at a box corner's r5 rounds set back 8). This weight
+/// keeps it under the plane but where it passes from a round's curvature to the plane's, and
+/// costs the loop little (2e-5 mm, 0.025° and 4e-4 per mm there).
+const FAIRNESS: f64 = 1e3 * SMOOTHNESS;
+/// A face beside the loop whose normal is closer than this cosine to square with the plane's
+/// stands along the plane's normal: the height field cannot be tangent to it.
+const MIN_NORMAL_COS: f64 = 0.05;
+
+/// What [`fill_matched`] is asked for.
+#[derive(Clone, Copy, Debug)]
+pub struct MatchedSpec {
+ /// How far the surface may be from the loop.
+ pub tol: f64,
+ /// How far (radians) its normal may turn from a G1/G2 neighbour's.
+ pub angle_tol: f64,
+ /// How far (1/length) its normal curvature across the loop may be from a G2 neighbour's,
+ /// clear of the corners' fades.
+ pub curvature_tol: f64,
+}
+
+/// The fill and what it achieved.
+#[derive(Clone, Debug, PartialEq)]
+pub struct MatchedFill {
+ /// The height field, its plane and its deviation from the loop (no crown).
+ pub fill: LoopFill,
+ /// The largest angle (radians) between the surface's normal and a neighbour's at the G1/G2
+ /// stations held to the angle tolerance, and at any G1/G2 station.
+ pub normal_deviation: f64,
+ pub normal_deviation_all: f64,
+ /// The largest difference (1/length) between the surface's normal curvature across the
+ /// loop and the neighbour's, at the G2 stations clear of the corners' fades, and at any G2
+ /// station.
+ pub curvature_mismatch: f64,
+ pub curvature_mismatch_all: f64,
+ /// Spans of the grid each way, and stations sampled.
+ pub spans: [usize; 2],
+ pub stations: usize,
+}
+
+/// Fill the closed loop of `sides` sides with one height field meeting each station's face as
+/// its `across` asks (see the module documentation). `stations(k, ts)` samples side `k` at the
+/// parameters `ts` (0 at its start, which is where side `k − 1` ends, towards 1 at its end); a
+/// station at `t = 0` marked `corner` is a corner of the loop.
+pub fn fill_matched(
+ sides: usize,
+ stations: &mut dyn FnMut(usize, &[f64]) -> Result<Vec<Station>, String>,
+ spec: &MatchedSpec,
+) -> SplineResult<MatchedFill> {
+ if sides == 0 || sides.saturating_mul(16) > MAX_LOOP_POINTS / 2 {
+ return Err(SplineError::TooLarge(format!("a loop of {sides} sides (at most {})", MAX_LOOP_POINTS / 32)));
+ }
+ let positive = |x: f64| x.is_finite() && x > 0.0;
+ if !(positive(spec.tol) && positive(spec.angle_tol) && positive(spec.curvature_tol)) {
+ return invalid("the fill tolerances must be positive");
+ }
+ let mut sample = |ts: &[f64]| -> SplineResult<Vec<Vec<Station>>> {
+ (0..sides)
+ .map(|k| {
+ let got = stations(k, ts).map_err(SplineError::Invalid)?;
+ if got.len() == ts.len() && got.iter().all(finite_station) {
+ Ok(got)
+ } else {
+ Err(SplineError::Invalid(format!("side {k} has no finite stations")))
+ }
+ })
+ .collect()
+ };
+ let mut per = 16usize;
+ let mut fit = sample(&(0..per).map(|i| i as f64 / per as f64).collect::<Vec<_>>())?;
+ let mut best = Shortfall::default();
+ let mut level = MIN_SPANS;
+ loop {
+ let check = sample(&(0..per).map(|i| (i as f64 + 0.5) / per as f64).collect::<Vec<_>>())?;
+ // The loop in order: fitted and checked stations alternating, side by side.
+ let mut all: Vec<(Station, bool)> = Vec::with_capacity(2 * per * sides);
+ for (f, c) in fit.iter().zip(&check) {
+ for (a, b) in f.iter().zip(c) {
+ all.push((*a, true));
+ all.push((*b, false));
+ }
+ }
+ match fit_round(&all, spec, level)? {
+ Round::Done(fill) => return Ok(*fill),
+ Round::Denser(s, at) => {
+ best = best.min(s);
+ level = at;
+ }
+ Round::Exhausted(s) => {
+ best = best.min(s);
+ break;
+ }
+ }
+ if all.len() * 2 > MAX_LOOP_POINTS {
+ break;
+ }
+ fit = fit.iter().zip(&check).map(|(f, c)| f.iter().zip(c).flat_map(|(a, b)| [*a, *b]).collect()).collect();
+ per *= 2;
+ }
+ Err(SplineError::Unsupported(format!(
+ "filling this loop with one surface meeting its neighbours: the closest fit stays {:e} off the loop (tolerance {:e}), turns {:.4}° from \
+ its neighbours (tolerance {:.4}°) and misses their curvature by {:e} (tolerance {:e})",
+ best.deviation,
+ spec.tol,
+ best.angle.to_degrees(),
+ spec.angle_tol.to_degrees(),
+ best.curvature,
+ spec.curvature_tol
+ )))
+}
+
+fn finite_station(s: &Station) -> bool {
+ s.p.is_finite() && s.across.is_none_or(|a| a.leave.is_finite() && a.normal.is_finite() && a.bend.is_none_or(|b| b.is_finite()))
+}
+
+/// How close a grid came.
+#[derive(Clone, Copy, Debug)]
+struct Shortfall {
+ deviation: f64,
+ angle: f64,
+ curvature: f64,
+}
+
+impl Default for Shortfall {
+ fn default() -> Shortfall {
+ Shortfall { deviation: f64::INFINITY, angle: f64::INFINITY, curvature: f64::INFINITY }
+ }
+}
+
+impl Shortfall {
+ /// The closer of two, by how many times its tolerance each misses.
+ fn min(self, other: Shortfall) -> Shortfall {
+ let worst = |s: &Shortfall| s.deviation + s.angle + s.curvature;
+ if worst(&other) < worst(&self) { other } else { self }
+ }
+}
+
+enum Round {
+ Done(Box<MatchedFill>),
+ /// Denser sampling is needed for the grid of this level (the coarser ones fell short).
+ Denser(Shortfall, usize),
+ Exhausted(Shortfall),
+}
+
+/// A station as the fit takes it: its place over the plane, its height, and what the face beside
+/// it asks there, in the plane's terms.
+struct Row {
+ q: [f64; 2],
+ h: f64,
+ fitted: bool,
+ /// G1: the height field's gradient there, and the face's unit normal on `n`'s side.
+ gradient: Option<([f64; 2], Vec3)>,
+ /// G2: the leave direction's plane components `(a, b)` and the second derivative of `h`
+ /// along them, `κ / N·n`, with `κ` itself.
+ curvature: Option<([f64; 2], f64, f64)>,
+ /// How near the station is to a corner, and to a clashing corner: its distance along the
+ /// loop to the nearer of the two around it, as a share of the run between them (0 at a
+ /// corner, ½ midway; 1 with no corner).
+ to_corner: f64,
+ to_clash: f64,
+ corner: bool,
+}
+
+/// The stations in the plane `f`'s terms, with their distances to the corners along the loop.
+fn rows(all: &[(Station, bool)], f: &LoopFrame) -> SplineResult<Vec<Row>> {
+ let m = all.len();
+ // Arc length along the loop (chords), and where its corners are.
+ let mut s = vec![0.0f64; m + 1];
+ for k in 0..m {
+ let (Some((a, _)), Some((b, _))) = (all.get(k), all.get((k + 1) % m)) else { return invalid("stations") };
+ let next = s.get(k).copied().unwrap_or(0.0) + a.p.dist(b.p);
+ if let Some(slot) = s.get_mut(k + 1) {
+ *slot = next;
+ }
+ }
+ let total = s.get(m).copied().unwrap_or(0.0);
+ if !(total > 0.0 && total.is_finite()) {
+ return invalid("the loop has no length");
+ }
+ let at = |k: usize| s.get(k).copied().unwrap_or(0.0);
+ let corners: Vec<f64> = (0..m).filter(|&k| all.get(k).is_some_and(|(st, _)| st.corner)).map(at).collect();
+ let clashes: Vec<f64> = (0..m).filter(|&k| all.get(k).is_some_and(|(st, _)| st.clash)).map(at).collect();
+ let share = |list: &[f64], x: f64| {
+ if list.is_empty() {
+ return 1.0;
+ }
+ let back = list.iter().map(|c| (x - c).rem_euclid(total)).fold(f64::INFINITY, f64::min);
+ let ahead = list.iter().map(|c| (c - x).rem_euclid(total)).filter(|d| *d > 0.0).fold(total, f64::min);
+ let run = back + ahead;
+ if run > 0.0 { back.min(ahead) / run } else { 0.0 }
+ };
+ let mut out = Vec::with_capacity(m);
+ for (k, (st, fitted)) in all.iter().enumerate() {
+ let d = st.p - f.o;
+ let q = [d.dot(f.x), d.dot(f.y)];
+ let mut gradient = None;
+ let mut curvature = None;
+ if let Some(a) = st.across {
+ let normal = a.normal.normalized().ok_or_else(|| SplineError::Invalid("a neighbour's normal has no direction".into()))?;
+ let side = if normal.dot(f.n) >= 0.0 { 1.0 } else { -1.0 };
+ let nn = normal * side;
+ let c = nn.dot(f.n);
+ if !(c > MIN_NORMAL_COS) {
+ return Err(SplineError::Unsupported("filling a loop beside a face that stands along the fill's normal".into()));
+ }
+ gradient = Some(([-nn.dot(f.x) / c, -nn.dot(f.y) / c], nn));
+ if let Some(bend) = a.bend {
+ let kappa = bend.dot(nn);
+ let w = a.leave;
+ curvature = Some(([w.dot(f.x), w.dot(f.y)], kappa / c, kappa));
+ }
+ }
+ out.push(Row {
+ q,
+ h: d.dot(f.n),
+ fitted: *fitted,
+ gradient,
+ curvature,
+ to_corner: share(&corners, at(k)),
+ to_clash: share(&clashes, at(k)),
+ corner: st.corner,
+ });
+ }
+ Ok(out)
+}
+
+/// The smoothstep `3t² − 2t³` of `share / FADE_SHARE` (1 from [`FADE_SHARE`] on).
+fn fade(share: f64) -> f64 {
+ let t = (share / FADE_SHARE).clamp(0.0, 1.0);
+ t * t * (3.0 - 2.0 * t)
+}
+
+/// The height field's derivatives at `q`: `[h, h_u, h_v, h_uu, h_uv, h_vv]`.
+fn derivatives(grid: &Grid, heights: &[f64], q: [f64; 2]) -> Option<[f64; 6]> {
+ let cu = *grid.count.first()?;
+ let mut out = [0.0; 6];
+ for (slot, (ru, rv)) in out.iter_mut().zip([(0, 0), (1, 0), (0, 1), (2, 0), (1, 1), (0, 2)]) {
+ let (i0, bu) = grid.basis_derivative(0, q[0], ru)?;
+ let (j0, bv) = grid.basis_derivative(1, q[1], rv)?;
+ let mut s = 0.0;
+ for (b, wv) in bv.iter().enumerate() {
+ for (a, wu) in bu.iter().enumerate() {
+ s += wu * wv * heights.get((j0 + b) * cu + i0 + a)?;
+ }
+ }
+ *slot = s;
+ }
+ out.iter().all(|x| x.is_finite()).then_some(out)
+}
+
+/// One grid's fit of the rows: the normal equations of the weighed rows and the energy.
+fn solve(grid: &Grid, rows: &[Row], cell: f64) -> SplineResult<Vec<f64>> {
+ let [cu, cv] = grid.count;
+ let n = cu * cv;
+ let mut band = Band::new(n, 3 * cu + 3);
+ let mut rhs = vec![0.0; n];
+ let add = |terms: &[(usize, f64)], value: f64, weight: f64, band: &mut Band, rhs: &mut Vec<f64>| {
+ let w2 = weight * weight;
+ for &(r, cr) in terms {
+ if let Some(slot) = rhs.get_mut(r) {
+ *slot += w2 * cr * value;
+ }
+ for &(s, cs) in terms {
+ band.add(r, s, w2 * cr * cs);
+ }
+ }
+ };
+ let mut fitted = 0usize;
+ for row in rows.iter().filter(|r| r.fitted) {
+ let basis = |r: [usize; 2]| -> SplineResult<(usize, [f64; 4], usize, [f64; 4])> {
+ let (Some((i0, bu)), Some((j0, bv))) = (grid.basis_derivative(0, row.q[0], r[0]), grid.basis_derivative(1, row.q[1], r[1])) else {
+ return invalid("a loop point is off the grid");
+ };
+ Ok((i0, bu, j0, bv))
+ };
+ // The 16 control heights a derivative of order `r` at the station draws on, scaled.
+ let terms = |r: [usize; 2], scale: f64| -> SplineResult<Vec<(usize, f64)>> {
+ let (i0, bu, j0, bv) = basis(r)?;
+ let mut t = Vec::with_capacity(16);
+ for (b, wv) in bv.iter().enumerate() {
+ for (a, wu) in bu.iter().enumerate() {
+ t.push(((j0 + b) * cu + i0 + a, wu * wv * scale));
+ }
+ }
+ Ok(t)
+ };
+ add(&terms([0, 0], 1.0)?, row.h, 1.0, &mut band, &mut rhs);
+ fitted += 1;
+ if row.corner {
+ continue;
+ }
+ if let Some((g, _)) = row.gradient {
+ let w = cell * fade(row.to_clash);
+ if w > 0.0 {
+ add(&terms([1, 0], 1.0)?, g[0], w, &mut band, &mut rhs);
+ add(&terms([0, 1], 1.0)?, g[1], w, &mut band, &mut rhs);
+ }
+ }
+ if let Some(([a, b], second, _)) = row.curvature {
+ let w = cell * cell * fade(row.to_corner) * fade(row.to_clash);
+ if w > 0.0 {
+ // a² h_uu + 2ab h_uv + b² h_vv, the three derivatives' terms summed per control
+ // height.
+ let mut sum: Vec<(usize, f64)> = Vec::with_capacity(48);
+ for (r, s) in [([2, 0], a * a), ([1, 1], 2.0 * a * b), ([0, 2], b * b)] {
+ for (idx, v) in terms(r, s)? {
+ match sum.iter_mut().find(|(i, _)| *i == idx) {
+ Some(slot) => slot.1 += v,
+ None => sum.push((idx, v)),
+ }
+ }
+ }
+ add(&sum, second, w, &mut band, &mut rhs);
+ }
+ }
+ }
+ let lambda = FAIRNESS * fitted as f64 / n as f64 * grid.cell(0) * grid.cell(1);
+ grid.add_energy(&mut band, lambda);
+ band.solve(rhs)
+}
+
+/// What a fitted grid achieves at the rows: the deviation from the loop, the normal's angle to
+/// the neighbours' (held stations, all), the curvature mismatch (held stations, all).
+fn achieved(grid: &Grid, heights: &[f64], rows: &[Row], f: &LoopFrame) -> SplineResult<[f64; 5]> {
+ let reach = FADE_SHARE;
+ let (mut dev, mut ang, mut ang_all, mut cur, mut cur_all) = (0.0f64, 0.0f64, 0.0f64, 0.0f64, 0.0f64);
+ for row in rows {
+ let Some([h, hu, hv, huu, huv, hvv]) = derivatives(grid, heights, row.q) else { return invalid("the fit is not finite") };
+ dev = dev.max((h - row.h).abs());
+ if row.corner {
+ continue;
+ }
+ let up = (1.0 + hu * hu + hv * hv).sqrt();
+ let normal = (f.n - f.x * hu - f.y * hv) * (1.0 / up);
+ if let Some((_, nn)) = row.gradient {
+ let a = normal.dot(nn).clamp(-1.0, 1.0).acos();
+ ang_all = ang_all.max(a);
+ if row.to_clash >= reach {
+ ang = ang.max(a);
+ }
+ }
+ if let Some(([a, b], _, kappa)) = row.curvature {
+ // The normal curvature along the unit tangent of the surface over (a, b): the second
+ // fundamental form over the first.
+ let t = f.x * a + f.y * b + f.n * (a * hu + b * hv);
+ let ii = (a * a * huu + 2.0 * a * b * huv + b * b * hvv) / up;
+ let k = ii / t.len2().max(1e-300);
+ let miss = (k - kappa).abs();
+ cur_all = cur_all.max(miss);
+ if row.to_corner >= reach && row.to_clash >= reach {
+ cur = cur.max(miss);
+ }
+ }
+ }
+ Ok([dev, ang, ang_all, cur, cur_all])
+}
+
+/// One round: the grids from `level` up, on these stations.
+fn fit_round(all: &[(Station, bool)], spec: &MatchedSpec, level: usize) -> SplineResult<Round> {
+ let fitted: Vec<Vec3> = all.iter().filter(|(_, f)| *f).map(|(s, _)| s.p).collect();
+ let frame = loop_frame(&fitted)?;
+ let points: Vec<Vec3> = all.iter().map(|(s, _)| s.p).collect();
+ let rows = rows(all, &frame)?;
+ let uv: Vec<[f64; 2]> = rows.iter().map(|r| r.q).collect();
+ check_projectable(&points, &uv)?;
+ let (mut lo, mut hi) = ([f64::INFINITY; 2], [f64::NEG_INFINITY; 2]);
+ for q in &uv {
+ for d in 0..2 {
+ lo[d] = lo[d].min(q[d]);
+ hi[d] = hi[d].max(q[d]);
+ }
+ }
+ for d in 0..2 {
+ let pad = 0.01 * (hi[d] - lo[d]);
+ lo[d] -= pad;
+ hi[d] += pad;
+ }
+ if !(lo[0] < hi[0] && lo[1] < hi[1] && (hi[0] - lo[0]).is_finite() && (hi[1] - lo[1]).is_finite()) {
+ return invalid("the loop's extent is not finite");
+ }
+ // The fitted stations' largest step each way: a grid finer than half of it waits for denser
+ // sampling.
+ let fq: Vec<[f64; 2]> = rows.iter().filter(|r| r.fitted).map(|r| r.q).collect();
+ let mut step = [0.0f64; 2];
+ for k in 0..fq.len() {
+ let (p, q) = (fq.get(k).copied().unwrap_or([0.0; 2]), fq.get((k + 1) % fq.len()).copied().unwrap_or([0.0; 2]));
+ for d in 0..2 {
+ step[d] = step[d].max((q[d] - p[d]).abs());
+ }
+ }
+ let extent = [hi[0] - lo[0], hi[1] - lo[1]];
+ let longer = extent[0].max(extent[1]);
+ let mut best = Shortfall::default();
+ let mut level = level;
+ while level <= MAX_MATCHED_SPANS {
+ let spans = [0, 1].map(|d| ((extent[d] / longer * level as f64).ceil() as usize).clamp(1, level));
+ let holds = (0..2).all(|d| extent[d] / spans[d] as f64 >= 2.0 * step[d]);
+ if !holds && level > MIN_SPANS {
+ return Ok(Round::Denser(best, level));
+ }
+ let grid = Grid::new(spans, lo, hi);
+ let cell = grid.cell(0).max(grid.cell(1));
+ let heights = solve(&grid, &rows, cell)?;
+ let [dev, ang, ang_all, cur, cur_all] = achieved(&grid, &heights, &rows, &frame)?;
+ let s = Shortfall { deviation: dev, angle: ang, curvature: cur };
+ best = best.min(s);
+ if dev <= spec.tol && ang <= spec.angle_tol && cur <= spec.curvature_tol && holds {
+ let surface = grid.surface(&heights, frame.o, frame.x, frame.y, frame.n)?;
+ let fill = LoopFill {
+ surface,
+ origin: frame.o,
+ axes: [frame.x, frame.y],
+ normal: frame.n,
+ counter_clockwise: frame.counter_clockwise,
+ deviation: dev,
+ evaluations: all.len(),
+ crown: 0.0,
+ crowned: 0,
+ crown_drift: 0.0,
+ };
+ return Ok(Round::Done(Box::new(MatchedFill {
+ fill,
+ normal_deviation: ang,
+ normal_deviation_all: ang_all,
+ curvature_mismatch: cur,
+ curvature_mismatch_all: cur_all,
+ spans,
+ stations: all.len(),
+ })));
+ }
+ if !holds {
+ return Ok(Round::Denser(best, level));
+ }
+ level *= 2;
+ }
+ Ok(Round::Exhausted(best))
+}
+
+#[cfg(test)]
+#[path = "fill_matched_tests.rs"]
+mod tests;
diff --git a/crates/geom/src/fill_matched_tests.rs b/crates/geom/src/fill_matched_tests.rs
new file mode 100644
index 0000000000..527631802f
--- /dev/null
+++ b/crates/geom/src/fill_matched_tests.rs
@@ -0,0 +1,181 @@
+use super::*;
+use crate::fill_general::Across;
+use std::f64::consts::FRAC_PI_2;
+
+/// The face tolerance of the 60 x 40 x 20 box the corner is cut from (10⁻⁶ of its size).
+const TOL: f64 = 7.5e-5;
+const ANGLE: f64 = 0.05 * std::f64::consts::PI / 180.0;
+/// Half a percent of the 1/5 per mm a rolling ball of radius 5 jumps by across its seams.
+const CURVATURE: f64 = 1e-3;
+
+fn spec() -> MatchedSpec {
+ MatchedSpec { tol: TOL, angle_tol: ANGLE, curvature_tol: CURVATURE }
+}
+
+/// The hole a setback leaves at the corner of three rounds of radius `r` set back `s` (> r)
+/// along each edge of a corner at the origin, the solid below it in every axis: three sections
+/// of the rounds (quarter circles on the cylinders about the three edges) and three curves on the
+/// faces between their ends, each a quarter circle about the point `s` back along both edges
+/// (radius `s − r`), meeting the rounds' contact lines tangentially. Each side is G2 to its face:
+/// a round leaves its section along its axis, where it is straight, a face anywhere; both have no
+/// curvature across the hole.
+fn setback_hole(r: f64, s: f64, g2: bool) -> impl FnMut(usize, &[f64]) -> Result<Vec<Station>, String> {
+ let rho = s - r;
+ move |k, ts| {
+ ts.iter()
+ .map(|t| {
+ let a = t * FRAC_PI_2;
+ let (sin, cos) = a.sin_cos();
+ let (p, normal, leave) = match k {
+ 0 => (Vec3::new(-s, -r + r * sin, -r + r * cos), Vec3::new(0.0, sin, cos), Vec3::X),
+ 1 => (Vec3::new(-s + rho * sin, 0.0, -s + rho * cos), Vec3::Y, Vec3::new(sin, 0.0, cos)),
+ 2 => (Vec3::new(-r + r * sin, -r + r * cos, -s), Vec3::new(sin, cos, 0.0), Vec3::Z),
+ 3 => (Vec3::new(0.0, -s + rho * cos, -s + rho * sin), Vec3::X, Vec3::new(0.0, cos, sin)),
+ 4 => (Vec3::new(-r + r * cos, -s, -r + r * sin), Vec3::new(cos, 0.0, sin), Vec3::Y),
+ 5 => (Vec3::new(-s + rho * cos, -s + rho * sin, 0.0), Vec3::Z, Vec3::new(cos, sin, 0.0)),
+ _ => return Err(format!("no side {k}")),
+ };
+ let up = Vec3::new(1.0, 1.0, 1.0).normalized().unwrap_or(Vec3::Z);
+ Ok(Station { p, up, across: Some(Across { leave, normal, bend: g2.then_some(Vec3::ZERO) }), corner: *t == 0.0, clash: false })
+ })
+ .collect()
+ }
+}
+
+#[test]
+fn a_setback_corner_hole_is_filled_g2_to_its_rounds_and_faces() {
+ let f = fill_matched(6, &mut setback_hole(5.0, 8.0, true), &spec()).unwrap();
+ eprintln!(
+ "setback hole: spans {:?}, {} stations, deviation {:e}, normal {:.5}° (all {:.5}°), curvature {:e} (all {:e})",
+ f.spans,
+ f.stations,
+ f.fill.deviation,
+ f.normal_deviation.to_degrees(),
+ f.normal_deviation_all.to_degrees(),
+ f.curvature_mismatch,
+ f.curvature_mismatch_all
+ );
+ assert!(f.fill.deviation <= TOL && f.normal_deviation <= ANGLE && f.curvature_mismatch <= CURVATURE);
+ // The plane is the corner's diagonal one, by symmetry.
+ let d = Vec3::new(1.0, 1.0, 1.0).normalized().unwrap();
+ assert!(f.fill.normal.dot(d) > 1.0 - 1e-9, "{:?}", f.fill.normal);
+ // The patch is the corner's cap: inside the corner cube's octant and within the hull of the
+ // three rounds' tangent planes at 45° (the box's corner cut back by the rounds).
+ let [du, dv] = f.fill.surface.domain();
+ let mut highest = f64::NEG_INFINITY;
+ for i in 0..=40 {
+ for j in 0..=40 {
+ let u = (du[0] + (du[1] - du[0]) * i as f64 / 40.0).min(du[1]);
+ let v = (dv[0] + (dv[1] - dv[0]) * j as f64 / 40.0).min(dv[1]);
+ let p = f.fill.surface.eval(u, v).unwrap();
+ // Over the loop only: the box's corners outside the hole are not the patch.
+ if p.x > -8.0 && p.y > -8.0 && p.z > -8.0 && p.x < 0.0 && p.y < 0.0 && p.z < 0.0 {
+ highest = highest.max(p.dot(d));
+ }
+ }
+ }
+ eprintln!("setback hole: highest point along the diagonal {highest:.6}");
+ assert!(highest < 0.0);
+}
+
+#[test]
+fn a_setback_corner_hole_is_filled_g1_on_a_coarser_grid() {
+ let f = fill_matched(6, &mut setback_hole(5.0, 8.0, false), &spec()).unwrap();
+ eprintln!("setback hole G1: spans {:?}, deviation {:e}, normal {:.5}°", f.spans, f.fill.deviation, f.normal_deviation.to_degrees());
+ assert!(f.fill.deviation <= TOL && f.normal_deviation <= ANGLE);
+ // Flat to the second order along a curved plane's curve is what makes G2 the harder fill.
+ let g2 = fill_matched(6, &mut setback_hole(5.0, 8.0, true), &spec()).unwrap();
+ assert!(f.spans[0] < g2.spans[0], "{:?} {:?}", f.spans, g2.spans);
+}
+
+/// A hole in a cylinder of radius 5 about the x axis (its top line through the origin), the rim
+/// over the circle of radius 2 about the z axis, G2 all round: the loop has no corner, and the
+/// fill repeats the cylinder there.
+#[test]
+fn a_hole_in_a_cylinder_is_filled_with_the_cylinder_to_the_second_order() {
+ let r = 5.0;
+ let mut rim = move |_: usize, ts: &[f64]| -> Result<Vec<Station>, String> {
+ ts.iter()
+ .map(|t| {
+ let a = t * std::f64::consts::TAU;
+ let (x, y) = (2.0 * a.cos(), 2.0 * a.sin());
+ let z = (r * r - y * y).sqrt() - r;
+ let p = Vec3::new(x, y, z);
+ let normal = Vec3::new(0.0, y, z + r).normalized().ok_or("normal")?;
+ let tangent = Vec3::new(-a.sin(), a.cos(), -a.cos() * y / (z + r)).normalized().ok_or("tangent")?;
+ // Into the hole, square to the rim in the cylinder.
+ let leave = tangent.cross(normal).normalized().ok_or("leave")?;
+ let leave = if leave.dot(Vec3::new(-x, -y, 0.0)) > 0.0 { leave } else { leave * -1.0 };
+ // The cylinder's normal curvature along `leave`: its part across the axis, squared,
+ // over the radius, bending away from the normal.
+ let across = leave - Vec3::X * leave.x;
+ let bend = normal * (-across.len2() / r);
+ Ok(Station { p, up: normal, across: Some(Across { leave, normal, bend: Some(bend) }), corner: false, clash: false })
+ })
+ .collect()
+ };
+ let f = fill_matched(1, &mut rim, &spec()).unwrap();
+ eprintln!("cylinder hole: spans {:?}, deviation {:e}, curvature {:e}", f.spans, f.fill.deviation, f.curvature_mismatch_all);
+ assert!(f.fill.deviation <= TOL && f.normal_deviation_all <= ANGLE && f.curvature_mismatch_all <= CURVATURE);
+}
+
+#[test]
+fn hostile_matched_fills_are_refused() {
+ let bad = MatchedSpec { tol: 0.0, ..spec() };
+ assert!(fill_matched(6, &mut setback_hole(5.0, 8.0, true), &bad).is_err());
+ assert!(fill_matched(0, &mut setback_hole(5.0, 8.0, true), &spec()).is_err());
+ // A face beside the loop standing along the fill's normal.
+ let mut wall = |_: usize, ts: &[f64]| -> Result<Vec<Station>, String> {
+ Ok(ts
+ .iter()
+ .map(|t| {
+ let a = t * std::f64::consts::TAU / 3.0;
+ let p = Vec3::new(a.cos(), a.sin(), 0.0);
+ Station { p, up: Vec3::Z, across: Some(Across { leave: Vec3::Z, normal: p, bend: None }), corner: false, clash: false }
+ })
+ .collect())
+ };
+ assert!(matches!(fill_matched(3, &mut wall, &spec()), Err(SplineError::Unsupported(_))));
+}
+
+/// How far the fill of `setback_hole(r, s)` rises past the planes it is G2 to, over the loop
+/// (the corner is convex: all of it should lie under them), sampled.
+fn over_the_planes(f: &MatchedFill, r: f64, s: f64) -> f64 {
+ let mut st = setback_hole(r, s, true);
+ let ts: Vec<f64> = (0..256).map(|i| i as f64 / 256.0).collect();
+ let poly: Vec<[f64; 2]> = (0..6)
+ .flat_map(|k| st(k, &ts).unwrap())
+ .map(|q| {
+ let d = q.p - f.fill.origin;
+ [d.dot(f.fill.axes[0]), d.dot(f.fill.axes[1])]
+ })
+ .collect();
+ let [du, dv] = f.fill.surface.domain();
+ let n = 200;
+ let mut over = f64::NEG_INFINITY;
+ for i in 0..=n {
+ for j in 0..=n {
+ let u = (du[0] + (du[1] - du[0]) * i as f64 / n as f64).min(du[1]);
+ let v = (dv[0] + (dv[1] - dv[0]) * j as f64 / n as f64).min(dv[1]);
+ if crate::fill::inside_loop([u, v], &poly) {
+ let p = f.fill.surface.eval(u, v).unwrap();
+ over = over.max(p.x).max(p.y).max(p.z);
+ }
+ }
+ }
+ over
+}
+
+/// Set back from 1.5 to 3 times the radius the G2 fill stays under the planes it meets, but by
+/// under a thousandth where it passes from a round's curvature to the plane's at the hole's
+/// corners (SMLib's own setback patch rises past them beyond about twice the radius, by 0.002 at
+/// 2.2 r and 0.25 at 3 r).
+#[test]
+fn a_setback_g2_fill_stays_under_its_planes() {
+ for s in [7.5, 8.0, 10.0, 12.0, 15.0] {
+ let f = fill_matched(6, &mut setback_hole(5.0, s, true), &spec()).unwrap();
+ let over = over_the_planes(&f, 5.0, s);
+ eprintln!("set back {s}: spans {:?}, curvature {:.2e}, over the planes {over:.2e}", f.spans, f.curvature_mismatch);
+ assert!(over < 1e-3, "set back {s}: {over}");
+ }
+}
diff --git a/crates/geom/src/lib.rs b/crates/geom/src/lib.rs
index fdd234a4b9..c1b3bc7c3a 100644
--- a/crates/geom/src/lib.rs
+++ b/crates/geom/src/lib.rs
@@ -22,6 +22,7 @@ pub mod env;
pub mod fill;
pub mod fill_general;
pub mod fill_iso;
+pub mod fill_matched;
mod grid;
mod mesh;
pub mod mesh_distance;
diff --git a/docs/book/src/guide/getting-started.md b/docs/book/src/guide/getting-started.md
index 4bb2db13eb..9403fe7c35 100644
--- a/docs/book/src/guide/getting-started.md
+++ b/docs/book/src/guide/getting-started.md
@@ -322,7 +322,10 @@ cargo run --release -p solidcraft-cli -- eval examples/bracket.json --json-out m
To find the slow steps of a script, `--timings` prints how long each command took instead of
the measurement: `{"timings": [{"index", "command", "ms"}], "total_ms"}`, with `index` counted
from 0. `--profile` adds each command's `profile: {"boolean_ms", "tessellate_ms", "other_ms"}`,
-its wall time in the kernel's booleans, in tessellation and in everything else. With
+its wall time in the kernel's booleans, in tessellation and in everything else, and prints the
+profiler's table on stderr: where the time went, SMLib's calls to the commands
+(`docs/perf.md`, "Where the time goes"); `--profile-out trace.json` also writes the spans as a
+Chrome trace. `--profile` works on a design or STEP file too. With
`--results` as well, the results go in the same object as `results`; `--results` alone still
prints a plain array.
diff --git a/docs/perf.md b/docs/perf.md
index 6f36e29cb8..94c5b204ed 100644
--- a/docs/perf.md
+++ b/docs/perf.md
@@ -1,3 +1,37 @@
+# Where the time goes: the profiler
+
+Every app is built with the profiler (`crates/profile`, the apps' default `profile` feature).
+It records nothing until switched on: `SOLIDCRAFT_PROFILE=1`, the CLI's `--profile`, the
+**Profile operations** preference (Graphics page) or `diagnostics.profile {"enabled": true}`.
+Off, a span is one relaxed atomic load.
+
+What it records, as nested spans on each thread:
+
+| Category | Spans |
+|---|---|
+| `smlib` | every SMLib C API call, timed by the C API itself (`steady_clock`) |
+| `kernel` | booleans, blends, sweeps, lofts, shell/draft/offset, healing, sewing, conversions, meshing, measuring |
+| `import` | the stages of a STEP or IGES import: parse, index, each solid, placement, mesh check, convert batches |
+| `feature` | each feature computed, by its type; `doc evaluate` around them |
+| `command` | each `Session::execute`, by command id |
+| `io` | import, export, design read and write |
+
+Self time is a span's time less the spans inside it; its total counts only its outermost run
+on a thread, so a command run by a command is not counted twice. Work handed to other threads
+shows under their own spans. The report is a table (the most self time first, with self time
+per category) and the individual spans as a Chrome trace-event file for chrome://tracing or
+ui.perfetto.dev (at most 200,000 spans; later ones still count in the table).
+
+```sh
+solidcraft-cli run part.step --profile --profile-out trace.json # table on stderr
+solidcraft-cli run part.solidcraft --profile --quiet
+solidcraft-cli bench-open part.step --profile
+```
+
+Over the control channel or MCP: `diagnostics.profile {"reset": true, "enabled": true}`, do the
+work, then `diagnostics.profile {"top": 30, "trace": "trace.json"}`. A STEP or IGES import's
+reply carries its own profile while recording.
+
# Design loading
## Edges made by booleans: each point evaluated once (2026-10-16)