Text-to-CAD实战：用Python和CadQuery实现参数化建模与URDF导出

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

第一次听到 “text-to-cad” 这个词，很多人脑子里冒出来的画面大概是：对着电脑敲一行字，比如“一个长宽高 100×60×30 的带圆角盒子”，然后软件啪一下给你生成一个能直接用的三维模型文件。这个理解方向没错，但真正落地到工程里，它要解决的远不止“省几下鼠标”这么简单。

我在机械设计和自动化仿真这条线上摸爬滚打十来年，最深的体会是：建模本身不难，难的是“重复建模”和“模型流转”。一个减速器箱体，参数改一次，你要重新拉伸、打孔、倒角、装配；一批零件要导入仿真环境，你得一个个手动导出、转换格式、对齐坐标系。这些活儿技术含量不高，但极其消耗时间，而且特别容易出错。text-to-cad 的核心价值，就是把这套“描述—建模—导出—验证”的链路用代码串起来，让模型变成可编程、可批量、可复现的产物。

它适合谁？我梳理了三类人。第一类是做参数化设计的工程师，手里有大量结构相似、尺寸不同的零件，想用脚本批量生成；第二类是搞机器人仿真的开发者，需要把 CAD 模型转成 URDF 这类描述文件，导入仿真环境做运动学和动力学验证；第三类是想入门 CAD 二次开发的程序员，懂 Python 但不懂建模，想找个切入点把两者结合起来。这三类人的共同点是：都不满足于“手动点鼠标”，都希望模型能像代码一样被管理起来。

这里要先厘清一个概念。text-to-cad 里的 “text”，不一定非得是自然语言。在实际工程中，它更多指的是结构化的文本描述——可以是一段 JSON、一个 YAML 配置、一张参数表，甚至是一段 Python 字典。真正意义上的“自然语言直接生成精确工程模型”，目前还处在比较早期的阶段，因为工程模型对尺寸、公差、拓扑关系的要求太严格了，容不得“大概齐”。所以我在实际项目里采用的方案，是用结构化文本驱动参数化建模，再辅以自然语言做前端输入。这样既保证了精度，又保留了“说人话就能建模”的便利。

下面这张表，是我对 text-to-cad 常见输入形式的一个归纳，你可以对照自己的场景选：

理解了这一层，你就明白为什么 text-to-cad 会和 CAD、STEP、URDF、Python 这几个词绑在一起。CAD 是建模的载体，STEP 是通用的三维交换格式，URDF 是机器人仿真的描述语言，Python 是把它们串起来的胶水。接下来我会一层层拆开讲，从整体设计思路到具体实操，把这条链路走通。

2. 整体方案设计：为什么选 Python + 参数化 + 标准格式

2.1 技术选型背后的取舍逻辑

做 text-to-cad，第一个要拍板的问题是：用什么工具来生成几何。市面上的路子大概有这么几条，我一条条给你分析。

第一条路是直接调用商业 CAD 的 API，比如通过 COM 接口操作桌面端 CAD 软件。这条路的好处是生成的模型“原生”，后续在 CAD 里编辑无缝衔接。但坑也很明显：依赖特定软件安装、版本兼容性差、脚本运行慢，而且一旦软件授权出问题，整条链路就断了。我早年做过一个批量出图的项目，客户换了 CAD 版本，脚本直接罢工，排查了两天才发现是接口签名变了。从那以后，我对强依赖商业软件 API 的方案就保持警惕。

第二条路是用开源几何内核，比如 OpenCASCADE，通过 Python 绑定（pythonocc 之类）来建模。这条路自由度高、可移植性强，生成的就是标准 B-rep 实体，能导出 STEP。缺点是学习曲线陡，文档零散，很多操作要自己啃源码。但对于追求“可复现、可部署”的场景，这是最稳的选择。

第三条路是用代码化建模语言，比如 OpenSCAD、CadQuery。它们本质上是把建模操作抽象成函数调用，写起来像编程，生成的模型精度也够。CadQuery 底层就是 OpenCASCADE，语法比直接调内核友好得多，是我目前最推荐的入门方案。

我最终给出的组合是：Python 做编排层，CadQuery 做几何生成，STEP 做交换格式，URDF 做仿真接口。这个组合的理由很实在——Python 生态成熟、库多、上手快；CadQuery 把复杂的几何操作封装成了直观的链式调用；STEP 是工业界公认的中性格式，几乎所有 CAD 和仿真软件都认；URDF 则是机器人领域的通用语言。四者结合，既能建模，又能流转，还能仿真。

2.2 从文本到模型的完整数据流

