1. 项目缘起与核心思路拆解
第一次听到 text-to-cad 这个词，我的直觉是：终于有人把“嘴炮出图”这件事往工程方向推了。过去我们做 CAD 建模，流程基本是固定的——打开软件、画草图、拉伸、倒角、装配，一套下来少说半小时，复杂的零件图能耗掉一整个下午。而 text-to-cad 想做的事情很直接：你用自然语言描述一个零件，比如“一个 80x60x10 的底板，四角各有一个直径 6 的通孔，孔中心距边缘 10 毫米”，系统直接吐出可用的 CAD 文件，格式通常是 STEP，有时候还会附带 URDF 用于机器人仿真。
这个项目的核心价值不在于“炫技”，而在于它切中了一个真实痛点：重复性建模工作太多，而工程师的时间应该花在真正的设计决策上。我见过太多人每天在画标准件、改孔位、调壁厚，这些事情完全可以用程序生成。text-to-cad 就是把“程序生成”这一步的门槛从“你得会写 OpenSCAD 或 CadQuery”降到“你得会说话”。
从技术路径上看，目前主流的 text-to-cad 方案大致分两派。一派是基于大语言模型直接生成 CAD 脚本，比如让模型输出 CadQuery 或 OpenSCAD 代码，再执行代码得到 STEP 文件。另一派是基于参数化模板加语义解析，先把常见零件抽象成模板库，再用自然语言匹配参数。两派各有优劣：前者灵活但容易出错，后者稳定但覆盖范围有限。我实际测试下来，混合方案最靠谱——用 LLM 做意图理解和参数抽取，用模板库做几何生成，最后用 CadQuery 或 build123d 做布尔运算和导出。
为什么选 Python 作为主力语言？因为 CAD 领域的开源生态几乎都围绕 Python 转。CadQuery 基于 OpenCASCADE，能直接输出 STEP、STL、DXF；build123d 是它的后继者，API 更现代；pythonocc 更底层但更灵活。再加上 Python 在数据处理、自动化脚本、与 URDF 转换库的衔接上都有天然优势，所以 text-to-cad 用 Python 实现几乎是必然选择。
还有一个关键点：STEP 和 URDF 是两种完全不同的输出目标。STEP 是通用 CAD 交换格式，关注几何精度和制造可行性；URDF 是机器人描述格式，关注连杆、关节、惯性矩阵。text-to-cad 如果同时支持这两种输出，就意味着它不仅能服务机械设计，还能服务机器人仿真。这一点在热词里出现“urdf导入coppeliasim”就能看出来——用户确实有把 CAD 模型直接丢进仿真环境的需求。
2. 核心细节解析与实操要点
2.1 自然语言到参数的映射逻辑
text-to-cad 最核心的一步是把“人话”翻译成“参数”。比如用户说“一块 100 毫米长、50 毫米宽、5 毫米厚的板，中间挖一个直径 20 的圆孔”，系统需要抽取出：长度=100，宽度=50，厚度=5，孔直径=20，孔位置=中心。这一步看起来简单，但实际做起来坑很多。
第一个坑是单位歧义。用户可能说“10 厘米”也可能说“100 毫米”，还可能只说“100”而不带单位。我的做法是：默认单位设为毫米，但在解析时检测常见单位词（厘米、米、英寸），并做统一转换。如果用户完全没提单位，就在返回结果里显式标注“假设单位为毫米”，让用户确认。
第二个坑是空间关系描述。用户说“孔在角落”，这个“角落”到底是哪个角？距离边缘多少？我的处理方式是：把模糊描述映射到一组默认值，比如“角落”默认距两边各 10 毫米，然后在输出时说明“已按默认边距 10 毫米处理，如需调整请指定”。这样既不会卡住流程，又给了用户修正的机会。
第三个坑是特征顺序。先打孔再倒角，和先倒角再打孔，结果可能完全不同。text-to-cad 需要根据特征类型自动排序：通常先做主体形状，再做减材特征（孔、槽），最后做倒角、圆角。这个顺序在 CadQuery 里体现为布尔运算的先后关系，写错了就会报错或者得到奇怪的结果。
2.2 CadQuery 与 build123d 的选型对比
我一开始用的是 CadQuery，因为它文档多、社区大、例子丰富。但用了一段时间后发现，CadQuery 的链式 API 在复杂模型上会变得很难读，而且调试困难。后来转到 build123d，感觉像是从 jQuery 换到了 React——更结构化，更符合直觉。
| 对比项 | CadQuery | build123d |
|---|---|---|
| API 风格 | 链式调用，fluent 风格 | 上下文管理器，面向对象 |
| 学习曲线 | 较低，例子多 | 中等，但逻辑更清晰 |
| 布尔运算 | 直接支持 | 直接支持，且支持代数模式 |
| 导出格式 | STEP、STL、DXF、AMF | STEP、STL、DXF、SVG |
| 调试体验 | 报错信息较模糊 | 报错更具体，容易定位 |
| 社区活跃度 | 高，但更新放缓 | 快速增长中 |
实测下来，如果你的 text-to-cad 项目需要快速原型，CadQuery 够用；如果打算长期维护、支持复杂装配，build123d 更合适。我现在的做法是：简单零件用 CadQuery，复杂装配用 build123d，两者都封装成统一的生成接口，上层根据模型复杂度自动路由。
2.3 URDF 转换的关键参数
把 CAD 模型转成 URDF 不是简单导出就完事。URDF 需要每个连杆的质量、惯性矩阵、碰撞体、视觉体。CAD 模型通常只有几何信息，没有材料和惯性数据。我的处理流程是：
- 从 STEP 文件读取几何体，计算体积。
- 根据用户指定的材料密度（默认钢 7850 kg/m³，铝 2700 kg/m³）计算质量。
- 用几何体的包围盒或凸包近似计算惯性矩阵。
- 生成 URDF 的 link 和 joint 标签，joint 默认设为 fixed，除非用户指定运动副。
这里有个经验：惯性矩阵的精度对仿真稳定性影响很大。如果只是做运动学仿真，用包围盒近似就够了；如果做动力学仿真，最好用 CAD 软件先算好惯性张量再导入。我一般会在 URDF 里加一个注释，说明惯性数据的来源和精度等级。
3. 实操过程与核心环节实现
3.1 环境搭建与依赖安装
先搞定 Python 环境。我推荐用 Python 3.10 或 3.11，太新的版本有些 CAD 库还没适配。安装命令如下：
python -m venv text2cad-env source text2cad-env/bin/activate # Linux/Mac text2cad-env\Scripts\activate # Windows pip install cadquery build123d numpy scipy pip install openai # 如果要用 LLM 做语义解析如果安装 cadquery 时报错，大概率是 OpenCASCADE 的依赖没装好。Ubuntu 下需要先装：
sudo apt-get install libocct-* occt-miscWindows 下通常 pip 直接能装上，但如果遇到 C++ 2005 运行时错误，去微软官网下载对应的 redistributable 包安装即可。这个问题在热词里也出现了，说明是常见坑。
3.2 语义解析模块的实现
我用 OpenAI 的 API 做意图理解，prompt 设计如下：
import openai import json SYSTEM_PROMPT = """ 你是一个 CAD 参数抽取助手。用户会用自然语言描述一个零件， 你需要输出 JSON 格式的参数。字段包括： - shape_type: 零件类型，如 plate, cylinder, bracket - dimensions: 尺寸字典，如 {"length": 100, "width": 50, "thickness": 5} - features: 特征列表，每个特征包含 type, position, size - material: 材料，默认 steel - unit: 单位，默认 mm 只输出 JSON，不要解释。 """ def parse_description(text): response = openai.ChatCompletion.create( model="gpt-4", messages=[ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": text} ], temperature=0 ) return json.loads(response.choices[0].message.content)这个 prompt 的关键是强制 JSON 输出和默认值设定。temperature 设为 0 是为了保证每次解析结果一致，避免同一个描述生成不同参数。
3.3 几何生成与 STEP 导出
拿到参数后，用 build123d 生成几何体：
from build123d import * def generate_plate(params): dims = params["dimensions"] with BuildPart() as plate: Box(dims["length"], dims["width"], dims["thickness"]) for feat in params.get("features", []): if feat["type"] == "hole": with Locations((feat["position"]["x"], feat["position"]["y"], 0)): Hole(radius=feat["size"]["diameter"] / 2) return plate.part def export_step(part, filename): export_step(part, filename) print(f"STEP 文件已导出：{filename}")这段代码里，Locations用来定位孔的位置，Hole会自动做减材布尔运算。注意孔的深度默认是贯穿整个零件，如果需要盲孔，要额外指定深度参数。
3.4 URDF 生成与验证
URDF 生成我用的是urdfpy和trimesh组合：
import trimesh from urdfpy import URDF def step_to_urdf(step_file, urdf_file, density=7850): mesh = trimesh.load(step_file) mass = mesh.volume * 1e-9 * density # mm³ 转 m³ inertia = mesh.moment_inertia * 1e-9 * density urdf_content = f"""<?xml version="1.0"?> <robot name="generated_part"> <link name="base_link"> <visual> <geometry> <mesh filename="{step_file}"/> </geometry> </visual> <collision> <geometry> <mesh filename="{step_file}"/> </geometry> </collision> <inertial> <mass value="{mass}"/> <inertia ixx="{inertia[0][0]}" ixy="{inertia[0][1]}" ixz="{inertia[0][2]}" iyy="{inertia[1][1]}" iyz="{inertia[1][2]}" izz="{inertia[2][2]}"/> </inertial> </link> </robot>""" with open(urdf_file, "w") as f: f.write(urdf_content)生成后一定要用check_urdf工具验证：
check_urdf generated_part.urdf如果报错，通常是惯性矩阵不是正定矩阵，或者 mesh 路径不对。惯性矩阵的问题可以通过调整密度或使用凸包近似来解决。
4. 常见问题与排查技巧实录
4.1 语义解析偏差与修正
问题：用户说“一个圆盘，直径 100，厚 10，中间有个 20 的孔”，模型解析成圆柱体但孔没打穿。
排查：检查 JSON 输出，发现 features 里 hole 的 depth 字段缺失，默认值被设成了 0。
解决：在 prompt 里明确“如果未指定深度，默认贯穿”，并在代码里做二次校验——如果 depth 为 0 或 None，自动设为零件厚度加 1。
4.2 STEP 导出失败与几何修复
问题：导出 STEP 时报错“BRepCheck failed”，模型有自相交或微小边。
排查：用part.is_valid()检查，发现布尔运算后产生了退化边。
解决：在布尔运算后加一步clean()，或者用fix()修复。如果还不行，把公差从默认的 1e-6 放宽到 1e-4。
4.3 URDF 导入 CoppeliaSim 的注意事项
热词里有人问“urdf导入coppeliasim”，我实测下来有几个坑：
- CoppeliaSim 对 URDF 的 mesh 路径很敏感，最好用绝对路径或把 mesh 放在 URDF 同目录。
- 惯性矩阵如果太小（比如质量设成了 0.001 kg），仿真会抖动。建议质量至少 0.1 kg。
- joint 的 origin 要仔细核对，否则装配体会错位。
4.4 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 解析出的尺寸单位不对 | 用户未指定单位 | 默认 mm，输出时标注 |
| 孔位置偏移 | 坐标系原点不明确 | 统一以零件底面中心为原点 |
| STEP 导出报错 | 几何自相交 | 加 clean() 或放宽公差 |
| URDF 仿真抖动 | 惯性矩阵过小 | 调整密度或质量下限 |
| LLM 返回非 JSON | prompt 不够严格 | 加“只输出 JSON”并设 temperature=0 |
| 复杂模型生成慢 | 布尔运算过多 | 合并特征，减少运算次数 |
4.5 独家避坑技巧
技巧一：参数范围校验。在生成几何前，先检查尺寸是否合理。比如厚度不能为负，孔直径不能大于零件宽度。我写了一个validate_params函数，把常见错误挡在生成之前，省得后面报一堆几何错误。
技巧二：缓存 LLM 解析结果。同一个描述反复解析会浪费 token，而且结果可能不一致。我用functools.lru_cache把解析结果缓存起来，key 是描述文本的 hash。
技巧三：分步导出。先导出 STL 快速预览，确认形状对了再导出 STEP。STL 导出快，STEP 导出慢，这样能节省大量调试时间。
技巧四：URDF 的 mesh 用 STL 而不是 STEP。CoppeliaSim 和 Gazebo 对 STL 的支持更好，STEP 有时候会丢面。我一般同时导出 STL 和 STEP，URDF 里引用 STL，制造用 STEP。
5. 扩展方向与个人体会
text-to-cad 目前还处在“能用但不够好用”的阶段。我实际跑下来，简单零件（板、轴、支架）的生成成功率大概八成，复杂装配（多零件、运动副）就掉到五成以下。主要瓶颈在于：LLM 对空间关系的理解还不够精确，而且 CAD 的几何约束逻辑和自然语言的模糊性之间有天然鸿沟。
下一步我打算做两件事：一是引入草图约束求解器，让用户可以用“平行”“垂直”“相切”这类约束词，而不是只给具体尺寸；二是支持多轮对话修正，用户说“孔再往左移 5 毫米”，系统能基于上一版模型做增量修改，而不是重新生成。
另外，热词里出现“python批量对cad修改”，这其实和 text-to-cad 是互补的。批量修改是“已有模型改参数”，text-to-cad 是“从零生成模型”。如果能把两者结合——先用 text-to-cad 生成基础模型，再用批量脚本做变体——那效率提升会非常明显。我在一个项目里试过这个组合，原本需要两天画完的系列零件，半天就搞定了。
最后分享一个小技巧：把常用零件做成模板库。比如法兰、轴承座、齿轮这些标准件，没必要每次都让 LLM 解析，直接匹配关键词调模板，速度快而且结果稳定。LLM 只用来处理非标零件和复杂描述。这个策略我用了三个月，生成成功率从六成提到了九成以上。
