Python + CadQuery：用代码生成参数化零件¶

本页用 Python + CadQuery 演示如何用代码生成参数化 CAD 模型。它与实操 Lab：用 FreeCAD 建一个带孔矩形板是同一目标（建立第一个 CAD 零件）的两种不同路径：FreeCAD 走图形化界面，CadQuery 走 Python 代码。

本页面是 FreeCAD 图形化工作流的**补充**，不是替代。读者在阅读本页之前，建议先完成实操 Lab：用 FreeCAD 建一个带孔矩形板或 FreeCAD 实操线：从建模到 G-code 的学习路径，建立"几何建模 → STEP/STL 导出"的基本认知。

A. 本页解决什么问题¶

FreeCAD 是图形化 CAD 工作流¶

在实操 Lab：用 FreeCAD 建一个带孔矩形板中，你用鼠标和菜单完成：

画矩形草图
标注尺寸约束
拉伸成实体
打孔

整个流程是**所见即所得**，每次修改都需要打开 FreeCAD、点击按钮。

CadQuery 是代码化参数建模方式¶

CadQuery 是一个 Python 库，它让你用代码描述几何形状：

length = 80
width = 50
thickness = 8

plate = cq.Workplane("XY").box(length, width, thickness)

上面 3 行代码就创建了一个 80×50×8 的矩形板。修改 length 变量值，零件尺寸随之改变。

同一个零件的两种表达方式¶

下面用一张表对比 FreeCAD 和 CadQuery 的表达思路：

同一种零件的两种建模方式¶
操作	FreeCAD（图形化）	CadQuery（代码化）
创建矩形板	画草图 → 拉伸 Pad	`Workplane.box(length, width, thickness)`
在中心打孔	草图 → Pocket	`.faces(">Z").workplane().hole(diameter)`
修改尺寸	打开模型、双击约束、改数字	改 Python 变量值、重新运行
版本管理	保存 `.FCStd` 文件	保存 `.py` 文件
批量生成多个尺寸	手动复制多份	`for length in [60, 80, 100]: ...`

代码化建模特别适合：

重复生成：同一类零件、不同尺寸
参数调整：快速修改并比较
版本管理：模型和代码一起进 Git
教学场景：每个建模步骤对应一行代码，逻辑清晰

B. CadQuery 在 CAD/CAM 学习中的位置¶

本页介绍的 CadQuery 不是用来"替代 FreeCAD"，而是用来补全你理解工具链的一环。

完整的数据流转链路：

Python 参数（length, hole_diameter, ...）
    ↓
CadQuery 几何建模（.box, .hole, .fillet, ...）
    ↓
生成实体（Workplane 对象）
    ↓
导出 STEP / STL
    ↓
STEP/STL mini-lab（格式验证）
    ↓
CAM worksheet（freecad-to-cam-worksheet）
    ↓
G-code 理解（gcode-toolpath-visualization）

理解这条链路的关键点：

Python 参数是源头：所有几何特征都由变量驱动
CadQuery 是转换器：把参数变成几何实体
STEP/STL 是桥接格式：和 FreeCAD、Fusion 360、CAM 软件的共同语言
下游工具不关心建模方式：无论是 FreeCAD 还是 CadQuery，只要能正确导出 STEP/STL 即可

C. 第一个示例：带孔矩形板¶

下面用与实操 Lab：用 FreeCAD 建一个带孔矩形板中相似但略有不同的尺寸，建一个带孔矩形板。

零件规格¶

带孔矩形板参数¶
参数	数值	说明
`length`	80 mm	板的长度（X 方向）
`width`	50 mm	板的宽度（Y 方向）
`thickness`	8 mm	板的厚度（Z 方向）
`hole_diameter`	20 mm	中心通孔直径

完整代码¶

下方代码展示了用 CadQuery 创建此零件、添加倒角、并导出 STEP/STL 的完整流程。

"""
带孔矩形板 — CadQuery 参数化建模示例

本文件是 CAD-CAM-Technology-docs 项目的教学示例，
配合 examples/cadquery-parametric-modeling.rst 使用。

依赖：cadquery
安装：pip install cadquery
运行：python plate_with_hole.py
"""

import cadquery as cq

# ---------- 参数集中区 ----------
# 改这里就能生成不同尺寸的零件
length = 80.0          # 板的长度 (X)
width = 50.0           # 板的宽度 (Y)
thickness = 8.0        # 板的厚度 (Z)
hole_diameter = 20.0   # 中心通孔直径
chamfer_size = 1.0     # 倒角尺寸（可选）

# ---------- 几何建模 ----------
# 1. 创建基础矩形板
plate = cq.Workplane("XY").box(length, width, thickness)

# 2. 在板中心打一个通孔
plate = (
    plate
    .faces(">Z")                       # 选择顶面
    .workplane()                       # 进入草图平面
    .hole(hole_diameter)               # 打孔
)

# 3. 在 8 个竖直棱边上添加倒角
plate = plate.edges("|Z").chamfer(chamfer_size)

# ---------- 导出 ----------
# STEP 文件保留完整几何，适合后续 CAD/CAM/CAE
cq.exporters.export(plate, "plate_with_hole.step")

# STL 文件是三角网格，适合 3D 打印
cq.exporters.export(plate, "plate_with_hole.stl")

print("导出完成：plate_with_hole.step, plate_with_hole.stl")

代码逐段解读¶

参数集中区：

length、width、thickness、hole_diameter 四个变量决定整个零件的尺寸。改一个数字，整套几何随之变化。这是 CadQuery 与 FreeCAD 最大的区别——参数显式可见。

创建基础矩形板：

cq.Workplane("XY") 创建一个工作平面，"XY" 表示工作平面是 XY 平面（Z=0）。.box(length, width, thickness) 在该平面上创建一个长方体，结果是一个中心在原点的盒子。

中心打孔：

.faces(">Z") 选择零件顶面（Z 正方向最大值的面）。.workplane() 在该面上新建工作平面。.hole(diameter) 在工作平面原点打一个贯穿零件的孔。

倒角：

.edges("|Z") 选中所有与 Z 轴平行的棱边（也就是 4 条顶面边和 4 条底面边，共 8 条）。.chamfer(chamfer_size) 在每条边上做指定尺寸的倒角。

导出：

cq.exporters.export(plate, "plate_with_hole.step") 导出 STEP，保留 B-rep 完整几何。
cq.exporters.export(plate, "plate_with_hole.stl") 导出 STL，转为三角网格（注意：会丢失圆孔的精确表示，详见 Mini-Lab：STEP 与 STL 格式对比实验）。

D. 参数化的意义¶

CadQuery 的核心价值不是"写代码比点鼠标酷"，而是**参数化**。

尺寸修改的本质¶

想象你需要为不同客户生产同一类零件，只是长度不同：

for length in [60, 80, 100, 120]:
    plate = cq.Workplane("XY").box(length, 50, 8).faces(">Z").workplane().hole(20)
    cq.exporters.export(plate, f"plate_L{length}.step")

4 行代码生成 4 个不同长度的零件。在 FreeCAD 里，你需要复制 4 次文件、每个文件手工改尺寸。

参数命名 vs 直接画图¶

参数命名 vs 直接画图¶
维度	FreeCAD 草图尺寸	CadQuery 变量
表达形式	数字（带单位 mm）	变量名 + 值
复用性	同一文件可改，不能批量	函数参数，跨文件可调用
可读性	数字即含义	变量名即文档
版本管理	数字变化看不出意图	变量名变化可读出意图
文档同步	容易忘记更新文档	变量名就是文档

代码模型与 Git 协作¶

.py 文件天然适合用 Git 管理：

diff 直观：length: 80 → 100 一眼能看出"长度从 80 改成 100"
review 友好：PR 中能 review 几何设计变更
分支实验：在分支里改参数、对比结果，不会污染主分支

相比之下，.FCStd 文件是 FreeCAD 的二进制格式，diff 不可读、PR 几乎无法 review 几何变更。

E. 与 FreeCAD 工作流对比¶

下面从 7 个维度对比 FreeCAD 图形化建模和 CadQuery 代码建模：