整个系统的数据流，我习惯画成一条“流水线”来理解。最上游是输入层，接收自然语言或结构化配置；中间是解析层，把文本翻译成参数字典；再往下是建模层，用参数驱动几何生成；然后是导出层，把模型写成 STEP 或 URDF；最后是验证层，检查模型是否合法、尺寸是否正确。

这条流水线里，最容易出问题的是解析层和建模层的衔接。举个例子，用户说“一个带四个安装孔的底板”，解析层要能识别出“底板”对应一个长方体，“四个安装孔”对应四个圆柱切除特征，还要推断出孔的合理位置——是四角均布还是沿边排列？孔径多大？这些如果全靠自然语言推断，误差会很大。所以我的做法是：自然语言只负责“意图识别”，具体参数走默认值或追问确认。比如识别到“底板+四孔”，就套用一个预设模板，孔径默认按板厚的一半取，位置默认四角内缩一个边距。用户不满意再改参数。这样既快又稳。

2.3 为什么 STEP 和 URDF 缺一不可

很多人会问：既然都能导出模型了，为什么还要分 STEP 和 URDF 两种格式？这不是多此一举吗？其实它们服务的目标完全不同。

STEP 是几何层面的交换格式，它描述的是“这个零件长什么样”，包含精确的边界表示（B-rep），适合加工、装配、出图。你在 CAD 软件里打开 STEP，能看到完整的实体，能测量尺寸，能继续编辑。

URDF 是运动学层面的描述格式，它描述的是“这个机器人由哪些连杆和关节组成，怎么运动”。它不关心零件的精确几何，只关心连杆的质量、惯性矩、关节类型和运动范围。你把 URDF 导入仿真环境，是为了做动力学仿真，不是为了看外观。

所以一个完整的 text-to-cad 流程，往往是先用 STEP 保证几何正确，再转成 URDF 保证仿真可用。两者是互补关系，不是替代关系。我在做机械臂项目时，就是先用 CadQuery 生成各连杆的 STEP，再写脚本把它们组装成 URDF，最后导入仿真环境验证运动范围。这套流程跑顺了，改一个连杆尺寸，STEP 和 URDF 能同步更新，效率比手动改高出一个数量级。

3. 核心细节解析：参数化建模的关键要点

3.1 参数化建模的“骨架”思维

参数化建模最忌讳的是“想到哪建到哪”。我见过不少新手，拿到需求就开始拉伸、切除，结果改一个尺寸，整个模型全乱。正确的做法是先搭“骨架”——用少量关键参数定义模型的拓扑结构，让所有几何特征都挂在这些参数上。

举个具体例子。假设要建一个法兰盘，关键参数有：外径 D、内径 d、厚度 t、螺栓孔数量 n、螺栓孔直径 dh、螺栓孔分布圆直径 Dp。这六个参数就是骨架。建模时，先画外圆（D），再画内孔（d），拉伸厚度（t），然后在分布圆（Dp）上阵列 n 个直径 dh 的孔。整个过程没有任何“硬编码”的尺寸，全部引用参数。这样改 D，外径变；改 n，孔数变；改 Dp，孔的位置变。模型始终自洽。

这种思维落到代码里，就是把参数定义成变量，把几何操作写成函数。下面是我常用的一个 CadQuery 法兰盘建模函数，你可以直接参考：

import cadquery as cq def make_flange(D=100, d=40, t=10, n=6, dh=8, Dp=80): """ 生成一个法兰盘 D: 外径 d: 内径 t: 厚度 n: 螺栓孔数量 dh: 螺栓孔直径 Dp: 螺栓孔分布圆直径 """ # 主体：外圆拉伸 flange = ( cq.Workplane("XY") .circle(D / 2) .circle(d / 2) .extrude(t) ) # 螺栓孔：在分布圆上打孔 flange = ( flange.faces(">Z") .workplane() .polarArray(Dp / 2, 0, 360, n) .hole(dh) ) return flange # 生成并导出 result = make_flange(D=120, d=50, t=12, n=8, dh=10, Dp=95) cq.exporters.export(result, "flange.step")

这段代码里，make_flange就是一个“文本到模型”的转换器。你给它一组参数（文本），它给你一个 STEP 文件（模型）。参数改了，模型自动更新，不需要重新画。这就是参数化的威力。

3.2 坐标系与基准面的选择陷阱

参数化建模里，坐标系的选择看似小事，实则影响巨大。我踩过最深的坑，是在做装配体的时候，各零件用了不同的基准面，结果装配时全对不上，一个个手动挪，挪到怀疑人生。

