text-to-cad实战：Python驱动参数化建模与STEP/URDF导出

1. 从一句话到三维模型：text-to-cad 到底在解决什么问题

第一次听到 “text-to-cad” 这个说法，很多人会以为是某个新出的 CAD 插件，或者某个厂商的营销概念。其实把它拆开看就清楚了：text 是自然语言描述，cad 是计算机辅助设计模型，中间那条横线代表一条自动化的转换链路。你输入一句“一个长 80mm、宽 40mm、高 20mm 的带圆角底座，四角各有一个直径 6mm 的通孔”，系统输出一个可以被 CAD 软件打开、可以被仿真工具加载、可以被 3D 打印机切片的三维模型文件。这就是 text-to-cad 最朴素的定义。

它解决的问题非常具体。传统建模流程里，一个结构工程师拿到需求，要先在脑子里把尺寸关系理清楚，再打开 SolidWorks、Fusion 360 或者中望 CAD，一步步拉伸、切除、倒角、打孔。一个简单零件可能十几分钟，一个带装配关系的复杂结构可能几个小时。而 text-to-cad 想做的事情，是把“描述需求”和“得到模型”之间的手工操作压缩掉，让文本直接驱动几何生成。对于需要批量出模型、快速验证设计意图、或者做参数化系列产品的场景，这个价值是实打实的。

适合关注这个方向的人其实比想象中多。做机械设计的工程师可以用它快速出初版方案；做机器人仿真的同学可以用它生成 URDF 里的连杆几何；做 3D 打印的玩家可以用它把脑子里的想法直接变成 STL；甚至做工业设计的学生，也可以用它来快速对比不同尺寸方案的外观比例。核心关键词 text-to-cad、CAD、STEP、URDF、Python 基本覆盖了这条链路的两端：一端是自然语言和 Python 脚本，另一端是 STEP 这种通用三维交换格式和 URDF 这种机器人描述格式。

需要先说明一点：text-to-cad 目前并不是一个“说一句话就给你一个完美工程图”的魔法。它更像是一个参数化建模的自动化前端，把文本解析成结构化的几何参数，再调用底层几何内核去生成实体。理解这一点，后面的所有实操和坑才有意义。

2. 整体设计思路：为什么是 Python + 几何内核 + STEP/URDF

2.1 为什么选 Python 作为胶水层

这条链路里，Python 的角色不是“画图工具”，而是编排层。自然语言解析、参数校验、几何内核调用、文件导出，这些环节需要一个既能快速写逻辑、又有大量现成库的语言来串起来。Python 在这件事上有几个现实优势：文本处理库丰富，调用 C++ 几何内核的绑定成熟，生成 URDF 这种 XML 结构也方便。热搜词里频繁出现 python安装、python教程、python安装numpy库的方法，说明大量想尝试这个方向的人其实卡在环境这一步，而不是卡在几何算法上。

我自己的选择逻辑很简单：如果一件事需要频繁改参数、频繁试错，就用 Python。text-to-cad 的早期阶段一定是在反复调尺寸、调约束、调导出格式，用 Python 写脚本改一行就能重跑，比在 GUI 里点来点去快得多。

2.2 几何内核的选型考量

真正把参数变成实体的是几何内核。常见的有 OpenCASCADE（通过 PythonOCC 或 CadQuery 调用）、以及一些轻量级的网格生成库。选型的核心矛盾是：要 B-Rep 实体还是网格。如果你最终要导出 STEP，那必须用支持 B-Rep 的内核，因为 STEP 本质上是边界表示格式，记录的是面、边、顶点的拓扑关系，不是三角面片。如果你只是要 3D 打印的 STL，那网格库也能凑合，但精度和后续编辑能力差很多。

提示：STEP 和 STL 的区别，可以理解成“矢量图”和“位图”。STEP 记录的是几何定义，放大不损失精度，能被专业 CAD 继续编辑；STL 是一堆三角面片，放大会看到棱角，基本只能用于打印或显示。

2.3 为什么输出要同时考虑 STEP 和 URDF

这两个格式面向的是完全不同的下游。STEP 面向通用 CAD 和制造，你导出的模型可以发给供应商、导入中望 CAD 或者任何主流软件继续加工。URDF 面向机器人仿真，它描述的是连杆之间的运动学关系，几何只是其中一部分，还要定义关节类型、坐标系、惯性矩阵。热搜里出现 urdf导入coppeliasim，说明很多人做 text-to-cad 的最终目的是把生成的模型丢进仿真环境里跑。

所以一个完整的 text-to-cad 方案，设计上应该是一份参数，多路导出：同一组几何参数，既能生成 STEP 给制造，也能生成 URDF 给仿真。这也是为什么中间层要用结构化的数据格式，而不是直接拼字符串。

3. 核心细节解析：文本怎么变成几何参数

3.1 文本解析的三种务实做法

自然语言转结构化参数，听起来很 AI，但实际落地时我建议分三档来做，按复杂度递增：

