在传统 CAD 工作流中，设计师打开图形界面、点击一系列操作、导出 STL、发现螺栓孔位置偏移 2 毫米，然后重复整个流程。这种以鼠标为中心的设计模式在参数化修改时效率极低，且难以版本控制。vcad 的作者 Cam Pedersen 在为机器人设计零件时遇到了同样的痛点，于是决定用 Rust 实现一个代码驱动的参数化 CAD 库。本文将深入探讨 vcad 的核心技术实现，特别是 CSG 树求值、边界表示法与数值精度控制这几个关键工程问题。
CSG 树的结构与 Rust 类型安全
构造实体几何的核心思想是将复杂几何体表示为一棵二叉树：叶子节点是基本图元（如立方体、圆柱体），内部节点是布尔运算（并集、交集、差集）。vcad 通过 Rust 的运算符重载将这种树形结构转化为直观的代数表达式。查看其源码可以看到，开发者定义了三组核心运算符：减号表示差集 A - B，加号表示并集 A + B，与号表示交集 A & B。这种设计使得几何定义读起来就像数学公式一样自然，十二行代码就能描述一个带有中心孔和螺栓阵列的安装板。
从类型系统的角度来看，vcad 的每个几何对象都实现了统一的操作接口。原始图元函数如 centered_cube 和 centered_cylinder 返回一个实现了 BinaryOperation trait 的结构体，该结构体持有左右两个操作数以及运算类型的枚举值。当多个运算符链式调用时，Rust 编译器会逐层嵌套这些结构体，最终形成一个完整的 CSG 树。这种设计避免了运行时构建抽象语法树的开销，因为树的结构在编译期就已经通过类型推断确定。运算符重载并非语法糖，而是将用户输入直接编译为可以直接求值的数据结构，这是 Rust 零成本抽象理念的典型应用。
值得注意的是，vcad 刻意保持了 API 的精简。图元、布尔运算、变换、图案复制 —— 这四类操作构成了整个建模语言。这种约束并非限制，而是经过深思熟虑的设计决策。任何复杂的几何形状都可以通过这四类操作的组合来表达，而过于丰富的原语会增加 API 的认知负担和实现复杂度。vcad 的 L 型支架示例展示了这种组合能力：底座和侧壁通过并集合并，再分别减去对应的安装孔阵列，整个过程只需定义一次孔的位置参数。
Manifold 引擎与边界表示法的可靠性
几何求值的核心挑战在于确保运算结果的拓扑正确性。两个几何体进行布尔运算时，产生的必须是流形（manifold）几何体 —— 每条边恰好被两个面共享，每个顶点被至少三条边连接。如果结果存在非流形情况（如悬边或重叠面），后续的切片、打印或仿真都会出现问题。vcad 选择绑定 Google 的 Manifold 引擎来处理这部分计算，这个决定直接解决了参数化 CAD 最棘手的可靠性问题。
Manifold 引擎的核心算法基于分段映射（segmented mapping）和空间分区查询。与传统的 BSP 树或八叉树方法不同，Manifold 使用一种称为 slice-based boolean 的技术，将三维运算降维到二维平面切片进行处理。这种方法天然避免了三维空间中的数值精度陷阱，因为二维平面上的交点计算可以使用更高的相对精度。当处理复杂布尔链时（如 A 减 B 加 C 减 D），Manifold 会自动将表达式分解为多个二元运算并进行结果合并，同时确保中间结果的拓扑一致性。
从边界表示法的角度理解，Manifold 输出的是 watertight（不漏水）的三角网格。这意味着网格中不存在裂缝、重复顶点或法向不一致的面。vcad 在此基础上添加了额外的验证层：每个运算结果都会检查体积、表面积和包围盒的合理性。如果某个参数组合导致几何体退化（如所有维度为零），库会直接返回错误而非生成无效网格。这种防御性编程在参数化系统中尤为重要，因为用户可能通过循环变量意外传入负数或零值。
数值精度控制的工程实践
浮点数误差是几何引擎的永恒挑战。当计算两个几乎相交的面的交线时，极小的舍入误差可能导致交线不存在或产生零宽度的缝隙。vcad 通过几个层面的工程实践来缓解这个问题。首先，所有几何运算使用双精度浮点数（f64），这在 Rust 中是默认的数值类型，但开发者需要警惕在与其他系统交互时的精度降级 —— 例如导出 STL 时，某些库会将其降为单精度。
其次，vcad 在 API 层面进行了精度隔离。函数签名明确区分了整数和浮点数参数：角度分段数使用 usize，而尺寸和位置使用 f64。这种区分不仅提高了类型安全性，还暗示了一个重要的工程原则：离散参数（如分辨率）应当与连续参数（如尺寸）在数值上分离管理。在螺栓阵列的示例中，环形半径和螺栓直径是浮点数，而螺栓数量是整数，这种分离使得参数扫描和敏感性分析更加清晰。
第三个精度控制策略是增量式求值与缓存。CSG 树的求值过程会沿着树结构自底向上进行，每个内部节点的结果会被缓存以避免重复计算。当用户修改单个参数时，只有受影响的那棵子树需要重新求值，其他分支的结果可以直接复用。这种设计不仅提升了性能，还减少了累积误差的机会 —— 因为每次求值都直接使用原始图元的参数，而非中间结果的近似值。
vcad 还特别处理了几何体的导出环节。STL 文件格式有两种变体：ASCII 和二进制。ASCII 格式便于调试但文件体积大，二进制格式紧凑但存在字节序问题。vcad 统一采用二进制 STL 导出，并在文件头部嵌入几何体的包围盒信息，以便下游工具快速验证模型的有效性。对于需要材质信息的场景，vcad 支持导出 glTF 格式，并使用 TOML 配置文件定义 PBR（基于物理的渲染）材质属性。这种多格式支持使得同一几何定义可以无缝对接 3D 打印、CAD 软件和实时渲染引擎。
面向 AI 代理的架构设计
vcad 的一个独特设计目标是支持 AI 编码代理。传统的 CAD 软件通过图形界面与人类交互，这种交互模式对代理而言是黑盒。vcad 将建模过程完全用代码表达，使得代理可以读取文档、生成几何、导出模型、导入 Blender、设置相机、渲染预览 —— 整个流程都在终端中完成，无需人类介入 GUI 操作。
这种设计对 API 提出了额外的要求：文档必须是机器可读的，错误信息必须指导代理进行修正，接口必须具有幂等性以支持重试。vcad 的 README 包含了完整的 API 表格、可复制粘贴的食谱式示例，以及与 Blender MCP 集成的说明。每个 API 都有明确的前置条件和后置条件描述，代理可以根据这些契约式信息构建正确的调用序列。类型系统在这里发挥了双重作用：一方面防止人类开发者犯错，另一方面为代理提供了静态的类型检查能力。
从实际效果来看，这种代理友好的设计显著缩短了设计迭代周期。代理可以在一次对话中完成多轮几何生成和渲染预览的循环，而传统工作流需要人类频繁切换上下文。vcad 的作者提到，本文中的所有渲染图都是由 Claude 代理使用 vcad 生成几何、导入 Blender、设置灯光后自动渲染的。这种人机协作模式可能预示着未来 CAD 工具的发展方向：几何引擎专注于可靠的数学计算，AI 代理处理设计探索和可视化，人类设计师专注于定义设计意图和验收标准。
工程参数与监控要点
如果要在生产环境中使用类似 vcad 的 CSG 引擎，以下几个参数值得特别关注。几何运算的分辨率参数决定了曲面的细分程度 —— 圆柱体的分段数直接影响其视觉光滑度和后续加工精度，通常 32 到 64 分段是合理的默认范围。布尔运算的容差参数控制多大间隙被认定为相交，这在处理薄壁结构时尤为关键。vcad 使用的 Manifold 引擎默认使用相对容差，但用户可以通过环境变量覆盖绝对容差阈值以适应特定打印机或加工设备。
导出流程中的单位转换也是常见的错误来源。vcad 使用毫米作为内部单位，但 STL 和 glTF 规范都不包含单位信息，这可能导致下游工具按米或英寸解释同一模型。建议在导出文件名中明确包含单位后缀，并在工程图中显式标注尺寸单位。对于涉及公差配合的机械零件，建议在 CSG 定义之外维护一张公差映射表，记录每对配合面的公差等级和配合性质。
版本控制是代码驱动 CAD 的天然优势。每个几何体的定义都是一段 Rust 代码，可以纳入 Git 版本控制。与二进制 STL 文件相比，文本形式的代码更容易进行差异比较和冲突合并。当发现设计缺陷时，可以使用 git bisect 快速定位引入问题的提交。对于团队协作，建议将常用的几何模式封装为库函数或宏，以保持不同设计之间的接口一致性。
vcad 目前处于 0.1 版本，核心功能已经稳定，但高级建模特性（如圆角、倒角、螺纹）仍在规划中。对于当前的参数化建模需求，vcad 已经提供了足够的表达能力：图元定义、布尔组合、变换操作、阵列复制。配合 Rust 的类型系统和包管理，这套工作流足以支撑从快速原型到可制造设计的完整链路。
参考资料
- vcad 项目主页与文档：https://vcad.io/、https://docs.rs/vcad
- Manifold 几何引擎：https://github.com/elalish/manifold