update docs
This commit is contained in:
Stewart Allen
parent
5881e94ecd
commit
5a34fd8c54
1 changed files with 226 additions and 0 deletions
226
docs/void/plan-chamfer-offset-v2.md
Normal file
226
docs/void/plan-chamfer-offset-v2.md
Normal file
|
|
@ -0,0 +1,226 @@
|
||||||
|
# Void Chamfer V2 Plan (Geometric Offset, Not Boolean Cutters)
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Why Change
|
||||||
|
|
||||||
|
1. Current path is boolean-driven (`solid/chamfer.js`) and depends on synthetic cutter prisms.
|
||||||
|
2. Boolean chamfer is fragile near:
|
||||||
|
- short edges
|
||||||
|
- dense/curved topology
|
||||||
|
- multi-edge corner interactions
|
||||||
|
- near-coplanar/low-angle neighborhoods
|
||||||
|
3. Provenance and boundary tracking are harder when chamfer is represented as a subtract operation, rather than explicit edge-face reconstruction.
|
||||||
|
4. Debugging and deterministic replay are harder with cutter generation and manifold fallback behavior.
|
||||||
|
|
||||||
|
## Current-State Findings
|
||||||
|
|
||||||
|
1. Chamfer currently:
|
||||||
|
- resolves selected edges
|
||||||
|
- builds cutter meshes from adjacent triangle normals
|
||||||
|
- performs boolean difference
|
||||||
|
- writes resulting body as manifold output
|
||||||
|
|
||||||
|
2. Signals in current code indicate boolean-centric lifecycle:
|
||||||
|
- `manifold_chamfer_passthrough`
|
||||||
|
- `manifold_chamfer_ready`
|
||||||
|
- cutter debug/failure logs
|
||||||
|
|
||||||
|
3. Edge references are already fairly good:
|
||||||
|
- chamfer refs use canonical boundary/segment identities
|
||||||
|
- this is strong input for a topology-based rebuild
|
||||||
|
|
||||||
|
## Target Architecture
|
||||||
|
|
||||||
|
Chamfer becomes a topology/geometry transform, not a subtractive solid operation.
|
||||||
|
|
||||||
|
1. Input:
|
||||||
|
- selected sharp edges (from stable boundary segment refs)
|
||||||
|
- chamfer distance (and later optional asymmetric distances)
|
||||||
|
|
||||||
|
2. Core operation:
|
||||||
|
- for each selected edge, offset its two incident face planes by chamfer distance
|
||||||
|
- intersect offset planes with local wedge to compute chamfer strip geometry
|
||||||
|
- trim neighboring faces and insert chamfer face(s)
|
||||||
|
|
||||||
|
3. Corner resolution:
|
||||||
|
- solve multi-edge vertex neighborhoods explicitly
|
||||||
|
- produce watertight corner patches without global booleans
|
||||||
|
|
||||||
|
4. Output:
|
||||||
|
- rebuilt manifold mesh + updated provenance/boundary mappings
|
||||||
|
- explicit chamfer faces with stable IDs (not anonymous boolean remnants)
|
||||||
|
|
||||||
|
## Data Model / Provenance Updates
|
||||||
|
|
||||||
|
1. Extend chamfer result metadata:
|
||||||
|
- `source_edge_segment_ids[]`
|
||||||
|
- `generated_face_ids[]`
|
||||||
|
- `status: geometric_chamfer_ready`
|
||||||
|
|
||||||
|
2. GeometryStore integration:
|
||||||
|
- chamfer faces emit boundaries/segments directly
|
||||||
|
- chamfer faces carry source edge lineage
|
||||||
|
|
||||||
|
3. Preserve compatibility:
|
||||||
|
- existing docs still readable
|
||||||
|
- optional fallback to legacy boolean chamfer behind feature flag
|
||||||
|
|
||||||
|
## Algorithm Plan
|
||||||
|
|
||||||
|
## Stage A: Topology Extraction
|
||||||
|
|
||||||
|
1. Build edge->incident-face adjacency from input mesh.
|
||||||
|
2. Identify valid chamfer candidates:
|
||||||
|
- manifold edges with exactly two incident faces
|
||||||
|
- non-smooth crease threshold gating
|
||||||
|
|
||||||
|
3. Group selected edges into connected chamfer regions.
|
||||||
|
|
||||||
|
## Stage B: Per-Edge Offset Construction
|
||||||
|
|
||||||
|
1. For each selected edge:
|
||||||
|
- compute incident face normals
|
||||||
|
- construct two offset face planes
|
||||||
|
- compute chamfer line as plane-plane intersection in local neighborhood
|
||||||
|
|
||||||
|
2. Create edge strip endpoints using neighboring trim constraints.
|
||||||
|
|
||||||
|
## Stage C: Face Trimming + Insertion
|
||||||
|
|
||||||
|
1. Trim original incident faces against chamfer boundary lines.
|
||||||
|
2. Insert chamfer quad/tri strip faces.
|
||||||
|
3. Maintain winding and local normal consistency.
|
||||||
|
|
||||||
|
## Stage D: Vertex Corner Solver
|
||||||
|
|
||||||
|
1. At each selected vertex:
|
||||||
|
- collect incoming chamfer strips
|
||||||
|
- solve intersection polygon in tangent frame
|
||||||
|
- triangulate corner patch deterministically
|
||||||
|
|
||||||
|
2. Handle edge cases:
|
||||||
|
- 2-edge corner
|
||||||
|
- n-edge star corner
|
||||||
|
- near-parallel incident faces
|
||||||
|
|
||||||
|
## Stage E: Rebuild + Mapping
|
||||||
|
|
||||||
|
1. Rebuild indexed mesh with new vertices/faces.
|
||||||
|
2. Recompute boundary segments and canonical edge refs.
|
||||||
|
3. Emit provenance mappings:
|
||||||
|
- old edge ref -> new chamfer face/segments
|
||||||
|
- unchanged faces preserve IDs where possible
|
||||||
|
|
||||||
|
## Execution Phases
|
||||||
|
|
||||||
|
## Phase 1: Infrastructure + Feature Flag
|
||||||
|
|
||||||
|
1. Add `chamfer_mode` toggle:
|
||||||
|
- `legacy_boolean` (default initially)
|
||||||
|
- `geometric_offset` (new path)
|
||||||
|
2. Build shared adjacency/topology helpers.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
1. New path can run no-op safely and fall back cleanly.
|
||||||
|
|
||||||
|
## Phase 2: Single-Edge Geometric Chamfer
|
||||||
|
|
||||||
|
1. Implement robust one-edge chamfer on simple prism/cube cases.
|
||||||
|
2. Add deterministic unit fixtures.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
1. Single selected edge produces expected geometry with no booleans.
|
||||||
|
|
||||||
|
## Phase 3: Multi-Edge Same-Face + Parallel Chains
|
||||||
|
|
||||||
|
1. Handle multiple selected edges on same body.
|
||||||
|
2. Ensure trim interactions are stable and watertight.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
1. Common user workflows work without mesh cracks.
|
||||||
|
|
||||||
|
## Phase 4: Corner Solver
|
||||||
|
|
||||||
|
1. Implement n-edge corner patches.
|
||||||
|
2. Add tolerance policy and degeneracy handling.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
1. Complex corners no longer require boolean fallback.
|
||||||
|
|
||||||
|
## Phase 5: Provenance + GeometryStore Wiring
|
||||||
|
|
||||||
|
1. Emit chamfer-derived boundaries/patch IDs with lineage.
|
||||||
|
2. Update hover/select mapping for chamfer outputs.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
1. Chamfer boundaries are first-class and traceable.
|
||||||
|
|
||||||
|
## Phase 6: Default Cutover
|
||||||
|
|
||||||
|
1. Make geometric mode default.
|
||||||
|
2. Keep legacy boolean fallback for one release window.
|
||||||
|
3. Remove legacy path after stability window.
|
||||||
|
|
||||||
|
## Testing Plan
|
||||||
|
|
||||||
|
## Unit
|
||||||
|
|
||||||
|
1. Edge adjacency correctness.
|
||||||
|
2. Plane offset/intersection math.
|
||||||
|
3. Corner patch triangulation determinism.
|
||||||
|
4. Degenerate geometry tolerance behavior.
|
||||||
|
|
||||||
|
## Integration
|
||||||
|
|
||||||
|
1. Cube single-edge chamfer.
|
||||||
|
2. Multiple connected edges.
|
||||||
|
3. Concave/convex mixed selections.
|
||||||
|
4. Timeline edits upstream/downstream with stable refs.
|
||||||
|
5. Interaction with boolean-added bodies.
|
||||||
|
|
||||||
|
## Regression
|
||||||
|
|
||||||
|
1. No face holes/non-manifold edges after chamfer.
|
||||||
|
2. No ID churn for unaffected faces.
|
||||||
|
3. Boundary segment refs remain selectable post-chamfer.
|
||||||
|
|
||||||
|
## Risks and Mitigations
|
||||||
|
|
||||||
|
1. Risk: corner solver complexity.
|
||||||
|
- Mitigation: staged rollout with strict fixtures before cutover.
|
||||||
|
|
||||||
|
2. Risk: precision instability on small geometry.
|
||||||
|
- Mitigation: unified epsilon policy + local frame math.
|
||||||
|
|
||||||
|
3. Risk: behavior divergence from existing chamfer expectations.
|
||||||
|
- Mitigation: side-by-side mode comparison tooling and temp dual-run validator.
|
||||||
|
|
||||||
|
## Implementation Touchpoints
|
||||||
|
|
||||||
|
1. `src/void/solid/chamfer.js`
|
||||||
|
- split into legacy boolean and new geometric engine.
|
||||||
|
|
||||||
|
2. `src/void/solid/rebuild.js`
|
||||||
|
- route chamfer feature to mode-specific executor.
|
||||||
|
|
||||||
|
3. `src/void/api/solids.js`
|
||||||
|
- preserve/refit canonical edge mappings after geometric chamfer.
|
||||||
|
- expose chamfer lineage for debug overlays.
|
||||||
|
|
||||||
|
4. `src/void/api/geometry_store.js`
|
||||||
|
- ensure chamfer outputs emit boundary/segment/provenance records consistently.
|
||||||
|
|
||||||
|
## Immediate Next Step
|
||||||
|
|
||||||
|
Implement Phase 1 + Phase 2 in parallel:
|
||||||
|
|
||||||
|
1. Add mode flag and new engine scaffolding.
|
||||||
|
2. Land deterministic single-edge geometric chamfer on planar solids.
|
||||||
Loading…
Reference in a new issue