STEP (.step/.stp) to glTF (GLB) converter using OpenCascade (OCCT) via a Node.js N-API addon
npm install occt-gltf-addonNode.js N-API 原生扩展:使用 OpenCascade (OCCT) 将 STEP (.step/.stp) 转换为 glTF 2.0 (GLB)。
---
``js
const { convertSTEPToGLTF } = require('occt-gltf-addon');
await convertSTEPToGLTF({
inputPath: '/abs/in.step',
outputPath: '/abs/out.glb',
tessellation: { linearDeflection: 0.1, angularDeflection: 0.5 },
filter: { outerShellOnly: true },
output: { unit: 'm', bakeTransforms: false, zUp: false },
});
`
支持一次调用输出多个变体(只做一次 STEP read + XDE transfer):
`js`
await convertSTEPToGLTF({
inputPath: '/abs/in.step',
logLevel: 'info',
variants: [
{ outputPath: '/abs/out.min.glb', tessellation: { linearDeflection: 5, angularDeflection: Math.PI / 3 } },
{ outputPath: '/abs/out.glb', tessellation: { linearDeflection: 0.1, angularDeflection: 0.5 } },
],
});
---
- Linux x64(Ubuntu 等):安装时自动从 COS 下载预编译二进制(包含 OCCT runtime),不需要系统安装 OCCT。
- macOS arm64(Apple Silicon):安装时自动从 COS 下载预编译二进制(包含 OCCT runtime),不需要系统安装 OCCT。
- 其他平台:默认在 npm install 时本地编译(cmake-js),需要 OCCT 开发文件(headers + libs)。
可通过环境变量指定下载地址(默认从 COS 拉取):
`bash`
export OCCT_GLTF_ADDON_PREBUILT_BASE_URL=https://cdn2-1304552240.cos.ap-shanghai.myqcloud.com/libs/occt/
运行时自检(兼容安装脚本被禁用的场景):
- 首次调用时若本地没有对应 prebuilt/,会尝试在运行时下载预编译包并缓存(优先写入包内 node_modules/occt-gltf-addon/prebuilt/,不可写时回退到 /tmp/occt-gltf-addon/prebuilt)。OCCT_GLTF_ADDON_RUNTIME_DOWNLOAD=0
- 可设置 关闭运行时下载。OCCT_GLTF_ADDON_PREBUILT_CACHE_DIR=/tmp/occt-gltf-addon/prebuilt
- 可设置 自定义缓存目录。OCCT_GLTF_ADDON_PREBUILT_ROOT
- 可设置 或 OCCT_GLTF_ADDON_PREBUILT_DIR 指定本地预编译包位置。
本地编译时通过环境变量指定 OCCT 安装前缀:
`bash`
export OCCT_ROOT=/path/to/occt/prefix
npm i occt-gltf-addon
强制源码编译(不推荐,且需要你自己装 OCCT):
`bash`
OCCT_GLTF_ADDON_FORCE_BUILD=1 OCCT_ROOT=/path/to/occt/prefix npm i occt-gltf-addon
跳过编译(不推荐,运行时会找不到 .node):
`bash`
OCCT_GLTF_ADDON_SKIP_BUILD=1 npm i occt-gltf-addon
跳过预编译下载(仅当你要强制本地编译时使用):
`bash`
OCCT_GLTF_ADDON_SKIP_DOWNLOAD=1 npm i occt-gltf-addon
Draco(Node.js 层压缩,避免原生依赖):
- 默认不链接原生 Draco;当设置 output.draco 时,会在 JS 层使用 gltf-pipeline + draco3d 压缩。OCCT_GLTF_ADDON_ENABLE_DRACO=1
- 如需恢复原生 Draco(可能引入 glibc 兼容问题),构建时设置:
---
convertSTEPToGLTF(options) => Promise
:STEP 文件路径(必须)
- outputPath:单输出模式下的输出路径
- variants:多输出模式(数组)
- tessellation:默认三角化参数
- filter:过滤参数
- output:输出参数
- logLevel:0|1|2|'quiet'|'info'|'debug'$3
- linearDeflection:线性偏差(>0)
- angularDeflection:角度偏差(弧度,>0)
- smoothNormals:是否平滑法线(默认 true)
- normalCreaseAngle:平滑折角(弧度,默认 60°)$3
- minBBoxDiagonal:按包围盒对角线过滤小零件(单位为 STEP/OCCT 导入后的单位,通常 mm)
- outerShellOnly:仅保留 solid 外壳(剔除内腔面),默认 true$3
- unit:'m'|'cm'|'mm'(默认导出为米)
- unitScale:自定义比例(>0)
- bakeTransforms:烘焙节点变换到顶点
- center:'none'|'xy'|'xz'|'yz'(配合 bake 使用)
- zUp:导出为 Z-up 坐标(非标准 glTF)
- draco:boolean | { enabled, compressionLevel, quantizationBitsPosition, quantizationBitsNormal }(Node.js 层 Draco 压缩)---
命令行辅助脚本
Smoke Test(安装后快速验证):
`bash
npm run smoke -- /abs/path/to/model.step /tmp/occt-gltf-out --draco --zup
`Quick Test(最小验证脚本):
`bash
node node_modules/occt-gltf-addon/quick_test.js /abs/path/to/model.step /tmp/out.glb
`---
预编译包构建(维护者)
Linux(x86_64):
`bash
OCCT_GLTF_BUILDX_CACHE=0 npm run docker:build:linux-amd64
`macOS(arm64,本机):
`bash
export OCCT_ROOT=/path/to/occt/build-or-install
npm run build
bash scripts/bundle-macos-arm64.sh
`统一构建(macOS + Linux):
`bash
npm run bundle:all
``---
本 addon 代码以 MIT 发布;运行时依赖 OCCT(LGPL 2.1)与可选 Draco(Apache 2.0)。