Healing & Sewing
Imported shapes (STEP from a designer, IGES from an old part library, STL from a 3D scan) almost never arrive perfectly valid. They have gaps between adjacent faces, edges with the wrong precision, vertices that don't quite match. brepjs's healing operations fix these. Read this chapter before you ship anything that imports STEP from third parties.
What "healing" actually means
OpenCascade ships a tool called ShapeFix_Shape that runs a battery of repair passes:
- Fix wires: close gaps between consecutive edges, drop tiny edges, reorder edges to be connected.
- Fix face boundaries: orient outer wires CCW and inner wires CW; ensure the face's natural orientation matches.
- Sew shells: find adjacent faces with shared boundaries that aren't connected at the topology level, and stitch them together.
- Fix tolerances: propagate sub-shape tolerances correctly to parent shapes.
- Remove micro-features: drop edges, faces, and slivers below a configurable size threshold.
brepjs wraps this as fixShape; autoHeal runs the shape-level fixers (ShapeFix_Solid, ShapeFix_Face, ShapeFix_Wire) plus optional sewing. There are also lower-level operations (sewShells, solidFromShell) when you need finer control.
autoHeal: the workhorse
import { box, autoHeal, unwrap } from 'brepjs/quick';
declare const importedShape: import('brepjs').Shape3D;
const { shape: ready, report } = unwrap(autoHeal(importedShape));
console.log('Healed shape ready for operations:', report.isValid);
void ready;
void box(1, 1, 1); // keep import liveautoHeal runs all repair passes with sane defaults, returns Result<{ shape, report }, BrepError>. Call it on every imported shape before any boolean / fillet / measurement.
Tuning tolerance
import { autoHeal, unwrap } from 'brepjs/quick';
declare const imported: import('brepjs').Shape3D;
// Conservative - only sew gaps below 0.001 mm
const tight = unwrap(autoHeal(imported, { sewTolerance: 0.001 })).shape;
// Aggressive - close gaps up to 0.05 mm (typical for STEP from low-precision sources)
const loose = unwrap(autoHeal(imported, { sewTolerance: 0.05 })).shape;
void tight;
void loose;Without sewTolerance, autoHeal skips the sewing step. Pass it for STL imports, scanned data, or known-rough sources. If you go too high you'll start fusing details that were supposed to be separate; if too low the heal won't fix the issues you imported with.
The short-circuit gotcha
If the input is already valid, autoHeal does nothing; it returns the input unchanged with report.alreadyValid = true:
import { autoHeal, unwrap, box } from 'brepjs/quick';
const valid = box(10, 10, 10);
const result = unwrap(autoHeal(valid));
// result.shape === valid (the same handle). No sewing, no fixing happened.
console.log('Valid box healed (noop):', valid === result.shape, result.report.alreadyValid);This is a performance optimization (there's nothing to do), but it means you cannot use autoHeal to "force a recheck". For that, see isValid below.
isValid and the healing report: what's actually wrong
When autoHeal doesn't fix what you expected, check isValid and read the healing report:
import { autoHeal, isValid, unwrap } from 'brepjs/quick';
declare const someShape: import('brepjs').Shape3D;
console.log('Valid:', isValid(someShape));
const { report } = unwrap(autoHeal(someShape));
console.log('Valid after heal:', report.isValid);
console.log('Steps:', report.steps);
// report.diagnostics is an array of { name, attempted, succeeded, detail? }
// name: 'sew', 'healSolid', 'healFace', 'healWire', 'finalValidation', etc.isValid runs the kernel's validity check (BRepCheck_Analyzer on OCCT) and returns a boolean. The report records which repair steps ran and whether each one succeeded.
Lower-level operations
sewShells: connect adjacent faces
When you have a collection of faces that should be a closed shell but aren't (the most common output of low-precision STL imports):
import { sewShells, unwrap } from 'brepjs/quick';
declare const facesOrShells: Array<import('brepjs').Face | import('brepjs').Shell>;
const sewn = unwrap(sewShells(facesOrShells));
// sewn is a connected shell; Err if the pieces don't weld into one.
void sewn;sewShells takes a collection of faces or shells and stitches them where their boundaries meet. Use it after STL import, after combining custom-built faces, or after any boolean that produced disconnected pieces. To sew with an explicit tolerance, pass sewTolerance to autoHeal.
solidFromShell: make a shell into a solid
If you have a sewn closed shell and need a ValidSolid:
import { solidFromShell, unwrap } from 'brepjs/quick';
declare const closedShell: import('brepjs').Shell;
const solid = unwrap(solidFromShell(closedShell));
void solid;The shell must be closed: every edge shared by exactly two faces. solidFromShell returns an Err if the result is not a solid or fails the validity check.
Standard healing pipeline
For an unknown imported shape, this is the safe order:
import {
autoHeal,
isValid,
isShape3D,
sewShells,
solidFromShell,
getFaces,
unwrap,
} from 'brepjs/quick';
declare const imported: import('brepjs').Shape3D;
// 1. Always autoHeal first - handles 90% of cases.
let s = unwrap(autoHeal(imported, { sewTolerance: 0.01 })).shape;
// 2. If still invalid, the faces may not be connected.
if (!isValid(s) && isShape3D(s)) {
// 3. Sew the faces into one shell and close it into a solid.
const shell = unwrap(sewShells(getFaces(s)));
s = unwrap(solidFromShell(shell));
}
// 4. Now `s` should be valid for downstream operations.
void s;In practice 95% of imports finish at step 1.
Exception: don't heal when you shouldn't
There are cases where you want to preserve features that healing would destroy:
- Embossed text with very thin features. Healing may erase serifs and dots.
- Bend reliefs in sheet metal. Tiny intentional gaps are part of the design.
- Lattice structures. Each strut is a thin feature.
For these, set sewTolerance very small (e.g. 1e-5) or skip healing entirely. BRepCheck may still pass even on non-healed input if the geometry is locally valid.
Performance
Healing is one of the most expensive brepjs operations. For a complex assembly imported from a third-party CAD tool, expect hundreds of milliseconds to several seconds. Two strategies:
- Heal once, save the healed version: serialize via
toBREPafter healing and re-load withfromBREPnext time. BREP is faster to parse than STEP and the healed shape doesn't need re-healing. - Heal in a worker: combine with Web Workers so the main thread stays unblocked.
Summary
- Run
autoHealon every imported shape before further operations. - Use
isValidand theautoHealreport to diagnose what's wrong whenautoHealdoesn't fix it. - For finer control, drop down to
sewShells,solidFromShell,fixShape. - Healing is expensive; cache the healed result, or do it in a worker.
Next steps
- Tolerance and Validity: what
BRepCheckactually validates - Import & Export: the operations that create the shapes you'll heal
- Performance: when healing dominates your runtime