occt-gltf-addon

$3

Node.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 压缩。
- 如需恢复原生 Draco（可能引入 glibc 兼容问题），构建时设置：OCCT_GLTF_ADDON_ENABLE_DRACO=1

---

API

convertSTEPToGLTF(options) => Promise

$3


- inputPath：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
``

---

License

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