经验是这样的：单个零件建模时，尽量让模型关于原点对称，或者让关键基准面与坐标平面重合。比如一个长方体，我习惯让它中心在原点，长宽高分别沿 X、Y、Z 轴。这样后续装配时，只要对齐原点，位置就对了。如果零件本身不对称，比如一个 L 形支架，那就把“安装面”放在 XY 平面上，让 Z 轴朝上，这样装配时也好定位。

还有一个细节：单位。CAD 里单位混乱是灾难。STEP 文件本身不强制单位，但大多数软件默认毫米。我建议全程用毫米，在代码里显式标注。CadQuery 默认就是毫米，这点比较省心。但如果你从别的库导入数据，一定要确认单位，我见过因为英寸和毫米混用导致模型放大 25.4 倍的惨案。

3.3 特征顺序与布尔运算的稳定性

建模时特征的先后顺序，会影响布尔运算的稳定性。什么叫稳定性？就是模型能不能顺利生成，会不会报错，会不会产生破面。我的经验是：先加后减，先大后小，先主体后细节。

先加后减，意思是先把所有“材料”加上去，再做切除。比如一个带孔的板，先拉伸整块板，再打孔。如果反过来，先打孔再拉伸，逻辑上也能做，但容易出问题。

先大后小，意思是先做大的几何特征，再做小的。比如先做主体，再做倒角、圆角。因为倒角和圆角对几何的连续性要求高，如果主体还没定型就倒角，后面一改主体，倒角全废。

先主体后细节，意思是把倒角、圆角、螺纹这些“装饰性”特征放在最后。这样改主体尺寸时，只需要重新生成细节，不用从头来。

这些顺序上的讲究，在手动建模时靠经验，在代码建模时就要靠函数的分层设计。我通常把建模函数分成三层：第一层生成主体，第二层添加功能特征（孔、槽），第三层做修饰（倒角、圆角）。每层独立，方便调试和复用。

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

4.1 环境准备与依赖安装

先把环境搭起来。我推荐用 Python 3.8 以上版本，太老的版本有些库不支持。安装 CadQuery 最省事的方式是用 conda，因为它依赖的几何内核比较重，pip 装有时候会缺依赖。

# 创建虚拟环境 conda create -n text2cad python=3.8 conda activate text2cad # 安装 CadQuery conda install -c conda-forge cadquery # 安装其他辅助库 pip install numpy pyyaml

如果你不用 conda，用 pip 也行，但可能要手动装一些系统依赖。我在 Linux 上装的时候，缺过 OpenGL 相关的库，报错信息很隐晦，后来查了半天才定位到。Windows 上相对省心，但要注意 Python 位数和库的位数要一致，32 位 Python 装 64 位库会失败。

装完之后，跑个简单测试验证一下：

import cadquery as cq box = cq.Workplane("XY").box(10, 10, 10) cq.exporters.export(box, "test.step") print("环境正常")

能生成 test.step 并且不报错，环境就算通了。

4.2 文本解析层的实现

解析层的作用，是把用户输入的文本变成参数字典。我分两步走：先做意图识别，再做参数提取。

意图识别可以用简单的关键词匹配，也可以用大模型。如果场景固定，关键词匹配就够了。比如输入里出现“法兰”，就走法兰模板；出现“底板”，就走底板模板。参数提取则用正则表达式从文本里抓数字。

import re def parse_text(text): """把自然语言文本解析成建模参数字典""" params = {} # 意图识别 if "法兰" in text: params["type"] = "flange" elif "底板" in text or "板" in text: params["type"] = "plate" else: params["type"] = "box" # 参数提取：抓取"数字+单位"的模式 numbers = re.findall(r'(\d+(?:\.\d+)?)\s*(?:mm|毫米)?', text) numbers = [float(n) for n in numbers] # 按类型分配参数 if params["type"] == "flange" and len(numbers) >= 3: params["D"], params["d"], params["t"] = numbers[0], numbers[1], numbers[2] return params # 测试 print(parse_text("生成一个外径120内径50厚度12的法兰")) # 输出: {'type': 'flange', 'D': 120.0, 'd': 50.0, 't': 12.0}

这个解析器很粗糙，但胜在简单可控。实际项目里，我会给每个参数设默认值，解析不到就用默认值，避免因为用户少说一个数就报错。

4.3 建模层的参数校验与生成

解析出来的参数不能直接拿去建模，必须先校验。尺寸是否为正、内径是否小于外径、孔是否超出边界，这些都要检查。我见过因为内径大于外径导致建模失败的案例，报错信息还特别难懂。

