Adjacency-driven fusing should be opt-in or removed #13

New issue

Closed

opened 2026-06-17 18:14:01 +00:00 by Mark · 0 comments

Mark commented

2026-06-17 18:14:01 +00:00

Owner

Context

From PLAN.md line 68:

[ ] TODO: revisit adjacency-driven fusing behavior (evaluate, document, and decide if it should be optional/configurable)

The current --fuse-mode adjacency setting builds an adjacency graph and fuses solids that share faces. This is on by default (choices=["adjacency", "none"], default="adjacency").

The problem: adjacency-based fusion can over-fuse when surfaces are nearly-coplanar (within tessellation tolerance). A base plane and a near-coplanar bottom face of a cylinder can get merged into a single face, breaking downstream feature detection (the user's "find the counterbored cylinder" workflow depends on distinct planar features).

Scope

Two options to evaluate:

Option A: Make fusing opt-in

Change --fuse-mode default to none
Document the trade-off: adjacency is faster, simpler output, but can over-fuse
Users opt in when they want a simpler BREP at the cost of fidelity

Option B: Smarter fusion

Add a coplanarity tolerance separate from adjacency
Only fuse faces whose normals differ by less than 1° AND whose planes are within <tol
Keep adjacency default but with the smarter criterion

Acceptance

Whichever option is chosen, document the trade-off in PLAN.md and pointcloud-to-cad-guide.md
Add a test case with two near-coplanar features (e.g., a base plane + cylinder bottom face within 1° of normal) that fails under naive fusion and passes under the chosen strategy
Update --fuse-mode help text

Why this matters

The user's workflow is feature detection from a scan — finding the holes, pads, ribs in a mechanical part. Over-fusing destroys features. This is a correctness issue, not a performance issue.

## Context From `PLAN.md` line 68: > [ ] TODO: revisit adjacency-driven fusing behavior (evaluate, document, and decide if it should be optional/configurable) The current `--fuse-mode adjacency` setting builds an adjacency graph and fuses solids that share faces. This is on by default (`choices=["adjacency", "none"], default="adjacency"`). The problem: adjacency-based fusion can over-fuse when surfaces are nearly-coplanar (within tessellation tolerance). A base plane and a near-coplanar bottom face of a cylinder can get merged into a single face, breaking downstream feature detection (the user's "find the counterbored cylinder" workflow depends on distinct planar features). ## Scope Two options to evaluate: ### Option A: Make fusing opt-in - Change `--fuse-mode` default to `none` - Document the trade-off: `adjacency` is faster, simpler output, but can over-fuse - Users opt in when they want a simpler BREP at the cost of fidelity ### Option B: Smarter fusion - Add a coplanarity tolerance separate from adjacency - Only fuse faces whose normals differ by less than `1°` AND whose planes are within `<tol` - Keep adjacency default but with the smarter criterion ## Acceptance - Whichever option is chosen, document the trade-off in `PLAN.md` and `pointcloud-to-cad-guide.md` - Add a test case with two near-coplanar features (e.g., a base plane + cylinder bottom face within 1° of normal) that fails under naive fusion and passes under the chosen strategy - Update `--fuse-mode` help text ## Why this matters The user's workflow is feature detection from a scan — finding the holes, pads, ribs in a mechanical part. Over-fusing destroys features. This is a correctness issue, not a performance issue.