第一档是模板匹配。预先定义好句式，比如“长 X 宽 Y 高 Z 的底座，四角直径 D 的通孔”，用正则表达式把数字抠出来。这种做法最稳，适合参数系列固定的产品，缺点是只能处理预设句式。

第二档是关键词加单位识别。扫描文本里的“长”“宽”“高”“直径”“半径”“圆角”“通孔”等词，结合后面的数字和单位（mm、cm、m）建立参数字典。这一档能覆盖大部分工程描述，实现难度适中。

第三档才是调用大模型做语义解析，把自由文本转成 JSON 参数。这一档最灵活，但引入了不确定性，需要做严格的参数校验和兜底。

我实际用下来，第二档性价比最高。纯模板太死，纯大模型太飘，关键词加单位识别既能处理一定程度的自由表达，又能保证参数可预测。

3.2 参数校验：最容易被忽略但最要命的一步

文本解析出来的数字，不能直接喂给几何内核。必须做校验，否则会生成一堆无效实体甚至让内核崩溃。校验至少包括：

• 数值范围：长宽高不能为负，不能为零，不能大到超出内核精度。
• 几何可行性：通孔直径不能大于底座最小边，圆角半径不能大于最小厚度的一半。
• 单位统一：文本里可能混用 mm 和 cm，必须统一到毫米。
• 约束冲突：如果同时指定了总长和两侧边距，要检查加起来是否超过总长。

def validate_params(p): errors = [] if p["length"] <= 0 or p["width"] <= 0 or p["height"] <= 0: errors.append("尺寸必须为正数") if p["hole_dia"] >= min(p["length"], p["width"]): errors.append("通孔直径超过底座最小边") if p["fillet_r"] > min(p["length"], p["width"], p["height"]) / 2: errors.append("圆角半径过大") return errors

这段校验逻辑看着简单，但能挡掉八成以上的低级错误。踩过的坑：有一次文本里写的是“直径 60mm 的孔”，但底座宽度只有 50mm，如果不校验，内核会生成一个穿透侧壁的畸形实体，导出 STEP 后打开一看全是破面，排查半天才发现是参数本身矛盾。

3.3 坐标系与基准面的约定

几何生成前必须约定清楚坐标系。我的习惯是：底座底面中心为原点，Z 轴向上，X 轴沿长度方向，Y 轴沿宽度方向。这个约定要和后续 URDF 的连杆坐标系对齐，否则导入仿真环境后模型姿态会乱。热搜里 cad导入layout步骤详解 这类问题，很多就是坐标系没对齐导致的。

4. 实操过程：从零搭一条可复现的生成链路

4.1 环境准备与依赖安装

先把环境弄干净。我建议用虚拟环境，避免和系统里的其他 Python 包打架。

python -m venv tcad_env source tcad_env/bin/activate # Windows 用 tcad_env\Scripts\activate pip install cadquery pip install numpy

CadQuery 是我常用的几何库，它封装了 OpenCASCADE，能用接近 Python 原生语法的方式描述实体，导出 STEP 也很方便。numpy 用于后续做参数计算和矩阵运算。如果你用的是其他内核，思路一样，换库即可。

注意：安装几何内核相关的库时，如果报 C++ 运行库缺失的错，先装对应的运行库再重试。热搜里 cad安装一直出现c++2005cpi错误 是同类问题，本质是底层依赖没装全。

4.2 参数解析模块实现

import re UNIT_MAP = {"mm": 1.0, "cm": 10.0, "m": 1000.0} def parse_text(text): params = {} # 匹配 "长 80mm" 这类描述 patterns = { "length": r"长\s*([\d.]+)\s*(mm|cm|m)?", "width": r"宽\s*([\d.]+)\s*(mm|cm|m)?", "height": r"高\s*([\d.]+)\s*(mm|cm|m)?", "hole_dia": r"(?:通孔|孔)\s*(?:直径)?\s*([\d.]+)\s*(mm|cm|m)?", "fillet_r": r"圆角\s*(?:半径)?\s*([\d.]+)\s*(mm|cm|m)?", } for key, pat in patterns.items(): m = re.search(pat, text) if m: value = float(m.group(1)) unit = m.group(2) or "mm" params[key] = value * UNIT_MAP[unit] return params

这段代码的核心是把单位换算内嵌进解析过程，避免后面再单独处理。实测下来，把单位在入口处统一，能省掉大量后续的换算错误。

4.3 几何生成与 STEP 导出

import cadquery as cq def build_base(p): # 底座主体 base = ( cq.Workplane("XY") .box(p["length"], p["width"], p["height"]) .edges("|Z") .fillet(p["fillet_r"]) ) # 四角通孔 dx = p["length"] / 2 - p["hole_dia"] dy = p["width"] / 2 - p["hole_dia"] base = ( base.faces(">Z") .workplane() .pushPoints([(dx, dy), (-dx, dy), (-dx, -dy), (dx, -dy)]) .hole(p["hole_dia"]) ) return base def export_step(model, path): cq.exporters.export(model, path)

