debugging-geometry

name

debugging-geometry

description

This skill should be used when debugging a geometry failure in brepjs — when a task says "boolean returned an invalid shape", "fuse/cut/intersect returned Err", "the result is empty", "measureVolume returns 0", "autoHeal didn't fix it", "shape is invalid", "STEP export crashed" or "WebAssembly.RuntimeError during export", "the part looks wrong, render it", "works on occt-wasm but fails on brepkit", or "is this a kernel divergence". Covers triage, numeric sanity checks, the healing pipeline, boolean failure modes (including the

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

Symptom	Class	First move
Op returned Result.Err	error result	Read error.code + error.suggestion + error.metadata?.diagnostics
Result is Ok but geometry is wrong	bad geometry	Numeric sanity (Step 2), then render (Step 5)
Result is empty / measureVolume==0	degenerate/empty	isEmpty, getBounds, volume-normalization rule (Step 2)
Session crashed / WebAssembly.RuntimeError on export	kernel trap	The #1126 export-crash class (Step 4 + references/boolean-failures.md)
Passes on one kernel, fails on another	divergence	Isolate under TEST_KERNEL (Step 6)

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:

Symptom	Likely cause	Fix
FUSE_* Err, "Got COMPOUND"	operands don't actually overlap	give a real overlap; for a weld, fuseAll(shapes, { unsafe: true })
BOOLEAN_HAS_ERRORS	coincident/near-tangent faces	perturb one operand slightly, or set fuzzyValue
overlapping coplanar / zero-thickness input	non-manifold input	autoHeal() operands first (the baked-in FUSE suggestion)
in-memory checks all pass, STEP writer traps	#1126 disjoint-fuse corruption	fuseAll(shapes, { strategy: 'pairwise' })

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).

Symptom	Likely cause	Fix
Fillet/chamfer landed on extra/other edges	predicate too loose — more entities matched than intended	findAll to count what actually matched, render with brep snapshot --label to see them, then tighten the predicate
findUnique returned Err (0 or >1 match)	predicate too strict (0) or ambiguous (>1)	Inspect findAll length; add a discriminating clause or switch to findAll if many are intended
normalAt(face) / a normal comes back null on the picked entity	the selected face/edge is degenerate, so the surface normal is undefined (normalAt, src/topology/faceFns.ts)	Confirm with describe/getBounds (Step 2); the finder selected a degenerate sub-shape — re-find geometrically or heal first

Step 5 — Visual debugging with the brep CLI

The brep CLI (bin in packages/brepjs-cad) renders and validates .brep.ts modules. For interpreting the verify report (checks, hints, body relations, the multi-body fragmentation advisory), defer to the sibling skill brepjs:verify (packages/brepjs-cad/skills/verify/SKILL.md) — this skill covers the debugging loop, not the report anatomy.

• brep verify <file>.brep.ts [--check] [--json] [--metrics] is the primary loop. --check typechecks first; --metrics adds deterministic manufacturability metrics + the interference matrix (off by default, slow). --expect-code <CODE> / --expect-invalid assert a known-bad part fails the right way.
• brep snapshot <file>.brep.ts [--out dir] [--label tag] renders all views in one pass: iso, front, top, right, iso-xray (reveals bores/internal walls an opaque render is blind to), plus a conditional aimed section shot and a marks (Set-of-Marks B#/H# label) shot when the report detects bores/bodies (snapshot/shoot.ts). Each PNG has its bbox size (W×D×H) burned in, so scale is readable from the image. --label writes to a subfolder for pre/post A/B pairing.
• Snapshots use a private ephemeral render server (fresh: true), so parallel snapshots don't contend on the shared :7373 server.
• Puppeteer is lazily/optionally imported: without it, the JSON report still emits and the CLI prints snapshots need puppeteer/Chrome — run: npm i puppeteer.
• Prefer one brep snapshot over rendering each angle separately — one pass gives every standard view. Judge fine surface finish (fine threads, small chamfers) from a real playground render rather than the snapshot, which can exaggerate thin features.

Compare geometry with brep diff <a> <b> (volumeDelta/areaDelta/bboxDelta/symmetricDifferenceVolume) and brep measure <a> [b].

Step 6 — Kernel-divergence isolation

Full mechanics in references/kernel-divergence.md. When a part passes on the default kernel but fails elsewhere (or vice-versa):

1. Re-run under the other kernel. npm run test:occt and npm run test:brepkit set TEST_KERNEL and run that vitest project (vitest.config.ts; tests/setup-kernel.ts). CI runs only occt-wasm (.github/workflows/ci.yml), so brepkit/manifold divergences must be reproduced locally.
2. Localize the diverging op. The in-repo technique (tests/kernelDivergenceCoverage.test.ts): compare against an analytic reference AND against an alternate representation of the same shape — e.g. a torus primitive is exact while a revolve sweep undershoots its volume by ~2%, which pins the loss to the sweep, not the primitive (#968).
3. When confirmed, register it in tests/helpers/kernelDivergences.ts (single source of truth; key = operation.specificCase, kinds not-implemented | skip | tolerance | topology-differs) and gate tests with skipIfDiverges(ctx, key). Always cite the upstream issue. The conformance matrix docs/kernel-conformance.md is auto-generated (npm run conformance:generate).

Note: the default occt-wasm kernel exposes no raw oc handle (kernelDivergences.ts) — raw-OCCT debugging tricks (poking TopoDS_*, patching FS) are unavailable there.

Step 7 — Writing the repro test

1. import { initKernel } from './setup.js' (initOC is a legacy alias) and beforeAll(async () => { await initKernel(); }, 30000).
2. Use unwrap(result) in tests; assert geometry with toBeCloseTo(expected, precision) — never exact float equality.
3. To force the invalid-shape healing path deterministically, spy kernel.isValid to return false on the first call then delegate — the mockKernelIsValid pattern in tests/autoHeal.test.ts. See the sibling skill writing-tests.

Additional resources

• references/healing.md — HealingReport/diagnostic-name tables, AutoHealOptions, escalation ladder, short-circuit semantics.
• references/boolean-failures.md — checkBoolean vs BooleanDiagnostics, error codes + baked-in suggestions, fuzzyValue, the #1126 case study.
• references/kernel-divergence.md — registry mechanics, divergence kinds, kernel capability table, occt-wasm no-raw-oc limits, brepkit #965–968 family status.
• docs/errors.md — full error-code catalog. docs/getting-started.md §Troubleshooting — the 4-step boolean recovery recipe. docs/kernel-conformance.md — capability matrix.
• Sibling skills: result-error-handling (Result/BrepError construction), writing-tests (test skeleton + divergence skips), kernel-abstraction (adding kernel methods), brepjs:verify (CLI report interpretation).