CadQuery程序化建模实战：从参数化设计到自动化机械建模-平芜编程栈

1. 从手动到程序化：为什么我们需要CadQuery？

如果你和我一样，在机械设计、3D打印或者产品原型开发领域摸爬滚打了好些年，一定经历过这样的场景：客户发来一个需求变更，要求把某个零件的孔径从5mm改成5.5mm，或者把外壳的壁厚从2mm增加到2.5mm。你打开熟悉的桌面建模软件，找到那个特征，修改参数，然后发现——整个模型报错了。一堆父子关系、约束冲突、布尔运算失败的红叉叉，让你瞬间血压升高。你不得不花上半小时甚至更久，去回溯、修复、重建，只为这一个看似简单的改动。这种“牵一发而动全身”的脆弱性，是传统交互式建模（比如SolidWorks, Fusion 360, FreeCAD的图形界面）难以避免的痛点。

这就是程序化建模（Procedural Modeling）要解决的核心问题。它把建模过程从鼠标点击，变成了编写代码。你定义的不是一个静态的几何体，而是一系列生成几何体的规则和逻辑。CadQuery，正是这个领域里一个强大而优雅的Python库。它不像OpenSCAD那样使用一种独特的函数式语言，而是让你直接用Python这门通用语言来“描述”你的模型。这意味着你可以利用Python的所有能力：循环、条件判断、函数封装、模块化、甚至调用NumPy进行复杂计算，来构建你的三维设计。

“33个CadQuery程序化建模实例”这个标题，背后指向的正是无数工程师、创客和设计师最迫切的需求：如何快速上手，并真正将程序化建模的威力应用到实际工作中？光知道“CadQuery很强大”没用，我们需要看到它在具体场景下是如何被使用的，从最简单的垫圈到复杂的有机形态，从参数化齿轮到可装配的结构。这些实例就是最好的路线图，它们展示了从想法到代码，再从代码到可制造模型的完整路径。接下来，我将结合常见的工程实践，为你拆解CadQuery的核心魅力、学习路径，并通过几个典型实例的深度剖析，让你不仅能“抄作业”，更能理解背后的设计哲学，从而创造出属于自己的程序化模型。

2. CadQuery核心工作流与思想基石

在深入实例之前，我们必须先统一思想。CadQuery的建模方式与图形界面有本质不同，理解其核心工作流和两个关键概念，是写出健壮、可维护代码的基础。

2.1 构建-选择-修改（Build-Select-Modify）流水线

这是CadQuery最核心的工作模式，几乎所有的操作都遵循这个三步循环：

构建（Build）：创建一个基础的几何体。比如一个长方体（cq.Workplane().box）、一个圆柱（cq.Workplane().cylinder）或者通过拉伸（extrude）、旋转（revolve）一个二维草图来生成。
选择（Select）：在当前的几何体上，指定你要操作的面、边或顶点。这是CadQuery非常强大的一点，你可以通过面法向、边类型、坐标位置等多种方式精确选择几何元素。例如，faces(“>Z”)选择Z轴正方向的面，edges(“|Z”)选择平行于Z轴的边。
修改（Modify）：对选中的几何元素进行操作。比如在选中的面上打孔（cboreHole）、对选中的边进行倒角（chamfer）或圆角（fillet）、将选中的面进行拉伸切割（cutBlind）等。

完成一次“修改”后，你通常会得到一个新的几何体，然后可以在此基础上开始新一轮的“选择-修改”。这种模式使得建模过程像搭积木一样清晰、可预测。一个典型的代码片段看起来是这样的：

import cadquery as cq # 1. 构建：创建一个底板 result = cq.Workplane(“XY”).box(100, 60, 10) # 2. 选择 & 3. 修改：在底板顶部中央打一个通孔 result = result.faces(“>Z”).workplane().hole(20) # 新一轮选择与修改：对顶面的四条边进行圆角 result = result.edges(“|Z”).fillet(5)

2.2 工作平面（Workplane）的绝对核心地位

工作平面是CadQuery中所有2D草图绘制的画布，也是3D操作的基准平面。你可以把它想象成建模软件里那个可以移动和旋转的坐标系网格。理解并熟练操控工作平面，是解锁复杂建模的关键。

