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(offset10)来在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(height30, thickness2, spacing3, count10, base_width40, base_length50, base_height5)核心要点与扩展参数驱动所有尺寸都来源于函数参数。只需修改参数值就能瞬间生成不同规格的散热器无需重画。数学计算定位通过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, centeredFalse) .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_dia19, inner_dia10, flat_distance16, thickness8)核心要点与扩展草图顺序在同一个.Workplane()上连续调用.circle().rect()等这些图形会形成一个“待处理”的轮廓集合。后续的.extrude()或.cutThruAll()会如何处理它们取决于具体方法。通常第一个图形是“加法”基础后续图形可能是“减法”或“交集”。逻辑一定要清晰。稳健的切割策略当切割逻辑复杂时像上面第二种方法那样显式地创建切割工具cutter并进行布尔运算cut往往比在草图里连续进行切割操作更清晰、更不容易出错。这尤其适用于切割工具本身需要复杂定位的情况。cutThruAllvscutBlindcutThruAll()会沿着工作平面法向穿透整个实体而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”, loccq.Location((0,0,0))) # 将齿轮装配到轴上位置在轴的一端 assy.add(gear, name“Gear”, loccq.Location((0,0,25))) # 假设轴从z0到z50齿轮在中间 # 可以输出装配体为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它就是一份完整的设计文档包含了所有逻辑和最终模型。这或许就是未来工程师的工作方式。 
长河君 · 2026/8/26 23:46:27 · 阅读 1.2k 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(offset10)来在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(height30, thickness2, spacing3, count10, base_width40, base_length50, base_height5)核心要点与扩展参数驱动所有尺寸都来源于函数参数。只需修改参数值就能瞬间生成不同规格的散热器无需重画。数学计算定位通过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, centeredFalse) .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_dia19, inner_dia10, flat_distance16, thickness8)核心要点与扩展草图顺序在同一个.Workplane()上连续调用.circle().rect()等这些图形会形成一个“待处理”的轮廓集合。后续的.extrude()或.cutThruAll()会如何处理它们取决于具体方法。通常第一个图形是“加法”基础后续图形可能是“减法”或“交集”。逻辑一定要清晰。稳健的切割策略当切割逻辑复杂时像上面第二种方法那样显式地创建切割工具cutter并进行布尔运算cut往往比在草图里连续进行切割操作更清晰、更不容易出错。这尤其适用于切割工具本身需要复杂定位的情况。cutThruAllvscutBlindcutThruAll()会沿着工作平面法向穿透整个实体而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”, loccq.Location((0,0,0))) # 将齿轮装配到轴上位置在轴的一端 assy.add(gear, name“Gear”, loccq.Location((0,0,25))) # 假设轴从z0到z50齿轮在中间 # 可以输出装配体为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它就是一份完整的设计文档包含了所有逻辑和最终模型。这或许就是未来工程师的工作方式。