occt-worker

在 Node.js 和浏览器 Worker 中使用 OCCT 建模，通过 WebAssembly 和 TypeScript API 完成几何计算。

English | 分层选择 | 文档导航 | 快速开始

无需安装原生 CAD 应用，即可创建实体、进行布尔运算和圆角处理、查询几何、生成网格及交换文件。 支持 STEP、IGES、BREP、STL、OBJ、PLY、VRML、glTF/GLB 和 XCAF。

包中还提供参数与特征模型、二维草图求解器和装配定义。具体范围见能力与限制。

选择能力分层

按应用需要的操作选择能力组合，称为 Profile。只查看 STEP/BREP 模型选 preview， 交互建模并显示结果选 mesh，同时需要建模和多格式导入导出时选完整内核。 首次接入可以从下方安装示例使用的完整内核开始。

| 应用需求 | Profile | 包含的能力与边界 | | --- | --- | --- | | 查看 STEP/BREP 模型 | preview | STEP/BREP 形状导入导出、拓扑查询和网格化；不含建模和装配文档交换。 | | 只做几何建模与计算 | core-modeling | 几何构造、布尔、圆角、分析和修复；不含网格化和常规文件交换。 | | 建模并生成可显示的网格 | mesh | core-modeling 的全部能力，加上网格化和三角化数据检查、编辑、修复；不含常规文件交换。 | | 文件转换与 CAD 文档交换 | exchange | STEP、IGES、BREP、XCAF 及网格格式导入导出；不含通用建模。 | | 在一个内核中完成建模、网格化与文件交换 | full-profile | 全部协议操作；npm 包附带的完整独立内核也提供相同操作集。 |

modeling-viewer 是 mesh 的别名，使用相同文件。mesh 包含 core-modeling， preview 和 exchange 则面向各自的用途。建模 Profile 也包含供内核间传输使用的 BREP 操作。 Profile 决定操作范围；几何精度由操作和参数决定。 具体操作见 Profile 能力表。

选择加载方式

| 需求 | 入口与加载方式 | 对应用的影响 | | --- | --- | --- | | 直接使用完整能力 | 完整独立内核：DirectClient 或 WorkerClient | 加载 npm 包附带的一个完整 WASM。前者在调用线程计算，后者在 Worker 中计算。 | | 只加载选定的能力组合 | 独立 Profile：createProfileClient(profile, options) | 在 Worker 中加载上表对应的一个 WASM；每个实例独立保存形状。 | | 随使用逐步加载操作模块 | 共享 Main/Side：SharedClient | 先加载公共内核 Main，首次调用时再加载对应操作模块 Side；模块共用同一份形状，已加载模块持续驻留。 |

需要多个独立 Profile 配合时，用 GeometryEngine 路由操作并复制所需形状， 通过 EngineCompatClient 使用作用域 API。一次只保留一个 Profile、随应用模式切换时， 用 SingleRuntimeSession；切换后需要重新加载或计算形状。

Profile 和共享模块文件作为单独的发布附件提供。共享 Main 包含 OCCT 依赖， 首次下载体积需按实际文件比较。SharedClient 在调用线程执行计算，放入 Worker 时需由应用提供消息接口。 加载示例见 API 指南，内存和形状归属见架构说明。

下载体积

包版本 1.3.3，按当前仓库产物测量；gzip level 9，Brotli quality 5，1 MiB = 1,048,576 字节。

| 加载内容 | 原始 MiB | gzip MiB | Brotli MiB | | --- | ---: | ---: | ---: | | 完整独立内核 | 31.93 | 8.80 | 7.13 | | preview | 12.12 | 3.72 | 3.09 | | core-modeling | 21.20 | 6.35 | 5.20 | | mesh | 21.73 | 6.50 | 5.32 | | exchange | 17.74 | 5.06 | 4.15 | | full-profile | 31.93 | 8.80 | 7.13 | | 共享 Main（含 JS） | 35.80 | 8.84 | 7.07 | | 共享 Main + 全部 Side | 37.48 | 9.34 | 7.50 |

按文件分别压缩，未计入客户端代码、渲染器和模型。完整数据与统计口径见 下载体积。

示例与模型演示

交互演示源码使用 Three.js 显示实际 OCCT 计算结果，支持旋转、面选择、 线框、调整孔半径、打开 STEP 和下载 STEP/STL。在源码目录中启动：

npm ci
npm run build
npm run demo

打开终端打印的本地地址，默认是 http://127.0.0.1:4173/，端口占用时自动换用下一个端口。 所有演示资源均从本地加载。运行条件与部署目录见示例指南。

| 示例源码 | 内容 | | --- | --- | | preview | 导入 STEP、网格化、导出及清理 | | mesh | 构造带孔支架、网格化及清理 | | SharedClient | 按需加载 Side，构造带孔法兰并导出 | | 完整工作流 | 导入 STEP、切孔、显示及导出，可比较完整内核与两个 Profile |

需求组合和跨 Profile 复制的开销见工作流选择。

安装并运行

以下示例使用完整独立内核。 使用 Node.js 20 或更高版本。示例需在 ES 模块中运行：文件扩展名使用 .mjs， 或在项目中设置 "type": "module"。

npm install occt-worker

import { readFile } from "node:fs/promises";
import { DirectClient } from "occt-worker";

const wasm = await readFile(new URL(import.meta.resolve("occt-worker/wasm")));
const kernel = await DirectClient.create(wasm);
const scope = await kernel.beginScope();

try {
  const plate = await scope.makeBox([100, 60, 4]);
  const hole = await scope.makeCylinder(8, 4, { origin: [50, 30, 0] });
  const cut = await scope.booleanCut(plate, [hole]);
  console.log(await kernel.bbox(cut.shape));
} finally {
  await scope.end();
}

这段代码会在板件上切出一个圆柱孔。形状由创建它的作用域管理； 结束作用域时，会一并释放最终形状和中间结果。

DirectClient 在调用线程上执行几何计算。交互应用中的耗时操作应使用 WorkerClient，让主线程继续响应界面操作。

使用计算结果

tessellate() 返回位置、法线、三角形索引和面分组的类型化数组，可以交给 Three.js 或其他渲染器。面分组用于把选中的三角形对应回 CAD 面。

文件导入导出、元数据和配套资源见文件交换。 参数、特征重算和草图约束见参数化建模。

支持范围

• 支持 Node.js 20+；测试覆盖桌面 Chromium、Firefox 和 WebKit。
• Wasmtime 使用独立的 occt-worker/wasm/wasmtime 导出。
• 浏览器中的共享缓冲区和协作取消需要跨源隔离。
• Worker 重建后，旧形状句柄失效，需要重新导入或计算模型。
• 移动浏览器和 WebView 需要在目标设备上验证。
• 当前 API 不包含通用 OCAF 编辑和 OCCT 并行执行。

环境配置见宿主支持，资源释放和错误处理见API 指南。

开发

检出源码后，构建 TypeScript 包并运行测试：

git clone --recurse-submodules https://github.com/kiseopt/occt-worker.git
cd occt-worker
npm ci
npm test

仓库包含预编译 WASM。修改 C++ 或协议后，需要重建相关文件，步骤见 构建与测试和贡献指南。

项目信息

变更记录 | 问题反馈 | 发布版本 | 安全政策 | 行为规范

项目代码和文档采用 Apache-2.0。 分发的二进制还包含 OCCT 等依赖，适用各自的许可证。再分发前请阅读 许可证说明、通知和对应源码说明。

本项目独立开发，与 Open Cascade SAS 无关联，也未获其背书。