第一章：Chili3D概述与入门

1.1 什么是Chili3D

Chili3D是一款基于Web浏览器的开源3D CAD（计算机辅助设计）应用程序，专为在线模型设计和编辑而构建。该项目由开发者”仙阁”创建，采用TypeScript编写，通过将OpenCascade（OCCT）几何建模内核编译为WebAssembly，并与Three.js 3D渲染引擎集成，实现了接近原生应用程序的性能表现。Chili3D的目标是让用户无需安装任何本地软件，即可在浏览器中完成强大的3D建模、编辑和渲染操作。

1.1.1 项目定位与目标

Chili3D的核心定位是成为一款轻量级、易用、功能强大的在线3D CAD工具。传统的CAD软件如AutoCAD、SolidWorks、CATIA等通常需要安装庞大的客户端程序，占用大量系统资源，而且往往需要高昂的许可证费用。Chili3D的出现打破了这些限制，它具有以下几个核心目标：

零安装部署：用户只需打开浏览器访问网站即可开始使用，无需下载、安装任何软件，大大降低了使用门槛。
跨平台兼容：由于基于Web技术构建，Chili3D可以在Windows、macOS、Linux等任何支持现代浏览器的操作系统上运行，真正实现了”一次开发，处处运行”的理念。
开源免费：Chili3D采用GNU Affero通用公共许可证v3.0（AGPL-3.0）发布，任何人都可以免费使用、学习和修改源代码，对于商业授权需求可联系开发者获取。
专业级建模能力：通过集成业界标准的OpenCascade几何内核，Chili3D提供了专业级的3D建模能力，支持精确的边界表示（B-Rep）建模、布尔运算、曲面操作等高级功能。
现代化用户体验：采用类Office风格的Ribbon界面设计，结合直观的3D视图控制，为用户提供熟悉且高效的操作体验。

1.1.2 技术架构概览

Chili3D采用现代Web技术栈构建，其技术架构可以分为以下几个核心层次：

前端层：

TypeScript：整个项目采用TypeScript编写，提供了强类型检查和更好的代码可维护性
Three.js：用于3D图形渲染，提供了高性能的WebGL封装
CSS Modules：用于组件级别的样式隔离，避免样式冲突

几何内核层：

OpenCascade（OCCT）：业界领先的开源几何建模内核，提供了完整的B-Rep建模能力
WebAssembly（WASM）：将C++编写的OpenCascade编译为WebAssembly，使其能够在浏览器中高效运行

构建工具层：

Rspack：新一代高性能构建工具，替代Webpack提供更快的构建速度
Jest：用于单元测试和集成测试

存储层：

IndexedDB：浏览器本地存储，用于保存文档和项目数据
文件系统API：支持导入/导出行业标准格式（STEP、IGES、BREP）

1.1.3 核心特性总览

Chili3D提供了丰富的功能特性，覆盖了3D CAD应用的各个方面：

建模工具：

基本形状创建：长方体、圆柱体、圆锥体、球体、棱锥体等
2D草图绘制：直线、圆弧、圆形、椭圆、矩形、多边形、贝塞尔曲线
高级操作：布尔运算（并集、差集、交集）、拉伸、旋转、扫掠、放样、偏移曲面、截面创建

捕捉与追踪：

对象捕捉：精确捕捉几何特征（点、边、面）
工作平面捕捉：捕捉到当前工作平面进行精确平面操作
轴追踪：沿追踪轴创建对象以实现精确对齐
特征点检测：自动检测并捕捉关键几何特征
追踪可视化：显示追踪线和参考点的可视化引导

编辑工具：

修改操作：倒角、圆角、修剪、打断、分割
变换操作：移动、旋转、镜像
高级编辑：特征移除、子形状操作、爆炸复合对象

测量工具：

角度和长度测量
长度、面积、体积的总和计算

文档管理：

创建、打开、保存文档
完整的撤销/重做堆栈与事务历史
导入/导出行业标准格式（STEP、IGES、BREP）

用户界面：

Office风格界面，上下文命令组织
分层装配管理，灵活的分组功能
动态工作平面支持
3D视口和相机控制
相机位置记忆

国际化：

内置多语言界面（i18n）支持
当前支持中文和英文

1.2 环境准备

在开始使用或开发Chili3D之前，需要准备好相应的开发环境。本节将详细介绍如何搭建开发环境。

1.2.1 系统要求

操作系统：

