geometry: patch tessellation

crates/nanobrush-geometry/src/lib.rs

@@ -102,3 +102,4 @@ impl Budget {
         Ok(())
     }
 }
+pub mod patch;

crates/nanobrush-geometry/src/patch.rs

@@ -0,0 +1,208 @@
+use crate::{math::*, *};
+use mb3_dat::Patch9;
+#[derive(Clone, Copy, Debug)]
+pub struct Sample {
+    pub point: DVec3,
+    pub normal: DVec3,
+}
+#[derive(Debug)]
+pub struct Mesh {
+    pub points: Vec<DVec3>,
+    pub normals: Vec<DVec3>,
+    pub columns: usize,
+    pub rows: usize,
+    pub bounds: Aabb,
+    pub stats: Stats,
+}
+fn shape(p: &Patch9) -> Result<(usize, usize)> {
+    let au = p.anchors_u as usize;
+    let av = p.anchors_v as usize;
+    if au < 3 || av < 3 || au % 2 == 0 || av % 2 == 0 || p.quads_u < 2 || p.quads_v < 2 {
+        return Err(Error::InvalidDimensions);
+    }
+    if p.anchors.len() != au.checked_mul(av).ok_or(Error::Overflow)? {
+        return Err(Error::InconsistentData);
+    }
+    Ok((au / 2, av / 2))
+}
+fn basis(t: f64) -> ([f64; 3], [f64; 3]) {
+    (
+        [(1. - t) * (1. - t), 2. * t * (1. - t), t * t],
+        [-2. * (1. - t), 2. - 4. * t, 2. * t],
+    )
+}
+fn evaluate(
+    p: &Patch9,
+    tile_u: usize,
+    tile_v: usize,
+    u: f64,
+    v: f64,
+    policy: Policy,
+) -> Result<Sample> {
+    let (bu, du) = basis(u);
+    let (bv, dv) = basis(v);
+    let mut point = [0.; 3];
+    let mut tangent_u = [0.; 3];
+    let mut tangent_v = [0.; 3];
+    for j in 0..3 {
+        for i in 0..3 {
+            let index = (tile_u * 2 + i) + (tile_v * 2 + j) * (p.anchors_u as usize);
+            let a = from_f32(*p.anchors.get(index).ok_or(Error::InconsistentData)?)?;
+            point = add(point, scale(a, bu[i] * bv[j]));
+            tangent_u = add(tangent_u, scale(a, du[i] * bv[j]));
+            tangent_v = add(tangent_v, scale(a, bu[i] * dv[j]));
+        }
+    }
+    let n = cross(unit(tangent_v)?, unit(tangent_u)?);
+    if length(n) <= policy.angular_epsilon {
+        return Err(Error::Degenerate);
+    }
+    Ok(Sample {
+        point: finite(point)?,
+        normal: unit(n)?,
+    })
+}
+pub fn sample(
+    p: &Patch9,
+    tile_u: usize,
+    tile_v: usize,
+    u: f64,
+    v: f64,
+    policy: Policy,
+) -> Result<Sample> {
+    let policy = policy.validate()?;
+    let (tu, tv) = shape(p)?;
+    if tile_u >= tu
+        || tile_v >= tv
+        || !u.is_finite()
+        || !v.is_finite()
+        || !(0. ..=1.).contains(&u)
+        || !(0. ..=1.).contains(&v)
+    {
+        return Err(Error::InvalidDimensions);
+    }
+    evaluate(p, tile_u, tile_v, u, v, policy)
+}
+pub fn tessellate(p: &Patch9, policy: Policy, limits: ComputeLimits) -> Result<Mesh> {
+    let policy = policy.validate()?;
+    let (tu, tv) = shape(p)?;
+    let qu = p.quads_u as usize;
+    let qv = p.quads_v as usize;
+    let columns = tu
+        .checked_mul(qu)
+        .and_then(|n| n.checked_add(1))
+        .ok_or(Error::Overflow)?;
+    let rows = tv
+        .checked_mul(qv)
+        .and_then(|n| n.checked_add(1))
+        .ok_or(Error::Overflow)?;
+    let n = columns.checked_mul(rows).ok_or(Error::Overflow)?;
+    if n > limits.max_vertices {
+        return Err(Error::Limit);
+    }
+    let mut b = Budget {
+        limits,
+        stats: Stats::default(),
+    };
+    b.work(p.anchors.len())?;
+    for v in &p.anchors {
+        from_f32(*v)?;
+    }
+    let mut points = b.reserve(n)?;
+    let mut normals = b.reserve(n)?;
+    for y in 0..rows {
+        let ty = (y / qv).min(tv - 1);
+        let v = (y - ty * qv) as f64 / qv as f64;
+        for x in 0..columns {
+            b.work(9)?;
+            let tx = (x / qu).min(tu - 1);
+            let u = (x - tx * qu) as f64 / qu as f64;
+            let s = evaluate(p, tx, ty, u, v, policy)?;
+            points.push(s.point);
+            normals.push(s.normal);
+        }
+    }
+    let bounds = Aabb::from_points(points.iter().copied())?.ok_or(Error::Degenerate)?;
+    b.stats.vertices = n;
+    Ok(Mesh {
+        points,
+        normals,
+        columns,
+        rows,
+        bounds,
+        stats: b.stats,
+    })
+}
+#[cfg(test)]
+pub(crate) fn flat(au: u32, av: u32) -> Patch9 {
+    Patch9 {
+        anchors_u: au,
+        anchors_v: av,
+        quads_u: 2,
+        quads_v: 2,
+        anchors: (0..av)
+            .flat_map(|v| (0..au).map(move |u| [u as f32, 0., v as f32]))
+            .collect(),
+        computed: None,
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn flat_patch_endpoints_grid_and_normals() {
+        let p = flat(3, 3);
+        let m = tessellate(&p, Policy::default(), ComputeLimits::default()).unwrap();
+        assert_eq!((m.columns, m.rows), (3, 3));
+        assert_eq!(m.points[0], [0., 0., 0.]);
+        assert_eq!(m.points[8], [2., 0., 2.]);
+        assert!(m.normals.iter().all(|v| *v == [0., 1., 0.]));
+        assert_eq!(m.bounds.min, [0.; 3]);
+    }
+    #[test]
+    fn curvature_midpoint_and_shared_seams() {
+        let mut p = flat(5, 3);
+        p.anchors[1][1] = 4.;
+        p.anchors[6][1] = 4.;
+        p.anchors[11][1] = 4.;
+        let left = sample(&p, 0, 0, 1., 0.5, Policy::default()).unwrap();
+        let right = sample(&p, 1, 0, 0., 0.5, Policy::default()).unwrap();
+        assert_eq!(left.point, right.point);
+        assert_eq!(
+            sample(&p, 0, 0, 0.5, 0.5, Policy::default()).unwrap().point,
+            [1., 2., 1.]
+        );
+        let m = tessellate(&p, Policy::default(), ComputeLimits::default()).unwrap();
+        assert_eq!((m.columns, m.rows), (5, 3));
+    }
+    #[test]
+    fn bad_shapes_degeneracy_and_limits() {
+        let mut p = flat(3, 3);
+        p.anchors.pop();
+        assert!(tessellate(&p, Policy::default(), ComputeLimits::default()).is_err());
+        p = flat(3, 3);
+        p.anchors.fill([0.; 3]);
+        assert!(tessellate(&p, Policy::default(), ComputeLimits::default()).is_err());
+        p = flat(3, 3);
+        for l in [
+            ComputeLimits {
+                max_vertices: 8,
+                ..Default::default()
+            },
+            ComputeLimits {
+                max_work: 1,
+                ..Default::default()
+            },
+            ComputeLimits {
+                max_owned_bytes: 1,
+                ..Default::default()
+            },
+        ] {
+            assert!(tessellate(&p, Policy::default(), l).is_err());
+        }
+        assert!(sample(&p, 1, 0, 0., 0., Policy::default()).is_err());
+        p.quads_u = u32::MAX;
+        p.quads_v = u32::MAX;
+        assert!(tessellate(&p, Policy::default(), ComputeLimits::default()).is_err());
+    }
+}

docs/GEOMETRY.md

@@ -11,3 +11,9 @@ Tests cover signed basis orientation, asymmetric three-plane intersections, para
 `brush::contours` enumerates checked plane triples, keeps interior intersections, welds points within distance epsilon and orders each face around its outward normal. Starts are rotated to lexicographically smallest coordinates. Every original plane must contribute a face: duplicate/redundant/degenerate faces are errors, preserving plane identity rather than silently dropping them. Feasible recession directions, missing/invalid edges and nonpositive volume reject unbounded or collapsed objects. Every edge must occur twice. This is a strict native convex profile, not the host's collapse/discard behavior.
 
 Defaults cap 64 planes, 100,000 generated face vertices, 10 million work units and 128 MiB requested scratch/output storage. Work includes recession checks, triple candidates, containment and welding; face sorting is additionally bounded by vertex caps. Allocations are fallible; errors return no partial mesh. Analytic cube, translated box, winding/topology/determinism, contradictory/open/redundant and resource-limit tests pass. Near-degenerate geometry can be rejected conservatively; exact legacy tolerances remain unverified.
+
+## Patch9 tessellation
+
+`patch::sample` evaluates a quadratic 3×3 tile and analytic derivatives; `tessellate` spans odd anchor grids with overlapping tiles every two anchors, U varying fastest. The evaluator uses the tensor product of three-control-point quadratic curves ([W3C quadratic curve definition](https://www.w3.org/TR/SVG/paths.html#PathDataQuadraticBezierCommands)); this tensor-product choice is native policy, not recovered host implementation. Basis is `[(1-t)^2,2t(1-t),t²]`; derivatives are `[-2(1-t),2-4t,2t]`.
+
+Anchor dimensions must be odd and at least three, and quads per tile at least two, matching source API declarations. Normals use `dv×du` to agree with exported OBJ quad winding. At an interior tile boundary, the right/upper tile supplies the derivative; positional seams are shared but normals are not averaged. Degenerate tangents/normals fail rather than inventing a direction. Sample count/products, work (nine control evaluations per sample) and requested point/normal allocations are bounded. Flat XZ patches, endpoints, exact quadratic midpoints, multi-tile seams and invalid/budget cases pass. Folded/self-intersecting surfaces and legacy seam-normal parity remain open.

docs/PROGRESS_2026-10-26.md

@@ -10,7 +10,7 @@ Scope: extend native headless formats and geometry. Each stage is independently
 | 4 | P6.26 | CLI OBJ with loss acknowledgement | Complete: `--to obj`, grouped preflight losses and explicit `--allow-lossy`; missing computed data remains blocking. Existing atomic publication is reused. CLI acknowledgement/preflight/regression tests pass. |
 | 5 | P5.15 | Geometry primitives/bounds | Complete: f64 vector helpers, checked unit plane equations/triple intersections, f32 boundary checks, MAP axes and AABBs. Analytic/degenerate/scaled-basis tests pass; native epsilon/interior policy documented separately from legacy parity. |
 | 6 | P5.16 | Convex brush contours | Complete: bounded half-space intersections, recession rejection, deterministic outward contours, closed-edge and volume checks. Cube/translation/winding/invalid/redundant/budget tests pass. |
-| 7 | P5.17 | Patch9 tessellation | Pending |
+| 7 | P5.17 | Patch9 tessellation | Complete: tiled tensor-quadratic positions, analytic derivatives, OBJ-consistent normals, shared-position seam policy and bounded allocations/work. Planar/curved/multi-tile/degenerate/limit tests pass. |
 | 8 | P5.18 | Computed world pipeline/CLI | Pending |
 | 9 | P5.19 | Nearest-hit ray queries | Pending |
 | 10 | P5.20 | Property table edits/reindexing | Pending |

docs/TODO.md

@@ -130,6 +130,8 @@ Each task ID is stable. Split tasks into child IDs as evidence grows. Record dep
 
 - [x] P5.16 Implement bounded native convex brush contour reconstruction, topology checks and analytic regressions ([GEOMETRY.md](GEOMETRY.md)).
 
+- [x] P5.17 Implement bounded native Patch9 tensor-quadratic sampling/tessellation and analytic normals ([GEOMETRY.md](GEOMETRY.md)).
+
 ## P6 — File formats and converters
 
 **Depends on:** P3 oracle where available, P5 document model. **Exit:** standalone format specifications, declared compatibility subsets, fixture corpus, and native codecs.