第01章：OpenSCAD 项目全景与学习路线

1. OpenSCAD 是什么

OpenSCAD 是一个面向工程零件、参数化模型和可重复生成流程的开源三维 CAD 系统。它的核心思想不是“用鼠标拖出模型”，而是“用脚本描述模型，再由程序解释、预览、渲染和导出”。官方仓库 https://github.com/openscad/openscad 的 README 将它称为用于创建实体三维 CAD 对象的软件，并明确强调它更关注 CAD 方面，而不是 Blender 这类艺术建模工具所关注的动画和视觉创作。

从使用者视角看，OpenSCAD 像一个三维建模编译器：你编写 .scad 文件，文件中包含基本几何体、变换、布尔运算、模块、函数和参数，OpenSCAD 将脚本解析为抽象语法树，再生成 CSG 结构，最终预览或求解成可导出的网格文件。从开发者视角看，OpenSCAD 是一个 C++17、CMake、Qt、CGAL、OpenCSG、Eigen、Boost 等库共同组成的桌面与命令行应用。

2. 与传统交互式 CAD 的差异

OpenSCAD 的最大差异是“声明式”和“可复现”。传统 CAD 通常记录特征树和用户操作，用户通过草图约束、拉伸、倒角、布尔等界面命令逐步构造模型。OpenSCAD 则把模型构造过程显式写在文本中。它没有复杂的鼠标交互特征编辑器，也不把模型历史隐藏在二进制工程文件里。

这种设计带来几个重要结果：

• 参数化天然存在：尺寸、孔距、厚度、阵列数量都可以是变量或函数结果。
• 版本控制友好：.scad 是文本文件，适合 Git diff、代码审查和分支合并。
• 批量生成容易：命令行可用不同 -D 参数导出多个规格。
• 复用方式像编程：通过 module、function、use、include 组织库。
• 不适合自由曲面雕刻：复杂有机造型、交互式曲面编辑、艺术细节不属于它的强项。

3. 典型应用场景

OpenSCAD 特别适合以下任务：

1. 3D 打印零件：支架、外壳、夹具、连接件、螺母座、治具。
2. 参数化产品族：同一模型通过宽度、高度、孔位、数量生成多个规格。
3. 教学与算法建模：用简单脚本解释 CSG、矩阵变换、递归和网格精度。
4. 自动化导出：在 CI 或脚本中生成 STL、OFF、3MF、SVG、PNG 等结果。
5. 可审查工程模型：团队能用代码审查模型变化，而不依赖专有二进制格式。
6. 与其他程序集成：由 Python、Make、Ninja、Node、WebAssembly 前端或生成器写出 .scad，再交给 OpenSCAD 渲染。

不建议用 OpenSCAD 处理高阶参数化装配约束、大型工业图纸管理、复杂曲面造型、有限元前处理、CAM 刀路生成或 BIM 协同。它可以作为这些流程中的“参数化几何生成器”，但不是完整 PLM/CAD/CAE 平台。

4. 官方仓库透露出的项目结构

结合官方仓库可以总结出 OpenSCAD 的核心层次：

• src/core：语言、抽象语法树、上下文、表达式、模块、函数、求值、CSG 节点等核心逻辑。
• src/geometry：二维与三维几何表示、布尔、网格、CGAL/OpenCSG 相关几何处理。
• src/io：STL、OFF、AMF、3MF、SVG、DXF、图片等导入导出和文件处理。
• src/gui：Qt 主窗口、编辑器、预览视图、参数面板、偏好设置、交互命令。
• src/glview：OpenGL 视图、相机、渲染器、着色和显示控制。
• src/python：与 Python 相关的实验性或辅助能力。
• examples：基础、函数、参数化和高级示例。
• tests：命令行、渲染、导出、回归、图片比较等测试资产。
• scripts：跨平台依赖安装、构建、发布、WebAssembly、Windows 交叉编译等脚本。

这说明学习 OpenSCAD 应分为两条线：一条是 .scad 语言与建模方法；另一条是 OpenSCAD 自身源码、构建、测试和扩展开发。

5. 学习路线建议

建议按下面顺序学习：

1. 理解 OpenSCAD 的定位：代码建模、CSG、参数化、预览与渲染差异。
2. 安装桌面程序和命令行工具，学会打开、预览、渲染、导出 STL。
3. 掌握基础语法：变量、表达式、向量、字符串、注释、语句块。
4. 掌握模块与函数：参数默认值、命名参数、作用域、children()。
5. 掌握基本体和变换：cube、sphere、cylinder、translate、rotate、scale。
6. 掌握布尔建模：union、difference、intersection 和可制造性设计。
7. 掌握 2D 到 3D：polygon、text、linear_extrude、rotate_extrude、projection。
8. 学会库组织：use、include、MCAD、BOSL2 等生态库。
9. 学会自动化：CLI、-D 参数、批量导出、CI 检查。
10. 阅读源码：从解析、求值、CSG、几何后端、GUI、IO、测试逐步深入。

6. 本教程结构

本教程按照当前博客的 CAD 教程布局组织，每章一个 Markdown 文件，不创建 README。章节覆盖从入门建模、语言语法、工程实战到源码开发与贡献流程。读者可以把前 12 章作为 OpenSCAD 使用教程，把后 4 章作为 OpenSCAD 开发和二次集成教程。

7. 学习时的实践原则

• 每章都应配合一个 .scad 文件练习，不要只阅读文字。
• 每次修改参数后观察 F5 预览和 F6 渲染的差异。
• 对可打印零件，始终考虑壁厚、倒角、装配间隙、支撑和切片方向。
• 对复杂模型，先做二维截面和小模块，再组合成整体。
• 对库文件，优先保持模块纯粹：输入参数明确，输出几何可预测。
• 对团队项目，保持文件命名、参数命名、单位和导出目录一致。