Windows 10/11
macOS 10.15+
Ubuntu 18.04+ 或其他主流Linux发行版

浏览器要求（用于运行）：

Google Chrome 90+（推荐）
Mozilla Firefox 90+
Microsoft Edge 90+
Safari 14+

开发环境要求：

Node.js 18.0+ （推荐使用LTS版本）
npm 9.0+ 或更高版本
Git 2.30+
Visual Studio Code（推荐）或其他代码编辑器

1.2.2 安装Node.js

Node.js是JavaScript运行时环境，是Chili3D开发的基础。推荐使用Node.js版本管理工具如nvm来安装和管理Node.js版本。

Windows用户：

访问Node.js官网（https://nodejs.org/）下载并安装LTS版本。安装完成后，打开命令提示符或PowerShell，执行以下命令验证安装：

node --version
npm --version

macOS/Linux用户：

推荐使用nvm（Node Version Manager）来管理Node.js版本：

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载shell配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装Node.js LTS版本
nvm install --lts

# 验证安装
node --version
npm --version

1.2.3 安装Git

Git是版本控制系统，用于克隆Chili3D源代码仓库。

Windows用户：

访问Git官网（https://git-scm.com/）下载并安装Git for Windows。安装过程中可以选择默认选项。

macOS用户：

# 使用Homebrew安装
brew install git

# 或通过Xcode命令行工具安装
xcode-select --install

Linux用户：

# Ubuntu/Debian
sudo apt update
sudo apt install git

# Fedora
sudo dnf install git

# Arch Linux
sudo pacman -S git

验证Git安装：

git --version

1.2.4 克隆项目

准备好开发环境后，可以从GitHub克隆Chili3D项目：

# 克隆仓库
git clone https://github.com/xiangechen/chili3d.git

# 进入项目目录
cd chili3d

1.2.5 安装依赖

项目使用npm作为包管理器，执行以下命令安装所有依赖：

npm install

这个过程可能需要几分钟，取决于网络速度。安装完成后，项目目录中会生成node_modules文件夹，包含所有依赖包。

1.3 快速开始

1.3.1 启动开发服务器

安装完依赖后，可以启动开发服务器：

npm run dev

命令执行后，开发服务器将在 http://localhost:8080 启动。打开浏览器访问该地址，即可看到Chili3D的主界面。

开发服务器支持热模块替换（HMR），当修改源代码并保存后，浏览器会自动刷新以显示更改。

1.3.2 构建生产版本

要构建生产环境版本，执行以下命令：

npm run build

构建完成后，生成的文件将位于dist目录中。这些文件可以部署到任何静态文件服务器上。

1.3.3 运行测试

Chili3D使用Jest作为测试框架。执行以下命令运行测试：

npm run test

要生成测试覆盖率报告，执行：

npm run testc

1.3.4 代码格式化

项目使用Prettier进行代码格式化。执行以下命令格式化所有代码文件：

npm run format

1.4 项目结构

理解项目结构对于学习和开发Chili3D至关重要。本节将详细介绍项目的目录结构和各个包的功能。

1.4.1 顶层目录结构

chili3d/
├── cpp/                    # C++源代码（OpenCascade绑定）
├── packages/               # TypeScript包（Monorepo结构）
├── public/                 # 静态资源文件
├── screenshots/            # 截图文件
├── scripts/                # 构建和发布脚本
├── .github/                # GitHub Actions配置
├── .vscode/                # VS Code配置
├── package.json            # 项目配置
├── tsconfig.json           # TypeScript配置
├── rspack.config.js        # Rspack构建配置
├── jest.config.js          # Jest测试配置
├── Dockerfile              # Docker配置
├── compose.yml             # Docker Compose配置
└── README.md               # 项目说明

1.4.2 Packages目录结构

Chili3D采用Monorepo架构，所有核心包都位于packages目录下：

packages/
├── chili/                  # 主应用包
├── chili-builder/          # 应用构建器
├── chili-controls/         # UI控件库
├── chili-core/             # 核心库
├── chili-geo/              # 几何计算库
├── chili-storage/          # 存储层
├── chili-three/            # Three.js集成
├── chili-ui/               # 用户界面
├── chili-vis/              # 可视化层
├── chili-wasm/             # WebAssembly绑定
├── chili-web/              # Web入口
└── global.d.ts             # 全局类型定义

1.4.3 核心包详解

chili-core：核心库，包含了应用程序的基础设施代码。主要功能包括：

