text-to-cad实战：用Python将自然语言生成STEP与URDF三维模型

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

第一次听到 text-to-cad 这个词，很多人脑子里浮现的画面大概是：对着电脑敲一句“给我画一个长宽高 100×60×40 的带圆角盒子”，然后屏幕上就自动出现一个可以旋转、可以导出、可以继续编辑的三维模型。这个画面放在几年前还属于科幻范畴，但现在已经有一批开源项目和商业工具把它做成了能跑通的流程。text-to-cad 的核心，就是把自然语言描述转换成计算机辅助设计软件能够识别的几何数据，最终落地成 STEP、STL、URDF 这类标准格式文件。

这件事为什么值得关注？因为传统 CAD 建模的门槛并不低。你得先学会草图约束、拉伸切除、倒角圆角、装配配合这一整套操作逻辑，还得熟悉具体软件的界面和快捷键。对于机械工程师来说这不算什么，但对于做机器人仿真的、做强化学习环境搭建的、做快速原型验证的开发者来说，为了一个简单的几何体去啃 CAD 软件，时间成本太高了。text-to-cad 瞄准的就是这个缝隙：让描述需求的人不需要成为 CAD 专家，也能拿到可用的几何文件。

从热搜词也能看出这个领域的真实需求分布。一边是大量“cad安装”“cad教程”“cad制图初学入门”这类基础搜索，说明 CAD 的入门门槛依然是很多人的痛点；另一边是“urdf导入coppeliasim”“python构建邻接矩阵”“python批量对cad修改”这类偏开发向的搜索，说明已经有一批人在用 Python 做 CAD 相关的自动化处理。text-to-cad 正好卡在这两拨人中间：它既需要理解 CAD 的几何语义，又需要用 Python 这类编程语言来实现自动化生成。

这篇文章适合谁看？如果你是做机器人仿真的，需要批量生成 URDF 模型；如果你是做算法验证的，需要快速构造带特定参数的几何体；如果你是做 CAD 二次开发的，想了解怎么用 Python 操作几何数据；或者你只是对“用文字生成模型”这件事好奇，想看看背后到底是怎么实现的——那接下来的内容应该对你有用。我会从整体设计思路讲起，然后拆解核心实现细节，再给出一套可以跟着做的实操流程，最后把常见的坑和排查方法整理出来。

2. 整体设计思路：为什么是 Python + STEP + URDF 这套组合

2.1 核心架构的选型逻辑

text-to-cad 的实现路径可以粗略分成两大流派。一派是“生成式”路线，用大模型直接输出几何代码或者点云，再后处理成 CAD 格式；另一派是“参数化”路线，先把自然语言解析成结构化的参数，再调用几何内核生成模型。两条路线各有优劣，但落到实际工程里，参数化路线更可控、更可调试、更容易保证几何有效性。

我倾向于用 Python 作为主语言，原因很直接：几何处理生态成熟。cadquery、build123d、trimesh、numpy-stl这些库覆盖了从参数化建模到网格处理的全流程。而且 Python 的字符串处理和自然语言解析能力也够用，不需要为了解析一句话去引入额外的重型依赖。热搜词里“python安装”“python安装numpy库的方法”“python环境变量配置”出现频率很高，说明大量用户本身就在 Python 生态里工作，用 Python 做 text-to-cad 的落地语言，学习成本最低。

输出格式选 STEP 和 URDF 也是有讲究的。STEP 是 CAD 领域的通用交换格式，几乎所有主流 CAD 软件都能读写，适合做后续的编辑和加工。URDF 是机器人描述格式，专门用来描述刚体、关节、连杆之间的运动学关系，适合做仿真和运动规划。一个 text-to-cad 工具如果只能输出 STL，那它只能用于 3D 打印或者可视化；如果能输出 STEP 和 URDF，那它的应用场景就扩展到了机械设计和机器人仿真两个大领域。

2.2 自然语言到几何参数的映射策略

把“一个长 100 宽 60 高 40 的盒子，四个角倒 R5 圆角”这句话变成几何模型，中间需要经过几步转换。第一步是实体识别：找出“盒子”这个几何类型，找出“长 100 宽 60 高 40”这组尺寸参数，找出“R5 圆角”这个特征操作。第二步是参数归一化：把“长宽高”映射到几何内核能理解的length、width、height变量，把“R5”映射到fillet_radius=5。第三步是代码生成：根据几何类型和参数，拼出一段调用几何内核的 Python 代码。第四步是执行与验证：跑这段代码，检查生成的几何体是否有效，体积、包围盒是否符合预期。

