在 3D CAD 建模领域，传统交互式建模工具虽然直观，但难以满足需要批量生成变体、快速迭代设计的工程场景需求。CadQuery 作为一款开源 Python 库，通过将 CAD 建模过程抽象为可编程的脚本，使得模型具备版本可控、参数化驱动、无需图形界面的特性。本文将从参数化脚本 API 设计、布尔运算实现机制以及几何约束求解三个维度，深入解析 CadQuery 在工程实践中的应用要点。
参数化脚本 API 的设计哲学
CadQuery 的核心设计理念是将三维建模操作转化为链式方法调用，这一设计借鉴了函数式编程的流式接口思想。开发者无需关心底层几何引擎的复杂调用，只需在工作平面（Workplane）上依次描述建模意图即可。以创建一个带有通孔的方块为例，首先定义尺寸参数，然后通过链式调用完成模型构建：定义长度、宽度、高度作为 Python 变量，创建基准工作平面，绘制矩形轮廓后向上拉伸形成基体，接着选择顶面作为新工作平面，绘制圆形轮廓后向下切除形成通孔。整个过程清晰直观，参数修改后模型会自动重生。
工作平面的概念是 CadQuery 参数化能力的基石。当在三维空间中创建第一个基准平面后，后续的建模操作都可以相对于已有几何体的面、边或顶点展开。这种相对定位方式确保了当参数变化时，各特征之间的拓扑关系得以保持。例如，在一个板件上添加多个相同规格的螺钉孔，只需在一个孔的位置建模完成后，通过选择边或面的方式将孔特征复制到其他位置，修改孔径参数时所有孔会同步更新。这种基于设计意图而非绝对坐标的参数化方式，是 CadQuery 区别于传统 CAD 脚本编程的关键优势。
选择器（Selector）机制是实现相对定位的技术核心。CadQuery 提供了丰富的选择器语法，支持按方向（>Z 表示 Z 轴正向、<X 表示 X 轴负向）、按尺寸（>10 表示大于 10 毫米）、按标签（tag 方法命名的几何元素）等方式筛选面、边、顶点。复杂选择可以链式组合，如先选择顶面（faces (">Z")），再选择该面上的特定边（edges ("<X")），最后定位到边的端点（vertices ("<Y")），从而精确定位到模型的三维角落。这种递进式的选择机制，使得基于拓扑关系的参数化建模成为可能，同时也保证了模型在参数变化时的鲁棒性。
布尔运算的实现与性能优化
布尔运算是 CAD 建模的基础能力，CadQuery 基于 Open Cascade（OCCT）几何引擎提供了三种核心布尔操作：并集（union / 加法）、差集（cut / 减法）、交集（common / 相交）。这些操作既可以作为对象方法直接调用（如 result.cut (other)），也可以作为独立函数使用（如 cut (result, other)），灵活性很高。在参数化建模中，布尔运算通常用于组合多个建模特征，比如将多个拉伸体合并为一个整体，或者通过减法操作在实体上创建凹槽、通孔等特征。
实际工程应用中，布尔运算的性能是需要重点关注的因素。OCCT 底层在处理复杂布尔运算时计算量较大，尤其是在循环内部频繁执行布尔操作会显著影响脚本运行速度。针对这一痛点，CadQuery 最佳实践建议将多个待合并的形状预先组合为复合体，再进行最终的布尔运算。例如需要在一个面板上创建数十个相同孔位时，不应在循环中逐个执行 cut 操作，而是先将所有孔的轮廓统一拉伸为多个实体，然后一次性与面板进行差集运算。测试数据显示，这种优化策略在孔位数量超过二十个时，性能提升可达数倍。
另一个值得注意的技术细节是布尔运算的精度控制与容差处理。OCCT 引擎默认使用严格的几何求交算法，在处理共面或相切几何体时可能产生意外结果。CadQuery 提供了模糊布尔（Fuzzy Boolean）选项，通过设置容差值来容忍一定范围内的几何偏差，这在处理导入的外部几何数据或存在制造公差的模型时尤为实用。使用模糊布尔时需要谨慎设置容差数值，过大的容差可能导致边界表达不准确，过小则可能无法解决原本需要模糊处理的几何问题。
几何约束求解与装配应用
除了单一模型的参数化建模，CadQuery 还提供了装配（Assembly）功能，支持将多个零件组合并施加几何约束进行求解。在装配场景中，零件之间的相对位置不再依赖硬编码的坐标数值，而是通过约束条件定义。约束类型包括平面贴合（Plane）、轴线对齐（Axis）、点在线上（PointOnLine）、点距固定（PointDistance）等，覆盖了工程装配中的常见定位需求。
约束求解的典型工作流程是：首先为需要参与约束的几何元素打标签（tag 方法），然后定义约束关系，最后调用 solve 方法求解满足所有约束的零件配置。例如在面板上装配把手组件，可以将面板的特定面和把手的配合面分别标记为 panel_mate 和 handle_mate，添加 Plane 约束使两者贴合，再添加 Axis 约束使把手的安装孔与面板上的定位销对齐，最后求解得到精确的装配位置。这种基于约束的装配方式，使得产品变体设计变得简单：只需修改约束参数或替换零件，自动化流程即可生成新的装配结果。
需要指出的是，CadQuery 的约束求解能力相较于专业 CAD 软件的装配模块仍有差距，目前更适合简单装配或标准化组件的快速组合。对于复杂装配关系或多自由度机构运动仿真等专业场景，仍需借助商业 CAD 软件的装配功能。但在大批量标准化零件的参数化生成、自动化 BOM 输出、工程图标注等场景下，CadQuery 的约束机制已经足够实用。
工程落地的关键参数与监控要点
将 CadQuery 应用于实际工程项目时，有几个关键参数值得特别关注。首先是默认精度设置，OCCT 引擎的工作精度直接影响布尔运算的成功率和模型质量，对于精密制造相关模型，建议将精度设置为 1e-6 量级，并在导入外部 STEP 或 STL 文件时明确检查公差匹配情况。其次是缓存机制，CadQuery 默认会缓存中间计算结果以加速重复渲染，但在参数化脚本调试阶段，频繁修改参数后应手动清除缓存或使用 reload 选项，避免旧结果干扰调试判断。
模型导出环节需要根据下游用途选择合适格式。STEP 格式保留完整的边界表达（B-Rep）数据，适合继续在 CAD 软件中编辑；STL 格式则是 3D 打印的事实标准，但仅包含三角面片近似，精度损失不可避免。对于需要直接用于制造的场景，建议在导出前增加模型合法性检查，包括体积非零、闭合实体、无自交等基本验证，这些检查可以通过 CadQuery 的 isValid、isClosed 等方法实现。
从工程管理角度，CadQuery 模型文件的版本控制优势不容忽视。由于模型以纯 Python 代码形式存储，天然支持 Git 等版本管理工具的差异比对，配合 CI/CD 流水线还可以实现模型的自动化回归测试 —— 每次代码提交后自动生成标准视角渲染图或导出文件，与基准版本进行像素级或文件级对比，确保参数修改未引入意外变更。
综合来看，CadQuery 为 Python 开发者提供了一条低门槛进入 3D CAD 建模的路径，其参数化脚本 API 设计体现了现代工程工具的抽象层次提升。在需要批量生成设计变体、集成到自动化生产线或构建参数驱动的设计流程时，CadQuery 值得作为技术选型的重要参考。
资料来源：CadQuery 官方文档（https://cadquery.readthedocs.io/）