应用程序接口定义（application.ts）
文档管理（document.ts）
命令系统（command/）
序列化系统（serialize/）
数学工具（math/）
形状接口（shape/）
视觉系统接口（visual/）
国际化支持（i18n/）
选择系统（selection.ts）
属性系统（property.ts）
材质系统（material.ts）

chili：主应用包，实现了核心库中定义的各种接口。主要功能包括：

应用程序实现（application.ts）
文档实现（document.ts）
命令实现（commands/）
几何体实现（bodys/）
捕捉系统（snap/）
服务层（services/）
选择实现（selection.ts）

chili-wasm： WebAssembly绑定包，封装了OpenCascade的调用。主要功能包括：

几何工厂（factory.ts）
形状操作（shape.ts）
曲线处理（curve.ts）
曲面处理（surface.ts）
网格化（mesher.ts）
数据转换（converter.ts）
辅助函数（helper.ts）

chili-three： Three.js集成包，负责3D渲染和视图管理。主要功能包括：

视图管理（threeView.ts）
相机控制（cameraController.ts）
几何体工厂（threeGeometryFactory.ts）
可视化上下文（threeVisualContext.ts）
高亮显示（threeHighlighter.ts）
视图小部件（viewGizmo.ts）
网格导出（meshExporter.ts）

chili-ui：用户界面包，实现了各种UI组件。主要功能包括：

主窗口（mainWindow.ts）
编辑器（editor.ts）
功能区（ribbon/）
项目面板（project/）
属性面板（property/）
状态栏（statusbar/）
视口（viewport/）
对话框（dialog.ts）
Toast提示（toast/）
鼠标光标（cursor/）

chili-builder：应用构建器包，负责组装和初始化应用程序。主要功能包括：

应用构建器（appBuilder.ts）
功能区配置（ribbon.ts）
数据交换（defaultDataExchange.ts）
附加模块（additionalModule.ts）

chili-storage：存储层包，处理数据持久化。主要功能包括：

IndexedDB存储
文件系统操作
文档序列化

1.5 界面介绍

Chili3D采用现代化的用户界面设计，主要由以下几个部分组成：

1.5.1 功能区（Ribbon）

功能区位于窗口顶部，采用类似Microsoft Office的Ribbon设计。功能区分为多个选项卡，每个选项卡包含相关的命令组：

首页选项卡：

文件操作：新建、打开、保存
撤销/重做
剪贴板操作

绘图选项卡：

基本形状：长方体、球体、圆柱体、圆锥体等
2D草图：直线、圆、矩形、多边形等
曲线工具：贝塞尔曲线、样条曲线

修改选项卡：

变换：移动、旋转、缩放、镜像
编辑：倒角、圆角、修剪、分割
布尔运算：并集、差集、交集

视图选项卡：

标准视图：前视图、后视图、左视图、右视图、顶视图、底视图
视图控制：缩放、平移、旋转
显示设置：线框、着色、透明度

1.5.2 项目树

项目树位于窗口左侧，显示当前文档的层级结构：

文档节点：最顶层节点，代表当前打开的文档
文件夹：用于组织和分类对象
几何对象：各种3D形状和2D草图
组：多个对象的逻辑组合

通过项目树，用户可以：

查看和选择对象
重命名对象
调整对象层级
控制对象可见性
删除对象

1.5.3 属性面板

属性面板位于窗口右侧，显示当前选中对象的属性：

基本属性：名称、类型、ID
几何属性：位置、尺寸、方向
外观属性：颜色、材质、透明度
特定属性：根据对象类型显示的特殊属性

用户可以直接在属性面板中修改对象属性，更改会立即反映在视图中。

1.5.4 3D视口

3D视口是主工作区域，占据窗口的大部分空间：

视图控制：

旋转：按住鼠标中键并拖动
平移：按住鼠标中键 + Shift并拖动
缩放：滚动鼠标滚轮

视图小部件：

位于视口右上角
显示当前视图方向
点击可快速切换到标准视图

网格和坐标系：

显示工作平面网格
显示X、Y、Z坐标轴
网格可根据需要显示/隐藏

1.5.5 状态栏

状态栏位于窗口底部，显示以下信息：

当前命令提示：指导用户下一步操作
坐标显示：鼠标位置的3D坐标
捕捉状态：当前激活的捕捉模式
选择状态：当前选中对象的数量

1.6 基本操作

本节介绍Chili3D的基本操作方法，帮助用户快速上手。

1.6.1 创建新文档

点击功能区左上角的”新建”按钮
或使用键盘快捷键 Ctrl+N
系统将创建一个空白文档

1.6.2 打开和保存文档

打开文档：

点击”打开”按钮
选择之前保存的.chili文件
文档将在新标签页中打开

保存文档：

点击”保存”按钮（Ctrl+S）
首次保存时需要输入文件名
文档将保存到浏览器本地存储

1.6.3 创建基本形状

以创建长方体为例：

点击”绘图”选项卡
点击”长方体”按钮
在视口中点击确定起点
移动鼠标确定长度和宽度
点击确定尺寸
移动鼠标确定高度
点击完成创建

1.6.4 选择对象

单选：

在视口中点击对象

多选：

按住Ctrl键点击多个对象
或框选：按住鼠标左键拖动创建选择框

取消选择：

在空白区域点击
或按Esc键

1.6.5 变换对象

移动：

选择对象
点击”移动”按钮或按M键
指定基点
指定目标点

旋转：

选择对象
点击”旋转”按钮或按R键
指定旋转中心
指定旋转角度

镜像：

选择对象
点击”镜像”按钮
指定镜像平面

1.6.6 使用捕捉

Chili3D提供多种捕捉模式：

端点捕捉：捕捉到边的端点
中点捕捉：捕捉到边的中点
圆心捕捉：捕捉到圆或圆弧的圆心
交点捕捉：捕捉到边的交点
垂足捕捉：捕捉到边上的垂足点
网格捕捉：捕捉到工作平面网格

捕捉模式可以通过状态栏或快捷键切换。

1.6.7 使用工作平面

工作平面定义了2D绘图的基准面：

设置工作平面：

点击”视图”选项卡中的”工作平面”
选择预设平面（XY、YZ、XZ）
或选择一个平面作为工作平面

工作平面捕捉：

启用后，所有点都会投影到工作平面上
适用于2D草图绘制

1.7 在线使用

如果不想本地搭建开发环境，可以直接在线使用Chili3D：

1.7.1 官方网站

访问官方网站：https://chili3d.com

这是Chili3D的主要部署站点，提供了最新的稳定版本。

1.7.2 Cloudflare镜像

访问Cloudflare部署：https://chili3d.pages.dev

这是备用镜像站点，提供相同的功能。

1.7.3 在线使用注意事项

浏览器兼容性：建议使用最新版本的Chrome、Firefox或Edge浏览器
WebGL支持：确保浏览器已启用WebGL
本地存储：文档保存在浏览器本地存储中，清除浏览器数据会导致文档丢失
导出备份：建议定期将重要文档导出为STEP或IGES格式备份

1.8 获取帮助

1.8.1 社区资源

GitHub讨论区： https://github.com/xiangechen/chili3d/discussions

这是与开发者和社区交流的主要渠道，可以：

提出问题
分享使用经验
讨论功能建议

GitHub Issues： https://github.com/xiangechen/chili3d/issues

用于报告bug或提交功能请求。

1.8.2 视频教程

中文用户可以访问B站观看视频教程： https://space.bilibili.com/539380032/lists/3108412?type=season

这里包含了开发者发布的官方教程和更新日志。

1.8.3 邮件联系

如需私下联系开发者，可以发送邮件至：xiangetg@msn.cn

1.8.4 商业授权

Chili3D采用AGPL-3.0许可证，对于需要商业授权的场景，请联系开发者获取商业许可选项。

1.9 本章小结

本章介绍了Chili3D的基本概念、技术架构、环境搭建和基本操作。通过本章的学习，读者应该能够：

理解Chili3D的定位和核心特性
成功搭建本地开发环境
了解项目的目录结构和各个包的功能
熟悉用户界面的各个组成部分
掌握基本的建模和编辑操作
知道如何获取帮助和社区资源

在后续章节中，我们将深入探讨Chili3D的核心架构、几何建模原理、二次开发方法等高级主题，帮助读者成为Chili3D的专业用户和开发者。

Chili3D作为一个活跃开发中的项目，功能在不断完善和扩展。建议读者关注项目的GitHub仓库，及时了解最新的开发动态和版本更新。同时，也欢迎有兴趣的开发者参与到项目的开发中来，通过提交代码、报告bug或提供反馈来帮助改进这个优秀的开源项目。

下一章预告：第二章将深入分析Chili3D的核心架构，包括应用程序生命周期、文档模型、命令系统、序列化机制等核心概念，为后续的二次开发打下坚实的基础。