occt-js

WebAssembly build of OpenCASCADE Technology (OCCT) v7.9.3 for CAD import and triangulation. Designed for use in browser-based CAD viewers (e.g., Babylon.js).

Live Demo — drag and drop STEP/IGES/BREP files, face/edge/vertex picking, hover preview

Features

• Import STEP / IGES / BREP files from memory (Uint8Array)
• Full B-Rep topology output (Face/Edge/Vertex with stable IDs and adjacency)
• XDE assembly tree traversal with names and per-face colors
• BRepMesh triangulation with configurable deflection
• Manufacturing-oriented single-part orientation analysis for STEP / IGES / BREP
• Embind-based API returning a structured scene graph
• Babylon.js demo with interactive face/edge/vertex selection

Prerequisites

| Tool | Version | |------|---------| | Emscripten SDK | 3.1.69 | | CMake | 3.20+ | | Git | (for OCCT submodule) |

Setup

# Clone with submodule
git clone --recurse-submodules <repo-url>
cd occt-js

# If you already cloned the repo or are working in a fresh git worktree:
git submodule update --init --recursive occt

# Windows: install Emscripten into build/wasm/emsdk
tools\setup_emscripten_win.bat

# Linux/macOS: install Emscripten manually or use emsdk

Build

# Windows
npm run build:wasm:win

# Linux/macOS: activate Emscripten first, then:
bash tools/build_wasm.sh

Output files are written to dist/:

• occt-js.js — ES module loader
• occt-js.wasm — WebAssembly binary
• occt-js.d.ts — tracked TypeScript definitions published with the package

Root tests and downstream consumers require the generated dist/occt-js.js and dist/occt-js.wasm artifacts to exist. In a clean clone or worktree, build them before running npm test. The tracked dist/occt-js.d.ts file is not regenerated by the Wasm build and should not be deleted. If it is missing, restore it with:

git restore --source=HEAD -- dist/occt-js.d.ts

The Windows build entrypoint fails early with a clear error if either prerequisite is missing:

• occt/src/Standard from the occt git submodule
• build/wasm/emsdk/emsdk_env.bat from tools\setup_emscripten_win.bat

Windows build failures retain a log file at build/wasm-build.log. If a parallel build fails intermittently, retry with lower parallelism:

set BUILD_JOBS=1 && tools\build_wasm_win.bat Release

Repository Layout (2026-03-30)

This stays a single occt-js repository without Babylon fork maintenance.
Within this repository we keep two maintained modules:

• @tx-code/occt-core (packages/occt-core)
  • OCCT Wasm runtime binding and normalized CAD model output.
  • Unified import API for step / iges / brep.
• @tx-code/occt-babylon-loader (packages/occt-babylon-loader)
  • Babylon-facing model loader and scene builder.
  • Delegates CAD parsing to occt-core.

Babylon Packages

• @tx-code/occt-babylon-loader: OCCT model to Babylon nodes.
• @tx-code/occt-babylon-viewer: scene-first Babylon viewer runtime helpers.
• @tx-code/occt-babylon-widgets: optional viewer widgets such as ViewCube.

API

import OcctJS from './dist/occt-js.js';

const occt = await OcctJS();

const buffer = new Uint8Array(/* ... CAD file bytes ... */);
const result = occt.ReadFile("step", buffer, {
    rootMode: "one-shape",
    linearUnit: "millimeter",
    linearDeflectionType: "bounding_box_ratio",
    linearDeflection: 0.1,
    angularDeflection: 0.5,
    readNames: true,
    readColors: true
});

// Also available:
// occt.ReadIgesFile(buffer, options)
// occt.ReadBrepFile(buffer, options)

// result.success       — boolean
// result.sourceFormat  — "step"
// result.rootNodes     — tree of nodes with children, transforms, meshes[]
// result.geometries    — array of { positions, normals, indices, faces, edges, vertices, triangleToFaceMap }
// result.materials     — deduplicated color list
// result.stats         — { rootCount, nodeCount, partCount, triangleCount, ... }

rootMode behavior by format:

• "one-shape": default. Multiple top-level XDE free shapes are exposed under one logical root node.
• "multiple-shapes": preserves each top-level free shape as an independent root node.
• BREP one-shape: keeps the current single-root behavior.
• BREP multiple-shapes: if the imported file resolves to a compound/compsolid wrapper chain, occt-js unwraps single-child wrappers and exposes the first meaningful compound level as multiple root nodes.

Orientation Analysis

occt-js also exposes a separate manufacturing-oriented orientation analysis API for single parts:

const orientation = occt.AnalyzeOptimalOrientation("step", buffer, {
    mode: "manufacturing",
    linearUnit: "millimeter"
});

if (orientation.success) {
    // 4x4 transform that aligns the part into its suggested working pose.
    console.log(orientation.transform);

    // Local reference frame derived from the oriented bounding box.
    console.log(orientation.localFrame);

    // Analysis diagnostics.
    console.log(orientation.strategy);   // e.g. "planar-base-with-cylinder-support+projected-min-area-rect"
    console.log(orientation.stage1);     // base face / detected axis
    console.log(orientation.stage2);     // rotationAroundZDeg
    console.log(orientation.confidence); // 0..1 heuristic score
}

Supported formats for AnalyzeOptimalOrientation(...):

• step
• iges
• brep

Current scope:

• single-part / one-shape analysis
• manufacturing-oriented heuristic based on exact B-Rep geometry
• optional presetAxis override to constrain stage 1 alignment

License

This project links against OCCT which is licensed under the GNU Lesser General Public License v2.1.