Skip to content
CNCKitchenPublic

About

No description, website, or topics provided.

Resources

Contributing

Stars

61 stars

Watchers

0 watching

Forks

Repository files navigation

meshStep


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

The meshStep web viewer showing a converted part with its CAD face boundaries and a "Watertight · print-ready" verdict

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.

Install

npm install meshstep

npm

Plain 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 below

Why another STEP importer?

Because 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 slot and hole meshed by OpenCASCADE (left: long needle fans across flat faces, slivers down the walls) and by meshStep (right: even triangles everywhere)

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 / solidOfTri map every triangle back to its STEP face and body, and feature edges are exact from the B-rep EDGE_CURVE set — 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: colors resolves the STYLED_ITEM chains 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. And structure exposes 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. faces adds 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: true evaluates exact per-vertex normals from the B-rep surfaces (a coarse cylinder still displaces/shades with perfectly radial normals — no faceting bands), and parameterUVs: true exports 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: true meshes 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. mergeTolerance collapses 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 gapcheck harness 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.

How it compares

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_triangulation can 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.

Status

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

Current limitations

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.

Quick start (dev)

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 models
import { 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.triangleCount

Analytic 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 space

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

The same slot meshed in the default mode (left) and the isotropic mode (right)

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 top with a 0.04 mm step meshed without merging (left: dense patches of tiny triangles at both ends of the step) and with mergeTolerance 0.1 (right: the patches are gone)

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.

Identity & versioning — the stability contract

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 / solidOfTri values, MeasureEdge.edgeId, and every id-keyed map (faces, colors, structure bodies) use the STEP file's own entity record numbers (the #123 of the ADVANCED_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 AP203 CURVE_BOUNDED_SURFACE sheet-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.instance for a placed occurrence) and re-resolve after re-import. Pin an exact meshstep version, and record the exported VERSION constant 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 diagnostics improve 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);

Import diagnostics

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: true only 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 from openSolids excluded). 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 with code, severity, the STEP faceId, and a human-readable detail. 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.

Web verification studio

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.

License

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

About

No description, website, or topics provided.

Resources

Contributing

Stars

61 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages