1. 项目概述从手动到程序化的建模思维跃迁如果你和我一样在机械设计、3D打印或者产品原型开发领域摸爬滚打多年一定经历过这样的场景客户一个微小的设计变更比如把某个孔的直径从5mm改成5.5mm或者把加强筋的厚度增加0.2mm你就得在传统的CAD软件比如SolidWorks、Fusion 360里重新定位草图、修改尺寸、重建特征运气不好还会遇到特征失败需要花大量时间排查和修复父子关系。这种基于历史树和图形界面的建模方式在快速迭代和参数化驱动设计时效率瓶颈非常明显。这正是“程序化建模”要解决的核心痛点。而CadQuery正是这个领域里一个强大且优雅的解决方案。它不是一个带图形界面的软件而是一个基于Python的库。你通过编写Python代码来“描述”你的三维模型每一个尺寸、每一个特征、每一次布尔运算都是一行清晰、可复用的代码。这次分享的“33个CadQuery程序化建模实例”就是一套从零到一、由浅入深的实战指南。它不仅仅是33个孤立的模型文件更是一套思维训练教你如何用程序员的逻辑去思考和构建三维实体将设计意图从鼠标点击转化为可版本控制、可参数驱动、可批量生成的代码。这套实例的价值在于它覆盖了从基础几何体创建、二维草图绘制与约束到复杂特征操作如放样、扫掠、阵列、再到装配体管理和工程图导出的完整工作流。无论你是想自动化生成一批规格相似的零件还是构建一个高度参数化的产品族亦或是将设计流程无缝集成到你的CI/CD持续集成/持续部署流水线中这33个实例都能为你提供坚实的脚手架和灵感来源。接下来我将为你深度拆解这套实例背后的核心逻辑、关键技术点并分享我在实际应用中踩过的坑和总结出的高效技巧。2. 核心设计思路与CadQuery工作流解析2.1 为何选择CadQuery超越OpenSCAD的现代选择在程序化建模领域OpenSCAD是许多人的入门选择。它语法简单专注于CSG构造实体几何建模。然而当模型变得复杂尤其是涉及复杂曲线、曲面或需要与外部数据如Excel表格、数据库交互时OpenSCAD的局限性就显现出来了其自定义函数语言表达能力有限调试困难缺乏成熟的生态系统。CadQuery则站在了Python这个“巨人的肩膀”上。选择CadQuery意味着你获得了完整的Python生态你可以直接使用NumPy进行数值计算用Pandas处理表格数据用Matplotlib进行可视化预览甚至用Flask或FastAPI搭建一个在线的参数化设计Web服务。基于边界表示B-Rep的建模内核CadQuery底层依赖于OCCTOpen CASCADE Technology内核这与主流商业CAD软件如CATIA, SolidWorks同源。这意味着它能创建和操作非常复杂的曲面支持圆角、倒角、抽壳等高级特征并且模型精度高可直接用于工程分析和制造。链式调用Fluent APICadQuery的API设计非常人性化支持链式调用。这使得代码读起来就像是在用英语描述建模步骤“从一个矩形开始把它拉伸成实体然后在顶面上打一个孔最后把所有的边倒圆角”。这种流畅性大大提升了代码的可读性和编写效率。无缝的2D草图工作流通过cqgiCadQuery Geometry Interface模块你可以像在传统CAD中一样先绘制带有几何约束和尺寸约束的二维草图再将其拉伸或旋转成三维实体。这是构建参数化模型的基石。这套“33个实例”正是基于这些优势构建的它引导你从最简单的box()、cylinder()命令开始逐步过渡到复杂的草图约束和特征组合最终实现一个完全由代码驱动的、灵活可调的设计系统。2.2 程序化建模的通用工作流框架无论构建什么模型一个清晰的程序化建模工作流都包含以下几个阶段这33个实例也暗含了这条主线参数定义与初始化将所有驱动模型的变量如长度、直径、角度、数量在代码开头明确定义。这是实现参数化的第一步。好的实践是使用Python字典或数据类来分组管理参数。基础几何创建创建最原始的三维实体立方体、圆柱体、球体或二维草图的基本几何元素线段、圆弧、样条曲线。草图构建与约束对于复杂形状使用cqgi绘制二维轮廓。关键在于添加几何约束水平、垂直、相切、同心等和尺寸约束确保草图完全定义且易于通过修改参数来驱动变更。特征操作对基础几何或草图进行三维操作如拉伸(extrude)、旋转(revolve)、放样(loft)、扫掠(sweep)。同时包括修饰特征如圆角(fillet)、倒角(chamfer)、抽壳(shell)、阵列(pattern)。布尔运算与组合通过并集(union)、差集(cut)、交集(intersect)来组合多个实体构建最终形状。后期处理与导出进行最后的修饰计算质量属性并将模型导出为STEP用于协作、STL用于3D打印或SVG/DXF用于激光切割等格式。这个工作流的核心思想是“分而治之”和“关注点分离”。将复杂的模型分解为多个特征或子部件分别用函数或类进行封装最后再组装起来。这样不仅代码结构清晰也便于单独调试和复用。3. 关键技术点深度剖析与实例解读3.1 草图约束程序化建模的“灵魂”在传统CAD中我们用鼠标拖动线条并添加约束。在CadQuery中我们用代码做同样的事。这是新手最容易感到困惑但也是最重要的部分。33个实例中至少有10个是围绕草图展开的。核心概念草图约束分为两类。几何约束定义图元之间的关系如Coincident重合、Horizontal水平、Tangent相切、Perpendicular垂直。尺寸约束定义图元的大小或位置如Distance距离、Radius半径、Angle角度。一个典型实例带键槽的轴套法兰这个实例综合运用了多种约束。假设我们要画一个法兰盘草图包含一个外圆、一个内孔和一个键槽。import cadquery as cq # 定义参数 outer_dia 50.0 inner_dia 20.0 key_width 6.0 key_depth 3.0 # 创建草图 sketch ( cq.Workplane(XY) .circle(outer_dia / 2) # 外圆 .circle(inner_dia / 2) # 内圆自动与原点同心 .rect(key_width, key_depth) # 画一个矩形代表键槽 .vertices() # 选择矩形的所有顶点 .fillet(0.5) # 对键槽拐角做圆角 ) # 此时矩形的位置是自由的。我们需要用约束来定位它。 # 在实际代码中我们会使用cqgi来添加约束例如将矩形下边线的中点与X轴重合并距离原点一定尺寸。注意上面的代码仅展示了图形创建真正的约束需要在cqgi.Sketch环境下完成。关键技巧是先添加几何约束固定形状关系再添加尺寸约束驱动具体大小。例如先约束键槽矩形两侧边与Y轴平行底边与X轴重合然后再用尺寸约束定义其宽度、深度和距原点的距离。实操心得草图约束失败是常事。我的排查顺序是1) 检查是否过约束红色提示2) 检查是否欠约束图形可以鼠标拖动3) 检查尺寸约束引用的是否是正确的几何元素。多用sketch.solve()中间状态输出或导出为DXF到其他CAD软件中查看约束状态。3.2 特征操作从2D到3D的魔法将草图转化为三维实体主要依靠拉伸、旋转、扫掠和放样。33个实例中对每种操作都有专项练习。拉伸 (extrude) 的进阶技巧 最基本的extrude(10)是单向拉伸。但CadQuery支持更复杂的拉伸双向拉伸extrude(10, bothTrue)会以草图平面为中间面向两侧各拉伸5mm。带拔模斜度的拉伸extrude(10, taper15)对于注塑件或铸造件设计至关重要15表示拔模角度。到指定面的拉伸extrude(until“next”)可以拉伸到下一个相交的实体表面这在创建支撑结构时非常有用。扫掠 (sweep) 与放样 (loft) 这两个是创建复杂曲面体的利器。扫掠一个截面沿着一条路径移动成形。实例中可能有一个“弹簧”或“管道”的模型。关键点是路径必须连续通常用Wire构建截面必须垂直于路径。一个常见错误是截面方向不对导致扫掠扭曲。可以用normal参数或frenet算法来调整。放样在多个截面之间创建平滑过渡的实体。实例中可能有从方形过渡到圆形的变径管。截面数量和质量直接影响放样结果。所有截面最好有相同数量的线段并且通过makeFilled()确保截面是闭合的平面Wire。对于复杂放样建议先用debug()方法查看截面位置和方向是否对齐。一个综合实例参数化散热片这个实例会用到阵列(pattern)和布尔运算。# 假设已有一个基板 base fin_width 1.0 fin_height 15.0 fin_spacing 4.0 num_fins 10 # 创建第一个散热片 fin cq.Workplane(“XZ”).rect(fin_width, fin_height).extrude(20) # 假设深度20 fin fin.translate((0, 0, base.height)) # 移动到基板顶部 # 线性阵列散热片 fins fin for i in range(1, num_fins): fins fins.union(fin.translate((i * (fin_width fin_spacing), 0, 0))) # 也可以使用 .rarray 进行矩形阵列但手动循环更直观可控 # 与基板做并集 heat_sink base.union(fins)提示对于大量重复特征的阵列polarArray环形阵列和rarray矩形阵列函数性能更好。但在阵列前务必确认原始特征的位置是准确的因为阵列是基于原特征进行复制的。3.3 装配体管理让多个零件“各就各位”当模型由多个零件组成时就需要装配体管理。CadQuery本身不提供严格的“装配体”概念但我们可以通过坐标变换来模拟。核心方法locate()和moved()。 每个零件在创建时都默认在自己的局部坐标系原点。装配时我们需要计算每个零件相对于全局坐标系或另一个零件的位姿位置和姿态然后使用moved()进行移动和旋转。实例一个简单的轴-轴承-座装配创建零件分别创建轴(shaft)、轴承(bearing)、座(housing)三个独立的Workplane对象。定义装配关系轴承内圈与轴是过盈配合同心且端面对齐。轴承外圈与座是过渡配合同心。轴肩用于轴向定位。实施装配# 假设零件都已创建好并有关键尺寸属性 # 将轴承装配到轴上 bearing_on_shaft bearing.moved(cq.Location((0, 0, shaft.shoulder_height))) # 将带轴承的轴装配到座里 # 需要计算座内孔中心与全局原点的偏移 assembly housing.union(bearing_on_shaft.moved(cq.Location((housing_center_x, housing_center_y, 0))))高级技巧对于复杂装配建议定义一个“主装配坐标系”所有零件的位姿都存储在一个字典或列表里。甚至可以写一个简单的类来管理零件名称、实例和位姿。导出时可以分别导出单个零件并在元数据中记录其位姿供下游装配软件使用。4. 从实例到项目实战工作流与问题排查4.1 构建一个参数化零件库的完整流程让我们以一个具体的项目——“创建一系列参数化的六角头螺栓”——来串联33个实例中的知识点。步骤1参数化设计首先分析螺栓的驱动尺寸。通常螺纹规格如M6、长度L、头高K、对边宽度S是主要参数。我们可以从标准件手册或数据库中建立这些参数的关联。from dataclasses import dataclass dataclass class BoltSpec: 螺栓规格参数类 thread_dia: float # 螺纹公称直径如6.0 pitch: float # 螺距如1.0 length: float # 螺杆长度 head_type: str # 头型如 hex # 以下参数可根据直径查表获得 key_width: float # 对边宽度S head_height: float # 头高K washer_face_dia: float # 垫圈面直径 classmethod def from_standard(cls, size: str, length: float): 从标准规格如M6创建参数 # 这里可以内置一个查找表或连接数据库 lookup_table { M3: {thread_dia: 3.0, pitch: 0.5, key_width: 5.5, head_height: 2.0}, M6: {thread_dia: 6.0, pitch: 1.0, key_width: 10.0, head_height: 4.0}, # ... 更多规格 } specs lookup_table.get(size, lookup_table[M6]) # 默认值 return cls(thread_diaspecs[thread_dia], pitchspecs[pitch], lengthlength, head_typehex, key_widthspecs[key_width], head_heightspecs[head_height], washer_face_diaspecs[thread_dia] * 1.6) # 经验公式步骤2建模函数化将螺栓的各个部分六角头、螺杆、螺纹段建模过程封装成函数。def create_hex_head(key_width, head_height, washer_dia): 创建六角头 # 使用多边形命令创建六边形然后拉伸 head (cq.Workplane(XY) .polygon(6, key_width) # 六边形外接圆直径为key_width .extrude(head_height) .faces(Z) # 选择顶面 .circle(washer_dia / 2) # 创建垫圈面草图 .cutBlind(-0.5) # 切出一个浅凹面 ) return head def create_shank(diameter, length, with_threadFalse, pitchNone): 创建螺杆可选择是否创建螺纹简化表示 shank cq.Workplane(XY).circle(diameter / 2).extrude(length) if with_thread and pitch: # 这里不创建真实螺纹计算量大而是用螺旋扫掠切出一个示意性螺纹 # 或者更简单在圆柱表面画一条螺旋线作为视觉参考 pass return shank def create_bolt(spec: BoltSpec): 组装成完整的螺栓 head create_hex_head(spec.key_width, spec.head_height, spec.washer_face_dia) shank create_shank(spec.thread_dia, spec.length) # 将螺杆移动到六角头下方 bolt head.union(shank.translate((0, 0, -spec.length))) return bolt步骤3批量生成与导出利用循环或列表推导式批量生成不同规格的螺栓并自动命名导出。specs [BoltSpec.from_standard(M6, 20), BoltSpec.from_standard(M8, 25)] for i, spec in enumerate(specs): bolt create_bolt(spec) # 导出为STEP和STL cq.exporters.export(bolt, fbolt_M{int(spec.thread_dia)}x{int(spec.length)}.step) cq.exporters.export(bolt, fbolt_M{int(spec.thread_dia)}x{int(spec.length)}.stl) print(f已生成螺栓: 螺纹{spec.thread_dia}mm, 长度{spec.length}mm)4.2 常见问题、错误排查与性能优化在实际使用CadQuery进行程序化建模时你一定会遇到各种报错和性能问题。下面是我总结的“避坑指南”。问题1几何体创建失败报错ValueError: ...或RuntimeError可能原因1无效的输入参数。例如创建圆角(fillet)时指定的半径大于边的长度。排查检查所有尺寸参数是否为正数且符合几何逻辑如内圆半径不能大于外圆半径。可能原因2零厚度几何。在进行布尔运算特别是cut时如果两个实体恰好相切或产生无限薄的区域OCCT内核会报错。排查这是最棘手的问题之一。解决方法通常是引入一个微小的偏移量(tol1e-6)。例如在切割时将切割工具稍微做大一点或移动一点点避免完美贴合。可能原因3非流形几何。创建的实体有自相交或孤立的边/面。排查对于复杂操作尤其是放样和扫掠后使用val().isValid()检查实体有效性。可以用exporters.export(shape, ‘debug.brep’)导出为BREP格式用FreeCAD或OCCT的Draw Test Harness打开可视化检查。问题2草图约束求解失败可能原因约束冲突或过约束。这是草图建模中最常见的问题。排查采用增量式构建法。每添加2-3个约束就尝试sketch.solve()。一旦报错最近添加的约束就是嫌疑对象。简化草图先用最少约束定义大致形状再逐步添加细节约束。问题3模型重建速度慢可能原因特征历史链过长或操作过于复杂。CadQuery会记录操作历史复杂的模型重建时需要逐步回放。优化1合理使用combine()。在完成一系列连续的、不再需要单独修改的布尔运算后使用combine()将它们合并为一个单一实体可以缩短历史链。优化2避免在循环内进行昂贵的操作。如非必要不要在循环内进行fillet、chamfer或复杂的split操作。可以先完成所有主要实体的创建和组合最后再统一进行圆角等修饰。优化3利用缓存。如果某些子部件是固定的可以将其生成后保存为STEP文件后续直接导入(importers.importStep)而不是重新计算。问题4导出的STL文件有破面或质量差可能原因默认的STL细分精度不够。CadQuery通过OCCT将B-Rep模型转换为三角网格时有一个精度参数。解决在导出STL时指定tolerance和angularTolerance参数。tolerance控制线性偏差值越小越精确文件也越大。对于需要3D打印的模型通常设置tolerance0.01毫米是个不错的起点。cq.exporters.export(shape, ‘model.stl’, tolerance0.01, angularTolerance0.1)一个实用的调试技巧可视化中间步骤在建模过程中经常需要查看中间结果。除了使用Jupyter Notebook的即时显示你可以在代码中插入导出语句。# ... 部分建模代码 ... intermediate_result some_workplane.extrude(10) cq.exporters.export(intermediate_result, ‘step1_debug.step’) # 导出为STEP可用任何CAD软件查看 # ... 继续建模 ...这能帮你精确定位是哪一步操作导致了问题。5. 超越实例CadQuery在真实工作流中的集成应用掌握了33个实例中的技能后我们可以将其融入更广阔的工程和设计自动化场景。场景一基于配置表的变体设计在产品族设计中往往有数十个尺寸参数不同的变体。我们可以用CSV或Excel表格来管理这些配置。import pandas as pd # 读取配置表 config_df pd.read_csv(‘product_variants.csv’) for index, row in config_df.iterrows(): # 从表格行中读取参数 length row[‘长度L’] width row[‘宽度W’] hole_dia row[‘孔径D’] # 调用参数化建模函数 part create_parametric_part(lengthlength, widthwidth, hole_diahole_dia) # 以配置命名导出 export(part, f’part_variant_{index}.step’)这样只需更新表格就能一键重生所有产品变体模型和图纸。场景二与仿真分析结合使用CadQuery生成的模型可以无缝导入到有限元分析FEA软件中。例如你可以写一个脚本根据受力分析结果自动调整某些部位的厚度或加强筋的布局然后重新生成模型进行迭代分析实现初步的拓扑优化循环。场景三生成加工指令或报告模型建好后可以自动提取加工所需的特征信息。# 计算模型体积、重量需材料密度 mass_props part.val().MassProperties() volume mass_props[‘volume’] mass volume * material_density # 假设已知密度 # 查找所有孔特征简化示例寻找所有圆柱形内表面 holes [] for solid in part.solids().vals(): for face in solid.Faces(): if type(face.Surface()) Geom_Plane: # 如果是平面 # 进一步判断平面上是否有圆边... pass # 生成一个包含孔径、深度、位置的钻孔表格这些数据可以自动填入工艺卡片或成本估算报告。我个人在将CadQuery引入团队工作流时最大的体会是“前期投入长期受益”。初期需要花时间搭建参数化模型框架和编写基础函数库这比用鼠标直接画一个零件要慢。但一旦框架建成应对设计变更、生成系列化产品、进行设计探索的效率是传统方式无法比拟的。它迫使你将设计逻辑思考得更清楚最终产出的不仅是模型更是一份可执行的设计文档。最后分享一个小技巧善用Python的logging模块。在你的建模脚本中设置不同级别的日志INFO, DEBUG记录关键参数、步骤耗时和警告信息。当脚本运行出错或性能不佳时这些日志是 priceless 的调试助手。例如在开始一个复杂特征操作前记录logging.info(“Starting loft operation with %d profiles”, len(profiles))能帮你快速定位问题发生的环节。