Pure-TypeScript STEP → mesh importer. Reads ISO-10303-21 B-rep geometry (AP203 / AP214 / AP242) and produces watertight, low-sliver, process-grade triangle meshes — meshes you can displace, voxelize, offset, slice, or simulate, not just look at.
Try it live: cnckitchen.github.io/meshStep — the web viewer runs the importer entirely in your browser (files never leave your machine).
Zero runtime dependencies: no WASM, no native code, no build step. The whole library is ~18,000 lines of TypeScript (~300 KB minified, ~115 KB gzipped) that run as-is in the browser, in a Web Worker, and in Node ≥ 22.18. Built to feed bumpmesh (displacement texturing) and infeall (smart infill), where mesh defects aren't cosmetic — they break the algorithm.
npm install meshstepPlain ESM with TypeScript types included, zero dependencies. Works in Node ≥ 22.18 and in any
modern browser via a bundler — the import is synchronous and CPU-bound, so in a UI run it inside
a Web Worker (wire up onProgress and signal, as the web viewer does).
import { importStep } from "meshstep";
const result = importStep(stepFileText); // positions always in mm — see Quick start belowBecause every existing route from "STEP file" to "triangles" optimizes for rendering, and rendering tolerates broken meshes.
Whatever converts your STEP file today — a CAD program's STL export, an OpenCASCADE-based converter, an online tool — almost certainly tessellates each B-rep face independently, with curvature-adaptive spacing tuned for screen-space smoothness. That looks right in a viewer, but structurally it's a per-face triangle soup: duplicated vertices along every face border, hairline cracks between faces, extreme sliver triangles on cylinders and fillets, and occasionally faces missing outright (the Better STEP dataset paper measured OpenCASCADE's mesher leaving faces unmeshed in ~1.5% of ABC-dataset models and ~9% of their assembly set). Algorithms that consume the mesh — displacement mapping, winding-number voxelization, Boolean/offset operations, slicing, FEM — choke on exactly those defects.
meshStep starts from the opposite end: the mesh is the product.
The same part, both at 0.005 mm surface deviation and 15°. Left: OpenCASCADE via occt-import-js (4,724 triangles for the whole part), ideal for rendering, but every flat face is a fan of needles and the walls are slivers. Right: meshStep (68,632 triangles), even triangles up to the 0.5 mm max edge, welded across every face boundary.
- Watertight per body, by construction. Shared B-rep edges are sampled once and welded, so every body imports as a closed, consistently outward-oriented 2-manifold — verified as 0 open edges / 0 non-manifold edges across the curated test corpus (see Status for honest numbers on wilder corpora). Multi-body parts and assemblies stay separate welded components.
- No seam twist, no sliver storm. Every face is triangulated in its natural (u,v) parameter space with a robust constrained-Delaunay pass; periodic faces (cylinder/cone/sphere/torus seams) are unwrapped flat first, so the spiral "twist" that plagues generic B-rep tessellators cannot occur. Fillets get ruling-aligned anisotropy and normal-smoothing diagonal flips for clean shading.
- CAD topology survives into the mesh.
faceOfTri/solidOfTrimap every triangle back to its STEP face and body, and feature edges are exact from the B-repEDGE_CURVEset — a cube stays a cube. Downstream tools can segment and mask by real CAD faces instead of re-detecting features from a triangle soup. STEP presentation colors come along too:colorsresolves theSTYLED_ITEMchains into a palette plus per-face / per-body indices, so a viewer can render the CAD colors and tools can group surfaces by shared color. Andstructureexposes the product tree (part names, assembly hierarchy, occurrence counts) keyed to the same body ids, so per-part selection and hiding work straight off the mesh.facesadds per-face metadata — normalized surface class (plane/cylinder/sphere/…), analytic origin/axis/radius, mesh area and mean normal — so "select this whole CAD face" or "mask every planar face" are one lookup, no dihedral-angle heuristics. - Analytic attributes on demand.
vertexNormals: trueevaluates exact per-vertex normals from the B-rep surfaces (a coarse cylinder still displaces/shades with perfectly radial normals — no faceting bands), andparameterUVs: trueexports each face's own parameter-space (u,v) per triangle corner, so textures can wrap a periodic surface seamlessly in its native parameterization. - FE-style isotropic mode.
isotropic: truemeshes the way an FE pre-processor does: edges are seeded evenly from one growth-limited size field (default growth 1.5× per row), faces get near-equilateral triangles from a per-face optimiser, and fillets and other single-curved four-sided faces become a mapped grid of near-square cells (two triangles each), so they print without contour wobble. Across the 65-model test corpus it is never less correct than the default mode and costs ~1.3× the triangles. - Small-feature clean-up.
mergeTolerancecollapses edges shorter than a given length, and the riser faces of tiny steps, on the B-rep before meshing, so a 0.02 mm offset between two faces no longer forces microscopic triangles. Guarded: a merge that would squash a wall, pull a face past the end of its surface or make a boundary touch itself is refused, and if the merged model meshes less soundly than the original, the original is returned. - The true surface stays available. The optional isotropic remesh (
remesh: true) splits/collapses/flips/smooths toward uniform, near-equilateral triangles and reprojects every vertex onto the exact analytic/NURBS surface (feature edges frozen) — quality passes converge to the CAD geometry, not to a frozen first tessellation. - Cross-validated against OpenCASCADE and audited against the exact B-rep. The
gapcheckharness converts every corpus model with both meshStep and OCCT and compares global + per-face deviation: NIST test models, real-world Printables downloads, and a ~1,800-part Voron-assembly sweep. A second audit checks every triangle against the exact CAD surface: folded or flipped triangles (watertight and on-surface, so invisible to other checks) are a hard gate in the characterization suite, together with surface deviation, normal tilt and slivers.
| Route | In browser | Footprint | Mesh output | Watertight welded | Face→tri topology | License |
|---|---|---|---|---|---|---|
| meshStep | ✅ pure TS | ~115 KB gzip | uniform, low-sliver, seam-safe; optional FE-style isotropic | ✅ per welded body | ✅ | AGPL-3.0 (commercial) |
| occt-import-js | ✅ WASM | ~8 MB WASM | curvature-adaptive, per face | ❌ | ✅ face ranges | LGPL-2.1 (OCCT) |
| opencascade.js | ✅ WASM | larger (custom builds) | same OCCT mesher | ❌ | manual | LGPL-2.1 (OCCT) |
| cascadio / pythonOCC / FreeCAD | ❌ Python/desktop | native wheels/app | same OCCT mesher | ❌ | varies | LGPL (bundles OCCT) |
| gmsh | ❌ desktop/Python | native | FE-quality, isotropic | ✅ (when it succeeds) | GPL-2.0+ | |
| truck / foxtrot (Rust) | ✅ via WASM | MB-scale WASM | generic; twist on periodic faces | ❌ | Apache-2.0 / MIT | |
| STL export from your CAD app | ❌ manual step | — | curvature-adaptive, sliver-heavy | usually | ❌ | proprietary app |
| Commercial SDKs (CAD Exchanger, HOOPS) | server/native | licensed | good | ✅ | ✅ | proprietary, per-seat/app |
License fine print: the OCCT-based routes statically bundle an LGPL-2.1 kernel — workable, but with linking/relinking obligations that get murky in WASM; gmsh's GPL rules out closed-source embedding entirely. meshStep is AGPL-3.0 for open-source use, and because the copyright is held by a single owner with zero third-party code bundled, a clean commercial exception for closed-source products is available directly — see COMMERCIAL.md.
Honest notes on the alternatives:
- occt-import-js is excellent for what it's
built for — viewing (it powers Online 3D Viewer), and it reads IGES and
BREP too. Its output is three.js-style geometry tessellated per face by OCCT's
curvature-adaptive
BRepMesh; welding, watertightness, and triangle quality are simply not its goals. meshStep uses it as the reference implementation in its validation harness. - opencascade.js gives you the full OCCT kernel in the browser — booleans, filleting, sewing, everything — at the cost of a large custom WASM build and its toolchain. If you need a modeling kernel in JS, that's the tool; if you only need STEP → clean mesh, it's a lot of freight.
- gmsh is the serious open-source option for quality meshes from STEP — but it's a desktop/Python FEA tool, imports geometry through OCCT (so inherits its failure modes), and doesn't run in a browser tab.
- truck is a real Rust B-rep kernel (it powers
Loft's browser STEP viewer), and
infeall's own importer builds on it. meshStep exists partly because truck's generic
robust_triangulationcan twist trimmed periodic faces — on a cylinder-with-cutout test, 13% of edges spiralled by up to 177°. foxtrot is a fast but abandoned proof-of-concept with incomplete NURBS support. - Commercial SDKs (CAD Exchanger, HOOPS Exchange) are robust, fast, and read every format — as native/server-side libraries with per-seat/per-app licensing.
When meshStep is the wrong tool: you need formats beyond STEP (IGES, JT, Parasolid), PMI / metadata, a modeling kernel (booleans, sewing, healing of dirty geometry), or maximum robustness against pathological enterprise CAD exports. Use an OCCT-based stack or a commercial SDK for those.
Coverage:
- Surfaces: plane, cylinder, cone, sphere, torus (incl. degenerate), B-spline / NURBS (rational and complex-form), surface of linear extrusion, surface of revolution, offset surfaces.
- Curves: lines, circles, ellipses, B-spline curves (incl. intersection edges of drilled holes).
- Structure: multi-body parts, assemblies with full product-structure instancing,
per-representation units,
BREP_WITH_VOIDS; AP242 tessellated-geometry bodies pass through as-is. Face/body presentation colors (STYLED_ITEM/OVER_RIDING_STYLED_ITEM, AP214/AP242) are extracted palette-indexed. - Mesh I/O: binary STL out (
writeBinarySTL), plus standalone zero-dependency readers so tools can ingest existing meshes through the same library — STL in (readSTL, binary + ASCII, with soup→indexed welding) and 3MF in (read3MF: ZIP + XML parsing, component/build transforms, per-triangle colors, object types).
Robustness is tracked over four corpora of increasing wildness, cross-validated against
OpenCASCADE output with the gapcheck harness (per-face deviation + watertightness) and
audited triangle by triangle against the exact B-rep (folds, flips, deviation, tilt, slivers).
Where it stands (November 2026):
| Corpus | Result |
|---|---|
| 13 curated repo models (analytic + NURBS + assemblies) | all watertight (0 open, 0 non-manifold), 0 folded or flipped triangles |
| 64-model characterization corpus (repo models, real Printables downloads, NIST AP242 test cases), frozen bit-for-bit at the default 0.01 mm / 1 mm | 51 closed and manifold · 2 surface models (open sheets by design) · 8 with localized open-edge leaks (6 NIST models) · 3 rejected up front as far too fine for the absolute default tolerances (they mesh at size-scaled settings). 58 have 0 folded or flipped triangles; the other 6 are tracked with exact counts |
| Voron-family assemblies, 1,820 parts (July 2026) | 1,793 OK · 26 WARN · 1 FAIL vs OCC cross-check at tight tolerance (the FAIL is an artifact of the OCC reference, not the mesh) |
| ABC dataset chunks 0002–0005, 40,000 wild CAD files | 39,780 watertight (99.45%) — closed, manifold, every face meshed. 37,871 (94.7%) also pass the strict B-rep audit (no folded or flipped triangle anywhere). Remainder: mostly flipped triangles on B-spline grids and thin strips · 63 untriangulated faces · 49 timeouts (90 s) · 20 crashes / unreadable files |
meshStep is not (yet) an industrial-strength importer — it's tuned for the kind of parts people actually 3D-print, and the numbers above are deliberately honest about the rest:
- Wild CAD still has a tail. On the ABC research corpus (uncurated files from many CAD systems, full of degenerate, microscopic, and exotic geometry) ~0.5% of models come out with open or non-manifold edges or an unmeshed face, and ~5% more carry a few folded or flipped triangles, mostly on B-spline faces whose parametrisation speed varies several-fold and on hairline strips. The tail shrinks with every release, but OpenCASCADE-based tools will still read more of the truly pathological files — they just hand back per-face triangle soup, not a watertight mesh.
- Pathological models can be slow. Pure TypeScript is fast enough for interactive use on print-scale parts, but 49 of 40,000 ABC models blew a 90 s budget — native OCCT is faster on huge or degenerate inputs.
- Isotropic mode is new. Narrow faces still get no proximity sizing (cusp slivers where a face pinches), and the optimiser does not yet run on the cone, sphere-cap and thin-strip meshers.
- No geometry healing. meshStep trusts the STEP file: gaps, self-intersections, or broken topology in the source B-rep are not repaired, only reported.
- Remaining features: 3MF export (a 3MF reader is in), the Low/Med/High refinement-preset UI, and seam routing for multi-turn thread/spiral faces. Pipeline details in DESIGN.md.
Requires Node ≥ 22.18 (native TypeScript type-stripping — no build step, no dependencies).
node test/convert.ts # import every test STEP, export STL to out/, report quality vs reference
node test/check-all.ts # watertightness check over the repo test modelsimport { importStep, writeBinarySTL } from "./src/index.ts";
const result = importStep(stepText, { surfaceDeviation: 0.01, maxEdge: 1.0 });
// result.mesh (positions/indices), result.faceOfTri, result.solidOfTri
if (!result.diagnostics.ok) console.warn(result.diagnostics); // see "Import diagnostics"
writeFileSync("out.stl", writeBinarySTL(result.mesh));
// STEP colors (null if the file has none): palette + palette index per B-rep face/body.
// Triangle t's sRGB color, and a ready-made grouping key for surfaces:
if (result.colors) {
const { palette, faceColor } = result.colors;
const rgb = palette[faceColor.get(result.faceOfTri[t])]; // undefined index = unstyled face
}
// Part/component tree (STEP product structure): names, nesting, occurrence counts.
// node.bodies[].id keys into result.solidOfTri — filter triangles on it to hide/select a part.
const walk = (node, depth = 0) => {
console.log(" ".repeat(depth) + `${node.name} ×${node.occurrences} (${node.bodies.length} bodies)`);
node.children.forEach((c) => walk(c, depth + 1));
};
walk(result.structure);
// Per-face metadata: surface class + analytic identity + area/normal, keyed by faceOfTri ids.
const info = result.faces.get(result.faceOfTri[t]);
// info.type: "plane" | "cylinder" | "cone" | "sphere" | "torus" | "bspline" | ...
// info.surface: { kind, origin?, axis?, radius?, semiAngle? } (part-local, mm / radians)
// info.area (mm²), info.meanNormal (unit, outward), info.triangleCountAnalytic attributes (both opt-in, computed by projecting the finished mesh back onto the exact B-rep surfaces — repair-fill triangles that lie off-surface get honest fallbacks):
const r = importStep(stepText, { vertexNormals: true, parameterUVs: true });
r.normals; // Float32Array, unit xyz per vertex — analytic on curved faces, crease-averaged at edges
r.uv; // Float32Array, (u,v) per triangle CORNER (welded vertices have one (u,v) per face;
// NaN where no analytic surface exists). Corners are seam-unwrapped per triangle.
r.faceUV; // Map<faceId, { uRange, vRange, uPeriod?, vPeriod? }> for normalizing into texture spaceOptions mirror Fusion's mesh-export dialog: surfaceDeviation (mm), normalDeviation (deg),
maxEdge (mm). For near-equilateral FE-style output use isotropic: true (see below); the older
remesh: true post-pass also exists but degrades the default tessellation's aligned diagonals. onProgress reports parse / tessellate /
finalize progress for long imports; signal (an AbortSignal) cancels a running import at the
next work-unit boundary — in a worker UI, abort first and keep terminate() as the hard stop.
measureGeometry: true additionally collects exact per-edge curve identity (circle
centers/radii/axes, boundary polylines coincident with the mesh) into result.measure, so a
viewer can offer CAD-style measuring on the tessellation.
Several threads: importStepAsync returns exactly what importStep returns (the same
vertices, triangles, ids and warnings) and meshes the faces on worker threads:
import { importStepAsync } from "meshstep";
const result = await importStepAsync(stepText, opts); // Node: nothing else to set up
// In a browser, or when the library is bundled: say how to start a worker on meshStep's worker module
const result2 = await importStepAsync(stepText, {
...opts,
createWorker: () => new Worker(new URL("meshstep/worker", import.meta.url), { type: "module" }),
});A large model takes about half the time in the default mode (6 workers on a 12-core Apple M6:
Ontos_V2 17.2 s → 9.2 s, nist_ctc_04 11.7 s → 6.2 s, GoProHandlePod 5.7 s → 2.6 s; the whole
60-model corpus 146 s → 93 s). The isotropic mode gains less (155 s → 119 s), because half of
its work is preparation that one thread does. A small model is
meshed on the calling thread without a worker being started, so it costs what importStep
costs. threads sets the number of workers (default: half the hardware threads, at most 6, and
fewer for a very large file); each worker reads the model itself, so memory use grows by about
one parsed copy of the model per worker. Without a way to start workers the import runs on the
calling thread. signal aborts as before, and here also while a worker is in the middle of a
face.
Per-face overrides: faceOverrides refines (or coarsens) individual CAD faces, keyed by the
face ids faceOfTri reports, each with its own surfaceDeviation / normalDeviation /
maxEdge (an omitted value falls back to the global one). Every B-rep edge is still sampled
once, at the finest values of the faces it bounds, so the mesh stays watertight and the
neighbours grade into the refined face; faces that share nothing with it come out unchanged.
Typical use: a few faces under a stress probe at 2–4° without meshing the whole part that fine.
An empty map is the same as no option (bit-identical output). Not applied by remesh. Locked by
test/face-overrides.ts.
const fine = importStep(stepText, { ...opts, faceOverrides: { 55: { normalDeviation: 3, maxEdge: 1.2 } } });Isotropic ("pretty") mesh mode: isotropic: true swaps the default ruling-aligned triangles
for near-equilateral ones, graded smoothly away from small features like an FE pre-processor
mesh. growthRate (default 1.5) is the size ratio allowed between neighbouring rows, minEdge
(mm) floors the smallest edge the mesher may ask for, and mappedFillets (default true) meshes
fillets as a grid of near-square cells. Small fillets cost more triangles than in the default
mode (~1.3× over the test corpus). Off by default, and without it the output is bit-identical.
Both at 0.005 mm surface deviation and a 3 mm max edge. Left: default mode, triangles aligned
with the rulings of each face (16,142 triangles for the whole part). Right: isotropic: true,
near-equilateral triangles that start small at the fillets and holes and grow by up to 1.5× per
row toward the 3 mm cap, with mapped grids on the hole and slot walls (37,734 triangles).
Merge tolerance: mergeTolerance (mm) cleans the B-rep before meshing in either mode. An
edge shorter than it collapses to a point and the riser face of a small step is removed, so
offsets far below the mesh size stop forcing tiny triangles (and, in isotropic mode, a patch of
fine mesh around them). The surface may move by up to the tolerance at such a spot.
result.merged reports what changed (edges, faces, maxMove) and reverted: true when the
merged model meshed less soundly and the untouched one was returned instead.
A box whose top is split by a 0.04 mm step, isotropic mode. Left: the step's ends force patches
of tiny triangles (2,614 triangles). Right: mergeTolerance: 0.1 removes the riser face before
meshing (1,932 triangles; the surface moved by 0.04 mm).
const pretty = importStep(stepText, { ...opts, isotropic: true, mergeTolerance: 0.05 });
console.log(pretty.merged); // { edges, faces, maxMove, reverted }Both options need version 0.2.0 or later.
Units: mesh.positions — and every derived length (areas, radii, measure geometry) — are
always millimetres, whatever length unit the STEP file declares (inch, metre, mixed-unit
assemblies with per-part contexts included). result.units is the detected label ("mm", "in",
…) for display only; nothing downstream needs to rescale. Locked by test/units.ts.
Applications that persist references into an imported model (face selections, edge measurements, cached meshes) can rely on the following:
- Entity ids come from the STEP file, not from meshStep.
faceOfTri/solidOfTrivalues,MeasureEdge.edgeId, and every id-keyed map (faces,colors,structurebodies) use the STEP file's own entity record numbers (the#123of theADVANCED_FACE,EDGE_CURVE, or solid record). For byte-identical input they are stable across meshStep versions by construction — persisted selections survive a meshStep upgrade. Repair passes (T-junction zips, micro-hole fills) tag their triangles with an adjacent real face id; meshStep never fabricates ids. (One exception: the AP203CURVE_BOUNDED_SURFACEsheet-model fallback synthesizes body id 0.) - The triangulation itself is NOT stable across releases. Meshing improvements change
vertex positions, counts, and triangle layout in nearly every version (bit-for-bit
stability is enforced only within a version, by the characterization suite). Never
persist triangle or vertex indices — persist entity ids (plus
SolidInstance.instancefor a placed occurrence) and re-resolve after re-import. Pin an exactmeshstepversion, and record the exportedVERSIONconstant alongside any cached mesh so it can be invalidated on upgrade. - Ids are stable per file, not per design. Re-exporting the same part from CAD renumbers every entity; hash the STEP file to detect that and re-bind selections.
- Face coverage can grow between versions. A face that failed to tessellate in an
older version may succeed in a newer one (and
diagnosticsimprove accordingly) — ids are never renumbered, but tolerate ids appearing in or dropping out of the meshed set.
The tolerances are absolute, so one default can't fit both a 5 mm clip and a 3 m assembly.
estimateStepSize(src) measures the model without tessellating (parse + point scan, sub-second
even on large assemblies) and autoTessellation(diagMm) turns that into size-adaptive defaults —
anchored so a ~100 mm part gets the standard 0.01 mm / 1 mm:
import { estimateStepSize, autoTessellation } from "meshstep";
const est = estimateStepSize(stepText); // { bbox, diag, units } | null
const opts = est ? autoTessellation(est.diag) : {}; // { surfaceDeviation, maxEdge }
const result = importStep(stepText, opts);Every import returns a diagnostics verdict so an application can tell a trustworthy conversion
from a suspect one — and tell the user when they'd be better served exporting a mesh directly
from their CAD package:
const { diagnostics: d } = importStep(stepText);
if (!d.ok) {
const broken = d.openEdges > 0 || d.nonManifoldEdges > 0
|| d.warnings.some((w) => w.severity === "error");
showBanner(broken
? "This STEP file imported with defects (missing or leaking geometry). " +
"Consider exporting an STL/3MF directly from your CAD software instead."
: "Some faces needed heuristic repairs — please inspect the result.");
}ok— strict:trueonly when the mesh is closed and manifold, no faces were dropped or skipped, and no heuristic repair paths fired.openEdges/nonManifoldEdges— final edge-defect audit of the returned mesh (open-by-design surface bodies fromopenSolidsexcluded). Non-zero means cracks/holes or bad welds.facesDropped/facesSkipped— geometry that is missing: malformed face records dropped while reading the B-rep, and faces the tessellator could not mesh.warnings— structured findings withcode,severity, the STEPfaceId, and a human-readabledetail. Severity"error"means geometry is missing;"warning"means a rescue path (earcut hole-bridge fill, degenerate-boundary CDT rescue, fold surgery, self-intersecting trim loops) reconstructed a region heuristically — the result is usually fine, but it was not derived from clean topology.
meshDefects(mesh, solidOfTri?, openSolids?) is exported separately for re-auditing a mesh after
downstream processing.
A browser UI for visually checking output lives in web/ — hosted at
cnckitchen.github.io/meshStep: upload a STEP (or an
existing STL/3MF — same toolset, no conversion), tune the settings (auto-scaled to the model's
size, with toggles for the isotropic mode, its growth rate and the merge tolerance), and inspect
the result: the model's STEP/3MF colors (on by default, toggleable), a parts tree with per-part
show/hide, an exploded view for assemblies, shaded / transparent / wireframe / edges render
styles, a section view with a draggable clipping plane, CAD-style measuring (exact circle centers/radii from the
B-rep), deviation coloring against a reference STL (3D-scan style), and open-edge highlighting.
cd web && npm install && npm run dev.
AGPL-3.0-only. Copyright held by CNC Kitchen; commercial licenses for closed-source use are available — see COMMERCIAL.md. The library ships with zero third-party code, so the whole artifact can be licensed directly.
Contributions are welcome under the CLA and dependency-license policy in CONTRIBUTING.md (enforced in CI).



