第13章：OpenSCAD 源码架构与核心执行流程

1. 源码学习目标

学习 OpenSCAD 源码的目标不是立刻修改几何内核，而是理解脚本如何变成模型：源码文件如何组织，语言如何解析，模块如何求值，CSG 如何表示，预览和渲染如何分流，导入导出如何接入。

官方仓库显示源码主要在 src 下，包含 core、geometry、io、gui、glview、platform、utils 等目录，并有 openscad.cc、openscad_gui.cc 作为命令行和 GUI 入口相关文件。

2. 总体分层

可按以下方式理解：

1. 入口层：解析命令行参数，决定 GUI、命令行导出、测试或特殊模式。
2. 语言层：读取 .scad 文件，词法/语法解析，构建 AST。
3. 求值层：处理变量、函数、模块、作用域、include/use、children。
4. CSG 层：把模块调用变成 CSG 节点树。
5. 几何层：将 CSG 转换为可显示或可导出的几何表示。
6. 渲染层：OpenCSG/OpenGL 预览或 CGAL 等精确几何计算。
7. IO 层：导入导出 STL、OFF、DXF、SVG、PNG 等格式。
8. GUI 层：编辑器、视图、菜单、参数、控制台、设置和用户交互。

3. core 目录

src/core 是语言和模型语义的核心。结合文件命名可看到 AST、表达式、上下文、模块、函数、内置能力、CSG 节点等内容。阅读顺序建议：

1. 从 AST 和表达式类理解脚本结构如何表示。
2. 阅读上下文和作用域实现，理解变量与参数解析。
3. 阅读模块和函数相关代码，理解调用、默认值和 children。
4. 阅读内置模块注册，了解 cube、sphere、translate、difference 等如何映射。
5. 阅读 CSG 节点结构，理解几何树如何建立。

修改 core 时风险较高，因为语言行为会影响所有模型。

4. geometry 目录

src/geometry 处理二维、三维几何和后端算法。这里可能涉及多边形、网格、CGAL、Clipper、manifold、偏移、布尔和转换。学习重点：

• OpenSCAD 内部如何表示 2D 与 3D 几何。
• 预览几何与最终渲染几何有何差异。
• 多边形、网格、面片、法线、闭合性如何维护。
• CGAL 或其他几何库的调用边界在哪里。
• 错误、警告和退化几何如何传播到用户。

几何层通常是最复杂、最需要测试的部分。

5. io 目录

src/io 负责文件格式导入导出。阅读 IO 层时可按格式分类：

• 网格格式：STL、OFF、3MF、AMF 等。
• 二维格式：DXF、SVG。
• 图片输出：PNG 等。
• 文件路径、资源、缓存和依赖追踪。

导入导出修改通常需要准备真实样例文件，并同时测试 GUI 和命令行路径。

6. gui 与 glview

src/gui 负责 Qt 图形界面，包括主窗口、编辑器、偏好设置、控制台、参数面板和操作命令。src/glview 更关注三维视图、相机、OpenGL 渲染、选择和显示。

GUI 开发应注意：

• 不要把几何核心逻辑写死在界面层。
• 长时间渲染不能阻塞用户反馈。
• 错误信息要能从核心层传到控制台或状态栏。
• 设置项要兼容旧配置。
• 跨平台快捷键、字体和 OpenGL 能力存在差异。

7. 命令行入口

OpenSCAD 的命令行能力是自动化的基础。src/openscad.cc 等入口文件通常负责参数解析、输入输出路径、导出格式、变量覆盖、相机/图片参数和错误码。

阅读命令行实现时关注：

• -o 如何推断导出格式。
• -D 如何传给语言求值层。
• GUI 与 headless 路径如何分离。
• 导出失败时错误码是否正确。
• 日志和 warning 如何输出。

8. 从脚本到模型的流程

可以把执行流程简化为：

.scad 文件
  -> 词法/语法解析
  -> AST
  -> 上下文求值
  -> 模块实例化
  -> CSG 树
  -> 预览渲染或精确渲染
  -> 几何对象
  -> 导出文件或 GUI 显示

调试源码时应先确定问题发生在哪一层。例如：语法报错属于解析层，变量值不对属于求值层，F5 正确 F6 错误多半属于几何/布尔层，STL 文件异常属于导出层。

9. 阅读源码的方法

• 从一个简单模型开始，例如 cube(10);。
• 在入口处观察命令行参数如何传入。
• 找到 cube 内置模块注册和实例化位置。
• 跟踪 CSG 节点生成。
• 比较 F5 和 F6 的调用路径。
• 最后观察 STL 导出如何遍历几何。

不要一开始从最大文件逐行阅读。以具体模型和具体问题为线索更有效。

10. 源码修改风险

• 语言兼容性：旧模型可能依赖历史行为。
• 几何稳定性：一个小改动可能影响大量回归图像。
• 跨平台：Qt、OpenGL、字体、路径在三大系统上差异明显。
• 性能：更精确的算法可能让常见模型变慢。
• 错误信息：开发者能理解的异常不一定适合用户。

因此修改源码必须配合测试和最小复现模型。