def validate_flange_params(params): """校验法兰参数合法性""" errors = [] if params.get("D", 0) <= 0: errors.append("外径必须大于0") if params.get("d", 0) >= params.get("D", 0): errors.append("内径必须小于外径") if params.get("t", 0) <= 0: errors.append("厚度必须大于0") if params.get("Dp", 0) >= params.get("D", 0): errors.append("分布圆直径必须小于外径") return errors # 校验 errors = validate_flange_params({"D": 100, "d": 120, "t": 10}) if errors: print("参数错误:", errors)

校验通过后，再调用建模函数生成模型。这一步的关键是异常捕获。几何内核有时候会因为数值精度问题报错，比如两个面几乎重合导致布尔运算失败。我的做法是给建模函数包一层 try-except，出错时记录参数，方便复现和排查。

4.4 导出 STEP 与生成 URDF

模型生成后，导出 STEP 很简单，一行代码的事。但导出 URDF 就复杂一些，因为 URDF 需要定义连杆、关节、惯性矩阵这些信息。

我的做法是：先用 STEP 保证几何正确，再写一个转换脚本，把 STEP 的几何信息提取出来，填充到 URDF 模板里。惯性矩阵可以用近似公式算，比如把连杆近似成圆柱或长方体，用标准公式计算。

def generate_urdf(link_name, step_file, mass, joint_type="fixed"): """生成一个简单的 URDF 片段""" urdf_template = f""" <link name="{link_name}"> <visual> <geometry> <mesh filename="{step_file}"/> </geometry> </visual> <inertial> <mass value="{mass}"/> <inertia ixx="0.001" ixy="0" ixz="0" iyy="0.001" iyz="0" izz="0.001"/> </inertial> </link> """ return urdf_template

惯性矩阵这里我用了占位值，实际项目里要根据几何形状精确计算。如果对仿真精度要求高，这一步不能偷懒。我通常会用 Python 的 trimesh 库读取 STEP 转成的网格，计算体积和惯性矩，再填进去。

4.5 完整流程串起来

把上面各层串起来，就是一个完整的 text-to-cad 流水线：

def text_to_cad(text, output_step="output.step"): # 1. 解析 params = parse_text(text) # 2. 校验 if params["type"] == "flange": errors = validate_flange_params(params) if errors: return {"status": "error", "errors": errors} # 3. 建模 try: if params["type"] == "flange": model = make_flange(**{k: v for k, v in params.items() if k != "type"}) else: model = cq.Workplane("XY").box(50, 50, 20) except Exception as e: return {"status": "error", "errors": [str(e)]} # 4. 导出 cq.exporters.export(model, output_step) return {"status": "ok", "file": output_step} # 使用 result = text_to_cad("生成一个外径120内径50厚度12的法兰") print(result)

这套流程跑通后，你就可以批量处理了。比如从 CSV 读一百行参数，循环调用text_to_cad，几分钟就能生成一百个模型。这种效率，手动建模是没法比的。

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

5.1 建模报错与几何内核的“脾气”

几何内核报错是家常便饭，尤其是做布尔运算的时候。最常见的错误是“布尔运算失败”，原因通常是两个实体有共面、共边或者微小间隙。我的排查思路是：先简化，再定位，后修复。

先简化，就是把模型拆成最小的可复现单元。比如一个复杂零件报错，我就先只建主体，看是否报错；不报错再加一个特征，逐步逼近出错点。

再定位，就是找到具体是哪两个特征之间的运算出问题。CadQuery 的报错信息有时候会指出大致位置，但不够精确。我通常会在代码里加打印，标记每一步的执行状态。

后修复，常用的手段有：微调尺寸（比如把 10 改成 10.001，避免共面）、调整运算顺序（先减后加改成先加后减）、用切割代替布尔差。这些技巧都是踩坑踩出来的，文档里不会写。

5.2 STEP 导出后的“破面”问题

STEP 导出后，有时候在别的软件里打开会发现破面或者实体变成了曲面片。这通常是几何精度的问题。STEP 有精度设置，默认可能不够。我一般会在导出时显式指定精度：

cq.exporters.export(model, "output.step", tolerance=0.001)

tolerance 越小，精度越高，文件也越大。0.001 毫米对大多数机械零件够用了。如果还破面，那可能是建模阶段就有问题，比如曲面连续性不够，这时候要回头检查建模步骤。

5.3 URDF 导入仿真环境的坐标系错位

URDF 导入仿真环境后，模型位置不对，这是坐标系没对齐。URDF 里每个 link 都有自己的坐标系，如果建模时的坐标系和 URDF 定义的坐标系不一致，就会错位。