这里有几个细节值得说。倒角要在打孔之前做，否则孔边缘的倒角会干扰圆角计算。孔的位置用中心偏移计算，dx 和 dy 留出至少一个孔径的边距，避免孔壁太薄。导出时 CadQuery 会自动处理 B-Rep 拓扑，生成的 STEP 可以直接被中望 CAD 或任何主流软件打开。

4.4 URDF 生成：把几何和运动学绑在一起

URDF 本质是一个 XML 文件，描述连杆和关节。几何部分可以引用 STEP 或者 STL，运动学部分定义关节轴和坐标系。

def build_urdf(link_name, mesh_path, mass=1.0): urdf = f"""<?xml version="1.0"?> <robot name="generated"> <link name="{link_name}"> <visual> <geometry> <mesh filename="{mesh_path}"/> </geometry> </visual> <collision> <geometry> <mesh filename="{mesh_path}"/> </geometry> </collision> <inertial> <mass value="{mass}"/> <inertia ixx="0.01" ixy="0" ixz="0" iyy="0.01" iyz="0" izz="0.01"/> </inertial> </link> </robot>""" return urdf

惯性矩阵这里先给了一个占位值，实际使用时需要根据几何和质量重新计算。踩过的坑：如果惯性矩阵给得不合理，导入仿真环境后模型会抖动甚至飞出去。热搜里 urdf导入coppeliasim 遇到的问题，相当一部分是惯性参数没配对。

4.5 完整调用流程

text = "长 80mm 宽 40mm 高 20mm 的底座，四角直径 6mm 的通孔，圆角半径 3mm" params = parse_text(text) errors = validate_params(params) if errors: print("参数错误:", errors) else: model = build_base(params) export_step(model, "base.step") urdf = build_urdf("base_link", "base.step") with open("base.urdf", "w") as f: f.write(urdf)

这条链路跑通之后，改一句文本就能重新生成模型，效率比手工建模高一个数量级。

5. 常见问题与排查技巧实录

5.1 参数解析类问题

5.2 几何生成类问题

最常见的报错是内核抛出拓扑异常，通常是因为参数组合导致了几何自交或者零厚度。排查顺序是：先单独生成主体，确认没问题；再加倒角；最后打孔。一步一步加特征，哪一步崩了就说明那一步的参数有问题。这个思路和手工建模时“分步检查草图”是一个道理。

另一个高频问题是导出 STEP 后打开是空文件或者破面。这通常是倒角半径过大，导致相邻面之间产生了退化边。把圆角半径调小一点，或者改成只对部分边倒角，基本能解决。

5.3 URDF 导入仿真环境的问题

导入后模型位置不对，九成是坐标系原点没对齐。URDF 里每个 link 的视觉几何默认以 link 坐标系为基准，如果你的 STEP 模型原点不在几何中心或者底面中心，导入后就会偏移。解决办法是在生成 STEP 时就约定好原点位置，或者在 URDF 里加一个 origin 偏移。

模型导入后没有碰撞效果，检查 collision 标签是否引用了正确的 mesh。有些仿真环境对 collision mesh 的面数有要求，太复杂的网格会拖慢碰撞检测，必要时用简化后的凸包代替。

5.4 独家避坑技巧

• 参数留余量：文本里给的尺寸往往是名义值，实际生成时留 0.1mm 的余量，避免因为浮点误差导致面重合。
• 文件名别用中文：STEP 和 URDF 的路径里如果有中文，某些内核和仿真环境会读取出错，统一用英文加下划线。
• 版本锁定：几何库的 API 在不同版本间可能变化，项目里固定版本号，避免换环境后跑不起来。
• 批量生成时加日志：一次生成几十个模型时，把每个模型的参数和导出路径写进日志，出问题能快速定位是哪个参数组合。

6. 这条链路还能怎么扩展

把基础链路跑通之后，扩展方向其实很多。参数化系列产品是最直接的应用：把尺寸做成变量，批量生成不同规格的模型，导出 STEP 发给供应商。和仿真流程打通是另一个方向：生成的 URDF 直接加载进仿真环境，验证运动学是否正确，再回头调整几何参数。反向解析也很有意思：给一张工程图或者一段现有模型的尺寸标注，自动提取参数，重建模型。

我个人在实际操作中的体会是，text-to-cad 的价值不在于完全替代手工建模，而在于把重复性的、参数驱动的建模工作自动化。真正复杂的设计决策还是得靠人，但那些“改个尺寸重新出一版”的活，交给脚本去做，省下来的时间可以用来想更值得想的问题。最后再分享一个小技巧：把常用的参数组合存成 JSON 配置文件，文本解析和配置读取走同一套参数结构，这样既能用自然语言快速试，也能用配置文件做精确控制，两条路互不干扰。