这个流程里最容易被低估的是第三步和第四步。很多人以为只要把参数提取出来就完事了，实际上几何内核的 API 调用有很多细节：倒圆角的边怎么选、坐标系怎么定、单位怎么统一。而且生成的几何体不一定有效，比如圆角半径大于了最小边长的一半，内核会直接报错。所以一个健壮的 text-to-cad 流程必须包含几何有效性检查。

2.3 为什么不用端到端大模型直接生成

有人会问：现在大模型这么强，为什么不直接让模型输出 STEP 文件？原因在于几何数据的表示方式。STEP 文件本质上是边界表示（BRep）的文本描述，包含大量的拓扑和几何信息，直接让语言模型生成这种结构化数据，出错率极高，而且生成的模型往往拓扑无效，无法被 CAD 软件正常打开。相比之下，让模型生成一段调用几何内核的 Python 代码，再由内核去保证几何有效性，是更稳妥的做法。这也是目前大多数 text-to-cad 开源项目的共同选择。

3. 核心细节解析：几何内核、参数提取与格式转换

3.1 几何内核的选择与对比

Python 生态里能做参数化建模的库主要有几个，选哪个直接决定了后续的开发体验。

我实测下来，cadquery 是 text-to-cad 场景下最平衡的选择。它的 API 设计接近自然语言，比如cq.Workplane("XY").box(100, 60, 40).edges("|Z").fillet(5)这一行就完成了“在 XY 平面上画一个 100×60×40 的盒子，对 Z 方向的边倒 R5 圆角”的全部操作。这种表达方式很容易和自然语言描述对应起来，也方便做代码生成。

安装 cadquery 有个坑要注意：它依赖 OpenCASCADE 的 Python 绑定，在 Windows 上直接用 pip 安装有时会因为缺少 C++ 运行库而失败。热搜词里“安装cad一直出现c++2005cpi错误”虽然说的是 CAD 软件本身，但 cadquery 的安装也会遇到类似的运行库问题。稳妥的做法是先装好 Visual C++ Redistributable，再用 conda 安装 cadquery，比 pip 省心很多。

conda install -c conda-forge cadquery

如果坚持用 pip，建议先升级 pip 和 setuptools，再安装：

python -m pip install --upgrade pip setuptools wheel pip install cadquery

3.2 自然语言参数提取的实现细节

参数提取这块，可以用规则匹配，也可以用大模型做意图识别。规则匹配适合格式固定的描述，比如“长 X 宽 Y 高 Z”这种模板化表达；大模型适合处理更自由的语言，比如“帮我做一个差不多巴掌大的方块，边角圆润一点”。实际项目里可以两者结合：先用规则匹配尝试提取，匹配失败再走大模型兜底。

规则匹配的核心是正则表达式加单位归一化。比如下面这段代码可以提取尺寸参数：

import re def extract_dimensions(text): # 匹配 "长100宽60高40" 或 "100x60x40" 或 "100*60*40" patterns = [ r'长\s*(\d+\.?\d*)\s*宽\s*(\d+\.?\d*)\s*高\s*(\d+\.?\d*)', r'(\d+\.?\d*)\s*[xX*×]\s*(\d+\.?\d*)\s*[xX*×]\s*(\d+\.?\d*)', ] for p in patterns: m = re.search(p, text) if m: return tuple(float(g) for g in m.groups()) return None

单位处理是个容易被忽略的细节。CAD 里默认单位通常是毫米，但用户可能说“10 厘米”或者“0.1 米”。如果不做单位归一化，生成的模型尺寸会差一个数量级。我的做法是在提取参数后统一转成毫米，并在代码里显式标注单位。

圆角、倒角这类特征操作的提取也有讲究。“倒 R5 圆角”和“倒角 5mm”是两种不同的操作，前者是圆角（fillet），后者可能是倒角（chamfer）。需要根据关键词区分，并映射到不同的内核 API。

3.3 STEP 与 URDF 的输出差异

STEP 和 URDF 虽然都是三维模型格式，但用途完全不同，输出逻辑也不一样。

STEP 是纯几何格式，描述的是形状本身，不包含运动学信息。cadquery 导出 STEP 很简单：

import cadquery as cq result = cq.Workplane("XY").box(100, 60, 40).edges("|Z").fillet(5) cq.exporters.export(result, "output.step")

