occt-gltf-addon

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

快速开始

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）：

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 拉取）：

export OCCT_GLTF_ADDON_PREBUILT_BASE_URL=https://cdn2-1304552240.cos.ap-shanghai.myqcloud.com/libs/occt/

运行时自检（兼容安装脚本被禁用的场景）：

• 首次调用时若本地没有对应 prebuilt/<platform>-<arch>/，会尝试在运行时下载预编译包并缓存（优先写入包内 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 安装前缀：

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

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

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

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

OCCT_GLTF_ADDON_SKIP_BUILD=1 npm i occt-gltf-addon

跳过预编译下载（仅当你要强制本地编译时使用）：

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<void>

options（顶层）

• inputPath：STEP 文件路径（必须）
• outputPath：单输出模式下的输出路径
• variants：多输出模式（数组）
• tessellation：默认三角化参数
• filter：过滤参数
• output：输出参数
• logLevel：0|1|2|'quiet'|'info'|'debug'

tessellation

• linearDeflection：线性偏差（>0）
• angularDeflection：角度偏差（弧度，>0）
• smoothNormals：是否平滑法线（默认 true）
• normalCreaseAngle：平滑折角（弧度，默认 60°）

filter

• minBBoxDiagonal：按包围盒对角线过滤小零件（单位为 STEP/OCCT 导入后的单位，通常 mm）
• outerShellOnly：仅保留 solid 外壳（剔除内腔面），默认 true

output

• 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（安装后快速验证）：

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

Quick Test（最小验证脚本）：

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

预编译包构建（维护者）

Linux（x86_64）：

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

macOS（arm64，本机）：

export OCCT_ROOT=/path/to/occt/build-or-install
npm run build
bash scripts/bundle-macos-arm64.sh

统一构建（macOS + Linux）：

npm run bundle:all

License

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