FreeCAD vs CadQuery 工作流对比¶
维度	FreeCAD 图形化建模	CadQuery 代码建模	适合场景 / 初学者注意点
学习门槛	中等：需要熟悉 GUI 操作	中等偏高：需要 Python 基础	不会 Python 选 FreeCAD，会 Python 选 CadQuery
可视化程度	高：实时预览	中：需要运行后查看	CadQuery 适合配合 FreeCAD 预览
参数修改	双击约束、改数字	改变量、重新运行	一次改大量参数，CadQuery 更快
版本管理	二进制 FCStd，diff 不可读	纯文本 .py，diff 完全可读	团队协作 / Git 选 CadQuery
批量生成	手动复制	for 循环	同一类多尺寸零件选 CadQuery
导出 STEP/STL	都支持	都支持	两者导出能力相当
与 CAM 连接	STEP/STL 即可	STEP/STL 即可	下游工具不关心建模方式

选择建议：

初学者：建议先用 FreeCAD 建立几何直觉，再学 CadQuery
会 Python 的工程师：CadQuery 更高效
团队项目：CadQuery 代码模型更易于协作
一次性快速原型：FreeCAD 更快
参数族/尺寸族：CadQuery 显著优于 FreeCAD

F. 导出与检查¶

CadQuery 导出的 STEP/STL 与 FreeCAD 导出文件**没有本质区别**。导出后仍然要走 FreeCAD 导出 STEP/STL 检查清单的检查清单。

导出格式选择¶

CadQuery 导出格式选择¶
格式	CadQuery 调用	适用场景	文件大小（参考）
STEP	`cq.exporters.export(obj, "x.step")`	后续 CAD / CAM / CAE，保留 B-rep	几十 KB
STL	`cq.exporters.export(obj, "x.stl")`	3D 打印、CAM 后处理	几百 KB ~ 几 MB

关键提示：

STL 只是网格外壳：打孔、倒角等特征在 STL 中全部变成三角面片，圆孔变成多边形
STEP 更适合后续 CAD/CAM/CAE：完整 B-rep 表示，可被任何 CAD 软件读取
导出后必须检查：无论用 FreeCAD 还是 CadQuery 导出，都要走 FreeCAD 导出 STEP/STL 检查清单

导出检查流程¶

完整流程参考 FreeCAD 导出 STEP/STL 检查清单，关键检查点：

STEP 文件：用文本编辑器打开，确认单位（#143=... 行附近标注 SI_UNIT(.MILLI.,...) 表示毫米）
STL 文件：三角面片数量合理（约 1k ~ 100k 面片，零件越大面片越多）
几何验证：把导出的 STEP 文件重新导入 FreeCAD 或 Viewer（如 FreeCAD Viewer），目视确认形状正确

与下游工作流的衔接¶

导出的 STEP 文件可以：

导入 FreeCAD 做进一步编辑（与 CadQuery 代码协同）
导入 FreeCAD Path Workbench 入门：从 Job 到 G-code 介绍过的 FreeCAD Path Workbench 生成 G-code
作为支架零件 Capstone 综合项目综合项目的零件输入

G. 第二个示例：简化支架参数结构¶

真实 Capstone 项目（如支架零件 Capstone 综合项目中的 L 型支架）涉及更多参数。下表展示从"带孔板"扩展到"支架"的参数结构：

L 型支架参数结构¶
参数	典型值	说明
`base_length`	100 mm	底板长度
`base_width`	60 mm	底板宽度
`base_thickness`	10 mm	底板厚度
`vertical_height`	80 mm	立板高度
`vertical_thickness`	10 mm	立板厚度
`hole_diameter`	20 mm	底板通孔直径
`fillet_radius`	3 mm	内圆角半径（缓解应力集中）

从带孔板到支架的扩展思路¶

# 1. 创建底板（与带孔板类似）
base = cq.Workplane("XY").box(base_length, base_width, base_thickness)
base = base.faces(">Z").workplane().hole(hole_diameter)

# 2. 创建立板（定位在底板一侧）
vertical = (
    cq.Workplane("XY")
    .transformed(offset=(base_length/2, 0, base_thickness))
    .box(vertical_thickness, base_width, vertical_height)
)

# 3. 合并两个实体
bracket = base.union(vertical)

# 4. 添加内圆角（缓解应力集中）
bracket = bracket.edges("|Z or >X").fillet(fillet_radius)

# 5. 导出
cq.exporters.export(bracket, "bracket.step")

学习路径建议：

先用代码完成实操 Lab：用 FreeCAD 建一个带孔矩形板同样的带孔矩形板
再用代码生成 L 型支架（参数化版）
最后对比：FreeCAD 做的支架 vs CadQuery 做的支架，验证几何一致性

