chili3d · diff
git:20260911.ad2889a to git:20260922.e0d0947
20 added, 16 removed. Audit B to B.
---
name: chili3d
description: "Use when building browser-based 3D CAD applications with WebAssembly — STEP/B-Rep visualization, measurement tools, sectioning. Chili3D: pure Web 3D CAD built on OCCT.js compiled to WASM with TypeScript API."
tags:
- web
- 3d
- typescript
- wasm
- occt
- parametric
- step
- stl
---
> **项目地址：** <https://github.com/xiangechen/chili3d>
>
> **在线体验：** <https://chili3d.com/>
>
> **许可证：** AGPL-3.0
## 概述
Chili3D 主要特性：
- **纯前端 CAD**：基于 Three.js + OCCT.js（WebAssembly）
- **参数化建模**：草图、特征树、约束求解
- **基础几何**：立方体、圆柱、棱柱、扫掠、放样、布尔
- **修饰**：圆角、倒角、抽壳
- **数据交换**：STEP / IGES / BREP / STL / OBJ / glTF
- **保存格式**：自有 JSON 项目格式
- **国际化**：内置中/英文
---
## 在线使用
直接打开 <https://chili3d.com/>：
1. 选择「新建」或导入 STEP/IGES
2. 左侧工具栏：Sketch / Box / Cylinder / Sphere / ...
3. 右侧属性面板：编辑参数、变换
4. 顶部菜单：Boolean / Fillet / Chamfer / Shell
5. 文件 → 导出（STEP/STL/glTF）
---
## 本地部署 / 二次开发
```bash
git clone https://github.com/xiangechen/chili3d.git
cd chili3d
pnpm install
- pnpm dev # 本地开发服务器（http://localhost:5173）
- pnpm build # 静态构建
+ pnpm dev # 本地开发服务器（rspack dev）
+ pnpm build # 静态构建（rspack build）
```
构建产物可直接部署到任何静态托管（Nginx / Cloudflare Pages / GitHub Pages）。
---
## 项目结构
```
packages/
- ├── chili-core/ # 模型、命令、应用框架
- ├── chili-geo/ # 几何抽象、Visual
- ├── chili-three/ # Three.js 渲染
- ├── chili-occ/ # OCCT.js WebAssembly 桥接
- ├── chili-controls/ # 草图控件、操控器
- ├── chili-builder/ # 拉伸/扫掠/放样等特征构建器
- ├── chili-ui/ # UI 组件
- └── chili-web/ # 主 Web 应用
+ ├── core/ # 模型、命令、应用框架（@chili3d/core）
+ ├── three/ # Three.js 渲染（@chili3d/three）
+ ├── wasm/ # OCCT.js WebAssembly 桥接（@chili3d/wasm）
+ ├── builder/ # 拉伸/旋转/扫掠/放样等特征构建器（@chili3d/builder）
+ ├── element/ # Web Components 控件
+ ├── parametric/ # 参数化功能定义
+ ├── ui/ # UI 组件
+ ├── web/ # 主 Web 应用（@chili3d/web）
+ ├── app/ # 应用入口
+ ├── storage/ # 项目存储
+ ├── i18n/ # 国际化
+ └── ai/ # AI 助手集成
```
---
## 嵌入到自有应用
```html
<div id="cad" style="width:100%;height:100vh"></div>
<script type="module">
import { Application } from '@chili3d/web';
const app = new Application(document.getElementById('cad'));
await app.start();
</script>
```
或作为 iframe：
```html
<iframe src="https://chili3d.com/" allow="cross-origin-isolated"
style="width:100%;height:100vh;border:0"></iframe>
```
> WebAssembly OCC 需要启用 `SharedArrayBuffer`，要求站点设置 `Cross-Origin-Opener-Policy: same-origin` 与 `Cross-Origin-Embedder-Policy: require-corp`。
---
## 使用 OCCT.js 直接构造（脚本扩展）
```ts
- import { occt } from '@chili3d/occ';
+ import { occt } from '@chili3d/wasm'; // OCCT.js WebAssembly 模块
const oc = await occt();
const box = new oc.BRepPrimAPI_MakeBox_2(100, 60, 30).Shape();
- // 进一步通过 chili-core 的 Visual 对象包装显示
+ // 进一步通过 @chili3d/core 的 Visual 对象包装显示
```
---
## 命令系统
Chili3D 命令通过 `Command` 注册：
```ts
import { Command } from '@chili3d/core';
@Command({ id: 'my.line', display: '我的直线' })
export class MyLineCommand {
async execute(app) {
const p1 = await app.input.getPoint('选择起点');
const p2 = await app.input.getPoint('选择终点');
app.activeView.document.add(LineFactory.byPoints(p1, p2));
}
}
```
---
## 文件 I/O
- **保存项目**：菜单 File → Save → `.chili` JSON
- **导出**：File → Export → STEP/IGES/BREP/STL/OBJ/glTF
- **导入**：File → Import → 同上 + .chili
---
## 与 Three.js 集成
- Chili3D 渲染层在 `chili-three`，可定制材质、光照、PBR：
+ Chili3D 渲染层在 `packages/three`（`@chili3d/three`），可定制材质、光照、PBR：
```ts
import { ThreeView } from '@chili3d/three';
const view = ThreeView.fromCanvas(canvas);
view.scene.add(new THREE.AmbientLight(0xffffff, 0.5));
```
---
## 典型工作流
### 工作流一：在线参数化建模与导出
1. 打开 <https://chili3d.com/> 或本地部署实例
2. 新建项目，使用 Sketch 工具绘制 2D 轮廓
3. 通过 Extrude/Revolve 将草图转为 3D 实体
4. 添加圆角、倒角等修饰特征
5. 使用布尔运算（Union/Cut/Intersect）组合多个实体
6. 导出为 STEP/STL 用于下游加工或 3D 打印
### 工作流二：嵌入业务系统作为 Web CAD 组件
1. 在项目中安装 `@chili3d/web` 包
2. 在页面中创建容器 `<div>`，实例化 `Application`
3. 通过 Command 系统注册自定义绘图命令
4. 监听文档变更事件，同步模型数据到后端
5. 利用 OCCT.js 直接构造几何进行批量参数化生成
6. 构建为静态资源部署到生产环境
---
## 性能要点
1. WebAssembly OCCT 单线程（除非启用 pthreads + COOP/COEP）
2. 大模型加载前先压缩 STEP，导入后转 BREP 缓存
3. 渲染端使用 LOD：用 BVH 或 Decimator 减面
4. 频繁布尔操作建议在 Worker 线程中执行
5. 浏览器内存限制：模型大小通常不超过 100MB STEP
---
## 常见问题
| 问题 | 解决 |
|------|------|
| 加载 OCCT.wasm 失败 | 站点未启用 COOP/COEP；改用 `cross-origin-isolated` |
| 无法导入 DWG | 暂不支持 DWG，先转 DXF/STEP |
| 中文菜单 | Settings → Language 切换为中文 |
- | 性能差 | 确认 Vite 构建为 production；启用浏览器 SIMD |
+ | 性能差 | 确认使用 rspack 生产构建（`pnpm build`）；启用浏览器 SIMD |
| 模型透视错乱 | 检查相机近/远裁剪面与单位 |
---
## 适用场景
✅ 教育、Web 演示、轻量 3D 建模、定制配置器、嵌入业务系统
❌ 大型工业装配、复杂曲面（仍推荐 FreeCAD/OCCT 桌面）
---
## AI 使用建议
- - **推荐工作流模式**：AI 助手应区分两种使用场景——在线建模（引导用户通过 GUI 操作）与二次开发（通过 TypeScript SDK 嵌入）。对后者，优先使用 `@chili3d/occ` 直接调用 OCCT.js 进行几何构造，而非通过 UI 层间接操作。
+ - **推荐工作流模式**：AI 助手应区分两种使用场景——在线建模（引导用户通过 GUI 操作）与二次开发（通过 TypeScript SDK 嵌入）。对后者，优先使用 `@chili3d/wasm` 直接调用 OCCT.js 进行几何构造，而非通过 UI 层间接操作。
- **关键注意事项**：① WebAssembly OCCT 需要 COOP/COEP 头，部署时必须正确配置；② `SharedArrayBuffer` 依赖 HTTPS 或 localhost；③ OCCT.js 加载较慢（首次约 5-15s），需显示加载进度；④ 浏览器内存有限，大模型应考虑服务端处理。
- - **常用代码模式**：`occt()` 初始化 → `BRepPrimAPI_MakeBox` 等构造几何 → `chili-core` 的 Visual/Document 包装 → 渲染显示。自定义命令继承 `Command` 类，通过 `app.input.getPoint()` 获取用户交互。
+ - **常用代码模式**：`occt()` 初始化 → `BRepPrimAPI_MakeBox` 等构造几何 → `@chili3d/core` 的 Visual/Document 包装 → 渲染显示。自定义命令继承 `Command` 类，通过 `app.input.getPoint()` 获取用户交互。
---
## 相关技能
- **astral3d** — Web 3D 可视化与数字孪生框架：[../astral3d/SKILL.md](../astral3d/SKILL.md)
- **lightcad** — 轻量 Web 2D CAD 框架：[../lightcad/SKILL.md](../lightcad/SKILL.md)
- **occt** — 底层 OCCT 几何内核（C++/PythonOCC）：[../occt/SKILL.md](../occt/SKILL.md)
- **freecad** — 桌面参数化 CAD（同基于 OCCT）：[../freecad/SKILL.md](../freecad/SKILL.md)
---
## 参考资源
- 仓库：<https://github.com/xiangechen/chili3d>
- 在线：<https://chili3d.com/>
- OCCT.js：<https://github.com/donalffons/opencascade.js>
- 中文教程（znlgis）：<https://znlgis.github.io/cad/chili3d/>