From 6e31ede77143f2897f3b670827fa5783a134ee30 Mon Sep 17 00:00:00 2001 From: blackboots <47943405+aka-blackboots@users.noreply.github.com> Date: Wed, 4 Mar 2026 09:47:00 +0100 Subject: [PATCH 1/4] Add kernel and three.js boolean shape operations --- ...03-04-boolean-operations-implementation.md | 62 ++ .../examples-vite/index.html | 10 +- .../examples-vite/operations/boolean.html | 12 + .../src/pages/operations-boolean.ts | 78 +++ main/opengeometry-three/index.ts | 5 + .../src/operations/boolean.ts | 95 +++ .../src/operations/index.ts | 1 + main/opengeometry/src/lib.rs | 1 + main/opengeometry/src/operations/boolean.rs | 555 ++++++++++++++++++ 9 files changed, 818 insertions(+), 1 deletion(-) create mode 100644 AI-DOCs/2026-03-04-boolean-operations-implementation.md create mode 100644 main/opengeometry-three/examples-vite/operations/boolean.html create mode 100644 main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts create mode 100644 main/opengeometry-three/src/operations/boolean.ts create mode 100644 main/opengeometry-three/src/operations/index.ts create mode 100644 main/opengeometry/src/operations/boolean.rs diff --git a/AI-DOCs/2026-03-04-boolean-operations-implementation.md b/AI-DOCs/2026-03-04-boolean-operations-implementation.md new file mode 100644 index 0000000..94f9a57 --- /dev/null +++ b/AI-DOCs/2026-03-04-boolean-operations-implementation.md @@ -0,0 +1,62 @@ +# 2026-03-04 Boolean Operations Implementation + +## What changed + +- Added a new kernel operation module `operations::boolean` with a wasm-bindgen class `OGBoolean`. +- `OGBoolean::compute` accepts two triangle buffers (`[x,y,z,...]`), an operation (`union`, `intersection`, `difference`), and optional numeric constraints. +- Implemented a BSP/plane-splitting CSG pipeline (`Node`, `Plane`, `Polygon`) with tolerance-driven vertex snapping and post-op vertex welding. +- Exposed the new module from `main/opengeometry/src/lib.rs`. +- Added `@opengeometry/kernel-three` bindings: + - `BooleanShape` for running booleans on any `THREE.Mesh` with `BufferGeometry`. + - `BooleanConstraints` and `BooleanOperation` types. +- Added a new Vite example page (`examples-vite/operations/boolean.html`) and runtime page logic (`operations-boolean.ts`). +- Updated the examples index to advertise the new Boolean operation card. + +## Why it changed + +The project needed a shape-agnostic boolean pipeline. Existing shape wrappers already produce triangulated meshes, so this implementation uses those triangulations as a shared interchange format and applies constructive-solid-geometry operations in the kernel, then returns a new triangle buffer for rendering. + +## Paper alignment and robustness strategy + +The requested `RobustBoolean.pdf` was not available inside this execution environment, so direct line-by-line extraction from the paper was not possible during implementation. This change still applies common robust boolean principles typically emphasized in robust CSG literature: + +- Epsilon-based plane classification (`front`, `back`, `coplanar`, `spanning`) +- Grid snapping for deterministic splitting intersections +- Vertex welding after operation completion + +These controls are exposed as `constraints.epsilon` and `constraints.snap` so callers can tune behavior per model scale. + +## How to test locally + +1. Kernel tests: + +```bash +cargo test --manifest-path main/opengeometry/Cargo.toml +``` + +2. Build wasm package (requires `wasm-pack`): + +```bash +npm run build-core +``` + +3. Build Three adapter/examples: + +```bash +npm run build-three +npm --prefix main/opengeometry-three run build-example-three +``` + +4. Open `main/opengeometry-three/examples-vite/operations/boolean.html` through the Vite examples app. + +## Backward compatibility + +- No existing public API was removed. +- Existing shapes/primitives continue unchanged. +- New API is additive (`OGBoolean`, `BooleanShape`). + +## Known caveats and follow-ups + +- Current boolean output quality depends on clean manifold triangulations. +- Numerical controls may need per-project presets depending on unit scale. +- A follow-up should validate against the intended RobustBoolean paper test corpus once the PDF is available in-repo. diff --git a/main/opengeometry-three/examples-vite/index.html b/main/opengeometry-three/examples-vite/index.html index d4b3d00..d6e0f41 100644 --- a/main/opengeometry-three/examples-vite/index.html +++ b/main/opengeometry-three/examples-vite/index.html @@ -134,7 +134,7 @@

Shapes

Operations

-

3 items

+

4 items

@@ -153,6 +153,14 @@

Operations

Control
Thickness
 + +

Boolean

new

+

Union / intersection / difference with numeric robustness controls.

+
+
Domain
Kernel Ops
+
Control
Op + Epsilon
+
+

Sweep Path + Profile

ready

Operation-level sweep from path primitive + profile primitive.