URDF 则复杂得多。它描述的是机器人模型，包含 link（连杆）和 joint（关节）的层级关系。一个 URDF 文件里，每个 link 需要指定视觉几何、碰撞几何、惯性参数，每个 joint 需要指定类型、父连杆、子连杆、旋转轴。text-to-cad 生成 URDF 时，通常需要用户额外描述关节信息，比如“这个盒子是一个底座，上面有一个绕 Z 轴旋转的关节，连接一个圆柱体”。

URDF 的几何部分可以引用 STL 或 STEP 文件，也可以直接内嵌几何参数。引用外部文件的方式更常见，因为这样可以把几何和运动学描述分离，方便后续修改。下面是一个简化的 URDF 结构示例：

<robot name="simple_robot"> <link name="base_link"> <visual> <geometry> <box size="0.1 0.06 0.04"/> </geometry> </visual> <collision> <geometry> <box size="0.1 0.06 0.04"/> </geometry> </collision> <inertial> <mass value="1.0"/> <inertia ixx="0.001" ixy="0" ixz="0" iyy="0.001" iyz="0" izz="0.001"/> </inertial> </link> <joint name="joint1" type="revolute"> <parent link="base_link"/> <child link="arm_link"/> <axis xyz="0 0 1"/> <limit lower="-1.57" upper="1.57" effort="10" velocity="1.0"/> </joint> </robot>

注意 URDF 里的单位是米，不是毫米。从 STEP 转到 URDF 时，尺寸要除以 1000。这个单位转换如果搞错，导入 CoppeliaSim 或者 Gazebo 后模型会大得离谱或者小得看不见。热搜词里“urdf导入coppeliasim”是个高频操作，很多人第一次导入时都会遇到模型比例不对的问题，根源往往就在这里。

4. 实操过程：从零搭建一个 text-to-cad 流程

4.1 环境准备与依赖安装

先把环境搭起来。我推荐用 conda 创建独立环境，避免和系统里的其他 Python 包冲突。

conda create -n text2cad python=3.10 conda activate text2cad conda install -c conda-forge cadquery pip install numpy trimesh lxml

Python 版本选 3.10 是因为 cadquery 对 3.11 以上的支持还在完善中，3.10 最稳。numpy 用于数值计算，trimesh 用于网格处理，lxml 用于生成 URDF 的 XML 结构。

验证安装是否成功：

import cadquery as cq box = cq.Workplane("XY").box(10, 10, 10) print(box.val().Volume())

如果输出接近 1000，说明环境没问题。如果报错找不到 OpenCASCADE 相关库，检查 conda 环境是否激活，或者重新安装 cadquery。

4.2 自然语言解析模块的实现

解析模块的目标是把一句话拆成结构化的建模指令。我设计的数据结构是这样的：

from dataclasses import dataclass, field from typing import Optional @dataclass class ModelingIntent: shape_type: str # box, cylinder, sphere dimensions: dict # {"length": 100, "width": 60, "height": 40} features: list = field(default_factory=list) # [{"type": "fillet", "radius": 5}] units: str = "mm"

解析函数先做关键词匹配，确定几何类型：

SHAPE_KEYWORDS = { "box": ["盒子", "方块", "长方体", "立方体", "box"], "cylinder": ["圆柱", "圆筒", "cylinder"], "sphere": ["球", "圆球", "sphere"], } def detect_shape(text): for shape, keywords in SHAPE_KEYWORDS.items(): for kw in keywords: if kw in text: return shape return None

然后提取尺寸和特征。特征提取要区分圆角和倒角：

def extract_features(text): features = [] fillet_match = re.search(r'[Rr]\s*(\d+\.?\d*)\s*(?:圆角|倒圆)', text) if fillet_match: features.append({"type": "fillet", "radius": float(fillet_match.group(1))}) chamfer_match = re.search(r'倒角\s*(\d+\.?\d*)', text) if chamfer_match: features.append({"type": "chamfer", "distance": float(chamfer_match.group(1))}) return features

这套规则能覆盖大部分常见描述。遇到“边角圆润一点”这种模糊表达，规则匹配会失败，这时候可以调用大模型做兜底，让模型输出结构化的 JSON，再解析成ModelingIntent。

4.3 几何生成与有效性检查

拿到ModelingIntent后，生成 cadquery 代码并执行：

def build_model(intent): if intent.shape_type == "box": d = intent.dimensions model = cq.Workplane("XY").box(d["length"], d["width"], d["height"]) for feat in intent.features: if feat["type"] == "fillet": model = model.edges("|Z").fillet(feat["radius"]) elif feat["type"] == "chamfer": model = model.edges("|Z").chamfer(feat["distance"]) return model raise ValueError(f"Unsupported shape: {intent.shape_type}")

