occt-gltf-addon

Node.js N-API 原生扩展：使用 OpenCascade (OCCT) 将 STEP (.step/.stp) 转换为 glTF 2.0 (GLB)。

安装

• Linux x64（Ubuntu 等）：主包内置预编译二进制（包含 OCCT runtime），不需要系统安装 OCCT。
• macOS arm64（Apple Silicon）：主包内置预编译二进制（包含 OCCT runtime），不需要系统安装 OCCT。
• 其他平台：默认会在 npm install 时本地编译（cmake-js），需要 OCCT 开发文件（headers + libs）。

本地编译时通过环境变量指定 OCCT 安装前缀：

export OCCT_ROOT=/path/to/occt/prefix
npm i occt-gltf-addon

如需在 linux-x64 强制源码编译（不推荐，且需要你自己装 OCCT）：

OCCT_GLTF_ADDON_FORCE_BUILD=1 OCCT_ROOT=/path/to/occt/prefix npm i occt-gltf-addon

macOS 同理可用 OCCT_GLTF_ADDON_FORCE_BUILD=1 强制源码编译。

可选（仅在 源码编译 时用于启用 Draco 支持，需要开发包）：

• brew install draco / apt-get install libdraco-dev

如需跳过编译（不推荐，运行时会找不到 .node）：

OCCT_GLTF_ADDON_SKIP_BUILD=1 npm i occt-gltf-addon

API

const { convertSTEPToGLTF } = require('occt-gltf-addon');

await convertSTEPToGLTF({
  inputPath: '/abs/in.step',
  outputPath: '/abs/out.glb',
  tessellation: { linearDeflection: 0.1, angularDeflection: 0.5 },
});

支持一次调用输出多个变体（只做一次 STEP read + XDE transfer）：

await convertSTEPToGLTF({
  inputPath,
  logLevel: 'info',
  variants: [
    { outputPath: 'out.min.glb', tessellation: { linearDeflection: 5, angularDeflection: Math.PI/3 } },
    { outputPath: 'out.glb',     tessellation: { linearDeflection: 0.1, angularDeflection: 0.5 } },
  ],
});

Smoke Test（安装后快速验证）

npm run smoke -- /abs/path/to/model.step /tmp/occt-gltf-out --draco --zup

参数：

• --draco：启用 Draco 输出（可选）
• --zup：导出 Z-up（用于 three.js Z-up 世界；可选）
• --quiet：静默日志（可选）

Quick Test（最小验证脚本）

node node_modules/occt-gltf-addon/quick_test.js /abs/path/to/model.step /tmp/out.glb

可选参数：

• --draco：启用 Draco 输出（可选）
• --zup：导出 Z-up（可选）
• --quiet：静默日志（可选）

预编译包构建（维护者）

Linux（x86_64）：

OCCT_GLTF_BUILDX_CACHE=0 npm run docker:build:linux-amd64

macOS（arm64，本机）：

npm run build
bash scripts/bundle-macos-arm64.sh

统一构建（macOS + Linux）：

npm run bundle:all

关键选项说明（简版）

• tessellation.linearDeflection / angularDeflection：B-Rep 三角化精度
• tessellation.smoothNormals / normalCreaseAngle：平滑法线（默认开，60° crease）
• filter.minBBoxDiagonal：按包围盒对角线过滤小零件（单位为 STEP/OCCT 导入后的单位，通常 mm）
• filter.outerShellOnly：仅保留 solid 外壳（剔除内腔面）；默认 true
• output.unit：'m'|'cm'|'mm'（默认导出为米）
• output.bakeTransforms：把节点变换烘焙进顶点并把 node matrix 归零（类似 Blender Apply）
• output.center：'none'|'xy'|'xz'|'yz'（配合 bake 使用；Y-up 时 xz 会 ground 到 minY=0；Z-up 时 xy 会 ground 到 minZ=0）
• output.zUp：导出为 Z-up 坐标（适配 three.js THREE.Object3D.DEFAULT_UP.set(0,0,1)）；注意这会变成 非标准 glTF（标准是 Y-up）
• output.draco：启用 KHR_draco_mesh_compression（部分导入器不支持）

License

本 addon 代码以 MIT 发布；运行时依赖 OCCT（LGPL 2.1）与可选 Draco（Apache 2.0）。