diff --git a/main/opengeometry-three/examples-vite/operations/boolean.html b/main/opengeometry-three/examples-vite/operations/boolean.html new file mode 100644 index 0000000..dc870cb --- /dev/null +++ b/main/opengeometry-three/examples-vite/operations/boolean.html @@ -0,0 +1,12 @@ + + + + + + OpenGeometry • Boolean Operation + + +
+ + + diff --git a/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts b/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts new file mode 100644 index 0000000..c081cd4 --- /dev/null +++ b/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts @@ -0,0 +1,78 @@ +import * as THREE from "three"; +import { Vector3 } from "../../../../opengeometry/pkg/opengeometry"; +import { BooleanShape, Cuboid, Sphere } from "@og-three"; +import { + bootstrapExample, + mountControls, + replaceSceneObject, +} from "../shared/runtime"; + +const operations = ["union", "intersection", "difference"] as const; + +void bootstrapExample({ + title: "Boolean (Union / Intersection / Difference)", + description: + "Robust BSP-style constructive solid geometry over any OpenGeometry triangulated shape.", + build: ({ scene }) => { + let result: THREE.Mesh | null = null; + + const update = (state: Record) => { + const left = new Cuboid({ + center: new Vector3(-0.4, 0.9, 0), + width: state.leftWidth as number, + height: 1.8, + depth: 1.5, + color: 0x10b981, + }); + left.outline = true; + + const right = new Sphere({ + center: new Vector3(0.5, 0.9, 0), + radius: state.rightRadius as number, + widthSegments: 30, + heightSegments: 20, + color: 0xf97316, + }); + right.outline = true; + + const operation = operations[Math.round(state.operation as number)] ?? "union"; + const boolean = new BooleanShape(left, right, operation, { + epsilon: state.epsilon as number, + snap: state.snap as number, + }); + + boolean.material = new THREE.MeshStandardMaterial({ + color: 0x2563eb, + transparent: true, + opacity: 0.72, + }); + + scene.add(left); + scene.add(right); + result = replaceSceneObject(scene, result, boolean); + + left.removeFromParent(); + right.removeFromParent(); + }; + + mountControls( + "Boolean Controls", + [ + { type: "number", key: "operation", label: "Operation (0=Union,1=Intersect,2=Diff)", min: 0, max: 2, step: 1, value: 0 }, + { type: "number", key: "leftWidth", label: "Left Cuboid Width", min: 0.8, max: 2.2, step: 0.1, value: 1.4 }, + { type: "number", key: "rightRadius", label: "Right Sphere Radius", min: 0.5, max: 1.2, step: 0.05, value: 0.85 }, + { type: "number", key: "epsilon", label: "Plane Epsilon", min: 0.000001, max: 0.005, step: 0.000001, value: 0.00001 }, + { type: "number", key: "snap", label: "Snap Grid", min: 0.000001, max: 0.005, step: 0.000001, value: 0.00001 }, + ], + update + ); + + update({ + operation: 0, + leftWidth: 1.4, + rightRadius: 0.85, + epsilon: 0.00001, + snap: 0.00001, + }); + }, +}); diff --git a/main/opengeometry-three/index.ts b/main/opengeometry-three/index.ts index 01a6e71..2bd6d9c 100644 --- a/main/opengeometry-three/index.ts +++ b/main/opengeometry-three/index.ts @@ -666,3 +666,8 @@ export * from './src/shapes/'; * Reusable example builders for quickly wiring demo scenes. */ export * from './src/examples/'; + +/** + * Boolean/constructive solid geometry operations. + */ +export * from './src/operations/'; diff --git a/main/opengeometry-three/src/operations/boolean.ts b/main/opengeometry-three/src/operations/boolean.ts new file mode 100644 index 0000000..910093c --- /dev/null +++ b/main/opengeometry-three/src/operations/boolean.ts @@ -0,0 +1,95 @@ +import { OGBoolean } from "../../../opengeometry/pkg/opengeometry"; +import * as THREE from "three"; + +export type BooleanOperation = "union" | "intersection" | "difference"; + +export interface BooleanConstraints { + epsilon?: number; + snap?: number; +} + +export class BooleanShape extends THREE.Mesh { + private readonly kernelBoolean = new OGBoolean(); + + constructor( + left: THREE.Mesh, + right: THREE.Mesh, + operation: BooleanOperation, + constraints?: BooleanConstraints, + material?: THREE.Material + ) { + const geometry = BooleanShape.computeGeometry(left, right, operation, constraints); + super( + geometry, + material ?? + new THREE.MeshStandardMaterial({ + color: 0x3b82f6, + transparent: true, + opacity: 0.7, + }) + ); + } + + run( + left: THREE.Mesh, + right: THREE.Mesh, + operation: BooleanOperation, + constraints?: BooleanConstraints + ) { + this.geometry.dispose(); + this.geometry = BooleanShape.computeGeometry(left, right, operation, constraints, this.kernelBoolean); + this.geometry.computeVertexNormals(); + } + + static computeGeometry( + left: THREE.Mesh, + right: THREE.Mesh, + operation: BooleanOperation, + constraints?: BooleanConstraints, + kernelBoolean = new OGBoolean() + ) { + const leftBuffer = extractWorldSpaceTriangleBuffer(left); + const rightBuffer = extractWorldSpaceTriangleBuffer(right); + + const result = kernelBoolean.compute( + JSON.stringify(leftBuffer), + JSON.stringify(rightBuffer), + operation, + constraints ? JSON.stringify(constraints) : undefined + ); + + const positions = JSON.parse(result) as number[]; + const geometry = new THREE.BufferGeometry(); + geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3)); + geometry.computeVertexNormals(); + return geometry; + } +} + +function extractWorldSpaceTriangleBuffer(mesh: THREE.Mesh): number[] { + const geometry = mesh.geometry; + if (!(geometry instanceof THREE.BufferGeometry)) { + throw new Error("Boolean operations require THREE.BufferGeometry meshes."); + } + + const position = geometry.getAttribute("position"); + if (!position) { + throw new Error("Boolean operations require a position attribute."); + } + + mesh.updateWorldMatrix(true, false); + const world = mesh.matrixWorld; + + const source = geometry.toNonIndexed(); + const sourcePosition = source.getAttribute("position"); + const out: number[] = []; + const v = new THREE.Vector3(); + + for (let i = 0; i < sourcePosition.count; i++) { + v.fromBufferAttribute(sourcePosition, i).applyMatrix4(world); + out.push(v.x, v.y, v.z); + } + + source.dispose(); + return out; +} diff --git a/main/opengeometry-three/src/operations/index.ts b/main/opengeometry-three/src/operations/index.ts new file mode 100644 index 0000000..fc03593 --- /dev/null +++ b/main/opengeometry-three/src/operations/index.ts @@ -0,0 +1 @@ +export * from "./boolean"; diff --git a/main/opengeometry/src/lib.rs b/main/opengeometry/src/lib.rs index d33ebb4..e08d2cf 100644 --- a/main/opengeometry/src/lib.rs +++ b/main/opengeometry/src/lib.rs @@ -4,6 +4,7 @@ pub mod geometry { } pub mod operations { + pub mod boolean; pub mod extrude; pub mod offset; pub mod sweep; diff --git a/main/opengeometry/src/operations/boolean.rs b/main/opengeometry/src/operations/boolean.rs new file mode 100644 index 0000000..ceb4b2b --- /dev/null +++ b/main/opengeometry/src/operations/boolean.rs @@ -0,0 +1,555 @@ +use serde::{Deserialize, Serialize}; +use wasm_bindgen::prelude::*; + +#[derive(Debug, Clone, Copy, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum BooleanOperation { + Union, + Intersection, + Difference, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct BooleanConstraints { + #[serde(default = "default_epsilon")] + pub epsilon: f64, + #[serde(default = "default_snap")] + pub snap: f64, +} + +fn default_epsilon() -> f64 { + 1e-6 +} + +fn default_snap() -> f64 { + 1e-6 +} + +impl Default for BooleanConstraints { + fn default() -> Self { + Self { + epsilon: default_epsilon(), + snap: default_snap(), + } + } +} + +#[wasm_bindgen] +pub struct OGBoolean; + +#[wasm_bindgen] +impl OGBoolean { + #[wasm_bindgen(constructor)] + pub fn new() -> Self { + Self + } + + #[wasm_bindgen] + pub fn compute( + &self, + mesh_a_serialized: String, + mesh_b_serialized: String, + operation: String, + constraints_serialized: Option, + ) -> Result { + let vertices_a: Vec = serde_json::from_str(&mesh_a_serialized) + .map_err(|err| JsValue::from_str(&err.to_string()))?; + let vertices_b: Vec = serde_json::from_str(&mesh_b_serialized) + .map_err(|err| JsValue::from_str(&err.to_string()))?; + + let constraints = constraints_serialized + .as_deref() + .map(serde_json::from_str) + .transpose() + .map_err(|err| JsValue::from_str(&err.to_string()))? + .unwrap_or_default(); + + let op: BooleanOperation = + serde_json::from_str(&format!("\"{}\"", operation.to_lowercase())).map_err(|_| { + JsValue::from_str("operation must be union, intersection, or difference") + })?; + + let polygons_a = triangles_to_polygons(&vertices_a, &constraints)?; + let polygons_b = triangles_to_polygons(&vertices_b, &constraints)?; + + let result = match op { + BooleanOperation::Union => csg_union(polygons_a, polygons_b, constraints.epsilon), + BooleanOperation::Intersection => { + csg_intersection(polygons_a, polygons_b, constraints.epsilon) + } + BooleanOperation::Difference => { + csg_subtract(polygons_a, polygons_b, constraints.epsilon) + } + }; + + let flattened = polygons_to_triangle_buffer(&result); + serde_json::to_string(&flattened).map_err(|err| JsValue::from_str(&err.to_string())) + } +} + +#[derive(Debug, Clone, Copy)] +struct Vec3 { + x: f64, + y: f64, + z: f64, +} + +impl Vec3 { + fn new(x: f64, y: f64, z: f64) -> Self { + Self { x, y, z } + } + + fn plus(self, rhs: Self) -> Self { + Self::new(self.x + rhs.x, self.y + rhs.y, self.z + rhs.z) + } + + fn minus(self, rhs: Self) -> Self { + Self::new(self.x - rhs.x, self.y - rhs.y, self.z - rhs.z) + } + + fn times(self, t: f64) -> Self { + Self::new(self.x * t, self.y * t, self.z * t) + } + + fn dot(self, rhs: Self) -> f64 { + self.x * rhs.x + self.y * rhs.y + self.z * rhs.z + } + + fn cross(self, rhs: Self) -> Self { + Self::new( + self.y * rhs.z - self.z * rhs.y, + self.z * rhs.x - self.x * rhs.z, + self.x * rhs.y - self.y * rhs.x, + ) + } + + fn length(self) -> f64 { + self.dot(self).sqrt() + } + + fn normalize(self) -> Self { + let len = self.length(); + if len == 0.0 { + self + } else { + self.times(1.0 / len) + } + } +} + +#[derive(Debug, Clone)] +struct Vertex { + pos: Vec3, +} + +impl Vertex { + fn interpolate(&self, other: &Vertex, t: f64) -> Vertex { + Vertex { + pos: self.pos.plus(other.pos.minus(self.pos).times(t)), + } + } + + fn flip(&mut self) {} +} + +#[derive(Debug, Clone)] +struct Plane { + normal: Vec3, + w: f64, + epsilon: f64, +} + +impl Plane { + fn from_points(a: Vec3, b: Vec3, c: Vec3, epsilon: f64) -> Self { + let normal = b.minus(a).cross(c.minus(a)).normalize(); + Self { + normal, + w: normal.dot(a), + epsilon, + } + } + + fn flip(&mut self) { + self.normal = self.normal.times(-1.0); + self.w = -self.w; + } + + fn split_polygon( + &self, + polygon: &Polygon, + coplanar_front: &mut Vec, + coplanar_back: &mut Vec, + front: &mut Vec, + back: &mut Vec, + ) { + const COPLANAR: i32 = 0; + const FRONT: i32 = 1; + const BACK: i32 = 2; + const SPANNING: i32 = 3; + + let mut polygon_type = 0; + let mut types = Vec::with_capacity(polygon.vertices.len()); + for vertex in &polygon.vertices { + let t = self.normal.dot(vertex.pos) - self.w; + let vertex_type = if t < -self.epsilon { + BACK + } else if t > self.epsilon { + FRONT + } else { + COPLANAR + }; + polygon_type |= vertex_type; + types.push(vertex_type); + } + + match polygon_type { + COPLANAR => { + if self.normal.dot(polygon.plane.normal) > 0.0 { + coplanar_front.push(polygon.clone()); + } else { + coplanar_back.push(polygon.clone()); + } + } + FRONT => front.push(polygon.clone()), + BACK => back.push(polygon.clone()), + SPANNING => { + let mut f: Vec = Vec::new(); + let mut b: Vec = Vec::new(); + for i in 0..polygon.vertices.len() { + let j = (i + 1) % polygon.vertices.len(); + let ti = types[i]; + let tj = types[j]; + let vi = &polygon.vertices[i]; + let vj = &polygon.vertices[j]; + + if ti != BACK { + f.push(vi.clone()); + } + if ti != FRONT { + b.push(vi.clone()); + } + if (ti | tj) == SPANNING { + let t = (self.w - self.normal.dot(vi.pos)) + / self.normal.dot(vj.pos.minus(vi.pos)); + let v = vi.interpolate(vj, t); + f.push(v.clone()); + b.push(v); + } + } + + if f.len() >= 3 { + front.push(Polygon::new(f, self.epsilon)); + } + if b.len() >= 3 { + back.push(Polygon::new(b, self.epsilon)); + } + } + _ => unreachable!(), + } + } +} + +#[derive(Debug, Clone)] +struct Polygon { + vertices: Vec, + plane: Plane, +} + +impl Polygon { + fn new(vertices: Vec, epsilon: f64) -> Self { + let plane = Plane::from_points(vertices[0].pos, vertices[1].pos, vertices[2].pos, epsilon); + Self { vertices, plane } + } + + fn flip(&mut self) { + self.vertices.reverse(); + for v in &mut self.vertices { + v.flip(); + } + self.plane.flip(); + } +} + +#[derive(Debug, Clone)] +struct Node { + plane: Option, + front: Option>, + back: Option>, + polygons: Vec, +} + +impl Node { + fn new(polygons: Vec) -> Self { + let mut node = Self { + plane: None, + front: None, + back: None, + polygons: Vec::new(), + }; + node.build(polygons); + node + } + + fn all_polygons(&self) -> Vec { + let mut polygons = self.polygons.clone(); + if let Some(front) = &self.front { + polygons.extend(front.all_polygons()); + } + if let Some(back) = &self.back { + polygons.extend(back.all_polygons()); + } + polygons + } + + fn invert(&mut self) { + for polygon in &mut self.polygons { + polygon.flip(); + } + if let Some(plane) = &mut self.plane { + plane.flip(); + } + if let Some(front) = &mut self.front { + front.invert(); + } + if let Some(back) = &mut self.back { + back.invert(); + } + std::mem::swap(&mut self.front, &mut self.back); + } + + fn clip_polygons(&self, polygons: Vec) -> Vec { + let Some(plane) = &self.plane else { + return polygons; + }; + + let mut front = Vec::new(); + let mut back = Vec::new(); + let mut coplanar_front = Vec::new(); + let mut coplanar_back = Vec::new(); + for polygon in polygons { + plane.split_polygon( + &polygon, + &mut coplanar_front, + &mut coplanar_back, + &mut front, + &mut back, + ); + } + front.extend(coplanar_front); + back.extend(coplanar_back); + + if let Some(node) = &self.front { + front = node.clip_polygons(front); + } + if let Some(node) = &self.back { + back = node.clip_polygons(back); + } else { + back.clear(); + } + + front.extend(back); + front + } + + fn clip_to(&mut self, bsp: &Node) { + self.polygons = bsp.clip_polygons(self.polygons.clone()); + if let Some(front) = &mut self.front { + front.clip_to(bsp); + } + if let Some(back) = &mut self.back { + back.clip_to(bsp); + } + } + + fn build(&mut self, polygons: Vec) { + if polygons.is_empty() { + return; + } + + if self.plane.is_none() { + self.plane = Some(polygons[0].plane.clone()); + } + + let mut front = Vec::new(); + let mut back = Vec::new(); + let mut coplanar_front = Vec::new(); + let mut coplanar_back = Vec::new(); + + if let Some(plane) = &self.plane { + for polygon in polygons { + plane.split_polygon( + &polygon, + &mut coplanar_front, + &mut coplanar_back, + &mut front, + &mut back, + ); + } + } + + self.polygons.extend(coplanar_front); + self.polygons.extend(coplanar_back); + + if !front.is_empty() { + if self.front.is_none() { + self.front = Some(Box::new(Node::new(Vec::new()))); + } + if let Some(node) = &mut self.front { + node.build(front); + } + } + if !back.is_empty() { + if self.back.is_none() { + self.back = Some(Box::new(Node::new(Vec::new()))); + } + if let Some(node) = &mut self.back { + node.build(back); + } + } + } +} + +fn csg_union(a: Vec, b: Vec, epsilon: f64) -> Vec { + let mut a_node = Node::new(a); + let mut b_node = Node::new(b); + + a_node.clip_to(&b_node); + b_node.clip_to(&a_node); + b_node.invert(); + b_node.clip_to(&a_node); + b_node.invert(); + + a_node.build(b_node.all_polygons()); + let mut result = a_node.all_polygons(); + weld_vertices(&mut result, epsilon); + result +} + +fn csg_subtract(a: Vec, b: Vec, epsilon: f64) -> Vec { + let mut a_node = Node::new(a); + let mut b_node = Node::new(b); + + a_node.invert(); + a_node.clip_to(&b_node); + b_node.clip_to(&a_node); + b_node.invert(); + b_node.clip_to(&a_node); + b_node.invert(); + a_node.build(b_node.all_polygons()); + a_node.invert(); + + let mut result = a_node.all_polygons(); + weld_vertices(&mut result, epsilon); + result +} + +fn csg_intersection(a: Vec, b: Vec, epsilon: f64) -> Vec { + let mut a_node = Node::new(a); + let mut b_node = Node::new(b); + + a_node.invert(); + b_node.clip_to(&a_node); + b_node.invert(); + a_node.clip_to(&b_node); + b_node.clip_to(&a_node); + a_node.build(b_node.all_polygons()); + a_node.invert(); + + let mut result = a_node.all_polygons(); + weld_vertices(&mut result, epsilon); + result +} + +fn triangles_to_polygons( + vertices: &[f64], + constraints: &BooleanConstraints, +) -> Result, JsValue> { + if vertices.len() % 9 != 0 { + return Err(JsValue::from_str( + "triangle buffer must be flat xyz triples whose length is divisible by 9", + )); + } + + let polygons = vertices + .chunks_exact(9) + .map(|chunk| { + let points = [ + snap_vec3(Vec3::new(chunk[0], chunk[1], chunk[2]), constraints.snap), + snap_vec3(Vec3::new(chunk[3], chunk[4], chunk[5]), constraints.snap), + snap_vec3(Vec3::new(chunk[6], chunk[7], chunk[8]), constraints.snap), + ]; + Polygon::new( + points.into_iter().map(|pos| Vertex { pos }).collect(), + constraints.epsilon, + ) + }) + .collect(); + + Ok(polygons) +} + +fn snap_vec3(v: Vec3, snap: f64) -> Vec3 { + if snap <= 0.0 { + return v; + } + + Vec3::new( + (v.x / snap).round() * snap, + (v.y / snap).round() * snap, + (v.z / snap).round() * snap, + ) +} + +fn weld_vertices(polygons: &mut [Polygon], epsilon: f64) { + if epsilon <= 0.0 { + return; + } + + for polygon in polygons { + for vertex in &mut polygon.vertices { + vertex.pos = snap_vec3(vertex.pos, epsilon); + } + } +} + +fn polygons_to_triangle_buffer(polygons: &[Polygon]) -> Vec { + let mut out = Vec::new(); + for polygon in polygons { + if polygon.vertices.len() < 3 { + continue; + } + + let base = polygon.vertices[0].pos; + for i in 1..(polygon.vertices.len() - 1) { + let b = polygon.vertices[i].pos; + let c = polygon.vertices[i + 1].pos; + out.extend_from_slice(&[base.x, base.y, base.z, b.x, b.y, b.z, c.x, c.y, c.z]); + } + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn union_of_overlapping_cubes_returns_triangles() { + let cube_a = vec![ + -1.0, -1.0, -1.0, 1.0, -1.0, -1.0, 1.0, 1.0, -1.0, -1.0, -1.0, -1.0, 1.0, 1.0, -1.0, + -1.0, 1.0, -1.0, + ]; + let cube_b = vec![ + 0.0, -1.0, -1.0, 2.0, -1.0, -1.0, 2.0, 1.0, -1.0, 0.0, -1.0, -1.0, 2.0, 1.0, -1.0, 0.0, + 1.0, -1.0, + ]; + + let constraints = BooleanConstraints::default(); + let a = triangles_to_polygons(&cube_a, &constraints).unwrap(); + let b = triangles_to_polygons(&cube_b, &constraints).unwrap(); + + let triangles = polygons_to_triangle_buffer(&csg_union(a, b, constraints.epsilon)); + assert!(!triangles.is_empty()); + assert_eq!(triangles.len() % 9, 0); + } +} From ffca3a331d78a0d5d86035b2177f2e1475aa168f Mon Sep 17 00:00:00 2001 From: blackboots <47943405+aka-blackboots@users.noreply.github.com> Date: Wed, 4 Mar 2026 10:48:45 +0100 Subject: [PATCH 2/4] Add boolean outlines and enum-driven example controls --- ...03-04-boolean-operations-implementation.md | 70 +++++--- .../src/pages/operations-boolean.ts | 159 ++++++++++++++---- .../examples-vite/src/shared/runtime.ts | 30 +++- .../src/operations/boolean.ts | 85 +++++++++- main/opengeometry/src/operations/boolean.rs | 129 ++++++++++++-- 5 files changed, 385 insertions(+), 88 deletions(-) diff --git a/AI-DOCs/2026-03-04-boolean-operations-implementation.md b/AI-DOCs/2026-03-04-boolean-operations-implementation.md index 94f9a57..8e8fc55 100644 --- a/AI-DOCs/2026-03-04-boolean-operations-implementation.md +++ b/AI-DOCs/2026-03-04-boolean-operations-implementation.md @@ -2,61 +2,77 @@ ## What changed -- Added a new kernel operation module `operations::boolean` with a wasm-bindgen class `OGBoolean`. -- `OGBoolean::compute` accepts two triangle buffers (`[x,y,z,...]`), an operation (`union`, `intersection`, `difference`), and optional numeric constraints. -- Implemented a BSP/plane-splitting CSG pipeline (`Node`, `Plane`, `Polygon`) with tolerance-driven vertex snapping and post-op vertex welding. -- Exposed the new module from `main/opengeometry/src/lib.rs`. -- Added `@opengeometry/kernel-three` bindings: - - `BooleanShape` for running booleans on any `THREE.Mesh` with `BufferGeometry`. - - `BooleanConstraints` and `BooleanOperation` types. -- Added a new Vite example page (`examples-vite/operations/boolean.html`) and runtime page logic (`operations-boolean.ts`). -- Updated the examples index to advertise the new Boolean operation card. +- Added a stateful kernel boolean operation module `operations::boolean` with wasm-bindgen class `OGBoolean`. +- `OGBoolean::compute` now stores the resulting polygon set and returns triangulated mesh buffer output. +- Added a kernel outline export API: `OGBoolean::get_outline_geometry_serialized`. +- Outline generation is done in kernel code by traversing final CSG polygons and emitting deduplicated polygon-boundary edges. +- Added/updated `@opengeometry/kernel-three` bindings: + - `BooleanShape` now requests both mesh and outline buffers from kernel. + - Added boolean outline handling (`LineSegments`) with `outline` toggle behavior aligned with other wrapped shapes. + - Switched operation selection to symbolic enum-style constants (`BooleanOperation.Union`, `BooleanOperation.Intersection`, `BooleanOperation.Difference`) instead of numeric indices. +- Updated boolean example page: + - Added dropdown for operation selection. + - Added left/right shape dropdowns (Cuboid, Sphere, Cylinder, Wedge). + - Updated demo to run booleans across those shapes and display resulting outline. +- Extended example control runtime to support `select` controls in addition to number/boolean controls. ## Why it changed -The project needed a shape-agnostic boolean pipeline. Existing shape wrappers already produce triangulated meshes, so this implementation uses those triangulations as a shared interchange format and applies constructive-solid-geometry operations in the kernel, then returns a new triangle buffer for rendering. +Follow-up requirements requested parity with other shape wrappers: -## Paper alignment and robustness strategy +- boolean result must have outline support +- operation selection should be enum-based (not numeric) +- example must include additional operand shape types and a dropdown UX -The requested `RobustBoolean.pdf` was not available inside this execution environment, so direct line-by-line extraction from the paper was not possible during implementation. This change still applies common robust boolean principles typically emphasized in robust CSG literature: +## Robustness strategy + +The boolean implementation continues to use robust CSG controls: - Epsilon-based plane classification (`front`, `back`, `coplanar`, `spanning`) -- Grid snapping for deterministic splitting intersections -- Vertex welding after operation completion +- Grid snapping for deterministic split points +- Post-op welding via epsilon snapping -These controls are exposed as `constraints.epsilon` and `constraints.snap` so callers can tune behavior per model scale. +These are exposed via `constraints.epsilon` and `constraints.snap`. ## How to test locally -1. Kernel tests: +1. Kernel format + tests: ```bash +cargo fmt --manifest-path main/opengeometry/Cargo.toml cargo test --manifest-path main/opengeometry/Cargo.toml ``` -2. Build wasm package (requires `wasm-pack`): +2. TS lint check: + +```bash +npm run lint:check +``` + +3. Build wasm package (requires `wasm-pack`): ```bash npm run build-core ``` -3. Build Three adapter/examples: +4. Run examples app: ```bash -npm run build-three -npm --prefix main/opengeometry-three run build-example-three +npm --prefix main/opengeometry-three run dev-example-three ``` -4. Open `main/opengeometry-three/examples-vite/operations/boolean.html` through the Vite examples app. +Open: + +- `main/opengeometry-three/examples-vite/operations/boolean.html` ## Backward compatibility -- No existing public API was removed. -- Existing shapes/primitives continue unchanged. -- New API is additive (`OGBoolean`, `BooleanShape`). +- Existing shape and primitive wrappers are unchanged. +- Boolean API remains additive. +- `BooleanShape` API remains compatible while adding outline behavior. ## Known caveats and follow-ups -- Current boolean output quality depends on clean manifold triangulations. -- Numerical controls may need per-project presets depending on unit scale. -- A follow-up should validate against the intended RobustBoolean paper test corpus once the PDF is available in-repo. +- In this environment, `wasm-pack` is unavailable, so full wasm rebuild and example execution are limited. +- Existing repository lint errors outside boolean changes still cause `npm run lint:check` to fail. +- If very dense meshes are used, polygon edge outlines can be visually heavy; future work can add feature-edge filtering by angle threshold. diff --git a/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts b/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts index c081cd4..85eb44b 100644 --- a/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts +++ b/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts @@ -1,45 +1,96 @@ import * as THREE from "three"; import { Vector3 } from "../../../../opengeometry/pkg/opengeometry"; -import { BooleanShape, Cuboid, Sphere } from "@og-three"; +import { + BooleanOperation, + BooleanShape, + Cuboid, + Cylinder, + Sphere, + Wedge, +} from "@og-three"; import { bootstrapExample, mountControls, replaceSceneObject, } from "../shared/runtime"; -const operations = ["union", "intersection", "difference"] as const; +function buildOperand(kind: string, center: Vector3, color: number): THREE.Mesh { + switch (kind) { + case "sphere": { + const sphere = new Sphere({ + center, + radius: 0.9, + widthSegments: 30, + heightSegments: 20, + color, + }); + sphere.outline = true; + return sphere; + } + case "cylinder": { + const cylinder = new Cylinder({ + center, + radius: 0.7, + height: 1.9, + segments: 32, + angle: Math.PI * 2, + color, + }); + cylinder.outline = true; + return cylinder; + } + case "wedge": { + const wedge = new Wedge({ + center, + width: 1.6, + height: 1.8, + depth: 1.4, + color, + }); + wedge.outline = true; + return wedge; + } + default: { + const cuboid = new Cuboid({ + center, + width: 1.6, + height: 1.8, + depth: 1.5, + color, + }); + cuboid.outline = true; + return cuboid; + } + } +} void bootstrapExample({ title: "Boolean (Union / Intersection / Difference)", description: - "Robust BSP-style constructive solid geometry over any OpenGeometry triangulated shape.", + "Boolean operations over Cuboid, Sphere, Cylinder, and Wedge operands with kernel-generated outlines.", build: ({ scene }) => { let result: THREE.Mesh | null = null; - const update = (state: Record) => { - const left = new Cuboid({ - center: new Vector3(-0.4, 0.9, 0), - width: state.leftWidth as number, - height: 1.8, - depth: 1.5, - color: 0x10b981, - }); - left.outline = true; + const update = (state: Record) => { + const left = buildOperand( + String(state.leftShape), + new Vector3(-0.55, 0.9, 0), + 0x10b981 + ); + const right = buildOperand( + String(state.rightShape), + new Vector3(0.55, 0.9, 0), + 0xf97316 + ); - const right = new Sphere({ - center: new Vector3(0.5, 0.9, 0), - radius: state.rightRadius as number, - widthSegments: 30, - heightSegments: 20, - color: 0xf97316, - }); - right.outline = true; + const operation = (String(state.operation) as BooleanOperation) ?? + BooleanOperation.Union; - const operation = operations[Math.round(state.operation as number)] ?? "union"; const boolean = new BooleanShape(left, right, operation, { epsilon: state.epsilon as number, snap: state.snap as number, }); + boolean.outline = true; boolean.material = new THREE.MeshStandardMaterial({ color: 0x2563eb, @@ -58,21 +109,61 @@ void bootstrapExample({ mountControls( "Boolean Controls", [ - { type: "number", key: "operation", label: "Operation (0=Union,1=Intersect,2=Diff)", min: 0, max: 2, step: 1, value: 0 }, - { type: "number", key: "leftWidth", label: "Left Cuboid Width", min: 0.8, max: 2.2, step: 0.1, value: 1.4 }, - { type: "number", key: "rightRadius", label: "Right Sphere Radius", min: 0.5, max: 1.2, step: 0.05, value: 0.85 }, - { type: "number", key: "epsilon", label: "Plane Epsilon", min: 0.000001, max: 0.005, step: 0.000001, value: 0.00001 }, - { type: "number", key: "snap", label: "Snap Grid", min: 0.000001, max: 0.005, step: 0.000001, value: 0.00001 }, + { + type: "select", + key: "operation", + label: "Operation", + value: BooleanOperation.Union, + options: [ + { label: "Union", value: BooleanOperation.Union }, + { label: "Intersection", value: BooleanOperation.Intersection }, + { label: "Difference", value: BooleanOperation.Difference }, + ], + }, + { + type: "select", + key: "leftShape", + label: "Left Shape", + value: "cuboid", + options: [ + { label: "Cuboid", value: "cuboid" }, + { label: "Sphere", value: "sphere" }, + { label: "Cylinder", value: "cylinder" }, + { label: "Wedge", value: "wedge" }, + ], + }, + { + type: "select", + key: "rightShape", + label: "Right Shape", + value: "sphere", + options: [ + { label: "Cuboid", value: "cuboid" }, + { label: "Sphere", value: "sphere" }, + { label: "Cylinder", value: "cylinder" }, + { label: "Wedge", value: "wedge" }, + ], + }, + { + type: "number", + key: "epsilon", + label: "Plane Epsilon", + min: 0.000001, + max: 0.005, + step: 0.000001, + value: 0.00001, + }, + { + type: "number", + key: "snap", + label: "Snap Grid", + min: 0.000001, + max: 0.005, + step: 0.000001, + value: 0.00001, + }, ], update ); - - update({ - operation: 0, - leftWidth: 1.4, - rightRadius: 0.85, - epsilon: 0.00001, - snap: 0.00001, - }); }, }); diff --git a/main/opengeometry-three/examples-vite/src/shared/runtime.ts b/main/opengeometry-three/examples-vite/src/shared/runtime.ts index 480b8b2..2d82085 100644 --- a/main/opengeometry-three/examples-vite/src/shared/runtime.ts +++ b/main/opengeometry-three/examples-vite/src/shared/runtime.ts @@ -25,9 +25,16 @@ export type ExampleControlDefinition = key: string; label: string; value: boolean; + } + | { + type: "select"; + key: string; + label: string; + value: string; + options: Array<{ label: string; value: string }>; }; -export type ExampleControlState = Record; +export type ExampleControlState = Record; interface BootstrapConfig { title: string; @@ -242,7 +249,7 @@ export function mountControls( inputs.appendChild(rangeInput); inputs.appendChild(numberInput); row.appendChild(inputs); - } else { + } else if (definition.type === "boolean") { const boolWrap = document.createElement("div"); boolWrap.className = "og-control-bool"; @@ -267,6 +274,25 @@ export function mountControls( boolWrap.appendChild(boolLabel); row.appendChild(header); row.appendChild(boolWrap); + } else { + row.appendChild(header); + const select = document.createElement("select"); + select.className = "og-control-select"; + + for (const option of definition.options) { + const optionElement = document.createElement("option"); + optionElement.value = option.value; + optionElement.textContent = option.label; + optionElement.selected = option.value === definition.value; + select.appendChild(optionElement); + } + + select.addEventListener("change", () => { + state[definition.key] = select.value; + emitChange(); + }); + + row.appendChild(select); } panel.appendChild(row); diff --git a/main/opengeometry-three/src/operations/boolean.ts b/main/opengeometry-three/src/operations/boolean.ts index 910093c..0435dd1 100644 --- a/main/opengeometry-three/src/operations/boolean.ts +++ b/main/opengeometry-three/src/operations/boolean.ts @@ -1,7 +1,14 @@ import { OGBoolean } from "../../../opengeometry/pkg/opengeometry"; import * as THREE from "three"; -export type BooleanOperation = "union" | "intersection" | "difference"; +export const BooleanOperation = { + Union: "union", + Intersection: "intersection", + Difference: "difference", +} as const; + +export type BooleanOperationValue = + (typeof BooleanOperation)[keyof typeof BooleanOperation]; export interface BooleanConstraints { epsilon?: number; @@ -10,15 +17,22 @@ export interface BooleanConstraints { export class BooleanShape extends THREE.Mesh { private readonly kernelBoolean = new OGBoolean(); + #outlineMesh: THREE.LineSegments | null = null; constructor( left: THREE.Mesh, right: THREE.Mesh, - operation: BooleanOperation, + operation: BooleanOperationValue, constraints?: BooleanConstraints, material?: THREE.Material ) { - const geometry = BooleanShape.computeGeometry(left, right, operation, constraints); + const { geometry, outline } = BooleanShape.computeGeometry( + left, + right, + operation, + constraints + ); + super( geometry, material ?? @@ -28,23 +42,71 @@ export class BooleanShape extends THREE.Mesh { opacity: 0.7, }) ); + + this.applyOutline(outline); } run( left: THREE.Mesh, right: THREE.Mesh, - operation: BooleanOperation, + operation: BooleanOperationValue, constraints?: BooleanConstraints ) { this.geometry.dispose(); - this.geometry = BooleanShape.computeGeometry(left, right, operation, constraints, this.kernelBoolean); + const { geometry, outline } = BooleanShape.computeGeometry( + left, + right, + operation, + constraints, + this.kernelBoolean + ); + this.geometry = geometry; this.geometry.computeVertexNormals(); + this.applyOutline(outline); + } + + set outline(enable: boolean) { + if (!enable) { + if (this.#outlineMesh) { + this.remove(this.#outlineMesh); + this.#outlineMesh.geometry.dispose(); + (this.#outlineMesh.material as THREE.Material).dispose(); + this.#outlineMesh = null; + } + return; + } + + if (this.#outlineMesh) { + this.add(this.#outlineMesh); + } + } + + private applyOutline(outlinePositions: number[]) { + if (this.#outlineMesh) { + this.remove(this.#outlineMesh); + this.#outlineMesh.geometry.dispose(); + (this.#outlineMesh.material as THREE.Material).dispose(); + this.#outlineMesh = null; + } + + if (outlinePositions.length === 0) { + return; + } + + const outlineGeometry = new THREE.BufferGeometry(); + outlineGeometry.setAttribute( + "position", + new THREE.Float32BufferAttribute(outlinePositions, 3) + ); + const outlineMaterial = new THREE.LineBasicMaterial({ color: 0x111827 }); + this.#outlineMesh = new THREE.LineSegments(outlineGeometry, outlineMaterial); + this.add(this.#outlineMesh); } static computeGeometry( left: THREE.Mesh, right: THREE.Mesh, - operation: BooleanOperation, + operation: BooleanOperationValue, constraints?: BooleanConstraints, kernelBoolean = new OGBoolean() ) { @@ -58,11 +120,18 @@ export class BooleanShape extends THREE.Mesh { constraints ? JSON.stringify(constraints) : undefined ); + const outlineResult = kernelBoolean.get_outline_geometry_serialized(); + const positions = JSON.parse(result) as number[]; + const outline = JSON.parse(outlineResult) as number[]; const geometry = new THREE.BufferGeometry(); - geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3)); + geometry.setAttribute( + "position", + new THREE.Float32BufferAttribute(positions, 3) + ); geometry.computeVertexNormals(); - return geometry; + + return { geometry, outline }; } } diff --git a/main/opengeometry/src/operations/boolean.rs b/main/opengeometry/src/operations/boolean.rs index ceb4b2b..5733153 100644 --- a/main/opengeometry/src/operations/boolean.rs +++ b/main/opengeometry/src/operations/boolean.rs @@ -1,4 +1,5 @@ use serde::{Deserialize, Serialize}; +use std::collections::HashSet; use wasm_bindgen::prelude::*; #[derive(Debug, Clone, Copy, Serialize, Deserialize)] @@ -35,18 +36,22 @@ impl Default for BooleanConstraints { } #[wasm_bindgen] -pub struct OGBoolean; +pub struct OGBoolean { + last_result: Vec, +} #[wasm_bindgen] impl OGBoolean { #[wasm_bindgen(constructor)] pub fn new() -> Self { - Self + Self { + last_result: Vec::new(), + } } #[wasm_bindgen] pub fn compute( - &self, + &mut self, mesh_a_serialized: String, mesh_b_serialized: String, operation: String, @@ -72,7 +77,7 @@ impl OGBoolean { let polygons_a = triangles_to_polygons(&vertices_a, &constraints)?; let polygons_b = triangles_to_polygons(&vertices_b, &constraints)?; - let result = match op { + let mut result = match op { BooleanOperation::Union => csg_union(polygons_a, polygons_b, constraints.epsilon), BooleanOperation::Intersection => { csg_intersection(polygons_a, polygons_b, constraints.epsilon) @@ -82,9 +87,18 @@ impl OGBoolean { } }; - let flattened = polygons_to_triangle_buffer(&result); + weld_vertices(&mut result, constraints.epsilon); + self.last_result = result; + + let flattened = polygons_to_triangle_buffer(&self.last_result); serde_json::to_string(&flattened).map_err(|err| JsValue::from_str(&err.to_string())) } + + #[wasm_bindgen] + pub fn get_outline_geometry_serialized(&self) -> Result { + let outline = polygons_to_outline_buffer(&self.last_result); + serde_json::to_string(&outline).map_err(|err| JsValue::from_str(&err.to_string())) + } } #[derive(Debug, Clone, Copy)] @@ -326,6 +340,7 @@ impl Node { let mut back = Vec::new(); let mut coplanar_front = Vec::new(); let mut coplanar_back = Vec::new(); + for polygon in polygons { plane.split_polygon( &polygon, @@ -335,6 +350,7 @@ impl Node { &mut back, ); } + front.extend(coplanar_front); back.extend(coplanar_back); @@ -398,6 +414,7 @@ impl Node { node.build(front); } } + if !back.is_empty() { if self.back.is_none() { self.back = Some(Box::new(Node::new(Vec::new()))); @@ -409,7 +426,7 @@ impl Node { } } -fn csg_union(a: Vec, b: Vec, epsilon: f64) -> Vec { +fn csg_union(a: Vec, b: Vec, _epsilon: f64) -> Vec { let mut a_node = Node::new(a); let mut b_node = Node::new(b); @@ -420,12 +437,10 @@ fn csg_union(a: Vec, b: Vec, epsilon: f64) -> Vec { b_node.invert(); a_node.build(b_node.all_polygons()); - let mut result = a_node.all_polygons(); - weld_vertices(&mut result, epsilon); - result + a_node.all_polygons() } -fn csg_subtract(a: Vec, b: Vec, epsilon: f64) -> Vec { +fn csg_subtract(a: Vec, b: Vec, _epsilon: f64) -> Vec { let mut a_node = Node::new(a); let mut b_node = Node::new(b); @@ -438,12 +453,10 @@ fn csg_subtract(a: Vec, b: Vec, epsilon: f64) -> Vec a_node.build(b_node.all_polygons()); a_node.invert(); - let mut result = a_node.all_polygons(); - weld_vertices(&mut result, epsilon); - result + a_node.all_polygons() } -fn csg_intersection(a: Vec, b: Vec, epsilon: f64) -> Vec { +fn csg_intersection(a: Vec, b: Vec, _epsilon: f64) -> Vec { let mut a_node = Node::new(a); let mut b_node = Node::new(b); @@ -455,9 +468,7 @@ fn csg_intersection(a: Vec, b: Vec, epsilon: f64) -> Vec Vec { out.extend_from_slice(&[base.x, base.y, base.z, b.x, b.y, b.z, c.x, c.y, c.z]); } } + out } +fn polygons_to_outline_buffer(polygons: &[Polygon]) -> Vec { + let mut out = Vec::new(); + let mut seen = HashSet::new(); + + for polygon in polygons { + if polygon.vertices.len() < 2 { + continue; + } + + for i in 0..polygon.vertices.len() { + let start = polygon.vertices[i].pos; + let end = polygon.vertices[(i + 1) % polygon.vertices.len()].pos; + let key = EdgeKey::from_points(start, end); + if seen.insert(key) { + out.extend_from_slice(&[start.x, start.y, start.z, end.x, end.y, end.z]); + } + } + } + + out +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +struct EdgeKey { + a: QuantizedPoint, + b: QuantizedPoint, +} + +impl EdgeKey { + fn from_points(a: Vec3, b: Vec3) -> Self { + let qa = QuantizedPoint::from_vec3(a); + let qb = QuantizedPoint::from_vec3(b); + + if qa <= qb { + Self { a: qa, b: qb } + } else { + Self { a: qb, b: qa } + } + } +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] +struct QuantizedPoint { + x: i64, + y: i64, + z: i64, +} + +impl QuantizedPoint { + fn from_vec3(v: Vec3) -> Self { + const SCALE: f64 = 1_000_000.0; + Self { + x: (v.x * SCALE).round() as i64, + y: (v.y * SCALE).round() as i64, + z: (v.z * SCALE).round() as i64, + } + } +} + #[cfg(test)] mod tests { use super::*; @@ -552,4 +623,28 @@ mod tests { assert!(!triangles.is_empty()); assert_eq!(triangles.len() % 9, 0); } + + #[test] + fn outline_is_generated_for_polygon_result() { + let polygon = Polygon::new( + vec![ + Vertex { + pos: Vec3::new(0.0, 0.0, 0.0), + }, + Vertex { + pos: Vec3::new(1.0, 0.0, 0.0), + }, + Vertex { + pos: Vec3::new(1.0, 0.0, 1.0), + }, + Vertex { + pos: Vec3::new(0.0, 0.0, 1.0), + }, + ], + 1e-6, + ); + + let outline = polygons_to_outline_buffer(&[polygon]); + assert_eq!(outline.len(), 24); + } } From f38445134f3a00ebf3e81bfb06f139d317095817 Mon Sep 17 00:00:00 2001 From: blackboots <47943405+aka-blackboots@users.noreply.github.com> Date: Wed, 4 Mar 2026 11:08:23 +0100 Subject: [PATCH 3/4] Refine boolean outlines to brep-like edges and stabilize controls --- ...03-04-boolean-operations-implementation.md | 69 +++++++------- .../src/pages/operations-boolean.ts | 12 ++- .../src/operations/boolean.ts | 20 ++++- main/opengeometry/src/operations/boolean.rs | 90 +++++++++++++++++-- 4 files changed, 145 insertions(+), 46 deletions(-) diff --git a/AI-DOCs/2026-03-04-boolean-operations-implementation.md b/AI-DOCs/2026-03-04-boolean-operations-implementation.md index 8e8fc55..0beeba8 100644 --- a/AI-DOCs/2026-03-04-boolean-operations-implementation.md +++ b/AI-DOCs/2026-03-04-boolean-operations-implementation.md @@ -2,77 +2,80 @@ ## What changed -- Added a stateful kernel boolean operation module `operations::boolean` with wasm-bindgen class `OGBoolean`. -- `OGBoolean::compute` now stores the resulting polygon set and returns triangulated mesh buffer output. -- Added a kernel outline export API: `OGBoolean::get_outline_geometry_serialized`. -- Outline generation is done in kernel code by traversing final CSG polygons and emitting deduplicated polygon-boundary edges. -- Added/updated `@opengeometry/kernel-three` bindings: - - `BooleanShape` now requests both mesh and outline buffers from kernel. - - Added boolean outline handling (`LineSegments`) with `outline` toggle behavior aligned with other wrapped shapes. - - Switched operation selection to symbolic enum-style constants (`BooleanOperation.Union`, `BooleanOperation.Intersection`, `BooleanOperation.Difference`) instead of numeric indices. -- Updated boolean example page: - - Added dropdown for operation selection. - - Added left/right shape dropdowns (Cuboid, Sphere, Cylinder, Wedge). - - Updated demo to run booleans across those shapes and display resulting outline. -- Extended example control runtime to support `select` controls in addition to number/boolean controls. +- Updated the kernel boolean module to support **BRep-like outlines** for boolean outputs rather than raw triangulation edges. +- `OGBoolean` remains stateful (`last_result`) and now computes outlines by edge-adjacency analysis: + - build undirected edge buckets from result polygons + - suppress edges shared by coplanar faces (triangle-split seams) + - keep boundary edges and sharp-feature edges +- `OGBoolean::get_outline_geometry_serialized` now returns this BRep-like feature outline buffer. +- Added kernel test `coplanar_shared_triangle_edge_is_removed_from_outline` to verify internal triangulation diagonals are not emitted. +- Updated Three.js boolean binding API: + - Introduced `BooleanOperationKind` and `parseBooleanOperation` for deterministic operation selection. + - `BooleanShape` uses kernel outline output as before, but operation parsing now avoids ambiguous string casting in examples. +- Updated boolean example (`operations-boolean.ts`): + - added **Show Outline** toggle + - kept left/right shape selectors (Cuboid, Sphere, Cylinder, Wedge) + - operation dropdown now resolves via `parseBooleanOperation` for consistent behavior ## Why it changed -Follow-up requirements requested parity with other shape wrappers: +Follow-up requirements requested: -- boolean result must have outline support -- operation selection should be enum-based (not numeric) -- example must include additional operand shape types and a dropdown UX +1. BRep-like outlines instead of triangulated outlines +2. consistency in operation selection behavior +3. an explicit outline toggle in the example + +These are now addressed directly in kernel + wrapper + example layers. ## Robustness strategy -The boolean implementation continues to use robust CSG controls: +Boolean CSG core still uses robust controls: -- Epsilon-based plane classification (`front`, `back`, `coplanar`, `spanning`) -- Grid snapping for deterministic split points -- Post-op welding via epsilon snapping +- epsilon-based plane classification (`front`/`back`/`coplanar`/`spanning`) +- snap-grid normalization for deterministic splits +- post-op weld by epsilon snapping -These are exposed via `constraints.epsilon` and `constraints.snap`. +Outline extraction now adds topology-aware edge filtering to remove coplanar split seams. ## How to test locally -1. Kernel format + tests: +1. Kernel checks: ```bash cargo fmt --manifest-path main/opengeometry/Cargo.toml cargo test --manifest-path main/opengeometry/Cargo.toml ``` -2. TS lint check: +2. TS lint: ```bash npm run lint:check ``` -3. Build wasm package (requires `wasm-pack`): +3. Build wasm + three package: ```bash npm run build-core +npm run build-three ``` -4. Run examples app: +4. Example run: ```bash npm --prefix main/opengeometry-three run dev-example-three ``` -Open: +Then open: - `main/opengeometry-three/examples-vite/operations/boolean.html` ## Backward compatibility -- Existing shape and primitive wrappers are unchanged. -- Boolean API remains additive. -- `BooleanShape` API remains compatible while adding outline behavior. +- Existing non-boolean wrappers remain unchanged. +- Boolean API stays additive; operation constants are still `BooleanOperation.Union|Intersection|Difference`. +- New parser helper improves call-site safety without breaking existing valid operation strings. ## Known caveats and follow-ups -- In this environment, `wasm-pack` is unavailable, so full wasm rebuild and example execution are limited. -- Existing repository lint errors outside boolean changes still cause `npm run lint:check` to fail. -- If very dense meshes are used, polygon edge outlines can be visually heavy; future work can add feature-edge filtering by angle threshold. +- In this environment, wasm package artifacts (`main/opengeometry/pkg/opengeometry`) are unavailable, so full TS build/example rendering remains blocked. +- Existing repo-level lint errors outside this change still fail `npm run lint:check`. diff --git a/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts b/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts index 85eb44b..5f19897 100644 --- a/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts +++ b/main/opengeometry-three/examples-vite/src/pages/operations-boolean.ts @@ -5,6 +5,7 @@ import { BooleanShape, Cuboid, Cylinder, + parseBooleanOperation, Sphere, Wedge, } from "@og-three"; @@ -83,14 +84,13 @@ void bootstrapExample({ 0xf97316 ); - const operation = (String(state.operation) as BooleanOperation) ?? - BooleanOperation.Union; + const operation = parseBooleanOperation(String(state.operation)); const boolean = new BooleanShape(left, right, operation, { epsilon: state.epsilon as number, snap: state.snap as number, }); - boolean.outline = true; + boolean.outline = Boolean(state.showOutline); boolean.material = new THREE.MeshStandardMaterial({ color: 0x2563eb, @@ -144,6 +144,12 @@ void bootstrapExample({ { label: "Wedge", value: "wedge" }, ], }, + { + type: "boolean", + key: "showOutline", + label: "Show Outline", + value: true, + }, { type: "number", key: "epsilon", diff --git a/main/opengeometry-three/src/operations/boolean.ts b/main/opengeometry-three/src/operations/boolean.ts index 0435dd1..85f7d1b 100644 --- a/main/opengeometry-three/src/operations/boolean.ts +++ b/main/opengeometry-three/src/operations/boolean.ts @@ -7,9 +7,21 @@ export const BooleanOperation = { Difference: "difference", } as const; -export type BooleanOperationValue = +export type BooleanOperationKind = (typeof BooleanOperation)[keyof typeof BooleanOperation]; +export function parseBooleanOperation(value: string): BooleanOperationKind { + switch (value) { + case BooleanOperation.Intersection: + return BooleanOperation.Intersection; + case BooleanOperation.Difference: + return BooleanOperation.Difference; + case BooleanOperation.Union: + default: + return BooleanOperation.Union; + } +} + export interface BooleanConstraints { epsilon?: number; snap?: number; @@ -22,7 +34,7 @@ export class BooleanShape extends THREE.Mesh { constructor( left: THREE.Mesh, right: THREE.Mesh, - operation: BooleanOperationValue, + operation: BooleanOperationKind, constraints?: BooleanConstraints, material?: THREE.Material ) { @@ -49,7 +61,7 @@ export class BooleanShape extends THREE.Mesh { run( left: THREE.Mesh, right: THREE.Mesh, - operation: BooleanOperationValue, + operation: BooleanOperationKind, constraints?: BooleanConstraints ) { this.geometry.dispose(); @@ -106,7 +118,7 @@ export class BooleanShape extends THREE.Mesh { static computeGeometry( left: THREE.Mesh, right: THREE.Mesh, - operation: BooleanOperationValue, + operation: BooleanOperationKind, constraints?: BooleanConstraints, kernelBoolean = new OGBoolean() ) { diff --git a/main/opengeometry/src/operations/boolean.rs b/main/opengeometry/src/operations/boolean.rs index 5733153..b729458 100644 --- a/main/opengeometry/src/operations/boolean.rs +++ b/main/opengeometry/src/operations/boolean.rs @@ -1,5 +1,5 @@ use serde::{Deserialize, Serialize}; -use std::collections::HashSet; +use std::collections::HashMap; use wasm_bindgen::prelude::*; #[derive(Debug, Clone, Copy, Serialize, Deserialize)] @@ -542,8 +542,7 @@ fn polygons_to_triangle_buffer(polygons: &[Polygon]) -> Vec { } fn polygons_to_outline_buffer(polygons: &[Polygon]) -> Vec { - let mut out = Vec::new(); - let mut seen = HashSet::new(); + let mut edges: HashMap> = HashMap::new(); for polygon in polygons { if polygon.vertices.len() < 2 { @@ -554,15 +553,59 @@ fn polygons_to_outline_buffer(polygons: &[Polygon]) -> Vec { let start = polygon.vertices[i].pos; let end = polygon.vertices[(i + 1) % polygon.vertices.len()].pos; let key = EdgeKey::from_points(start, end); - if seen.insert(key) { - out.extend_from_slice(&[start.x, start.y, start.z, end.x, end.y, end.z]); - } + let entry = edges.entry(key).or_default(); + entry.push(EdgeSample { + start, + end, + normal: polygon.plane.normal, + }); + } + } + + let mut out = Vec::new(); + for samples in edges.values() { + if should_emit_edge(samples) { + let representative = samples[0]; + out.extend_from_slice(&[ + representative.start.x, + representative.start.y, + representative.start.z, + representative.end.x, + representative.end.y, + representative.end.z, + ]); } } out } +fn should_emit_edge(samples: &[EdgeSample]) -> bool { + if samples.len() <= 1 { + return true; + } + + const COPLANAR_NORMAL_DOT: f64 = 0.9999; + + for i in 0..samples.len() { + for j in (i + 1)..samples.len() { + let dot = samples[i].normal.dot(samples[j].normal).abs(); + if dot < COPLANAR_NORMAL_DOT { + return true; + } + } + } + + false +} + +#[derive(Debug, Clone, Copy)] +struct EdgeSample { + start: Vec3, + end: Vec3, + normal: Vec3, +} + #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] struct EdgeKey { a: QuantizedPoint, @@ -624,6 +667,41 @@ mod tests { assert_eq!(triangles.len() % 9, 0); } + #[test] + fn coplanar_shared_triangle_edge_is_removed_from_outline() { + let poly_a = Polygon::new( + vec![ + Vertex { + pos: Vec3::new(0.0, 0.0, 0.0), + }, + Vertex { + pos: Vec3::new(1.0, 0.0, 0.0), + }, + Vertex { + pos: Vec3::new(1.0, 0.0, 1.0), + }, + ], + 1e-6, + ); + let poly_b = Polygon::new( + vec![ + Vertex { + pos: Vec3::new(0.0, 0.0, 0.0), + }, + Vertex { + pos: Vec3::new(1.0, 0.0, 1.0), + }, + Vertex { + pos: Vec3::new(0.0, 0.0, 1.0), + }, + ], + 1e-6, + ); + + let outline = polygons_to_outline_buffer(&[poly_a, poly_b]); + // rectangle perimeter only: 4 line segments * 6 coordinates + assert_eq!(outline.len(), 24); + } #[test] fn outline_is_generated_for_polygon_result() { let polygon = Polygon::new( From 181545788fb8c78a0d6c025ba5f3a5e2c7c75c80 Mon Sep 17 00:00:00 2001 From: blackboots <47943405+aka-blackboots@users.noreply.github.com> Date: Wed, 4 Mar 2026 11:38:54 +0100 Subject: [PATCH 4/4] Clean boolean outlines by filtering smooth tessellation edges --- ...03-04-boolean-operations-implementation.md | 3 +- main/opengeometry/src/operations/boolean.rs | 41 +++++++++++-------- 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/AI-DOCs/2026-03-04-boolean-operations-implementation.md b/AI-DOCs/2026-03-04-boolean-operations-implementation.md index 0beeba8..cbac77a 100644 --- a/AI-DOCs/2026-03-04-boolean-operations-implementation.md +++ b/AI-DOCs/2026-03-04-boolean-operations-implementation.md @@ -6,6 +6,7 @@ - `OGBoolean` remains stateful (`last_result`) and now computes outlines by edge-adjacency analysis: - build undirected edge buckets from result polygons - suppress edges shared by coplanar faces (triangle-split seams) + - apply a feature-angle filter so smooth tessellation edges are hidden - keep boundary edges and sharp-feature edges - `OGBoolean::get_outline_geometry_serialized` now returns this BRep-like feature outline buffer. - Added kernel test `coplanar_shared_triangle_edge_is_removed_from_outline` to verify internal triangulation diagonals are not emitted. @@ -35,7 +36,7 @@ Boolean CSG core still uses robust controls: - snap-grid normalization for deterministic splits - post-op weld by epsilon snapping -Outline extraction now adds topology-aware edge filtering to remove coplanar split seams. +Outline extraction now adds topology-aware edge filtering to remove coplanar split seams and smooth-surface tessellation artifacts. ## How to test locally diff --git a/main/opengeometry/src/operations/boolean.rs b/main/opengeometry/src/operations/boolean.rs index b729458..926e16f 100644 --- a/main/opengeometry/src/operations/boolean.rs +++ b/main/opengeometry/src/operations/boolean.rs @@ -38,6 +38,7 @@ impl Default for BooleanConstraints { #[wasm_bindgen] pub struct OGBoolean { last_result: Vec, + last_constraints: BooleanConstraints, } #[wasm_bindgen] @@ -46,6 +47,7 @@ impl OGBoolean { pub fn new() -> Self { Self { last_result: Vec::new(), + last_constraints: BooleanConstraints::default(), } } @@ -88,6 +90,7 @@ impl OGBoolean { }; weld_vertices(&mut result, constraints.epsilon); + self.last_constraints = constraints; self.last_result = result; let flattened = polygons_to_triangle_buffer(&self.last_result); @@ -96,7 +99,7 @@ impl OGBoolean { #[wasm_bindgen] pub fn get_outline_geometry_serialized(&self) -> Result { - let outline = polygons_to_outline_buffer(&self.last_result); + let outline = polygons_to_outline_buffer(&self.last_result, &self.last_constraints); serde_json::to_string(&outline).map_err(|err| JsValue::from_str(&err.to_string())) } } @@ -541,7 +544,7 @@ fn polygons_to_triangle_buffer(polygons: &[Polygon]) -> Vec { out } -fn polygons_to_outline_buffer(polygons: &[Polygon]) -> Vec { +fn polygons_to_outline_buffer(polygons: &[Polygon], constraints: &BooleanConstraints) -> Vec { let mut edges: HashMap> = HashMap::new(); for polygon in polygons { @@ -552,7 +555,7 @@ fn polygons_to_outline_buffer(polygons: &[Polygon]) -> Vec { for i in 0..polygon.vertices.len() { let start = polygon.vertices[i].pos; let end = polygon.vertices[(i + 1) % polygon.vertices.len()].pos; - let key = EdgeKey::from_points(start, end); + let key = EdgeKey::from_points(start, end, constraints); let entry = edges.entry(key).or_default(); entry.push(EdgeSample { start, @@ -564,7 +567,7 @@ fn polygons_to_outline_buffer(polygons: &[Polygon]) -> Vec { let mut out = Vec::new(); for samples in edges.values() { - if should_emit_edge(samples) { + if should_emit_edge(samples, constraints) { let representative = samples[0]; out.extend_from_slice(&[ representative.start.x, @@ -580,22 +583,25 @@ fn polygons_to_outline_buffer(polygons: &[Polygon]) -> Vec { out } -fn should_emit_edge(samples: &[EdgeSample]) -> bool { +fn should_emit_edge(samples: &[EdgeSample], constraints: &BooleanConstraints) -> bool { if samples.len() <= 1 { return true; } - const COPLANAR_NORMAL_DOT: f64 = 0.9999; + let feature_angle_degrees = 28.0_f64; + let feature_dot = (feature_angle_degrees.to_radians()).cos(); for i in 0..samples.len() { for j in (i + 1)..samples.len() { let dot = samples[i].normal.dot(samples[j].normal).abs(); - if dot < COPLANAR_NORMAL_DOT { + if dot < feature_dot { return true; } } } + // If all normals are close, it is a smooth/coplanar tessellation edge and should be hidden. + let _ = constraints; false } @@ -613,9 +619,9 @@ struct EdgeKey { } impl EdgeKey { - fn from_points(a: Vec3, b: Vec3) -> Self { - let qa = QuantizedPoint::from_vec3(a); - let qb = QuantizedPoint::from_vec3(b); + fn from_points(a: Vec3, b: Vec3, constraints: &BooleanConstraints) -> Self { + let qa = QuantizedPoint::from_vec3(a, constraints); + let qb = QuantizedPoint::from_vec3(b, constraints); if qa <= qb { Self { a: qa, b: qb } @@ -633,12 +639,13 @@ struct QuantizedPoint { } impl QuantizedPoint { - fn from_vec3(v: Vec3) -> Self { - const SCALE: f64 = 1_000_000.0; + fn from_vec3(v: Vec3, constraints: &BooleanConstraints) -> Self { + let tol = constraints.snap.max(constraints.epsilon).max(1e-5); + let scale = 1.0 / tol; Self { - x: (v.x * SCALE).round() as i64, - y: (v.y * SCALE).round() as i64, - z: (v.z * SCALE).round() as i64, + x: (v.x * scale).round() as i64, + y: (v.y * scale).round() as i64, + z: (v.z * scale).round() as i64, } } } @@ -698,7 +705,7 @@ mod tests { 1e-6, ); - let outline = polygons_to_outline_buffer(&[poly_a, poly_b]); + let outline = polygons_to_outline_buffer(&[poly_a, poly_b], &BooleanConstraints::default()); // rectangle perimeter only: 4 line segments * 6 coordinates assert_eq!(outline.len(), 24); } @@ -722,7 +729,7 @@ mod tests { 1e-6, ); - let outline = polygons_to_outline_buffer(&[polygon]); + let outline = polygons_to_outline_buffer(&[polygon], &BooleanConstraints::default()); assert_eq!(outline.len(), 24); } }