From 9e3dc7848bd8c954a03f9dc7eb93a7dfeaaa2cc2 Mon Sep 17 00:00:00 2001 From: jyviko <2501648+jyviko@users.noreply.github.com> Date: Tue, 20 Oct 2026 22:53:02 -0400 Subject: [PATCH] Wave 1/509: kernel: exact pcurves of lines and splines on planes (and 3 more) 4 commits, squashed; the originals stay reachable from tag archive/merge-main-develop. - 7024ceec8 jyviko: CI: no runs for pull requests into kernel-smlib for now - 92d433ca9 jyviko: AGENTS.md: the kernel-smlib branch's rules (ADR 0002) - ee5deffaa jyviko: brep: Curve2 pcurve type and the truck pcurve entry point - 26ab8981d jyviko: kernel: exact pcurves of lines and splines on planes Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01DtL5M41G8Nua7HvuFPZkmJ --- .github/workflows/ci.yml | 3 + crates/geom/src/brep.rs | 2 + crates/geom/src/brep/curve2.rs | 67 ++++++++++++++++ crates/kernel/src/native.rs | 103 +++++++++++++++++++++++++ crates/kernel/src/native/pcurve.rs | 119 +++++++++++++++++++++++++++++ 5 files changed, 294 insertions(+) create mode 100644 crates/geom/src/brep/curve2.rs create mode 100644 crates/kernel/src/native/pcurve.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0f3c830ad..0e0a6a85a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -48,6 +48,9 @@ on: # only (other labels are skipped, see the top of this file). pull_request: types: [opened, synchronize, reopened, ready_for_review, labeled] + # The kernel-smlib branch (ADR 0002) runs no CI for now (owner, 2026-10-21). Drop this + # line before the branch merges back into main. + branches-ignore: [kernel-smlib] # The merge queue: each queued group runs the full suite before it lands on main. merge_group: push: diff --git a/crates/geom/src/brep.rs b/crates/geom/src/brep.rs index aef024e53..64e7851d1 100644 --- a/crates/geom/src/brep.rs +++ b/crates/geom/src/brep.rs @@ -3,7 +3,9 @@ //! Validation checks structure and resource budgets, not geometric equivalence or trust. use serde::{Deserialize, Serialize}; +mod curve2; pub mod envelope; +pub use curve2::Curve2; pub const VERSION: u32 = 3; pub const MAX_ITEMS: usize = 1_000_000; diff --git a/crates/geom/src/brep/curve2.rs b/crates/geom/src/brep/curve2.rs new file mode 100644 index 000000000..ba33f82c5 --- /dev/null +++ b/crates/geom/src/brep/curve2.rs @@ -0,0 +1,67 @@ +//! Pcurves: an edge in its face's surface parameters, (u, v). 2D B-splines only, as SMLib keeps +//! its UV trim curves (`SmBSplineCurve`); 2D lines and arcs are exact as degree-1 and rational +//! quadratic splines. +use serde::{Deserialize, Serialize}; + +use super::{Budget, Result, knots, numbers, require}; + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)] +pub enum Curve2 { + Spline { + knots: Vec, + points: Vec<[f64; 2]>, + }, + /// Homogeneous `[u*w, v*w, w]` coefficients. + RationalSpline { + knots: Vec, + homogeneous: Vec<[f64; 3]>, + }, +} + +impl Curve2 { + /// The active parameter interval `[knots[degree], knots[count]]`. + pub fn interval(&self) -> Option<[f64; 2]> { + let (k, count) = match self { + Curve2::Spline { knots, points } => (knots, points.len()), + Curve2::RationalSpline { knots, homogeneous } => (knots, homogeneous.len()), + }; + let degree = k.len().checked_sub(count.checked_add(1)?)?; + Some([*k.get(degree)?, *k.get(count)?]) + } +} + +#[allow(dead_code)] // called by the schema 4 validator +pub(super) fn curve2(c: &Curve2, budget: &mut Budget) -> Result<()> { + budget.add(1)?; + match c { + Curve2::Spline { knots: k, points } => { + knots(k, points.len(), budget)?; + budget.add(points.len())?; + numbers(points.iter().flatten().copied()) + } + Curve2::RationalSpline { knots: k, homogeneous } => { + knots(k, homogeneous.len(), budget)?; + budget.add(homogeneous.len())?; + numbers(homogeneous.iter().flatten().copied())?; + require(homogeneous.iter().all(|p| p[2] >= 1e-12), "non-positive rational weight") + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn pcurves_validate_and_round_trip() { + let line = Curve2::Spline { knots: vec![0., 0., 1., 1.], points: vec![[0., 0.], [1., 2.]] }; + curve2(&line, &mut Budget(0)).unwrap(); + assert_eq!(line.interval(), Some([0., 1.])); + assert_eq!(serde_json::from_str::(&serde_json::to_string(&line).unwrap()).unwrap(), line); + let bad = Curve2::RationalSpline { knots: vec![0., 0., 1., 1.], homogeneous: vec![[0., 0., 1.], [1., 2., 0.]] }; + assert!(curve2(&bad, &mut Budget(0)).is_err()); + let nan = Curve2::Spline { knots: vec![0., 0., 1., 1.], points: vec![[0., f64::NAN], [1., 2.]] }; + assert!(curve2(&nan, &mut Budget(0)).is_err()); + } +} diff --git a/crates/kernel/src/native.rs b/crates/kernel/src/native.rs index fe05f55da..95da32a1c 100644 --- a/crates/kernel/src/native.rs +++ b/crates/kernel/src/native.rs @@ -8,6 +8,8 @@ use std::sync::Arc; mod adapter; mod binary; mod metadata; +#[allow(dead_code)] +mod pcurve; mod preview; pub use preview::native_preview_mesh; @@ -350,4 +352,105 @@ mod tests { let restored = decode_native_body(&encode_native_body(&body).unwrap()).unwrap(); equal(&body, &restored); } + + /// Every pcurve of every face of `body` validates as the schema validator does, spans its + /// curve's range, lifts onto the surface within `tol` (64 samples and every span midpoint), + /// and each wire closes in (u, v): consecutive uses meet, or meet across a pole (the gap + /// lifts to one point). Returns the wires whose closure is a whole number of periods (a loop + /// round a pole or the surface), as (face, wire). + fn check_pcurves(body: &Body, tol: f64) -> Vec<(usize, usize)> { + use truck_modeling::{BoundedCurve, MetricSpace, ParametricCurve, ParametricSurface}; + let mut winding = Vec::new(); + for (f, face) in body.solid.face_iter().enumerate() { + let surface = face.surface(); + let all = pcurve::pcurves(face, tol).unwrap_or_else(|e| panic!("face {f}: {e}")); + let wires = face.boundaries(); + assert_eq!(all.len(), wires.len()); + let lift = |uv: [f64; 2]| surface.subs(uv[0], uv[1]); + for (w, (pcs, wire)) in all.iter().zip(&wires).enumerate() { + assert_eq!(pcs.len(), wire.len()); + let mut ends = Vec::new(); + for (i, (pc, edge)) in pcs.iter().zip(wire.edge_iter()).enumerate() { + let at = format!("face {f} wire {w} edge {i}"); + let (knots, count, values): (&Vec, usize, Vec) = match pc { + solidcraft_geom::brep::Curve2::Spline { knots, points } => (knots, points.len(), points.iter().flatten().copied().collect()), + solidcraft_geom::brep::Curve2::RationalSpline { knots, homogeneous } => { + assert!(homogeneous.iter().all(|h| h[2] >= 1e-12), "{at}: weight"); + (knots, homogeneous.len(), homogeneous.iter().flatten().copied().collect()) + } + }; + let degree = knots.len() - count - 1; + assert!((2..=4096).contains(&count) && (1..=16).contains(°ree) && degree < count, "{at}: size"); + assert!(knots.windows(2).all(|k| k[0] <= k[1]) && knots[degree] < knots[count], "{at}: knots"); + assert!(values.iter().chain(knots).all(|x| x.is_finite() && x.abs() <= 1e12), "{at}: numbers"); + let curve = edge.curve(); + let (t0, t1) = curve.range_tuple(); + assert_eq!(pc.interval(), Some([t0, t1]), "{at}: interval"); + let mut ts: Vec = (0..=64).map(|k| t0 + (t1 - t0) * k as f64 / 64.).collect(); + ts.extend(knots.windows(2).filter(|k| k[0] < k[1]).map(|k| 0.5 * (k[0] + k[1]))); + for t in ts { + let uv = pcurve::eval(pc, t).unwrap_or_else(|| panic!("{at}: eval at {t}")); + let d = lift(uv).distance(curve.subs(t)); + assert!(d <= tol, "{at}: lift error {d} at {t}"); + } + let (a, b) = (pcurve::eval(pc, t0).unwrap(), pcurve::eval(pc, t1).unwrap()); + ends.push(if edge.orientation() { (a, b) } else { (b, a) }); + } + let mut wraps = false; + for k in 0..ends.len() { + let (end, start) = (ends[k].1, ends[(k + 1) % ends.len()].0); + let gap = (end[0] - start[0]).abs().max((end[1] - start[1]).abs()); + if gap <= 1e-9 { + continue; + } + // A pole: the gap's ends and middle are one point in space. + let mid = [0.5 * (end[0] + start[0]), 0.5 * (end[1] + start[1])]; + let one = lift(end).distance(lift(start)).max(lift(end).distance(lift(mid))); + if one <= tol { + continue; + } + let periods = [surface.u_period(), surface.v_period()]; + let whole = (0..2).all(|d| { + let g = start[d] - end[d]; + g.abs() <= 1e-9 || periods[d].is_some_and(|p| (g / p - (g / p).round()).abs() <= 1e-9) + }); + assert!( + whole && lift(end).distance(lift(start)) <= tol, + "face {f} wire {w}: open between uses {k} and {}: {end:?} {start:?}", + (k + 1) % ends.len() + ); + wraps = true; + } + if wraps { + winding.push((f, w)); + } + } + } + winding + } + + #[test] + fn pcurves_on_planes_are_the_curves_mapped_exactly() { + use truck_modeling::{BoundedCurve, ParametricCurve, ParametricSurface}; + let cube = crate::box_solid(Vec3::new(-3., 1., 2.), Vec3::new(40., 30., 10.)).unwrap(); + assert!(check_pcurves(&cube, 1e-9).is_empty()); + // Bit for bit: each line's pcurve ends lift to the line's own ends. + for face in cube.solid.face_iter() { + let surface = face.surface(); + for (pcs, wire) in pcurve::pcurves(face, 1e-9).unwrap().iter().zip(face.boundaries()) { + for (pc, edge) in pcs.iter().zip(wire.edge_iter()) { + let solidcraft_geom::brep::Curve2::Spline { points, .. } = pc else { panic!("a line is a degree-1 spline") }; + let curve = edge.curve(); + let (t0, t1) = curve.range_tuple(); + assert_eq!(surface.subs(points[0][0], points[0][1]), curve.subs(t0)); + assert_eq!(surface.subs(points[1][0], points[1][1]), curve.subs(t1)); + } + } + } + // Arcs (rational) on the cylinder's caps. + let cyl = crate::cylinder(Vec3::ZERO, Vec3::Z, 5., 40.).unwrap(); + for face in cyl.solid.face_iter().filter(|f| matches!(f.surface(), truck_modeling::Surface::Plane(_))) { + assert!(pcurve::pcurves(face, 1e-9).unwrap().iter().flatten().all(|c| matches!(c, solidcraft_geom::brep::Curve2::RationalSpline { .. }))); + } + } } diff --git a/crates/kernel/src/native/pcurve.rs b/crates/kernel/src/native/pcurve.rs new file mode 100644 index 000000000..53d3767a1 --- /dev/null +++ b/crates/kernel/src/native/pcurve.rs @@ -0,0 +1,119 @@ +//! Pcurves for truck faces, which keep none: each edge use's curve in its face's surface +//! parameters, on the parameter of the edge's own curve (as the adapter writes it), running in +//! that curve's direction. Exact where the edge lies on its surface in closed form, otherwise a +//! 2D B-spline fitted within the tolerance. +use super::Result; +use crate::KernelError; +use crate::body::from_p3; +use crate::tess::uv; +use mt::BoundedCurve; +use solidcraft_geom::brep as b; +use solidcraft_geom::tess::EvalSurface; +use truck_modeling as mt; + +/// For each of `face`'s boundary wires, in order, the pcurve of each of its edges, in order, in +/// the (u, v) of the face's surface as truck evaluates it (`ParametricSurface::subs`), within +/// `tolerance` mm when lifted onto the surface. Wires and edges run as `face.boundaries()` lists +/// them (the order the adapter writes); each pcurve runs in its curve's own direction. +pub(super) fn pcurves(face: &mt::Face, tolerance: f64) -> Result>> { + if !(tolerance.is_finite() && tolerance > 0.0) { + return Err(KernelError::Invalid(format!("pcurve tolerance {tolerance}"))); + } + crate::guard("pcurves", || { + let surface = face.surface(); + let mut out = Vec::new(); + for (w, wire) in face.boundaries().iter().enumerate() { + let mut uses = Vec::new(); + for (i, edge) in wire.edge_iter().enumerate() { + let curve = edge.curve(); + let pc = pcurve(&surface, &curve).map_err(|e| KernelError::Failed(format!("pcurve of wire {w} edge {i}: {e}")))?; + uses.push(pc); + } + out.push(uses); + } + Ok(out) + }) +} + +fn pcurve(surface: &mt::Surface, curve: &mt::Curve) -> Result { + match surface { + mt::Surface::Plane(_) => on_plane(surface, curve), + _ => Err(KernelError::Failed("not supported yet: pcurves on curved surfaces".into())), + } +} + +/// A line or (rational) B-spline on a plane: the plane's parameters are affine in space, so the +/// pcurve is the curve's own knots and weights with its control points mapped. +fn on_plane(surface: &mt::Surface, curve: &mt::Curve) -> Result { + let Some(plane @ EvalSurface::Plane { .. }) = crate::tess::surface::eval_surface(surface) else { + return Err(KernelError::Failed("plane parameters".into())); + }; + let dom = uv::domain(&plane); + let map = |p: mt::Point3| uv::project(&plane, &dom, from_p3(p), None, 0.0).ok_or_else(|| KernelError::Failed("degenerate plane".into())); + Ok(match curve { + mt::Curve::Line(l) => { + let (t0, t1) = curve.range_tuple(); + b::Curve2::Spline { knots: vec![t0, t0, t1, t1], points: vec![map(l.0)?, map(l.1)?] } + } + mt::Curve::BSplineCurve(c) => b::Curve2::Spline { + knots: c.knot_vec().iter().copied().collect(), + points: c.control_points().iter().map(|p| map(*p)).collect::>()?, + }, + mt::Curve::NurbsCurve(c) => b::Curve2::RationalSpline { + knots: c.knot_vec().iter().copied().collect(), + homogeneous: c + .control_points() + .iter() + .map(|h| { + let [u, v] = map(mt::Point3::new(h.x / h.w, h.y / h.w, h.z / h.w))?; + Ok([u * h.w, v * h.w, h.w]) + }) + .collect::>()?, + }, + mt::Curve::IntersectionCurve(_) => return Err(KernelError::Failed("not supported yet: intersection pcurves".into())), + }) +} + +/// The point of `c` at `t` (`None` outside its interval or for malformed records). +pub(super) fn eval(c: &b::Curve2, t: f64) -> Option<[f64; 2]> { + let (knots, h): (&[f64], Vec<[f64; 3]>) = match c { + b::Curve2::Spline { knots, points } => (knots, points.iter().map(|&[u, v]| [u, v, 1.0]).collect()), + b::Curve2::RationalSpline { knots, homogeneous } => (knots, homogeneous.clone()), + }; + let p = knots.len().checked_sub(h.len() + 1)?; + let span = solidcraft_geom::bspline::find_span(knots, p, h.len(), t)?; + let n = basis(knots, p, span, t)?; + let mut s = [0.0; 3]; + for (j, nj) in n.iter().enumerate() { + let q = h.get(span + j - p)?; + for (a, x) in s.iter_mut().zip(q) { + *a += nj * x; + } + } + (s[2].abs() > 0.0).then(|| [s[0] / s[2], s[1] / s[2]]) +} + +/// The `p + 1` basis functions non-zero on knot span `span` at `t` (NURBS Book A2.2). +fn basis(knots: &[f64], p: usize, span: usize, t: f64) -> Option> { + if span < p || span + p >= knots.len() { + return None; + } + let k = |i: usize| knots.get(i).copied().unwrap_or(0.0); + let mut n = vec![0.0; p + 1]; + let (mut left, mut right) = (vec![0.0; p + 1], vec![0.0; p + 1]); + *n.first_mut()? = 1.0; + for j in 1..=p { + *left.get_mut(j)? = t - k(span + 1 - j); + *right.get_mut(j)? = k(span + j) - t; + let mut saved = 0.0; + for r in 0..j { + let (rr, lj) = (*right.get(r + 1)?, *left.get(j - r)?); + let den = rr + lj; + let tmp = if den != 0.0 { n.get(r)? / den } else { 0.0 }; + *n.get_mut(r)? = saved + rr * tmp; + saved = lj * tmp; + } + *n.get_mut(j)? = saved; + } + Some(n) +}