T-spline core library and sheet bodies (#250, step 1) (#337)

* Add B-spline basis, knot insertion and NURBS surfaces to geom

Freeform faces need local refinement and gap-free joins between patches
with different knot vectors, which tensor B-spline grids cannot give;
T-splines can, and the first user is an N-sided Boundary Fill of
non-planar loops. This lays the univariate groundwork they rest on, in
the L0 geometry crate so it stays independent of the B-rep kernel:

- Cox-de Boor basis of one function from its local knot vector, on
  half-open spans with a left-limit side for the domain end, with
  derivatives (NURBS Book eq. 2.5, 2.9)
- knot insertion into a single basis function (Sederberg et al. 2004
  section 3) and Bezier extraction of one function by repeated insertion
- Boehm knot insertion for curves (NURBS Book A5.1), de Casteljau
  evaluation and sub-segments
- a rational tensor NURBS surface with evaluation, knot insertion and
  clamping, and a rational Bezier patch type

All input is checked (finite, monotone knots, positive weights, size
caps) and returns SplineError; nothing indexes unchecked.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01J53sR6gEaVt56soFDpTck8

* Add T-spline surfaces: T-mesh, evaluation, AS check, refinement, extraction

Tensor B-spline faces refine only by whole rows and columns and cannot
join patches with different knot vectors without gaps. T-splines allow
T-junctions in the control net, which fixes both; the first user is an
N-sided Boundary Fill. This adds the maths only (no command, no change
in behaviour):

- T-mesh in index space with knot values per line, validated (outer
  rectangle, rectangular faces, no empty lines, size caps); local knot
  vectors read off rays from each vertex, rays leaving the mesh repeat
  the boundary (Sederberg et al. 2003 section 3)
- rational T-spline evaluation and first derivatives for odd bi-degree,
  with a complete (p-1)/2-line frame and the domain inside it
- T-junction extensions and the analysis-suitability check (Scott et al.
  2012 section 2)
- local refinement that keeps the surface exactly: requested knot lines
  are cut in, then every original blending function is carried as a
  record and split (violation 1) or the mesh gains edges (violations 2
  and 3) until each record is a blending function of the refined mesh
  (Sederberg et al. 2004 section 3); analysis-suitable input stays
  analysis-suitable by carrying conflicting T-junctions across faces
- NURBS <-> T-spline conversion for meshes without T-junctions, and
  Bezier extraction over the rectangles no blending-function knot line
  crosses

Measured: regular T-spline vs NURBS < 1e-12, round trip exact, partition
of unity with T-junctions < 1e-14, refinement deviation <= 1.4e-14 over
40 random refinements, Bezier patches vs surface < 1e-14.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01J53sR6gEaVt56soFDpTck8

* Convert T-splines to sewn NURBS sheet bodies in the kernel

A T-spline is only useful to the modeller once it is a B-rep face set.
tspline_sheet builds an open shell: a mesh without T-junctions becomes
one clamped NURBS face; otherwise each Bezier element is a face, and
sides are split at the T-points where neighbours' corners land, so all
faces share vertices and edges and the sheet is one oriented shell
(V - E + F = 1). Every truck call runs under guard. No command yet;
Boundary Fill will be the first caller.

Tests: one face for a regular surface, sewn Bezier faces with
T-junctions, tessellated points on the surface to ~1e-9 mm, and hostile
control nets (coincident, 1e300, needle-thin) never panic.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01J53sR6gEaVt56soFDpTck8

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>

crates/kernel/src/lib.rs

@@ -64,6 +64,7 @@ mod sweep_path;
 #[cfg(test)]
 mod thread_tests;
 mod topo;
+mod tspline;
 
 pub use blend::{ChamferSide, chamfer, chamfer_sides, fillet};
 pub use blend_corner::fillet_radii;
@@ -96,6 +97,7 @@ pub use surfaces::{copy_faces, extend, patch_edges, patch_region, stitch, thicke
 pub use sweep_path::sweep_path;
 pub use topo::{CylinderFace, cylinder_face_at};
 pub use topo::{TopoCounts, merged_topology, seam_flags};
+pub use tspline::tspline_sheet;
 
 #[derive(Debug, Clone, PartialEq, thiserror::Error)]
 pub enum KernelError {

crates/kernel/src/surfaces.rs

@@ -22,7 +22,7 @@ impl Body {
 }
 
 /// A body of faces as they are (no orientation fix: a surface has no inside).
-fn surface_body(faces: Vec<mt::Face>) -> Body {
+pub(crate) fn surface_body(faces: Vec<mt::Face>) -> Body {
     surface_of(mt::Shell::from(faces))
 }
 

crates/kernel/src/tspline.rs

@@ -0,0 +1,267 @@
+//! T-spline sheets: a T-spline surface (`solvecraft_geom::tspline`) as a surface body of NURBS
+//! faces. A T-mesh without T-junctions becomes one clamped tensor face; otherwise each Bézier
+//! element is a face, and the faces share their edges and vertices — a side that meets two
+//! neighbours is split at the T-point between them — so the sheet is one sewn open shell.
+
+use std::collections::hash_map::Entry;
+use std::collections::{BTreeMap, BTreeSet, HashMap};
+
+use solvecraft_geom::bspline::{BezierPatch, HPoint, NurbsSurface, SplineError, bezier_segment};
+use solvecraft_geom::tspline::TSpline;
+use truck_modeling as mt;
+
+use crate::body::Body;
+use crate::{KernelError, Result, guard};
+
+/// A T-spline as a surface body (an open shell of NURBS faces whose normals follow
+/// `∂S/∂s × ∂S/∂t`).
+pub fn tspline_sheet(ts: &TSpline) -> Result<Body> {
+    let faces = if ts.mesh().is_regular() {
+        let n = ts.to_nurbs().and_then(|n| n.clamped()).map_err(spline_err)?;
+        guard("t-spline sheet", || tensor_face(&n).map(|f| vec![f]))?
+    } else {
+        let patches = ts.bezier_elements().map_err(spline_err)?;
+        guard("t-spline sheet", || patch_faces(&patches))?
+    };
+    Ok(crate::surfaces::surface_body(faces))
+}
+
+fn spline_err(e: SplineError) -> KernelError {
+    KernelError::Invalid(format!("t-spline: {e}"))
+}
+
+fn fail(m: impl std::fmt::Display) -> KernelError {
+    KernelError::Failed(format!("t-spline sheet: {m}"))
+}
+
+fn h4(h: HPoint) -> mt::Vector4 {
+    mt::Vector4::new(h.x, h.y, h.z, h.w)
+}
+
+fn vertex(h: HPoint) -> Result<mt::Vertex> {
+    let p = h.project().ok_or_else(|| fail("a corner has no position"))?;
+    Ok(mt::builder::vertex(crate::body::p3(p)))
+}
+
+fn nurbs_curve(knots: mt::KnotVec, ctrl: &[HPoint]) -> Result<mt::Curve> {
+    let c = mt::BSplineCurve::try_new(knots, ctrl.iter().copied().map(h4).collect()).map_err(fail)?;
+    Ok(mt::Curve::NurbsCurve(mt::NurbsCurve::new(c)))
+}
+
+fn surface(knots: (mt::KnotVec, mt::KnotVec), rows: Vec<Vec<mt::Vector4>>) -> Result<mt::Surface> {
+    let s = mt::BSplineSurface::try_new(knots, rows).map_err(fail)?;
+    Ok(mt::Surface::NurbsSurface(mt::NurbsSurface::new(s)))
+}
+
+/// One face from a clamped tensor surface, bounded by its four boundary curves.
+fn tensor_face(n: &NurbsSurface) -> Result<mt::Face> {
+    let [nu, nv] = n.count();
+    let [ku, kv] = n.knots();
+    let (ku, kv) = (mt::KnotVec::from(ku.clone()), mt::KnotVec::from(kv.clone()));
+    let corners = [n.point(0, 0), n.point(nu - 1, 0), n.point(nu - 1, nv - 1), n.point(0, nv - 1)];
+    let v: Vec<mt::Vertex> = corners.into_iter().map(vertex).collect::<Result<_>>()?;
+    let row = |j: usize| -> Vec<HPoint> { (0..nu).map(|i| n.point(i, j)).collect() };
+    let column = |i: usize| -> Vec<HPoint> { (0..nv).map(|j| n.point(i, j)).collect() };
+    let (Some(v0), Some(v1), Some(v2), Some(v3)) = (v.first(), v.get(1), v.get(2), v.get(3)) else { return Err(fail("corners")) };
+    let edge = |a: &mt::Vertex, b: &mt::Vertex, c: mt::Curve| mt::Edge::try_new(a, b, c).map_err(fail);
+    let bottom = edge(v0, v1, nurbs_curve(ku.clone(), &row(0))?)?;
+    let right = edge(v1, v2, nurbs_curve(kv.clone(), &column(nu - 1))?)?;
+    let top = edge(v3, v2, nurbs_curve(ku.clone(), &row(nv - 1))?)?;
+    let left = edge(v0, v3, nurbs_curve(kv.clone(), &column(0))?)?;
+    let wire: mt::Wire = vec![bottom, right, top.inverse(), left.inverse()].into();
+    let rows: Vec<Vec<mt::Vector4>> = (0..nu).map(|i| (0..nv).map(|j| h4(n.point(i, j))).collect()).collect();
+    mt::Face::try_new(vec![wire], surface((ku, kv), rows)?).map_err(fail)
+}
+
+/// A parameter point, exact (knot values are shared, so equal points have equal bits).
+type Key = (u64, u64);
+
+fn key(s: f64, t: f64) -> Key {
+    ((s + 0.0).to_bits(), (t + 0.0).to_bits())
+}
+
+/// One face per Bézier patch, sharing vertices and edges; sides are split where a
+/// neighbour's corner lands on them.
+fn patch_faces(patches: &[BezierPatch]) -> Result<Vec<mt::Face>> {
+    // Corner parameters on each line of constant t (their s values) and of constant s.
+    let mut on_t: BTreeMap<u64, BTreeSet<u64>> = BTreeMap::new();
+    let mut on_s: BTreeMap<u64, BTreeSet<u64>> = BTreeMap::new();
+    for p in patches {
+        for s in p.s {
+            for t in p.t {
+                let (ks, kt) = key(s, t);
+                on_t.entry(kt).or_default().insert(ks);
+                on_s.entry(ks).or_default().insert(kt);
+            }
+        }
+    }
+    let mut verts: HashMap<Key, mt::Vertex> = HashMap::new();
+    let mut edges: HashMap<(Key, Key), mt::Edge> = HashMap::new();
+    let mut faces = Vec::with_capacity(patches.len());
+    for p in patches {
+        let mut wire: Vec<mt::Edge> = Vec::new();
+        for side in 0..4 {
+            // Side 0: t = t₀, 1: s = s₁, 2: t = t₁, 3: s = s₀; each runs with its parameter
+            // rising, sides 2 and 3 are walked backwards.
+            let (along_s, fixed, [lo, hi]) = match side {
+                0 => (true, p.t[0], p.s),
+                1 => (false, p.s[1], p.t),
+                2 => (true, p.t[1], p.s),
+                _ => (false, p.s[0], p.t),
+            };
+            let line = if along_s { on_t.get(&key(0.0, fixed).1) } else { on_s.get(&key(fixed, 0.0).0) };
+            let mut breaks: Vec<f64> = line.into_iter().flatten().map(|&b| f64::from_bits(b)).filter(|&x| x > lo && x < hi).collect();
+            breaks.insert(0, lo);
+            breaks.push(hi);
+            let ctrl = p.side(side);
+            let at = |x: f64| if along_s { key(x, fixed) } else { key(fixed, x) };
+            let mut pieces = Vec::with_capacity(breaks.len());
+            for w in breaks.windows(2) {
+                let &[x0, x1] = w else { continue };
+                let (ka, kb) = (at(x0), at(x1));
+                let e = if let Some(e) = edges.get(&(ka, kb)) {
+                    e.clone()
+                } else if let Some(e) = edges.get(&(kb, ka)) {
+                    e.inverse()
+                } else {
+                    let seg = bezier_segment(&ctrl, (x0 - lo) / (hi - lo), (x1 - lo) / (hi - lo)).map_err(spline_err)?;
+                    let (Some(&first), Some(&last)) = (seg.first(), seg.last()) else { return Err(fail("an empty side")) };
+                    let mut corner = |k: Key, h: HPoint| -> Result<mt::Vertex> {
+                        Ok(match verts.entry(k) {
+                            Entry::Occupied(e) => e.get().clone(),
+                            Entry::Vacant(e) => e.insert(vertex(h)?).clone(),
+                        })
+                    };
+                    let (va, vb) = (corner(ka, first)?, corner(kb, last)?);
+                    let curve = nurbs_curve(mt::KnotVec::bezier_knot(seg.len() - 1), &seg)?;
+                    let e = mt::Edge::try_new(&va, &vb, curve).map_err(fail)?;
+                    edges.insert((ka, kb), e.clone());
+                    e
+                };
+                pieces.push(e);
+            }
+            if side >= 2 {
+                pieces.reverse();
+                pieces.iter_mut().for_each(|e| *e = e.inverse());
+            }
+            wire.extend(pieces);
+        }
+        let [ps, pt] = p.degree;
+        let rows: Vec<Vec<mt::Vector4>> = (0..=ps).map(|i| (0..=pt).map(|j| h4(p.point(i, j))).collect()).collect();
+        let surf = surface((mt::KnotVec::bezier_knot(ps), mt::KnotVec::bezier_knot(pt)), rows)?;
+        faces.push(mt::Face::try_new(vec![wire.into()], surf).map_err(fail)?);
+    }
+    Ok(faces)
+}
+
+#[cfg(test)]
+mod tests {
+    use solvecraft_geom::Vec3;
+    use solvecraft_geom::bspline::NurbsSurface;
+    use solvecraft_geom::tspline::{Cut, TSpline};
+    use truck_modeling as mt;
+
+    use super::tspline_sheet;
+    use crate::fuzz::Rng;
+
+    /// A rational bicubic with uneven knots over a 10 × 8 mm area, bulging up to ~3 mm.
+    fn surface(seed: u64) -> TSpline {
+        let mut rng = Rng::new(seed);
+        let ku = vec![0.0, 0.0, 0.0, 0.0, 0.2, 0.45, 0.5, 0.8, 1.0, 1.0, 1.0, 1.0];
+        let kv = vec![0.0, 0.0, 0.0, 0.0, 0.3, 0.6, 1.0, 1.0, 1.0, 1.0];
+        let (nu, nv) = (ku.len() - 4, kv.len() - 4);
+        let mut pts = Vec::new();
+        for j in 0..nv {
+            for i in 0..nu {
+                pts.push(Vec3::new(10.0 * i as f64 / (nu - 1) as f64, 8.0 * j as f64 / (nv - 1) as f64, 3.0 * rng.unit()));
+            }
+        }
+        let w: Vec<f64> = (0..pts.len()).map(|_| 0.7 + 0.6 * rng.unit()).collect();
+        TSpline::from_nurbs(&NurbsSurface::new([3, 3], [ku, kv], &pts, &w).unwrap()).unwrap()
+    }
+
+    /// Distance from `p` to the T-spline: nearest of a sample grid, then Gauss–Newton.
+    fn distance(ts: &TSpline, p: Vec3) -> f64 {
+        let [ds, dt] = ts.domain();
+        let n = 24;
+        let mut best = (f64::MAX, 0.0, 0.0);
+        for i in 0..=n {
+            for j in 0..=n {
+                let (s, t) = (ds[0] + (ds[1] - ds[0]) * i as f64 / n as f64, dt[0] + (dt[1] - dt[0]) * j as f64 / n as f64);
+                let d = ts.eval(s, t).unwrap().dist(p);
+                if d < best.0 {
+                    best = (d, s, t);
+                }
+            }
+        }
+        let (_, mut s, mut t) = best;
+        for _ in 0..60 {
+            let [q, a, b] = ts.derivs(s, t).unwrap();
+            let r = q - p;
+            let (aa, ab, bb) = (a.dot(a), a.dot(b), b.dot(b));
+            let det = aa * bb - ab * ab;
+            if det.abs() < 1e-30 {
+                break;
+            }
+            let (ga, gb) = (a.dot(r), b.dot(r));
+            s = (s - (bb * ga - ab * gb) / det).clamp(ds[0], ds[1]);
+            t = (t - (aa * gb - ab * ga) / det).clamp(dt[0], dt[1]);
+        }
+        ts.eval(s, t).unwrap().dist(p)
+    }
+
+    fn check_sheet(ts: &TSpline, faces: usize) {
+        let body = tspline_sheet(ts).unwrap();
+        assert!(body.is_surface());
+        assert_eq!(body.shell_count(), 1);
+        assert_eq!(body.face_count(), faces);
+        let shell = &body.solid.boundaries()[0];
+        assert_eq!(shell.shell_condition(), mt::ShellCondition::Oriented, "neighbours share edges, run opposite ways");
+        let euler = body.vertex_count() as i64 - body.edge_count() as i64 + body.face_count() as i64;
+        assert_eq!(euler, 1, "one sewn sheet (a disc)");
+        let mesh = body.tessellate(0.01).unwrap();
+        assert!(!mesh.triangles.is_empty());
+        // Mesh points lie on the surface (not merely within the tessellation tolerance).
+        let step = (mesh.positions.len() / 300).max(1);
+        let worst = mesh.positions.iter().step_by(step).map(|p| distance(ts, *p)).fold(0.0, f64::max);
+        eprintln!("t-spline sheet: {faces} faces, {} mesh points, farthest checked {worst:e} mm from the surface", mesh.positions.len());
+        assert!(worst < 1e-6, "a mesh point is {worst} mm off the T-spline");
+    }
+
+    #[test]
+    fn regular_tspline_becomes_one_nurbs_face() {
+        check_sheet(&surface(1), 1);
+    }
+
+    #[test]
+    fn tspline_with_t_junctions_becomes_sewn_bezier_faces() {
+        let ts = surface(2).refine(&[Cut::S { s: 0.33, t0: 0.3, t1: 0.6 }, Cut::T { t: 0.45, s0: 0.2, s1: 0.45 }]).unwrap();
+        assert!(!ts.mesh().is_regular());
+        let n = ts.bezier_elements().unwrap().len();
+        check_sheet(&ts, n);
+    }
+
+    #[test]
+    fn hostile_tsplines_never_panic() {
+        let base = surface(3);
+        let n = base.mesh().vertices().len();
+        let mesh = base.mesh().clone();
+        // Every control point at one place, enormous coordinates, a needle-thin patch.
+        let cases: Vec<Vec<Vec3>> = vec![
+            vec![Vec3::new(1.0, 2.0, 3.0); n],
+            (0..n).map(|k| Vec3::new(1e300, -1e300, k as f64 * 1e299)).collect(),
+            (0..n).map(|k| Vec3::new(k as f64 * 1e-12, 0.0, 0.0)).collect(),
+        ];
+        for pts in cases {
+            let Ok(ts) = TSpline::new(mesh.clone(), [3, 3], &pts, &vec![1.0; n]) else { continue };
+            if let Ok(body) = tspline_sheet(&ts) {
+                let _ = body.tessellate(0.01);
+            }
+            if let Ok(r) = ts.refine(&[Cut::S { s: 0.33, t0: 0.3, t1: 0.6 }])
+                && let Ok(body) = tspline_sheet(&r)
+            {
+                let _ = body.tessellate(0.01);
+            }
+        }
+    }
+}