解决办法是：在建模阶段就统一坐标系。我习惯让每个连杆的坐标系原点放在关节连接处，Z 轴沿连杆方向。这样生成 URDF 时，关节的 origin 直接写零偏移就行。如果建模时没这么做，那就在 URDF 里加偏移量补偿，但这样容易出错，不如建模时就规范好。

下面这张表是我整理的常见问题速查表，你可以贴在工位上：

5.4 批量生成时的内存与性能

批量生成几百个模型时，内存会涨得很快。因为每次建模都会在内存里创建几何对象，如果不释放，累积起来就爆了。我的做法是每生成一个模型就导出并清空，不要把所有模型都留在内存里。

for params in param_list: model = make_part(**params) cq.exporters.export(model, f"{params['id']}.step") del model # 显式释放

另外，如果模型之间只有尺寸差异，可以考虑用同一个基础模型做缩放，而不是从头建模。但缩放对某些特征（比如孔）不适用，因为孔缩放后直径也变了，可能不符合要求。这个要视情况而定。

6. 进阶玩法：让 text-to-cad 更智能

6.1 接入大模型做自然语言理解

前面说的解析层用的是关键词匹配，能力有限。如果想支持更自由的自然语言，可以接入大模型做意图识别和参数抽取。做法是：把用户输入和一套预定义的参数 schema 一起发给模型，让模型输出结构化的 JSON。

import json def llm_parse(text, schema): """调用大模型解析文本（伪代码）""" prompt = f""" 根据以下schema，从用户输入中提取参数，输出JSON： schema: {json.dumps(schema)} 用户输入: {text} """ # 调用模型API，拿到返回 response = call_llm(prompt) return json.loads(response)

这样用户说“来个直径十公分的圆盘，中间开个五公分的孔”，模型也能理解“十公分”是 100 毫米，“五公分”是 50 毫米。比正则表达式灵活多了。但要注意，大模型输出的参数一定要校验，不能直接信。

6.2 参数化模板库的积累

做久了你会发现，很多零件是重复的。法兰、底板、支架、轴套，这些标准件可以做成模板库。每个模板对应一个建模函数和一套参数 schema。用户输入时，先匹配模板，匹配不到再走通用建模。

模板库的好处是质量和效率双赢。模板经过验证，不会出错；调用模板比从头建模快得多。我现在的项目里，百分之八十的零件都能从模板库直接生成，只有百分之二十的特殊件需要单独处理。

6.3 与仿真流程的自动化衔接

text-to-cad 的终极形态，是建模和仿真全自动。你给一段文本描述，系统生成模型，自动转 URDF，自动导入仿真环境，自动跑运动学验证，最后输出报告。这套流程我在机械臂项目里跑通过，虽然还不够通用，但方向是对的。

关键难点在于仿真参数的自动配置。比如关节的力矩、阻尼、摩擦系数，这些在 URDF 里要填，但文本描述里通常没有。我的做法是给一套默认值，然后根据模型的质量和尺寸做估算。精度要求高的话，还是要人工介入调参。

7. 我踩过的坑与实操心得

说几个印象深刻的坑。第一个是单位问题。有次从外部导入一组数据，没注意是英寸，生成模型后比预期大了 25.4 倍，装配时才发现，返工了一整天。从那以后，我在所有建模函数的入口都加了单位检查，不是毫米就报错。

第二个是浮点数精度。几何内核处理浮点数时，有时候 0.1+0.2 不等于 0.3，导致本该重合的面差了一点点，布尔运算就失败。解决办法是在关键尺寸上做圆整，比如保留三位小数，避免无限小数。

第三个是版本兼容。CadQuery 不同版本 API 有变化，我写的脚本在旧版本上跑不了。建议锁定版本，用 requirements.txt 管理依赖，别随便升级。

实操心得方面，我最想分享的是：先跑通最小闭环，再逐步加功能。别一上来就搞大而全的系统，先实现“一句话生成一个盒子并导出 STEP”，跑通了再加法兰、加 URDF、加批量。每加一个功能就验证一次，这样出问题好定位。我见过太多人一上来就搭架构，结果卡在某个细节上，整个项目推不动。

另外，日志要打全。建模过程中每一步的参数、耗时、结果都记下来。出问题时，日志就是你的救命稻草。我现在的脚本，每个关键步骤都有日志，排查效率比早期高了好几倍。

最后说个心态上的事。text-to-cad 这个方向，工具在快速迭代，今天好用的方案明天可能就过时了。但底层的思路——参数化、标准化、自动化——是不变的。把这三样吃透，换什么工具都能快速上手。我在这个领域折腾了这么多年，最大的收获不是学会了某个库，而是养成了“把重复劳动交给代码”的习惯。这个习惯，比任何具体技术都值钱。