1. 从一段文字到三维模型：text-to-cad 到底在解决什么问题
第一次听到 “text-to-cad” 这个词，我脑子里蹦出来的画面是：对着电脑敲一句“给我画一个 80×60×40 的法兰底座，中心开一个直径 30 的通孔”，然后 CAD 软件里就自动长出了这个零件。这个场景放在五年前还像科幻，但现在已经有一批工具和方案在往这个方向走了。所谓 text-to-cad，直译就是“文本转 CAD”，核心逻辑是把自然语言描述或者结构化文本，转换成 CAD 能识别的几何模型文件，常见输出格式包括STEP、GLB、STL这几类。
它解决的问题很实际。传统建模流程是：人脑理解需求 → 手动在 CAD 里画草图 → 拉伸/旋转/布尔运算 → 导出文件。这个链条里最耗时的是“人脑理解需求”到“手动画草图”之间的翻译过程，尤其是标准化零件、简单结构件、批量变体件，画起来机械重复，改一个尺寸就要重新走一遍特征树。text-to-cad 想干的事，就是把这层翻译自动化：你用文字描述参数和结构，工具负责生成几何。
适合关注这个方向的人其实比想象中多。做机械设计的工程师，手里有一堆相似零件要出图；做 3D 打印的玩家，想快速把脑子里的想法变成 STL 去切片；做前端或游戏开发的人，需要 GLB 格式的轻量模型放进场景；还有做工艺夹具、钣金件、建筑构件的人，日常就是和 STEP、STL 打交道。哪怕你只是刚学 CAD 制图入门，理解 text-to-cad 的思路也能帮你更快建立“参数—几何”的对应关系。
我先把话说在前面：text-to-cad 目前还不是“一句话替代建模工程师”的魔法。它更像一个高效的起点生成器，能帮你把 60% 到 80% 的基础结构快速搭出来，剩下的倒角、圆角、装配约束、工程图标注，还是得人工收尾。但就是这 60% 到 80%，在批量场景下已经能省下大量时间。下面我按实际落地的思路，把这个方向拆开讲清楚。
2. 核心思路拆解：文本怎么变成几何体
2.1 三种主流技术路线与选型逻辑
text-to-cad 不是单一技术，而是一类方案的统称。我把它分成三条路线，每条路线的成熟度、输出质量和适用场景差别很大。
第一条路线是参数化模板驱动。思路是先定义好一套参数化模型模板，比如“法兰”“支架”“齿轮毛坯”，然后用文本解析出尺寸参数，填入模板生成模型。这条路线最稳，因为几何逻辑是人工写死的，不会出现离谱形状。缺点是模板覆盖范围有限，遇到没定义过的结构就无能为力。适合标准化程度高的零件库场景。
第二条路线是程序化建模脚本生成。工具把自然语言转成建模脚本，比如 OpenSCAD 的代码、CadQuery 的 Python 脚本，或者 FreeCAD 的宏命令，然后执行脚本生成几何。这条路线灵活度高，因为脚本语言本身能表达复杂逻辑，而且生成结果可复现、可版本管理。缺点是对文本理解的准确性要求高，描述模糊时生成的脚本可能报错或形状不对。
第三条路线是深度学习直接生成几何表示。用模型直接输出网格、点云或者隐式场，再转成 STL 或 GLB。这条路线最“AI”，但目前在工程精度上还不太靠谱，生成的模型往往需要大量修复，尺寸公差更是没法保证。我实测下来，它更适合概念阶段的形状探索，不适合直接出工程图。
选型逻辑很简单：要精度和可制造性，走第一条或第二条；要快速概念验证，可以试试第三条。大多数实际项目里，第一条和第二条组合使用效果最好——模板负责常见结构，脚本负责变体和特殊逻辑。
2.2 为什么 STEP、GLB、STL 三种格式都要关注
这三种格式在 text-to-cad 流程里扮演不同角色，理解它们的差异能帮你少走弯路。
STEP是工程领域的通用交换格式，保留完整的边界表示（B-rep）信息，圆柱就是圆柱，平面就是平面，尺寸精确，能被主流 CAD 软件重新编辑特征。如果你生成的模型后续还要改尺寸、出工程图、做装配，STEP 是首选输出。
STL是三角网格格式，只记录表面三角形的顶点和法向量，没有特征信息。它的优势是几乎所有 3D 打印切片软件都认，缺点是精度受网格密度影响，圆孔会变成多边形，而且文件本身不可编辑。text-to-cad 输出 STL 通常是为了直接打印。
GLB是 glTF 的二进制版本，专为实时渲染和网络传输设计，文件小、加载快，适合放进网页、游戏引擎或者 AR 场景。它同样不带工程特征，但视觉效果好，材质和层级信息可以一起打包。
我一般建议：同一个文本描述，同时生成 STEP 和 STL 两个版本。STEP 存档和后续编辑，STL 直接送打印。如果要做展示，再补一个 GLB。这样一套流程下来，一个需求能覆盖设计、制造、展示三个环节。
2.3 文本描述的结构化程度决定成败
这是我在实际使用中体会最深的一点：text-to-cad 的效果，八成取决于你的文本描述有多结构化。你写“画个盒子”，工具只能猜；你写“长方体，长 100mm，宽 60mm，高 40mm，原点在底面中心”，工具就能精确执行。
我总结了一个描述模板，基本能覆盖大多数简单零件：
- 几何类型：长方体、圆柱、圆锥、球、拉伸体、旋转体
- 关键尺寸：长宽高、直径、半径、壁厚，全部带单位
- 位置关系：原点位置、对称方式、阵列数量和间距
- 布尔操作：开孔、切除、合并、相交
- 附加特征：倒角、圆角、螺纹孔规格
把这几项写清楚，生成成功率会大幅提升。反过来，如果描述里全是“大概”“差不多”“好看一点”这种词，再强的工具也救不了。这一点和写代码很像——输入越规范，输出越可靠。
3. 实操落地：从文本到可打印模型的完整流程
3.1 环境准备与工具链搭建
我目前用的组合是 Python + CadQuery + FreeCAD 命令行，这套方案开源、可脚本化、输出 STEP 和 STL 都方便。CadQuery 是一个基于 Python 的参数化建模库，语法接近自然语言，很适合做 text-to-cad 的中间层。
安装步骤不复杂，但有几个坑要注意：
# 建议用 conda 建独立环境，避免和系统 Python 冲突 conda create -n text2cad python=3.10 conda activate text2cad # 安装 cadquery，它会自动带上 OCP 几何内核 conda install -c conda-forge cadquery # 安装 freecad 用于格式转换和可视化检查 conda install -c conda-forge freecad注意：CadQuery 依赖的 OCP 内核在 Windows 上对 Visual C++ 运行库版本有要求。如果你之前装过其他 CAD 软件，可能会遇到 C++ 运行库冲突，表现是导入 cadquery 时报 DLL 加载失败。解决办法是安装最新的 Visual C++ Redistributable，或者用 conda 环境隔离，不要混用系统 Python。
环境搭好后，验证一下：
import cadquery as cq result = cq.Workplane("XY").box(10, 10, 10) print(result.val().Volume())能打印出体积数值，说明环境正常。
3.2 文本解析层的设计
这一步是 text-to-cad 的核心。我的做法是写一个轻量解析器，把中文描述拆成结构化字典。不追求理解所有自然语言，只覆盖我常用的那几类描述。
import re def parse_description(text): params = {} # 提取长宽高 dims = re.findall(r'(\d+(?:\.\d+)?)\s*(?:mm|毫米)?', text) # 提取关键词 if '长方体' in text or '方块' in text: params['type'] = 'box' elif '圆柱' in text or '圆棒' in text: params['type'] = 'cylinder' elif '法兰' in text: params['type'] = 'flange' # 提取尺寸 if params.get('type') == 'box' and len(dims) >= 3: params['length'] = float(dims[0]) params['width'] = float(dims[1]) params['height'] = float(dims[2]) return params这个解析器很粗糙，但对付日常简单零件够用了。关键是它把“文本”和“几何参数”之间的映射显式化了，后续要扩展新类型，加分支就行。
实操心得：不要一上来就追求大而全的 NLP 模型。先用正则和关键词把 80% 的常见描述覆盖掉，剩下的边缘情况再考虑用大模型兜底。这样系统稳定、调试方便，而且生成结果可预测。
3.3 几何生成与格式导出
解析出参数后，生成几何就是 CadQuery 的强项了。下面是一个完整示例，从文本描述生成法兰模型并导出 STEP 和 STL。
import cadquery as cq def build_flange(outer_d, inner_d, thickness, bolt_count, bolt_d, bolt_circle_d): # 主体圆盘 result = ( cq.Workplane("XY") .circle(outer_d / 2) .extrude(thickness) ) # 中心通孔 result = result.faces(">Z").workplane().hole(inner_d) # 螺栓孔阵列 result = ( result.faces(">Z").workplane() .polarArray(bolt_circle_d / 2, 0, 360, bolt_count) .hole(bolt_d) ) return result # 文本描述示例 desc = "法兰，外径120mm，中心孔40mm，厚度15mm，6个直径10mm的螺栓孔，分布圆直径90mm" params = { 'outer_d': 120, 'inner_d': 40, 'thickness': 15, 'bolt_count': 6, 'bolt_d': 10, 'bolt_circle_d': 90 } model = build_flange(**params) # 导出 STEP cq.exporters.export(model, "flange.step") # 导出 STL，设置公差控制网格精度 cq.exporters.export(model, "flange.stl", tolerance=0.01, angularTolerance=0.1)这里有个关键参数：STL 导出的tolerance。它控制三角网格的弦高误差，值越小网格越密、文件越大、圆孔越圆。0.01mm 对于大多数 3D 打印够用了，如果模型很大或者要精细打印，可以调到 0.005。但别调太小，否则文件体积会爆炸，切片软件也可能卡。
STEP 导出不需要额外参数，它保留的是精确几何，文件大小主要取决于特征复杂度。
3.4 批量生成与参数表驱动
text-to-cad 真正体现价值的地方是批量。我经常遇到一个系列几十个规格的零件，手动建模要疯掉。这时候用参数表驱动，一次生成全部。
import csv with open('flange_specs.csv', 'r', encoding='utf-8') as f: reader = csv.DictReader(f) for row in reader: params = {k: float(v) if v.replace('.','').isdigit() else v for k, v in row.items()} model = build_flange(**params) name = f"flange_D{int(params['outer_d'])}_d{int(params['inner_d'])}" cq.exporters.export(model, f"output/{name}.step") cq.exporters.export(model, f"output/{name}.stl", tolerance=0.01)CSV 里一行一个规格，跑一遍脚本，几十个模型全部生成。这个效率提升是数量级的。我之前做一个支架系列，12 个规格，手动建模加导出花了大半天，用脚本跑完不到两分钟。
注意：批量生成时一定要加异常捕获。某个规格参数不合理（比如内径大于外径），脚本会直接报错中断，后面的全不生成。建议每个规格单独 try-except，记录失败原因，最后统一看日志。
4. 常见问题与排查技巧实录
4.1 生成模型破面、孔洞、法线错误怎么处理
STL 文件最常见的质量问题就是网格不封闭、法线朝向不一致、存在自相交。这些问题在切片软件里表现为模型显示异常、切片结果有空洞或者打印出来缺料。
排查思路分三步。第一步，用网格修复工具检查，Meshmixer 或者 Blender 的 3D Print Toolbox 都能快速定位问题区域。第二步，回到生成端，检查几何操作是否有布尔运算失败的情况，比如两个实体刚好相切或者共面，布尔结果容易出问题。第三步，调整 STL 导出公差，有时候公差太大导致薄壁结构网格穿透。
我踩过的一个典型坑：法兰的螺栓孔分布圆直径刚好等于外径减去螺栓孔直径，导致孔边缘和圆盘边缘相切。这种相切在 B-rep 里是合法的，但转成 STL 网格时，相切位置容易生成退化三角形，切片软件识别为破面。解决办法是把分布圆直径稍微调小一点，留出至少 1mm 的壁厚余量。
4.2 尺寸精度对不上：单位、公差与坐标系
text-to-cad 生成模型后，第一件事是量尺寸。我遇到过好几次生成出来的模型尺寸差 10 倍，原因都是单位没统一。CadQuery 默认单位是毫米，但如果你从其他系统导入参数，可能是米或者英寸。建议在解析层强制统一成毫米，并且在导出前用包围盒尺寸做一次校验。
bb = model.val().BoundingBox() print(f"X: {bb.xlen:.2f}, Y: {bb.ylen:.2f}, Z: {bb.zlen:.2f}")如果包围盒尺寸和预期不符，先查单位，再查坐标系原点位置。有些操作会改变工作平面，导致后续特征偏移。我的习惯是每个模型生成后都打印包围盒，和预期值对比，偏差超过 0.1mm 就停下来查。
4.3 文本描述歧义导致的生成偏差
“在中心开一个孔”——哪个中心？顶面中心还是几何中心？“开一个通孔”——直径多少？这些歧义在人工建模时靠经验补全，但工具不会猜。
我的处理方式是建立一套默认规则，并在生成结果里标注假设。比如“中心”默认指当前工作平面的原点，“通孔”默认直径 10mm，除非文本里明确写了其他数值。生成后在日志里输出：“假设：中心孔直径 10mm，位置为顶面中心”。这样即使生成结果不对，你也能快速定位是哪个假设出了问题。
实操心得：把每次文本描述的原始输入、解析出的参数、生成结果的关键尺寸都记到日志里。积累一段时间后，你会发现哪些描述方式容易出问题，然后反过来优化你的描述模板。这个过程本身就是 text-to-cad 落地的一部分。
4.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决措施 |
|---|---|---|---|
| 导入切片软件显示破面 | STL 网格不封闭 | 用 Meshmixer 检查 | 调整导出公差，检查布尔运算 |
| 模型尺寸差倍数 | 单位不统一 | 打印包围盒尺寸 | 解析层强制统一为毫米 |
| 圆孔变成多边形 | STL 公差太大 | 观察孔壁面数 | 减小 tolerance 到 0.01 以下 |
| 布尔运算失败 | 实体相切或共面 | 检查特征位置关系 | 留 0.5-1mm 余量 |
| 批量生成中断 | 某个规格参数异常 | 查看报错日志 | 加 try-except 逐条捕获 |
| STEP 导入 CAD 后无法编辑 | 导出时丢失特征 | 检查导出设置 | 确保导出 B-rep 而非网格 |
| GLB 文件过大 | 网格密度过高 | 查看三角面数量 | 降低导出精度或做减面处理 |
5. 工具选型与扩展方向
5.1 开源方案与商业方案的取舍
开源方案里，CadQuery + FreeCAD 是我最推荐的组合，灵活、免费、社区活跃。OpenSCAD 更简单，但只支持 CSG 运算，复杂曲面吃力。商业方案里，一些主流 CAD 软件开始内置脚本化和 API 接口，能实现类似效果，但授权成本高，而且脚本环境封闭。
我的建议是：个人学习和小批量用开源方案，团队协作和工程化部署再考虑商业方案。开源方案的一个隐藏优势是生成脚本可以纳入 Git 管理，每次修改都有记录，模型可复现。这在工程场景里非常重要。
5.2 从 text-to-cad 到 text-to-3d-print 的延伸
生成模型只是第一步，后面还有切片、打印、后处理。我现在的流程是：text-to-cad 生成 STL → 用命令行切片工具（比如 PrusaSlicer 的命令行模式）自动切片 → 输出 G-code → 送打印机。整条链路可以脚本化，从文本描述到打印文件全自动。
这个延伸方向的价值在于，它把“想法到实物”的路径缩短到了极致。当然，前提是你的描述足够精确，生成的模型足够可靠。对于简单结构件，这条路已经跑得通了。
5.3 我个人的几条经验总结
第一，不要追求一步到位。先从最简单的长方体、圆柱开始，把文本解析、几何生成、格式导出这条链路跑通，再逐步增加复杂度。我见过太多人一上来就想做“任意文本生成任意模型”，结果卡在解析层就放弃了。
第二，生成结果一定要人工检查。text-to-cad 是助手不是替代品，尤其是涉及装配配合、公差链、受力结构的零件，生成后必须用 CAD 软件打开检查，确认尺寸、特征、坐标系都正确。
第三，积累自己的模板库和描述模板。每次做一个新类型零件，就把参数化脚本存下来，下次遇到类似结构直接复用。时间长了，你的模板库就是你的核心竞争力。
第四，关注 STEP 的版本兼容性。不同 CAD 软件对 STEP 协议的支持有差异，导出时如果遇到导入失败，可以尝试切换 AP214 和 AP203 两种协议。CadQuery 默认导出 AP214，大多数场景够用。
最后再分享一个小技巧：如果你手头有现成的 CAD 图纸或者 STL 模型，想反推参数化脚本，可以用 FreeCAD 的 Python 控制台逐步操作一遍，它会记录每一步的 API 调用。把这些调用整理成函数，就是一个现成的参数化模板。这个方法比从零写脚本快得多，而且生成的几何和原模型一致。