创建与定位：cq.Workplane(“XY”)创建在全局XY平面上的工作平面。你可以使用workplane(offset=10)来在Z方向偏移10mm，或者用workplane(center=(x, y, z), dir=(dx, dy, dz))来任意定位和定向工作平面。
草图绘制：在工作平面上，你可以使用circle,rect,polygon,lineTo,spline等方法绘制二维图形，这些图形构成了后续拉伸、旋转操作的基础。
上下文传递：当你通过faces(“>Z”).workplane()在一个模型表面上创建新的工作平面时，这个新平面不仅位置在该表面，其原点（origin）也通常位于该表面的中心或某个特征点上，这为后续的精准定位操作提供了极大便利。

实操心得：很多初学者卡住的地方，往往是对工作平面的状态理解不清。我的建议是，在编写复杂步骤时，可以尝试用result.val().Center()打印出当前实体的中心坐标，或者用临时导出STEP/STL的方式可视化中间步骤，来验证工作平面是否如你预期的那样定位。养成“每完成一个关键操作，心里都清楚当前工作平面在哪”的习惯，能避免大量后续的定位错误。

3. 实例深度解析：从简单零件到设计模式

“33个实例”涵盖的范围可能很广，我们可以将其归类，并选取每一类中有代表性的进行深度剖析，重点讲解其实现逻辑和可复用的设计模式。

3.1 基础形状与参数化：一个可配置的散热鳍片

这是理解参数化威力的最佳起点。假设我们要创建一个CPU散热器的鳍片，其高度、厚度、间距、数量都应可调。

import cadquery as cq def create_fin(height, thickness, spacing, count, base_width, base_length, base_height): """ 创建一组散热鳍片。 参数: height: 鳍片高度 thickness: 鳍片厚度 spacing: 鳍片之间的间隙 count: 鳍片数量 base_width: 底座宽度 base_length: 底座长度 base_height: 底座高度 """ # 1. 创建底座 heat_sink = cq.Workplane(“XY”).box(base_length, base_width, base_height) # 2. 计算第一个鳍片的起始位置 total_width = count * thickness + (count - 1) * spacing start_x = -total_width / 2 + thickness / 2 # 3. 循环创建每一个鳍片 for i in range(count): fin_x = start_x + i * (thickness + spacing) # 在工作平面上定位，并创建一个鳍片（简单长方体） fin = cq.Workplane(“XY”).transformed(offset=(fin_x, 0, base_height/2)).box(thickness, base_width, height) # 使用union()将鳍片合并到底座上 heat_sink = heat_sink.union(fin) return heat_sink # 使用函数生成模型 my_heat_sink = create_fin(height=30, thickness=2, spacing=3, count=10, base_width=40, base_length=50, base_height=5)

核心要点与扩展：

参数驱动：所有尺寸都来源于函数参数。只需修改参数值，就能瞬间生成不同规格的散热器，无需重画。
数学计算定位：通过total_width和start_x的计算，实现了鳍片的自动居中排列。这是程序化建模的典型思维：用算法解决几何布局问题。
循环结构：for循环是批量创建特征的神器。这在创建阵列孔、栅格、纹理表面时极其常用。
布尔运算：union()用于合并实体。与之对应的还有cut()（切割）和intersect()（交集）。确保进行布尔运算的实体在空间上有交集。

避坑指南：在进行大量循环布尔运算（尤其是union）时，模型可能会变得复杂，导致预览或导出变慢。对于非常规则的大量阵列（如上百个鳍片），可以考虑先创建一个“单元”，然后使用CadQuery的polarArray或rectArray方法，这些方法在内部可能进行了优化。另外，在循环中频繁调用.union()可能会产生历史树冗余，对于超大规模阵列，更高级的做法是使用cq.Assembly来管理，或者将阵列逻辑用cq.Solid直接构造。

3.2 二维草图与复杂轮廓：一个异形扳手头

很多零件不是简单的基本体堆砌，而是由复杂的二维轮廓拉伸而成。CadQuery的草图能力非常灵活。