生成之后必须做有效性检查。检查项包括：体积是否大于零、包围盒尺寸是否和输入参数一致、是否有自相交。cadquery 的val().isValid()可以检查拓扑有效性：

def validate_model(model, intent): solid = model.val() if not solid.isValid(): raise ValueError("Generated geometry is not valid") bb = solid.BoundingBox() expected = intent.dimensions tolerance = 0.1 if abs(bb.xlen - expected["length"]) > tolerance: raise ValueError(f"Length mismatch: {bb.xlen} vs {expected['length']}") return True

这个检查很有必要。我遇到过用户输入“长 10 宽 10 高 10，倒 R6 圆角”的情况，圆角半径大于了边长的一半，内核直接报错。如果没有有效性检查，程序会抛出一堆看不懂的内核异常；有了检查，可以给出明确的提示：“圆角半径过大，请减小到 5 以下”。

4.4 导出 STEP 与生成 URDF

导出 STEP 很简单，一行代码：

cq.exporters.export(model, "output.step")

生成 URDF 需要多做一些工作。首先要确定 link 和 joint 的结构。对于单几何体的情况，可以生成一个只有 base_link 的 URDF：

from lxml import etree def generate_urdf(model, name="model", mass=1.0): bb = model.val().BoundingBox() size = (bb.xlen / 1000, bb.ylen / 1000, bb.zlen / 1000) # 转米 robot = etree.Element("robot", name=name) link = etree.SubElement(robot, "link", name="base_link") visual = etree.SubElement(link, "visual") geom = etree.SubElement(visual, "geometry") box = etree.SubElement(geom, "box") box.set("size", f"{size[0]} {size[1]} {size[2]}") collision = etree.SubElement(link, "collision") cgeom = etree.SubElement(collision, "geometry") cbox = etree.SubElement(cgeom, "box") cbox.set("size", f"{size[0]} {size[1]} {size[2]}") inertial = etree.SubElement(link, "inertial") m = etree.SubElement(inertial, "mass") m.set("value", str(mass)) inertia = etree.SubElement(inertial, "inertia") # 简化计算，实际应根据几何形状计算转动惯量 for attr in ["ixx", "ixy", "ixz", "iyy", "iyz", "izz"]: inertia.set(attr, "0.001") return etree.tostring(robot, pretty_print=True, encoding="unicode")

这里有个细节：URDF 的视觉几何和碰撞几何可以不同。视觉几何用精细模型，碰撞几何用简化模型，可以提升仿真效率。text-to-cad 生成的模型通常比较简单，两者可以一致。

转动惯量的计算是个坑。上面代码里用了固定值 0.001，这在仿真里会导致物理行为不真实。正确的做法是根据几何形状和密度计算。对于长方体，转动惯量公式是：

• Ixx = m/12 * (h² + d²)
• Iyy = m/12 * (w² + h²)
• Izz = m/12 * (w² + d²)

其中 w、h、d 分别是长、高、宽。把这个计算补进去，URDF 的物理属性才靠谱。

4.5 完整流程串联与测试

把上面的模块串起来，形成一个完整的处理函数：

def text_to_cad(text, output_name="output"): intent = parse_text(text) model = build_model(intent) validate_model(model, intent) cq.exporters.export(model, f"{output_name}.step") urdf_str = generate_urdf(model, name=output_name) with open(f"{output_name}.urdf", "w") as f: f.write(urdf_str) return f"{output_name}.step", f"{output_name}.urdf"

测试一下：

text_to_cad("做一个长100宽60高40的盒子，四个角倒R5圆角", "test_box")

跑完之后应该得到test_box.step和test_box.urdf两个文件。STEP 文件可以用 FreeCAD 或者中望 CAD 打开检查，URDF 文件可以导入 CoppeliaSim 验证。

导入 CoppeliaSim 的步骤是：菜单栏选择Add->Robot->Import URDF，选中生成的 urdf 文件。如果模型显示不出来，检查 URDF 里的文件路径是否正确，以及单位是否匹配。CoppeliaSim 默认单位是米，如果 URDF 里写的是毫米数值，模型会大 1000 倍。

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

5.1 几何生成失败类问题

这类问题最典型的表现是程序抛出 OpenCASCADE 的异常，信息晦涩难懂。下面整理了几种常见情况和处理方法。

圆角半径的问题我踩过好几次。用户说“倒 R5 圆角”，但盒子高度只有 8，圆角半径 5 大于高度的一半 4，内核直接拒绝。这时候要么提示用户改小半径，要么自动把半径截断到安全值。我倾向于前者，因为自动截断会让用户困惑“为什么我设的 5 变成了 3.9”。

