Debugging Geometry

Debugging geometry failures

A symptom-ordered playbook for the five failure classes: an Err result, wrong-but-Ok geometry, an empty/degenerate result, a crash/trap, or a kernel divergence. Verify every hypothesis with numbers and a render before changing code.

Step 1 — Triage by failure class

Every fallible op returns Result<T, BrepError> with kind/code/message/suggestion?/cause?/metadata?. The full code catalog with per-code recovery advice lives in docs/errors.md — look codes up there, don't guess. error.suggestion is a first-class field; read it first (src/core/errors.ts).

Step 2 — Numeric sanity before trusting any render

Confirm the defect with numbers before opening an image; a render can hide a zero-thickness sliver or an open shell.

• measureVolume / measureArea / measureLength / measureDistance in src/measurement/measureFns.ts — all return Result<T> and pre-check null → NULL_SHAPE_INPUT.
• volume === 0 is itself a diagnostic. Volume is normalized to 0 for anything that is not a solid/compsolid/compound (measureVolumeProps, measureFns.ts, kernel divergence #1361). A "solid" reporting 0 volume is almost always an open shell that never got sewn/closed. Check describe(shape) and the shape type before assuming the volume math is wrong.
• isEmpty(shape) (src/topology/shapeFns.ts) is only a kernel null check — it does not detect degenerate-but-non-null geometry.
• getBounds(shape) (src/topology/topologyQueryFns.ts) returns the AABB and can throw on degenerate shapes — that throw is the basis of the pre-export probe (Step 4).
• describe(shape) (src/topology/topologyQueryFns.ts) gives a structural fingerprint (type + sub-shape counts) — use it to confirm "is this actually a solid, or a compound of two solids?".
• Measurements and validity are cached per shape. After healing or any in-place kernel repair, a stale isValid/measurement can lie — call invalidateShapeCache (exported from the index) if a value looks stale.

Step 3 — Invalid shapes and the healing pipeline

Full tables in references/healing.md. Core loop:

1. Check isValid(shape) (src/topology/healingFns.ts).
2. autoHeal(shape, options?) → Result<{ shape, report: HealingReport }>.
3. Escalate only if report.isValid is still false.

Critical caveat — the short-circuit. autoHeal returns immediately when the input is already valid: report.alreadyValid === true, steps === ['Shape already valid'], and diagnostics contains ONLY { name:'validation', attempted:true, succeeded:true } (healingFns.ts). The absence of sew/fixSelfIntersection/healSolid diagnostics does not mean those passes found nothing — they never ran. Never conclude "healing found no problems" from an alreadyValid report.

Two more traps:

• wiresHealed/facesHealed are Math.abs(after - before) count deltas, a heuristic change-detector — not a count of repaired defects.
• Sewing only runs when sewTolerance is passed; fixSelfIntersection defaults to false.

Escalation ladder when autoHeal leaves it invalid: pass a sewTolerance → fixShape (general ShapeFix_Shape) → solidFromShell for a shell that should be a solid → give up with HEAL_SOLID_INCOMPLETE / HEAL_NO_EFFECT. All in healingFns.ts; details in references/healing.md.

Step 4 — Failed booleans

Full recipes in references/boolean-failures.md. Two distinct diagnostic surfaces — do not conflate them:

• checkBoolean(base, tool, op) (src/topology/booleanDiagnosticFns.ts) is a pre-flight predictor: it returns { valid, issues } where issues are only 'null-shape' | 'not-valid' per operand. It predicts failure; it does not explain a failure after the fact.
• BooleanDiagnostics ({ hasErrors, hasWarnings, messages }) rides on results/errors when trackEvolution is on (default). messages is currently always empty — OCCT's Standard_OStream reporting is not reachable in WASM builds (src/kernel/types.ts). Rely on hasErrors/hasWarnings, not on message text. On hasErrors + null result the op retries without evolution tracking; on hasErrors + non-null it warns and continues (booleanFns.ts).

Boolean ops pre-validate null operands → NULL_SHAPE_INPUT before touching the kernel (booleanFns.ts). When the result cannot cast to 3D the error names the actual type ("Got COMPOUND instead.", booleanFns.ts) — a strong signal the boolean degenerated.

Symptom → cause → fix:

The #1126 export-crash class is the nastiest: fuseAll with the default strategy: 'native' (N-way BRepAlgoAPI_BuilderAlgo) can silently corrupt certain disjoint inputs so the result passes isValid, validSolid, mesh, measureArea, and getBounds — yet traps the STEP writer with a WebAssembly.RuntimeError that corrupts the Emscripten heap and poisons the kernel for the rest of the session (meshFns.ts). No known non-trapping check detects it; the only safety nets are the pre-export bounding-box probe (probeSerializable, catches some degenerates → STEP_EXPORT_UNSERIALIZABLE/STL_EXPORT_UNSERIALIZABLE with the offending sub-solid localized) and exportError classifying the trap as *_EXPORT_CRASHED. The fix is strategy: 'pairwise' (divide-and-conquer over BRepAlgoAPI_Fuse, a different algorithm that is unaffected; booleanFns.ts). Tracked upstream at andymai/opencascade.js#3.

Where export lives (structural gotcha). Import functions live in src/io/ (importFns.ts), but the STEP/STL/IGES export functions live in src/topology/meshFns.ts (exportSTEP/exportSTL/exportIGES) and assembly STEP in src/operations/exporterFns.ts — not in io/. importSTL auto-runs ShapeUpgrade_UnifySameDomain on the read shape (src/kernel/occt/ioOps.ts); IGES round-trips both ways.

Finder mis-selection (fillet/chamfer hit the wrong edges)

When a modifier lands on the wrong entities, the defect is the selection, not the op. Finder USAGE (predicates, when/inList/not, sorting) lives in the docs finders page (apps/docs/tasks/finders.md) and src/query/README.md; this skill owns the debugging angle. Core surface: findAll(shape) returns every match, findUnique(shape) returns Result<T> and errors when 0 or >1 match (src/query/finderCore.ts, findUniqueIn).