import cadquery as cq def create_wrench_head(outer_dia, inner_dia, flat_distance, thickness): """ 创建一个双开口扳手头。 参数: outer_dia: 扳手头外圆直径 inner_dia: 内孔（驱动孔）直径 flat_distance: 两个平行平面的距离（开口尺寸） thickness: 扳手头厚度 """ # 1. 在工作平面上开始绘制草图 profile = (cq.Workplane(“XY”) .center(0, 0) # 确保原点在中心 # 先画一个代表外轮廓的大圆 .circle(outer_dia / 2) # 再画一个代表内孔的小圆，它会自动被“剪掉”（因为后续操作） .circle(inner_dia / 2) # 现在，用两个矩形来切割出平行平面部分。 # 第一个矩形切掉上半部分，留下 flat_distance/2 的高度 .rect(outer_dia * 1.5, outer_dia - flat_distance, centered=False) .translate((0, flat_distance / 2)) # 将矩形移动到切割位置 .cutThruAll() # 执行切割 # 注意：cutThruAll()之后，工作对象变了。我们需要重新选择最开始的平面。 ) # 上面的写法在连续cut时容易出错，更稳健的做法是分别构建切割工具 # 让我们换一种更清晰的思路： # 先创建一个实心的圆盘 wrench = cq.Workplane(“XY”).circle(outer_dia / 2).extrude(thickness) # 切割出内六角孔（这里简化为圆孔） wrench = wrench.faces(“>Z”).workplane().circle(inner_dia / 2).cutThruAll() # 创建切割平行面的工具（一个足够大的长方体） cutter = cq.Workplane(“XY”).rect(outer_dia * 2, (outer_dia - flat_distance) / 2).extrude(thickness * 2) # 将切割工具移动到上方进行切割 wrench = wrench.cut(cutter.translate((0, flat_distance / 2, 0))) # 将切割工具移动到下方进行切割 wrench = wrench.cut(cutter.translate((0, -flat_distance / 2, 0))) return wrench # 生成一个M10扳手头（假设尺寸） wrench_m10 = create_wrench_head(outer_dia=19, inner_dia=10, flat_distance=16, thickness=8)

核心要点与扩展：

草图顺序：在同一个.Workplane()上连续调用.circle().rect()等，这些图形会形成一个“待处理”的轮廓集合。后续的.extrude()或.cutThruAll()会如何处理它们，取决于具体方法。通常，第一个图形是“加法”基础，后续图形可能是“减法”或“交集”。逻辑一定要清晰。
稳健的切割策略：当切割逻辑复杂时，像上面第二种方法那样，显式地创建切割工具（cutter）并进行布尔运算（cut），往往比在草图里连续进行切割操作更清晰、更不容易出错。这尤其适用于切割工具本身需要复杂定位的情况。
cutThruAllvscutBlind：cutThruAll()会沿着工作平面法向穿透整个实体，而cutBlind(depth)只切割指定的深度。根据需求选择。

3.3 高级选择与特征操作：一个带圆角和异形孔的壳体

模型的美观和实用性往往体现在细节上，比如圆角、倒角和各类异形孔。

import cadquery as cq def create_enclosure_with_details(length, width, height, wall_thickness, corner_radius, hole_pattern): """ 创建一个带圆角、安装孔和散热孔的壳体。 参数: hole_pattern: 一个列表，包含散热孔的中心坐标，如 [(x1,y1), (x2,y2), ...] """ # 1. 创建外壳实体 outer_box = cq.Workplane(“XY”).rect(length, width).extrude(height) # 2. 创建内腔实体（用于掏空） inner_box = (cq.Workplane(“XY”) .rect(length - 2*wall_thickness, width - 2*wall_thickness) .extrude(height - wall_thickness) # 底部留一个壁厚 .translate((0, 0, wall_thickness)) # 将内腔向上偏移一个壁厚，形成底部 ) enclosure = outer_box.cut(inner_box) # 3. 为外壳顶边添加圆角（选择所有顶部的边） # 注意：先抽壳后倒角是更符合制造逻辑的顺序 enclosure = enclosure.edges(“|Z”).fillet(corner_radius) # 4. 添加底部安装孔（沉头孔） # 假设在底板四个角附近打孔 mount_locations = [ (length/2 - 10, width/2 - 10), (length/2 - 10, -width/2 + 10), (-length/2 + 10, width/2 - 10), (-length/2 + 10, -width/2 + 10) ] for loc in mount_locations: enclosure = (enclosure.faces(“<Z”) # 选择底板下表面 .workplane(centerOption=“CenterOfMass”) .center(loc[0], loc[1]) # 将工作平面中心移动到打孔位置 .cboreHole(3, 6, 4) # 直径3mm通孔，沉头直径6mm，深度4mm ) # 5. 添加侧面散热孔阵列 if hole_pattern: # 选择壳体的一个侧面（例如+X面）来打孔 # 我们需要找到这个面。一种方法是选择所有法向指向X正方向的面，并过滤出位置合适的。 # 更简单的方法：创建一个工作平面在侧面。 side_plane = cq.Workplane(“YZ”).transformed(offset=(length/2, 0, height/2), rotate=(90, 0, 0)) for hole_loc in hole_pattern: # hole_loc 是相对于侧面中心的 (y, z) 坐标 hole = side_plane.center(hole_loc[0], hole_loc[1]).circle(2).extrude(-wall_thickness) enclosure = enclosure.cut(hole) return enclosure # 定义散热孔位置（简单网格） holes = [] for y in range(-15, 20, 10): # Y方向从-15到15，间隔10 for z in range(10, 40, 8): # Z方向从10到35，间隔8 holes.append((y, z)) my_case = create_enclosure_with_details(100, 60, 40, 2, 5, holes)

