在 Python 生态中，代码驱动的 CAD 建模长期依赖 OpenSCAD 作为事实标准。然而，OpenSCAD 自有的脚本语言与 Python 生态之间存在明显隔阂 —— 开发者无法直接使用 Python 的类型系统、循环结构或第三方库来增强建模能力。build123d 作为新一代基于 Python 的参数化 CAD 库，正是为了解决这一痛点而设计。它构建于 Open Cascade 几何内核之上，提供纯 Pythonic 的建模接口，同时保留 OpenSCAD「代码即模型」的设计哲学。

核心设计理念：双重建模范式

build123d 最具特色的设计在于它同时支持两种建模模式，开发者可以根据建模任务的复杂度灵活选择。这种「双轨制」设计在 CAD 编程库中较为罕见，却极大地提升了库的通用性。

第一种模式称为 Builder 模式，它采用 Python 上下文管理器（context manager）来管理建模状态的隐式传递。所有的几何操作在 with 语句块内完成，开发者无需显式传递中间对象，代码可读性接近自然语言描述。第二种模式称为 Algebra 模式，它完全摒弃状态管理，通过运算符重载实现无状态的链式调用，每一步操作都直接返回新的几何对象。这两种模式并非互斥，实际项目中经常混用 ——Builder 模式适合构建整体形状，Algebra 模式适合做局部变换与组合。

Builder 模式：上下文管理器驱动的分层建模

Builder 模式是 build123d 最具辨识度的 API 设计。它借鉴了设计模式中的 Builder 概念，通过嵌套的上下文管理器来实现几何对象的层次化构造。核心构建器包括三类：BuildPart 用于创建三维实体，BuildSketch 用于创建二维草图，BuildLine 用于创建一维线条。

以一个带圆角的矩形板为例，使用 Builder 模式编写如下：

from build123d import *

with BuildPart() as plate:
    with BuildSketch() as sketch:
        Rectangle(width=100, height=60)
        fillet(sketch.vertices(), radius=8)
    extrude(amount=10)
    fillet(plate.edges(), radius=3)

这段代码的语义极为清晰：首先创建一个草图，在其中绘制矩形并对顶点做圆角处理，然后拉伸为三维实体，最后对所有边进行圆角。关键在于，内部的 fillet 操作无需显式传递草图对象 —— 上下文管理器自动维护了当前工作平面的状态。官方文档将这种设计称为「隐式构建器实例变量」，它显著降低了复杂模型的编码负担。

在更复杂的场景中，Builder 模式支持多层嵌套。例如创建茶杯模型时，可以在 BuildPart 中嵌套 BuildSketch 绘制截面轮廓，再嵌套 BuildLine 绘制把手路径，最后通过 sweep 命令沿路径扫掠生成实体。整个过程保持了清晰的缩进层级关系，代码结构与模型结构一一对应。

Builder 模式的另一个优势在于「延迟计算」。几何对象的最终形状只有在上下文管理器退出时才会完整计算，这为参数化建模提供了天然的支持 —— 开发者只需在脚本顶部定义变量，修改参数后重新运行即可获得更新后的模型。

Algebra 模式：无状态的运算符驱动建模

与 Builder 模式的状态化设计不同，Algebra 模式追求完全的无状态化。它通过在几何对象上定义运算符（+、-、*、@ 等）来实现类似数学表达式的链式调用。这种模式适合需要频繁组合、变换几何对象的场景，尤其是在算法化生成复杂结构时。

在 Algebra 模式中，位置与变换通过乘法运算符实现。例如将一个立方体移动到特定位置并旋转：

from build123d import *

box = Box(40, 30, 20)
transformed = Plane.XZ * Pos(x=50, y=20) * Rot(z=45) * box

这里 Plane.XZ 定义了工作平面，Pos 和 Rot 分别表示平移和旋转，运算符 * 将它们组合为复合变换并作用于原始立方体。类似地，几何对象的布尔运算也通过 +（并集）、-（差集）、%（交集）来实现：

combined = box_a + box_b - cylinder_hole

Algebra 模式的核心优势在于它完全兼容 Python 的函数式编程范式。开发者可以将几何变换封装为函数，用 map、filter 等高阶函数批量处理一组对象，甚至将几何对象作为数据在管道中传递。这种表达能力是 OpenSCAD 原始脚本语言难以企及的。

参数化建模的工程实践

在实际工程中，参数化建模的核心挑战并非语法，而是如何组织参数与模型之间的关系。build123d 官方文档总结了若干最佳实践，可作为工程落地的参考。

首先是「先 2D 后 3D」原则。build123d 的几何内核基于 BREP（边界表示法），二维草图是创建复杂三维实体的基础。开发者应优先在 BuildSketch 中完成截面轮廓的绘制与编辑，再通过 extrude、revolve 或 loft 等操作生成三维几何。这不仅符合传统 CAD 软件的工作流程，也能充分利用 BuildSketch 提供的顶点与边选择器。

其次是「延迟圆角」原则。圆角与倒角操作应当放在建模流程的最后阶段执行。过早添加圆角可能导致后续布尔运算失败，因为圆角面的存在会增加几何求交的复杂度。正确的做法是先用锐边完成所有拉伸、切除、挖孔操作，最后再对需要平滑的边统一应用 fillet 或 chamfer。

第三是「参数集中管理」原则。所有可调参数应集中在脚本顶部统一赋值，使用有意义的变量命名，并配合 Python 类型提示（build123d 提供完整的 mypy 类型注解）。当需要批量生成系列化零件时，只需修改参数值并重新运行脚本即可。

与 OpenSCAD 的对比与迁移路径

对于已有 OpenSCAD 使用经验的团队，build123d 提供了平滑的迁移路径。官方文档专门章节讨论了从 OpenSCAD 到 build123d 的转换策略：核心区别在于 OpenSCAD 采用纯 CSG（构造实体几何）模型，而 build123d 基于 Open Cascade 的 BREP 内核，这意味着后者支持更丰富的几何类型与更精确的拓扑查询。

在 API 层面，OpenSCAD 的 translate、rotate、difference 等函数在 build123d 中都有对应实现，只是语法形式从函数调用变成了上下文管理器或运算符。build123d 还提供了 ocp_vscode 扩展，允许在 VS Code 中实时预览模型，进一步提升了开发体验。

小结

build123d 通过 Builder 模式与 Algebra 模式的双轨设计，成功在 Python 生态中实现了兼具可读性与表达力的参数化 CAD 编程。其基于 Open Cascade 的 BREP 内核保证了模型的精度与互操作性，而对 Python 语言的深度集成则让开发者能够充分利用 Python 的类型系统、控制流与生态工具。对于需要在 Python 项目中集成 CAD 建模能力的团队，build123d 提供了可靠的技术选型。

参考资料