Skip to content

Commit 5a34fd8

Browse files
stewartoallenstewartoallen
committed
update docs
1 parent 5881e94 commit 5a34fd8

1 file changed

Lines changed: 226 additions & 0 deletions

File tree

‎docs/void/plan-chamfer-offset-v2.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Void Chamfer V2 Plan (Geometric Offset, Not Boolean Cutters)
2+
3+
## Goal
4+
5+
Replace the current chamfer implementation based on cutter solids + boolean difference with a deterministic geometric chamfer pipeline that operates directly on mesh topology and face offsets.
6+
7+
## Why Change
8+
9+
1. Current path is boolean-driven (`solid/chamfer.js`) and depends on synthetic cutter prisms.
10+
2. Boolean chamfer is fragile near:
11+
- short edges
12+
- dense/curved topology
13+
- multi-edge corner interactions
14+
- near-coplanar/low-angle neighborhoods
15+
3. Provenance and boundary tracking are harder when chamfer is represented as a subtract operation, rather than explicit edge-face reconstruction.
16+
4. Debugging and deterministic replay are harder with cutter generation and manifold fallback behavior.
17+
18+
## Current-State Findings
19+
20+
1. Chamfer currently:
21+
- resolves selected edges
22+
- builds cutter meshes from adjacent triangle normals
23+
- performs boolean difference
24+
- writes resulting body as manifold output
25+
26+
2. Signals in current code indicate boolean-centric lifecycle:
27+
- `manifold_chamfer_passthrough`
28+
- `manifold_chamfer_ready`
29+
- cutter debug/failure logs
30+
31+
3. Edge references are already fairly good:
32+
- chamfer refs use canonical boundary/segment identities
33+
- this is strong input for a topology-based rebuild
34+
35+
## Target Architecture
36+
37+
Chamfer becomes a topology/geometry transform, not a subtractive solid operation.
38+
39+
1. Input:
40+
- selected sharp edges (from stable boundary segment refs)
41+
- chamfer distance (and later optional asymmetric distances)
42+
43+
2. Core operation:
44+
- for each selected edge, offset its two incident face planes by chamfer distance
45+
- intersect offset planes with local wedge to compute chamfer strip geometry
46+
- trim neighboring faces and insert chamfer face(s)
47+
48+
3. Corner resolution:
49+
- solve multi-edge vertex neighborhoods explicitly
50+
- produce watertight corner patches without global booleans
51+
52+
4. Output:
53+
- rebuilt manifold mesh + updated provenance/boundary mappings
54+
- explicit chamfer faces with stable IDs (not anonymous boolean remnants)
55+
56+
## Data Model / Provenance Updates
57+
58+
1. Extend chamfer result metadata:
59+
- `source_edge_segment_ids[]`
60+
- `generated_face_ids[]`
61+
- `status: geometric_chamfer_ready`
62+
63+
2. GeometryStore integration:
64+
- chamfer faces emit boundaries/segments directly
65+
- chamfer faces carry source edge lineage
66+
67+
3. Preserve compatibility:
68+
- existing docs still readable
69+
- optional fallback to legacy boolean chamfer behind feature flag
70+
71+
## Algorithm Plan
72+
73+
## Stage A: Topology Extraction
74+
75+
1. Build edge->incident-face adjacency from input mesh.
76+
2. Identify valid chamfer candidates:
77+
- manifold edges with exactly two incident faces
78+
- non-smooth crease threshold gating
79+
80+
3. Group selected edges into connected chamfer regions.
81+
82+
## Stage B: Per-Edge Offset Construction
83+
84+
1. For each selected edge:
85+
- compute incident face normals
86+
- construct two offset face planes
87+
- compute chamfer line as plane-plane intersection in local neighborhood
88+
89+
2. Create edge strip endpoints using neighboring trim constraints.
90+
91+
## Stage C: Face Trimming + Insertion
92+
93+
1. Trim original incident faces against chamfer boundary lines.
94+
2. Insert chamfer quad/tri strip faces.
95+
3. Maintain winding and local normal consistency.
96+
97+
## Stage D: Vertex Corner Solver
98+
99+
1. At each selected vertex:
100+
- collect incoming chamfer strips
101+
- solve intersection polygon in tangent frame
102+
- triangulate corner patch deterministically
103+
104+
2. Handle edge cases:
105+
- 2-edge corner
106+
- n-edge star corner
107+
- near-parallel incident faces
108+
109+
## Stage E: Rebuild + Mapping
110+
111+
1. Rebuild indexed mesh with new vertices/faces.
112+
2. Recompute boundary segments and canonical edge refs.
113+
3. Emit provenance mappings:
114+
- old edge ref -> new chamfer face/segments
115+
- unchanged faces preserve IDs where possible
116+
117+
## Execution Phases
118+
119+
## Phase 1: Infrastructure + Feature Flag
120+
121+
1. Add `chamfer_mode` toggle:
122+
- `legacy_boolean` (default initially)
123+
- `geometric_offset` (new path)
124+
2. Build shared adjacency/topology helpers.
125+
126+
Exit criteria:
127+
128+
1. New path can run no-op safely and fall back cleanly.
129+
130+
## Phase 2: Single-Edge Geometric Chamfer
131+
132+
1. Implement robust one-edge chamfer on simple prism/cube cases.
133+
2. Add deterministic unit fixtures.
134+
135+
Exit criteria:
136+
137+
1. Single selected edge produces expected geometry with no booleans.
138+
139+
## Phase 3: Multi-Edge Same-Face + Parallel Chains
140+
141+
1. Handle multiple selected edges on same body.
142+
2. Ensure trim interactions are stable and watertight.
143+
144+
Exit criteria:
145+
146+
1. Common user workflows work without mesh cracks.
147+
148+
## Phase 4: Corner Solver
149+
150+
1. Implement n-edge corner patches.
151+
2. Add tolerance policy and degeneracy handling.
152+
153+
Exit criteria:
154+
155+
1. Complex corners no longer require boolean fallback.
156+
157+
## Phase 5: Provenance + GeometryStore Wiring
158+
159+
1. Emit chamfer-derived boundaries/patch IDs with lineage.
160+
2. Update hover/select mapping for chamfer outputs.
161+
162+
Exit criteria:
163+
164+
1. Chamfer boundaries are first-class and traceable.
165+
166+
## Phase 6: Default Cutover
167+
168+
1. Make geometric mode default.
169+
2. Keep legacy boolean fallback for one release window.
170+
3. Remove legacy path after stability window.
171+
172+
## Testing Plan
173+
174+
## Unit
175+
176+
1. Edge adjacency correctness.
177+
2. Plane offset/intersection math.
178+
3. Corner patch triangulation determinism.
179+
4. Degenerate geometry tolerance behavior.
180+
181+
## Integration
182+
183+
1. Cube single-edge chamfer.
184+
2. Multiple connected edges.
185+
3. Concave/convex mixed selections.
186+
4. Timeline edits upstream/downstream with stable refs.
187+
5. Interaction with boolean-added bodies.
188+
189+
## Regression
190+
191+
1. No face holes/non-manifold edges after chamfer.
192+
2. No ID churn for unaffected faces.
193+
3. Boundary segment refs remain selectable post-chamfer.
194+
195+
## Risks and Mitigations
196+
197+
1. Risk: corner solver complexity.
198+
- Mitigation: staged rollout with strict fixtures before cutover.
199+
200+
2. Risk: precision instability on small geometry.
201+
- Mitigation: unified epsilon policy + local frame math.
202+
203+
3. Risk: behavior divergence from existing chamfer expectations.
204+
- Mitigation: side-by-side mode comparison tooling and temp dual-run validator.
205+
206+
## Implementation Touchpoints
207+
208+
1. `src/void/solid/chamfer.js`
209+
- split into legacy boolean and new geometric engine.
210+
211+
2. `src/void/solid/rebuild.js`
212+
- route chamfer feature to mode-specific executor.
213+
214+
3. `src/void/api/solids.js`
215+
- preserve/refit canonical edge mappings after geometric chamfer.
216+
- expose chamfer lineage for debug overlays.
217+
218+
4. `src/void/api/geometry_store.js`
219+
- ensure chamfer outputs emit boundary/segment/provenance records consistently.
220+
221+
## Immediate Next Step
222+
223+
Implement Phase 1 + Phase 2 in parallel:
224+
225+
1. Add mode flag and new engine scaffolding.
226+
2. Land deterministic single-edge geometric chamfer on planar solids.

0 commit comments

Comments
 (0)