核心要点与扩展：

选择器语法：edges(“|Z”)选择了所有平行于Z轴的边，也就是竖直边。faces(“<Z”)选择了法向指向Z轴负方向的面，即底面。熟练掌握>,<,|,#（和轴垂直）这些选择器，能让你精准定位模型特征。
顺序的重要性：通常，先进行主要的布尔运算（如掏空），再进行细节特征操作（如倒角、圆角）。如果顺序颠倒，圆角可能因为后续的切割而变得不完整或报错。
复杂定位：对于非标准位置的特征（如侧面孔），手动创建和定位工作平面（side_plane）比依赖自动选择器有时更可靠。transformed(offset=..., rotate=...)给了你完全的控制权。
cboreHole的便利性：这个方法一次性创建了沉头孔，包括通孔和沉头部分，非常适合机械设计。

4. 超越基础：装配体、曲线与性能优化

当33个实例覆盖了基础操作后，我们必然会走向更复杂的应用场景。

4.1 使用Assembly管理多个零件

真正的设计往往包含多个相互关联的零件。CadQuery的Assembly功能允许你将多个独立的Workplane对象组合在一起，并指定它们的约束关系（虽然约束求解能力相对简单，但用于静态展示和相对定位非常有用）。

import cadquery as cq from cadquery import Assembly # 假设我们有两个零件：一个轴和一个齿轮（简化版） def create_shaft(diameter, length): return cq.Workplane(“XY”).circle(diameter/2).extrude(length) def create_gear(pitch_dia, thickness, hole_dia): gear = cq.Workplane(“XY”).circle(pitch_dia/2).extrude(thickness) gear = gear.faces(“>Z”).workplane().circle(hole_dia/2).cutThruAll() # 这里可以添加齿廓，简化起见我们跳过 return gear shaft = create_shaft(10, 50) gear = create_gear(40, 8, 10.2) # 孔略大于轴，表示过盈或间隙配合 # 创建装配体 assy = Assembly() # 添加零件，并给它们命名 assy.add(shaft, name=“Shaft”, loc=cq.Location((0,0,0))) # 将齿轮装配到轴上，位置在轴的一端 assy.add(gear, name=“Gear”, loc=cq.Location((0,0,25))) # 假设轴从z=0到z=50，齿轮在中间 # 可以输出装配体为STEP，很多CAD软件可以识别其中的多个零件 # cq.exporters.export(assy, ‘gear_assembly.step’)

核心要点：Assembly主要用于视觉上的组合和导出。对于需要动态模拟干涉检查或运动关系的复杂装配，可能需要借助外部库或更专业的参数化CAD内核（如OpenCASCADE的更高阶用法）。

4.2 样条曲线与空间曲线建模

对于有机形态或流体动力学造型，需要用到样条曲线（Spline）。CadQuery支持通过点列表来创建样条，并沿其进行扫描（sweep）。