H. 常见误区¶

CadQuery 学习常见误区¶
#	误区	正确做法	影响等级
1	以为代码建模不需要几何理解	仍然需要理解草图、特征、布尔运算等概念	⭐⭐⭐
2	参数命名混乱（`a, b, c, d`）	用语义化命名（`length, width, hole_diameter`）	⭐⭐
3	单位假设不明确（毫米 vs 英寸）	顶部明确标注 `# 单位：毫米` 或使用变量 `UNIT = "mm"`	⭐⭐⭐
4	导出 STL 后以为仍保留特征	STL 只是三角网格，特征信息全部丢失	⭐⭐⭐
5	过早追求复杂模型	先完成带孔板，再扩到支架，最后考虑装配体	⭐⭐
6	没有保存导出检查记录	记录导出文件名、单位、面片数、STEP 文件大小	⭐⭐
7	复制粘贴代码不做参数化	把可变的部分抽成函数参数	⭐⭐
8	在 CadQuery 里写大量业务逻辑	CadQuery 只负责几何，业务逻辑放外部脚本	⭐

前 6 个误区是初学者最容易犯的，必须避免。后 2 个是进阶问题，等熟悉 CadQuery 后再考虑。

I. 与已有页面的关系¶

CadQuery 页面不是孤立的，它与以下页面形成完整闭环：

实操 Lab：用 FreeCAD 建一个带孔矩形板 — FreeCAD 图形化版带孔板（与本页面同一目标）
FreeCAD 导出 STEP/STL 检查清单 — 导出检查清单（CadQuery 导出后同样适用）
Mini-Lab：STEP 与 STL 格式对比实验 — STEP/STL 格式对比（理解为什么要选对格式）
FreeCAD 到 CAM 加工任务单 — 从模型到 CAM 加工任务（导出 STEP 后继续）
工作流路线图：从设计到制造 — CAD/CAM 全流程总览（本页面在 CAD 建模阶段的补充）
支架零件 Capstone 综合项目 — L 型支架 Capstone（从带孔板到支架的扩展）
Capstone 项目线：从支架零件到作品集提交 — Capstone 项目线学习路径

J. 下一步学习建议¶

最小路径 （约 2-3 小时）：

阅读本页面 B ~ E 节，理解 CadQuery 在工具链中的位置
复制 code/cadquery/plate_with_hole.py 到本地（不需要立刻安装 CadQuery）
在文本编辑器中通读代码，理解每行的几何含义
阅读 FreeCAD 导出 STEP/STL 检查清单，理解导出后如何验证

完整路径 （约 1-2 天）：

在本地安装 CadQuery：pip install cadquery
运行 code/cadquery/plate_with_hole.py，生成 STEP 和 STL
把生成的 STEP 文件导入 FreeCAD，目视检查几何
修改参数（length=120, hole_diameter=30），重新生成，对比结果
扩展到 L 型支架，参考 G 节的参数表和代码片段

进阶路径 （约 1 周+）：

把支架零件 Capstone 综合项目中的支架用 CadQuery 重写
配合 FreeCAD Path Workbench 入门：从 Job 到 G-code，从 CadQuery 生成的 STEP 进入 CAM 流程
学习 CadQuery 的装配体 API，处理多零件装配

K. 教学声明¶

本页面是 CAD/CAM 学习路径的辅助材料，不是生产环境指南。

教学示例不考虑工业级鲁棒性
不要求读者立刻安装 CadQuery，本页以阅读代码为主
不替代实操 Lab：用 FreeCAD 建一个带孔矩形板，两者是同一目标的两种路径
真实工程中应根据团队技能选择建模方式

L. V9B/V9C 实际运行与本地环境¶

V7A 代码仅能通过 py_compile 语法检查。实际运行需要 OCCT 环境：

CadQuery 真实运行与 STEP/STL 导出试点（V9B） —— V9B 服务器端环境诊断表、6 个文件运行结果
CadQuery 本地运行环境：从代码到 STEP/STL 导出（V9C） —— V9C 本地环境配置指南、conda/pip 路线、smoke test、导出检查

如果要在本机运行 V7A 代码，参考 V9C 页面的 2 条环境路线和 smoke test 脚本。