5.2 URDF 导入仿真环境的问题

URDF 导入 CoppeliaSim 或者 Gazebo 时，最常见的问题是模型不可见、位置不对、关节不动。

模型不可见通常是路径问题。URDF 里如果引用了外部 STL 文件，路径要写相对路径或者绝对路径，而且不同仿真器对路径的解析方式不一样。稳妥的做法是把几何直接内嵌在 URDF 里，用<box>、<cylinder>这类基本几何标签，避免路径问题。

关节不动通常是 joint 的 axis 设置有问题。URDF 里 axis 是单位向量，比如xyz="0 0 1"表示绕 Z 轴旋转。如果写成了xyz="0 0 0"，关节就没有旋转轴，仿真器会忽略这个关节。

还有一个隐蔽的坑是惯性矩阵。如果惯性矩阵设成了全零，仿真器计算动力学时会出问题，模型可能会飞走或者抖动。至少要给对角线元素一个合理的非零值。

5.3 单位与坐标系问题

单位问题是 text-to-cad 里最容易出错的地方。CAD 用毫米，URDF 用米，STL 没有单位约定（但通常按毫米处理）。如果中间不做转换，模型尺寸会差三个数量级。

我的做法是在ModelingIntent里统一用毫米，生成 URDF 时再除以 1000。同时在代码里加断言，检查转换后的尺寸是否在合理范围内：

def to_meters(mm_value): m = mm_value / 1000.0 assert 0.001 < m < 10, f"Size {m}m seems unreasonable" return m

坐标系的问题也很常见。cadquery 默认在 XY 平面建模，Z 轴向上。URDF 的坐标系约定是 X 向前、Y 向左、Z 向上。如果直接把 cadquery 的模型导出成 URDF，方向可能不对。需要在生成 URDF 时做坐标变换，或者在建模型时就按 URDF 的坐标系来。

5.4 批量生成时的性能问题

如果需要批量生成几十上百个模型，性能会成为瓶颈。cadquery 每次调用都会初始化内核，开销不小。优化方法是复用 Workplane 对象，或者用多进程并行。

from multiprocessing import Pool def generate_one(args): text, name = args return text_to_cad(text, name) with Pool(4) as p: results = p.map(generate_one, task_list)

多进程比多线程有效，因为 cadquery 的计算主要在 C++ 层，Python 的 GIL 会限制多线程的并行度。实测下来，4 进程比单进程快 3 倍左右。

另外，导出 STEP 时如果模型很复杂，文件会很大。可以在导出前做简化，比如降低圆角的段数。cadquery 的fillet方法可以指定segments参数，默认值比较大，适当减小可以显著降低文件体积。

6. 扩展方向与个人经验

text-to-cad 这个方向还有很多可以挖的地方。一个自然的扩展是支持更多几何类型，比如齿轮、螺纹、法兰这些标准件。这些零件的参数化程度很高，用规则匹配就能覆盖大部分需求。另一个扩展是支持装配体，让用户描述多个零件之间的位置关系和配合关系，生成完整的装配模型。

从工程落地的角度，我觉得最有价值的扩展是“模板库 + 参数填充”的模式。与其让用户用自然语言描述一切，不如提供一批常用模板，用户只需要填参数。比如“创建一个 M8 螺栓，长度 30”，背后调用的是预定义的螺栓模板，参数化生成几何。这种方式比纯自然语言生成更可靠，也更符合工程实际。

我在实际使用中最大的体会是：不要追求一步到位。text-to-cad 的价值不在于完全替代 CAD 软件，而在于把重复性的、模板化的建模工作自动化。对于简单的几何体，它能省下大量时间；对于复杂的曲面造型，它目前还力不从心。把边界划清楚，在能用的场景里用好，比追求全能更实际。

还有一个实用技巧：生成的 STEP 文件最好用 FreeCAD 做一次二次验证。FreeCAD 的 Python 控制台可以直接读取 STEP 文件并检查几何有效性，比在 cadquery 里检查更接近实际 CAD 软件的行为。如果 FreeCAD 能正常打开并显示，那这个文件基本就没问题了。

最后分享一个排查 URDF 问题的笨办法：把 URDF 文件用文本编辑器打开，逐行检查 link 和 joint 的定义，确认每个 link 都有 visual 和 collision，每个 joint 都有 parent 和 child，且 parent/child 的名字和 link 的名字完全一致。大部分导入失败的问题，根源都在这些基础定义上。