import cadquery as cq import numpy as np def create_bottle_silo(height, diameter, neck_ratio): """ 创建一个类似酒瓶的筒仓状模型，使用样条曲线定义轮廓。 """ # 定义轮廓关键点 (x, y)，x是半径，y是高度 points = [ (0, 0), # 底部中心 (diameter/2, 0), # 底部边缘 (diameter/2 * 0.9, height*0.2), # 略微收腰 (diameter/2 * neck_ratio, height*0.8), # 颈部开始 (diameter/2 * neck_ratio, height), # 颈部顶端 (0, height) # 顶部中心（闭合） ] # 在工作平面上绘制样条轮廓，然后旋转 profile = cq.Workplane(“XZ”).spline(points).close() # 绕Z轴旋转360度形成实体 silo = profile.revolve(360, (0,0,0), (0,0,1)) return silo my_silo = create_bottle_silo(100, 40, 0.4)

核心要点：spline()函数接受一个点列表。close()方法将开放的样条曲线首尾相连，形成闭合轮廓，这是进行旋转或拉伸操作的前提。通过精心设计点列表，你可以创建出非常复杂的自由曲面轮廓。

4.3 大规模建模的性能考量与代码组织

当模型变得极其复杂（例如，成百上千个特征）时，性能和代码可维护性成为挑战。

性能：
- 减少历史操作：CadQuery会记录操作历史。对于最终确定不再修改的复杂子部件，可以考虑将其转换为单纯的cq.Solid（使用.val()获取），后续操作基于这个Solid进行，可以减少历史树深度。
- 简化选择：避免使用过于宽泛或复杂的选择器（如edges()不带过滤器），这可能导致内部遍历所有边，速度变慢。尽量使用精确的选择器（faces(“>Z”),edges(“#XY”)）。
- 批量操作：对于完全相同的特征阵列，如果CadQuery内置的polarArray或rectArray能满足，优先使用它们，而不是Python循环。内置方法可能经过优化。
代码组织：
- 函数化：将重复的功能（如创建标准孔、加强筋、卡扣）封装成函数。如上文的create_fin,create_wrench_head。
- 类与参数对象：对于非常复杂的零件，可以定义一个类，将尺寸参数作为属性，将建模步骤作为方法。或者使用dataclass或SimpleNamespace来集中管理所有参数。
- 配置文件：将尺寸参数保存在JSON或YAML文件中，使设计与配置数据分离，便于版本管理和多方案比较。
- 模块化：将通用零件（如螺栓、轴承、型材断面）放在独立的.py文件中，通过import引用。

5. 从实例到创造：构建你自己的程序化零件库

学习“33个实例”的终极目的，不是记住33段代码，而是掌握一种思维方式和工具集，从而能够独立地将任何设计想法转化为参数化模型。我建议的学习和实践路径是：

临摹与修改：找几个最贴近你工作领域的实例，逐行读懂，然后在你的环境中运行。尝试修改每一个参数，观察模型如何变化。这是建立直觉最快的方式。
分解与重组：选择一个稍复杂的实例，尝试在不看代码的情况下，用语言描述出它的建模步骤（例如：“首先，创建一个长方体作为底座；然后，在底座顶部中央挖一个圆柱孔；接着，在底座四角添加带圆角的支柱…”）。然后，尝试自己用CadQuery实现这个描述。最后对比原代码，学习别人的实现技巧。
解决真实问题：从你手头一个简单的、参数化的需求开始。比如，一个需要适配不同螺丝长度的支架，一个可以调整格子数量的散热栅板。用CadQuery把它实现出来。遇到问题就去查文档、看源码或者社区求助。
抽象与封装：当你发现某些功能（比如创建各种标准孔、生成蛇形管道、构建散热齿）反复使用时，就是将它们封装成函数或类的时候了。逐渐地，你就会积累起属于你自己的、高度定制化的“程序化建模零件库”。

程序化建模的真正魅力在于“一次编写，随处生成”。当你用代码定义好一个变速箱外壳、一个无人机机架或一个定制化键盘底座后，这些设计就变成了活的、可随时调整的资产。版本控制（如Git）可以完美管理设计迭代，任何修改都有迹可循。设计与分析（如有限元分析、流体仿真）的边界也变得模糊，因为你可以直接从同一个参数源生成用于仿真的简化模型。

最后，一个非常实用的建议：将CadQuery与Jupyter Notebook结合使用。Notebook的交互式特性（分段执行代码、实时显示模型）对于探索性建模和调试来说是无价之宝。你可以边写代码边看结果，快速迭代你的想法。当你完成设计后，直接将Notebook导出为PDF或HTML，它就是一份完整的设计文档，包含了所有逻辑和最终模型。这，或许就是未来工程师的工作方式。