1. 从一段文字到三维模型text-to-cad 到底在解决什么问题第一次听到 “text-to-cad” 这个词很多人脑子里蹦出来的画面可能是对着电脑说一句“给我画个齿轮”然后屏幕上就自动出现一个可以旋转、可以导出、可以加工的 3D 模型。这个想象不算离谱但也不完全准确。更贴近工程现实的定义是用自然语言描述几何结构、尺寸约束和装配关系由程序自动生成 CAD 可识别的中间格式文件最终输出 STEP、URDF 等下游工具链能直接消费的模型文件。我最初接触这个方向是因为手头有一批重复性极高的零件建模任务。比如一批法兰盘区别只在孔径、孔数和外径又比如一批支架区别只在折弯角度和安装孔位。每次打开 CAD 软件重复画草图、拉伸、打孔、倒角一天下来手腕发酸真正需要动脑的地方其实不多。那时候我就在想能不能把“画图”这件事变成“写参数”这件事。text-to-cad 正好踩在这个需求上。它适合什么人我总结下来是三类。第一类是经常做参数化零件的机械工程师手里有大量结构相似、尺寸不同的模型要出。第二类是做机器人仿真的开发者需要频繁生成 URDF 模型去验证运动学手工在 CAD 里画连杆再导出效率太低。第三类是想入门 CAD 二次开发但被 API 文档劝退的 Python 使用者text-to-cad 提供了一条更平缓的路径先用文字描述再逐步深入到底层几何内核。需要提前说明的是text-to-cad 不是要取代 CAD 软件。它更像一个“前置生成器”。你用它把文字变成 STEP 或 URDF再导入到中望 CAD、FreeCAD 或者 CoppeliaSim 里做后续的装配、渲染、仿真。它的价值在于把重复劳动自动化把参数变更变成一行文本的修改而不是让你彻底告别 CAD 界面。提示如果你现在还在用“画完一个零件复制一份手动改尺寸”的方式工作text-to-cad 的思路值得你花一个下午认真了解一下。它省下来的时间远超过学习成本。2. 核心思路拆解为什么是“文本→中间格式→CAD”这条链路2.1 为什么不直接生成 CAD 原生文件很多人第一反应是既然要自动化为什么不直接生成 .dwg 或 .sldprt 文件这个问题我踩过坑。CAD 原生格式是闭源二进制结构不同软件之间兼容性极差而且版本升级经常导致旧文件打不开。你辛辛苦苦写了一个生成 .dwg 的脚本换一台电脑、换一个 CAD 版本可能就废了。更稳妥的做法是走中间格式。STEP 是 ISO 标准几乎所有主流 CAD 软件都能导入URDF 是机器人描述格式CoppeliaSim、Gazebo、RViz 都认。text-to-cad 的核心思路就是用 Python 描述几何输出 STEP 或 URDF再由下游工具接管。这样做的好处是解耦——生成逻辑和渲染逻辑分开你的文本描述只负责“结构是什么”不负责“怎么显示”。2.2 文本描述怎么变成几何体这里涉及一个关键概念边界表示法BRep。简单说一个三维实体由面、边、顶点组成面由曲面定义边由曲线定义。text-to-cad 工具通常基于 OpenCASCADE 这个几何内核它提供了完整的 BRep 建模能力。你在 Python 里写Box(10, 20, 30)内核会在内存里构建一个长方体六个面、十二条边、八个顶点全部用数学方程描述。那文本怎么映射到这些操作常见做法有两种。一种是结构化参数描述比如用 JSON 或 YAML 写{type: box, length: 10, width: 20, height: 30}程序解析后调用对应函数。另一种是自然语言解析比如输入“一个长10宽20高30的长方体中心有一个直径5的通孔”程序用规则或模型解析出“长方体”和“通孔”两个操作再按顺序执行。前者稳定可控后者灵活但容易出错。我个人的建议是生产环境用结构化描述探索阶段用自然语言。2.3 为什么 Python 是首选语言热词里 Python 出现频率极高这不是偶然。OpenCASCADE 有 Python 绑定pythonocc-coreCadQuery 本身就是 Python 库URDF 的生成也可以用 Python 脚本批量处理。更重要的是Python 的生态太全了numpy 做矩阵运算cv2 做图像处理甚至可以用 matplotlib 画个草图预览。你不需要在多个工具之间来回切换一个脚本从头管到尾。我试过用其他语言做类似的事情比如 JavaScript 的 three.js渲染很漂亮但做精确的 BRep 建模很吃力。Python 在“精确几何”和“快速开发”之间找到了一个很好的平衡点。而且热词里“python安装教程”“python环境变量配置”出现多次说明大量用户正在入门 Pythontext-to-cad 正好可以作为一个有成就感的练手项目——你写的不是打印星星的循环而是一个真实的三维模型。3. 环境准备从零搭建 text-to-cad 工作流3.1 Python 环境与核心库选择先解决 Python 安装。热词里“python官网下载”“python安装”“python环境变量配置”都是高频问题。我的建议是直接装 Miniconda不要单独装 Python。Miniconda 自带 conda 包管理器能自动处理 OpenCASCADE 这种带二进制依赖的库。你从官网下载 Miniconda 安装包一路下一步安装完成后在开始菜单里打开 Anaconda Prompt输入conda --version能看到版本号就成功了。接下来创建独立环境。这一步很多人跳过结果后面库版本冲突排查半天。命令如下conda create -n text2cad python3.10 conda activate text2cad为什么选 Python 3.10因为 pythonocc-core 和 CadQuery 对 3.10 的支持最稳定3.11 和 3.12 有些依赖还没跟上。装完环境后安装核心库conda install -c conda-forge pythonocc-core pip install cadquery pip install urdfpy这里解释一下选型逻辑。pythonocc-core是 OpenCASCADE 的 Python 绑定提供底层几何操作适合需要精细控制的情况。CadQuery是更高层的封装用链式调用写建模脚本代码更简洁。urdfpy用来生成和解析 URDF 文件。三个库配合使用覆盖从底层到应用层的全部需求。注意不要用 pip 安装 pythonocc-core它在 PyPI 上的包经常缺二进制文件装完导入报错。必须用 conda 从 conda-forge 频道安装。3.2 验证安装与第一个几何体装完后写个最小测试脚本确认环境没问题from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeBox from OCC.Display.SimpleGui import init_display box BRepPrimAPI_MakeBox(10, 20, 30).Shape() display, start_display, add_menu, add_function_to_menu init_display() display.DisplayShape(box, updateTrue) start_display()这段代码创建了一个 10x20x30 的长方体并显示出来。如果弹出一个窗口能看到长方体说明 pythonocc-core 工作正常。如果报错ModuleNotFoundError检查 conda 环境是否激活如果报错DLL load failed通常是缺少 Visual C 运行库去微软官网下载安装即可。热词里“安装cad一直出现c2005cpi错误”也是类似问题本质是运行库缺失。3.3 目录结构与版本管理我习惯把 text-to-cad 项目组织成这样的结构text2cad-project/ ├── models/ # 存放生成的 STEP/URDF 文件 ├── scripts/ # Python 生成脚本 ├── configs/ # YAML 参数配置文件 ├── templates/ # URDF 模板 └── README.md每个零件一个脚本参数抽到 YAML 里。比如法兰盘的脚本读flange.yaml里面写外径、内径、孔数、孔直径。改参数不用动代码只改 YAML。这样做的好处是同一套代码可以生成一系列零件配合循环就能批量出图。版本管理用 Git每次参数变更都有记录比在 CAD 里手动改可靠得多。4. 核心实操用文本描述生成 STEP 与 URDF4.1 从结构化文本到 STEP 文件先看一个完整例子生成一个带孔法兰盘。YAML 配置如下type: flange outer_diameter: 100 inner_diameter: 40 thickness: 10 bolt_hole_count: 6 bolt_hole_diameter: 8 bolt_circle_diameter: 80Python 脚本读取配置后用 CadQuery 建模import cadquery as cq import yaml with open(configs/flange.yaml) as f: cfg yaml.safe_load(f) result ( cq.Workplane(XY) .circle(cfg[outer_diameter] / 2) .circle(cfg[inner_diameter] / 2) .extrude(cfg[thickness]) ) # 打螺栓孔 import math for i in range(cfg[bolt_hole_count]): angle 2 * math.pi * i / cfg[bolt_hole_count] x (cfg[bolt_circle_diameter] / 2) * math.cos(angle) y (cfg[bolt_circle_diameter] / 2) * math.sin(angle) result ( result.faces(Z).workplane() .center(x, y) .hole(cfg[bolt_hole_diameter]) ) cq.exporters.export(result, models/flange.step)这段代码的逻辑很直白先画两个同心圆拉伸成环再在螺栓圆上均匀分布孔位逐个打孔。关键点是faces(Z)选择顶面作为工作平面center(x, y)把工作平面原点移到孔位hole()打穿整个厚度。参数计算部分角度用2πi/n均匀分配坐标用三角函数算出来这是最基础的极坐标转直角坐标。导出 STEP 后你可以直接拖进中望 CAD 或者 FreeCAD 里查看。我实测下来CadQuery 导出的 STEP 在主流 CAD 软件里兼容性很好曲面质量也够用。如果你需要更精细的控制比如变半径倒角、放样曲面可以切到 pythonocc-core 底层 API但代码量会大不少。4.2 生成 URDF 用于机器人仿真URDF 是机器人领域的标准格式CoppeliaSim 导入 URDF 后可以直接做运动学仿真。热词里“urdf导入coppeliasim”说明很多人卡在这一步。我用一个两连杆机械臂的例子说明怎么生成 URDF。URDF 本质是 XML描述连杆link和关节joint。连杆有视觉几何、碰撞几何、惯性参数关节有类型、轴、限位。用 Python 生成时我通常先写一个模板再用字符串替换填充参数URDF_TEMPLATE ?xml version1.0? robot namearm link namebase_link visual geometry cylinder radius{base_radius} length{base_height}/ /geometry /visual /link link namelink1 visual geometry box size{l1_x} {l1_y} {l1_z}/ /geometry /visual /link joint namejoint1 typerevolute parent linkbase_link/ child linklink1/ axis xyz0 0 1/ limit lower-3.14 upper3.14 effort10 velocity1/ /joint /robot params { base_radius: 0.05, base_height: 0.1, l1_x: 0.3, l1_y: 0.05, l1_z: 0.05, } with open(models/arm.urdf, w) as f: f.write(URDF_TEMPLATE.format(**params))这里单位是米不是毫米。URDF 遵循国际单位制导入 CoppeliaSim 后如果发现模型巨大或极小八成是单位搞错了。我踩过这个坑用毫米数值生成 URDF导入后机械臂有几百米长场景里根本看不到全貌。后来统一在脚本入口做单位转换毫米转米除以 1000问题解决。4.3 参数计算与约束检查text-to-cad 最容易出错的地方不是代码语法而是几何约束冲突。比如你写“外径 100内径 120”程序会报错或者生成一个空实体。再比如“螺栓圆直径 80螺栓孔直径 30孔数 6”相邻孔会重叠。这些在 CAD 里手动画图时你会立刻看到但在脚本里需要自己加检查。我的做法是在生成前加一段校验逻辑def validate_flange(cfg): if cfg[inner_diameter] cfg[outer_diameter]: raise ValueError(内径必须小于外径) hole_spacing ( math.pi * cfg[bolt_circle_diameter] / cfg[bolt_hole_count] ) if hole_spacing cfg[bolt_hole_diameter]: raise ValueError(螺栓孔间距不足孔会重叠) if cfg[bolt_circle_diameter] cfg[bolt_hole_diameter] cfg[outer_diameter]: raise ValueError(螺栓孔超出外径范围)这段校验看起来简单但能省下大量调试时间。你可以在 YAML 里随便改参数校验不通过直接报错不会生成一个错误的 STEP 文件流到下游。把问题拦截在生成阶段比导入 CAD 后才发现要返工成本低得多。5. 常见问题与排查技巧实录5.1 环境与安装类问题热词里大量出现“python安装”“python环境变量配置”“python安装numpy库的方法”说明环境问题是新手最大的拦路虎。我整理了一个速查表问题现象可能原因解决方法conda不是内部命令未将 conda 加入 PATH用 Anaconda Prompt 代替 cmdimport OCC报 DLL 错误缺少 VC 运行库安装 Visual C Redistributablepip install cadquery超时网络问题换 conda-forge 频道安装导入 STEP 后模型空白单位或坐标系问题检查导出时的单位设置URDF 导入 CoppeliaSim 报错XML 格式或路径错误用 xmllint 校验 XML其中“DLL 错误”和“URDF 导入报错”是我遇到最多的。DLL 问题基本靠装运行库解决URDF 问题多半是 mesh 文件路径写错了。URDF 里引用 STL 文件时路径可以是相对路径或package://格式CoppeliaSim 对相对路径的解析比较挑剔建议用绝对路径或者把 STL 和 URDF 放同一目录。5.2 几何生成类问题问题一布尔运算失败。当你做“长方体减去圆柱”时如果圆柱刚好和长方体表面相切布尔运算可能失败或产生退化面。解决方法是让圆柱稍微穿出表面比如多伸出去 0.1mm。这个技巧在 OpenCASCADE 里很常用叫“过切”。问题二倒角报错。对一条边倒角时如果相邻面的夹角太小或者倒角半径大于边长度操作会失败。我的经验是倒角半径不要超过最短边长度的 1/3并且优先对凸边倒角凹边倒角容易出问题。问题三STEP 导出后曲面丢失。这通常是精度设置问题。CadQuery 导出时可以指定公差cq.exporters.export(result, models/part.step, tolerance0.001)公差越小曲面越精细但文件越大。一般机械零件用 0.001mm 足够3D 打印用 0.01mm 也行。5.3 批量处理与自动化技巧热词里“python批量对cad修改”说明很多人有批量需求。我的做法是参数表格 循环生成。把不同零件的参数写进 CSV用 pandas 读取循环调用生成函数。比如import pandas as pd df pd.read_csv(configs/parts.csv) for _, row in df.iterrows(): cfg row.to_dict() validate_flange(cfg) generate_flange(cfg, fmodels/flange_{row[id]}.step)这样一次可以生成几十个零件每个文件名带 ID方便追溯。如果你需要合并多个 STEP 文件可以用 pythonocc-core 的STEPControl_Reader逐个读取再写入同一个文件但要注意坐标系对齐否则零件会叠在一起。提示批量生成前先用一个样本跑通全流程确认 STEP 能正常导入 CAD、URDF 能正常导入仿真环境再放开批量。否则错误会被放大几十倍排查起来很痛苦。6. 从文本到模型的进阶玩法与个人体会6.1 自然语言解析的可行路径前面主要讲结构化参数描述但 text-to-cad 的终极形态是自然语言直接生成。我试过用正则表达式提取“长10宽20高30”这类模式简单场景能用但稍微复杂一点就崩。比如“一个底座上面有个圆柱圆柱顶部倒角”正则根本处理不了。更可行的路径是规则引擎 模板匹配。先把常见几何特征归纳成模板比如“长方体”“圆柱”“孔”“倒角”“阵列”每个模板有对应的参数槽位。用户输入后用关键词匹配确定模板再用正则或分词提取参数。这种方法覆盖 80% 的常见需求剩下 20% 复杂结构还是得写脚本。我个人的判断是自然语言适合快速原型精确建模还是结构化描述靠谱。6.2 与 CAD 软件的双向协作text-to-cad 生成的 STEP 导入 CAD 后并不是终点。你可以在 CAD 里做进一步编辑比如添加工程图、标注尺寸、做装配约束。反过来CAD 里画好的模型也可以导出 STEP再用 Python 读取分析比如提取体积、表面积、重心。pythonocc-core 提供了GProp_GProps类做质量属性计算我常用它来验证生成模型的体积是否和理论值一致。这种双向协作的思路是用脚本做重复性生成用 CAD 做精细调整和出图。两者不是替代关系而是分工关系。我现在的流程是text-to-cad 生成初版导入中望 CAD 检查干涉和装配确认无误后出工程图。整个过程比纯手工建模快三到五倍。6.3 我踩过的坑与经验总结第一个坑是单位混乱。CAD 常用毫米URDF 用米STL 没有单位概念但导入时可能被缩放。我的做法是在项目根目录放一个units.py定义MM_TO_M 0.001所有转换都引用这个常量避免手写数字出错。第二个坑是坐标系不一致。CAD 里 Z 轴朝上机器人仿真里经常 Z 轴朝前或朝上导入后模型方向不对。解决方法是生成 URDF 时显式指定origin的rpy旋转或者在 CoppeliaSim 里导入后手动调整。我倾向于在生成阶段就处理好因为手动调整无法批量复现。第三个坑是文件命名冲突。批量生成时如果文件名只按类型命名后生成的会覆盖先生成的。加上时间戳或 ID 后缀就能避免。我现在的命名规则是{类型}_{ID}_{日期}.step比如flange_001_20250101.step一目了然。这个方向后续还可以这样扩展把生成脚本包装成命令行工具用argparse接收参数这样不写 Python 的人也能用或者接一个简单的 Web 界面输入参数点按钮就下载 STEP。再远一点结合参数优化算法自动搜索满足强度要求的最轻量化结构。不过那是另一个话题了先把基础流程跑通比什么都重要。
1. 从一段文字到三维模型text-to-cad 到底在解决什么问题第一次听到 “text-to-cad” 这个词很多人脑子里蹦出来的画面可能是对着电脑说一句“给我画个齿轮”然后屏幕上就自动出现一个可以旋转、可以导出、可以加工的 3D 模型。这个想象不算离谱但也不完全准确。更贴近工程现实的定义是用自然语言描述几何结构、尺寸约束和装配关系由程序自动生成 CAD 可识别的中间格式文件最终输出 STEP、URDF 等下游工具链能直接消费的模型文件。我最初接触这个方向是因为手头有一批重复性极高的零件建模任务。比如一批法兰盘区别只在孔径、孔数和外径又比如一批支架区别只在折弯角度和安装孔位。每次打开 CAD 软件重复画草图、拉伸、打孔、倒角一天下来手腕发酸真正需要动脑的地方其实不多。那时候我就在想能不能把“画图”这件事变成“写参数”这件事。text-to-cad 正好踩在这个需求上。它适合什么人我总结下来是三类。第一类是经常做参数化零件的机械工程师手里有大量结构相似、尺寸不同的模型要出。第二类是做机器人仿真的开发者需要频繁生成 URDF 模型去验证运动学手工在 CAD 里画连杆再导出效率太低。第三类是想入门 CAD 二次开发但被 API 文档劝退的 Python 使用者text-to-cad 提供了一条更平缓的路径先用文字描述再逐步深入到底层几何内核。需要提前说明的是text-to-cad 不是要取代 CAD 软件。它更像一个“前置生成器”。你用它把文字变成 STEP 或 URDF再导入到中望 CAD、FreeCAD 或者 CoppeliaSim 里做后续的装配、渲染、仿真。它的价值在于把重复劳动自动化把参数变更变成一行文本的修改而不是让你彻底告别 CAD 界面。提示如果你现在还在用“画完一个零件复制一份手动改尺寸”的方式工作text-to-cad 的思路值得你花一个下午认真了解一下。它省下来的时间远超过学习成本。2. 核心思路拆解为什么是“文本→中间格式→CAD”这条链路2.1 为什么不直接生成 CAD 原生文件很多人第一反应是既然要自动化为什么不直接生成 .dwg 或 .sldprt 文件这个问题我踩过坑。CAD 原生格式是闭源二进制结构不同软件之间兼容性极差而且版本升级经常导致旧文件打不开。你辛辛苦苦写了一个生成 .dwg 的脚本换一台电脑、换一个 CAD 版本可能就废了。更稳妥的做法是走中间格式。STEP 是 ISO 标准几乎所有主流 CAD 软件都能导入URDF 是机器人描述格式CoppeliaSim、Gazebo、RViz 都认。text-to-cad 的核心思路就是用 Python 描述几何输出 STEP 或 URDF再由下游工具接管。这样做的好处是解耦——生成逻辑和渲染逻辑分开你的文本描述只负责“结构是什么”不负责“怎么显示”。2.2 文本描述怎么变成几何体这里涉及一个关键概念边界表示法BRep。简单说一个三维实体由面、边、顶点组成面由曲面定义边由曲线定义。text-to-cad 工具通常基于 OpenCASCADE 这个几何内核它提供了完整的 BRep 建模能力。你在 Python 里写Box(10, 20, 30)内核会在内存里构建一个长方体六个面、十二条边、八个顶点全部用数学方程描述。那文本怎么映射到这些操作常见做法有两种。一种是结构化参数描述比如用 JSON 或 YAML 写{type: box, length: 10, width: 20, height: 30}程序解析后调用对应函数。另一种是自然语言解析比如输入“一个长10宽20高30的长方体中心有一个直径5的通孔”程序用规则或模型解析出“长方体”和“通孔”两个操作再按顺序执行。前者稳定可控后者灵活但容易出错。我个人的建议是生产环境用结构化描述探索阶段用自然语言。2.3 为什么 Python 是首选语言热词里 Python 出现频率极高这不是偶然。OpenCASCADE 有 Python 绑定pythonocc-coreCadQuery 本身就是 Python 库URDF 的生成也可以用 Python 脚本批量处理。更重要的是Python 的生态太全了numpy 做矩阵运算cv2 做图像处理甚至可以用 matplotlib 画个草图预览。你不需要在多个工具之间来回切换一个脚本从头管到尾。我试过用其他语言做类似的事情比如 JavaScript 的 three.js渲染很漂亮但做精确的 BRep 建模很吃力。Python 在“精确几何”和“快速开发”之间找到了一个很好的平衡点。而且热词里“python安装教程”“python环境变量配置”出现多次说明大量用户正在入门 Pythontext-to-cad 正好可以作为一个有成就感的练手项目——你写的不是打印星星的循环而是一个真实的三维模型。3. 环境准备从零搭建 text-to-cad 工作流3.1 Python 环境与核心库选择先解决 Python 安装。热词里“python官网下载”“python安装”“python环境变量配置”都是高频问题。我的建议是直接装 Miniconda不要单独装 Python。Miniconda 自带 conda 包管理器能自动处理 OpenCASCADE 这种带二进制依赖的库。你从官网下载 Miniconda 安装包一路下一步安装完成后在开始菜单里打开 Anaconda Prompt输入conda --version能看到版本号就成功了。接下来创建独立环境。这一步很多人跳过结果后面库版本冲突排查半天。命令如下conda create -n text2cad python3.10 conda activate text2cad为什么选 Python 3.10因为 pythonocc-core 和 CadQuery 对 3.10 的支持最稳定3.11 和 3.12 有些依赖还没跟上。装完环境后安装核心库conda install -c conda-forge pythonocc-core pip install cadquery pip install urdfpy这里解释一下选型逻辑。pythonocc-core是 OpenCASCADE 的 Python 绑定提供底层几何操作适合需要精细控制的情况。CadQuery是更高层的封装用链式调用写建模脚本代码更简洁。urdfpy用来生成和解析 URDF 文件。三个库配合使用覆盖从底层到应用层的全部需求。注意不要用 pip 安装 pythonocc-core它在 PyPI 上的包经常缺二进制文件装完导入报错。必须用 conda 从 conda-forge 频道安装。3.2 验证安装与第一个几何体装完后写个最小测试脚本确认环境没问题from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeBox from OCC.Display.SimpleGui import init_display box BRepPrimAPI_MakeBox(10, 20, 30).Shape() display, start_display, add_menu, add_function_to_menu init_display() display.DisplayShape(box, updateTrue) start_display()这段代码创建了一个 10x20x30 的长方体并显示出来。如果弹出一个窗口能看到长方体说明 pythonocc-core 工作正常。如果报错ModuleNotFoundError检查 conda 环境是否激活如果报错DLL load failed通常是缺少 Visual C 运行库去微软官网下载安装即可。热词里“安装cad一直出现c2005cpi错误”也是类似问题本质是运行库缺失。3.3 目录结构与版本管理我习惯把 text-to-cad 项目组织成这样的结构text2cad-project/ ├── models/ # 存放生成的 STEP/URDF 文件 ├── scripts/ # Python 生成脚本 ├── configs/ # YAML 参数配置文件 ├── templates/ # URDF 模板 └── README.md每个零件一个脚本参数抽到 YAML 里。比如法兰盘的脚本读flange.yaml里面写外径、内径、孔数、孔直径。改参数不用动代码只改 YAML。这样做的好处是同一套代码可以生成一系列零件配合循环就能批量出图。版本管理用 Git每次参数变更都有记录比在 CAD 里手动改可靠得多。4. 核心实操用文本描述生成 STEP 与 URDF4.1 从结构化文本到 STEP 文件先看一个完整例子生成一个带孔法兰盘。YAML 配置如下type: flange outer_diameter: 100 inner_diameter: 40 thickness: 10 bolt_hole_count: 6 bolt_hole_diameter: 8 bolt_circle_diameter: 80Python 脚本读取配置后用 CadQuery 建模import cadquery as cq import yaml with open(configs/flange.yaml) as f: cfg yaml.safe_load(f) result ( cq.Workplane(XY) .circle(cfg[outer_diameter] / 2) .circle(cfg[inner_diameter] / 2) .extrude(cfg[thickness]) ) # 打螺栓孔 import math for i in range(cfg[bolt_hole_count]): angle 2 * math.pi * i / cfg[bolt_hole_count] x (cfg[bolt_circle_diameter] / 2) * math.cos(angle) y (cfg[bolt_circle_diameter] / 2) * math.sin(angle) result ( result.faces(Z).workplane() .center(x, y) .hole(cfg[bolt_hole_diameter]) ) cq.exporters.export(result, models/flange.step)这段代码的逻辑很直白先画两个同心圆拉伸成环再在螺栓圆上均匀分布孔位逐个打孔。关键点是faces(Z)选择顶面作为工作平面center(x, y)把工作平面原点移到孔位hole()打穿整个厚度。参数计算部分角度用2πi/n均匀分配坐标用三角函数算出来这是最基础的极坐标转直角坐标。导出 STEP 后你可以直接拖进中望 CAD 或者 FreeCAD 里查看。我实测下来CadQuery 导出的 STEP 在主流 CAD 软件里兼容性很好曲面质量也够用。如果你需要更精细的控制比如变半径倒角、放样曲面可以切到 pythonocc-core 底层 API但代码量会大不少。4.2 生成 URDF 用于机器人仿真URDF 是机器人领域的标准格式CoppeliaSim 导入 URDF 后可以直接做运动学仿真。热词里“urdf导入coppeliasim”说明很多人卡在这一步。我用一个两连杆机械臂的例子说明怎么生成 URDF。URDF 本质是 XML描述连杆link和关节joint。连杆有视觉几何、碰撞几何、惯性参数关节有类型、轴、限位。用 Python 生成时我通常先写一个模板再用字符串替换填充参数URDF_TEMPLATE ?xml version1.0? robot namearm link namebase_link visual geometry cylinder radius{base_radius} length{base_height}/ /geometry /visual /link link namelink1 visual geometry box size{l1_x} {l1_y} {l1_z}/ /geometry /visual /link joint namejoint1 typerevolute parent linkbase_link/ child linklink1/ axis xyz0 0 1/ limit lower-3.14 upper3.14 effort10 velocity1/ /joint /robot params { base_radius: 0.05, base_height: 0.1, l1_x: 0.3, l1_y: 0.05, l1_z: 0.05, } with open(models/arm.urdf, w) as f: f.write(URDF_TEMPLATE.format(**params))这里单位是米不是毫米。URDF 遵循国际单位制导入 CoppeliaSim 后如果发现模型巨大或极小八成是单位搞错了。我踩过这个坑用毫米数值生成 URDF导入后机械臂有几百米长场景里根本看不到全貌。后来统一在脚本入口做单位转换毫米转米除以 1000问题解决。4.3 参数计算与约束检查text-to-cad 最容易出错的地方不是代码语法而是几何约束冲突。比如你写“外径 100内径 120”程序会报错或者生成一个空实体。再比如“螺栓圆直径 80螺栓孔直径 30孔数 6”相邻孔会重叠。这些在 CAD 里手动画图时你会立刻看到但在脚本里需要自己加检查。我的做法是在生成前加一段校验逻辑def validate_flange(cfg): if cfg[inner_diameter] cfg[outer_diameter]: raise ValueError(内径必须小于外径) hole_spacing ( math.pi * cfg[bolt_circle_diameter] / cfg[bolt_hole_count] ) if hole_spacing cfg[bolt_hole_diameter]: raise ValueError(螺栓孔间距不足孔会重叠) if cfg[bolt_circle_diameter] cfg[bolt_hole_diameter] cfg[outer_diameter]: raise ValueError(螺栓孔超出外径范围)这段校验看起来简单但能省下大量调试时间。你可以在 YAML 里随便改参数校验不通过直接报错不会生成一个错误的 STEP 文件流到下游。把问题拦截在生成阶段比导入 CAD 后才发现要返工成本低得多。5. 常见问题与排查技巧实录5.1 环境与安装类问题热词里大量出现“python安装”“python环境变量配置”“python安装numpy库的方法”说明环境问题是新手最大的拦路虎。我整理了一个速查表问题现象可能原因解决方法conda不是内部命令未将 conda 加入 PATH用 Anaconda Prompt 代替 cmdimport OCC报 DLL 错误缺少 VC 运行库安装 Visual C Redistributablepip install cadquery超时网络问题换 conda-forge 频道安装导入 STEP 后模型空白单位或坐标系问题检查导出时的单位设置URDF 导入 CoppeliaSim 报错XML 格式或路径错误用 xmllint 校验 XML其中“DLL 错误”和“URDF 导入报错”是我遇到最多的。DLL 问题基本靠装运行库解决URDF 问题多半是 mesh 文件路径写错了。URDF 里引用 STL 文件时路径可以是相对路径或package://格式CoppeliaSim 对相对路径的解析比较挑剔建议用绝对路径或者把 STL 和 URDF 放同一目录。5.2 几何生成类问题问题一布尔运算失败。当你做“长方体减去圆柱”时如果圆柱刚好和长方体表面相切布尔运算可能失败或产生退化面。解决方法是让圆柱稍微穿出表面比如多伸出去 0.1mm。这个技巧在 OpenCASCADE 里很常用叫“过切”。问题二倒角报错。对一条边倒角时如果相邻面的夹角太小或者倒角半径大于边长度操作会失败。我的经验是倒角半径不要超过最短边长度的 1/3并且优先对凸边倒角凹边倒角容易出问题。问题三STEP 导出后曲面丢失。这通常是精度设置问题。CadQuery 导出时可以指定公差cq.exporters.export(result, models/part.step, tolerance0.001)公差越小曲面越精细但文件越大。一般机械零件用 0.001mm 足够3D 打印用 0.01mm 也行。5.3 批量处理与自动化技巧热词里“python批量对cad修改”说明很多人有批量需求。我的做法是参数表格 循环生成。把不同零件的参数写进 CSV用 pandas 读取循环调用生成函数。比如import pandas as pd df pd.read_csv(configs/parts.csv) for _, row in df.iterrows(): cfg row.to_dict() validate_flange(cfg) generate_flange(cfg, fmodels/flange_{row[id]}.step)这样一次可以生成几十个零件每个文件名带 ID方便追溯。如果你需要合并多个 STEP 文件可以用 pythonocc-core 的STEPControl_Reader逐个读取再写入同一个文件但要注意坐标系对齐否则零件会叠在一起。提示批量生成前先用一个样本跑通全流程确认 STEP 能正常导入 CAD、URDF 能正常导入仿真环境再放开批量。否则错误会被放大几十倍排查起来很痛苦。6. 从文本到模型的进阶玩法与个人体会6.1 自然语言解析的可行路径前面主要讲结构化参数描述但 text-to-cad 的终极形态是自然语言直接生成。我试过用正则表达式提取“长10宽20高30”这类模式简单场景能用但稍微复杂一点就崩。比如“一个底座上面有个圆柱圆柱顶部倒角”正则根本处理不了。更可行的路径是规则引擎 模板匹配。先把常见几何特征归纳成模板比如“长方体”“圆柱”“孔”“倒角”“阵列”每个模板有对应的参数槽位。用户输入后用关键词匹配确定模板再用正则或分词提取参数。这种方法覆盖 80% 的常见需求剩下 20% 复杂结构还是得写脚本。我个人的判断是自然语言适合快速原型精确建模还是结构化描述靠谱。6.2 与 CAD 软件的双向协作text-to-cad 生成的 STEP 导入 CAD 后并不是终点。你可以在 CAD 里做进一步编辑比如添加工程图、标注尺寸、做装配约束。反过来CAD 里画好的模型也可以导出 STEP再用 Python 读取分析比如提取体积、表面积、重心。pythonocc-core 提供了GProp_GProps类做质量属性计算我常用它来验证生成模型的体积是否和理论值一致。这种双向协作的思路是用脚本做重复性生成用 CAD 做精细调整和出图。两者不是替代关系而是分工关系。我现在的流程是text-to-cad 生成初版导入中望 CAD 检查干涉和装配确认无误后出工程图。整个过程比纯手工建模快三到五倍。6.3 我踩过的坑与经验总结第一个坑是单位混乱。CAD 常用毫米URDF 用米STL 没有单位概念但导入时可能被缩放。我的做法是在项目根目录放一个units.py定义MM_TO_M 0.001所有转换都引用这个常量避免手写数字出错。第二个坑是坐标系不一致。CAD 里 Z 轴朝上机器人仿真里经常 Z 轴朝前或朝上导入后模型方向不对。解决方法是生成 URDF 时显式指定origin的rpy旋转或者在 CoppeliaSim 里导入后手动调整。我倾向于在生成阶段就处理好因为手动调整无法批量复现。第三个坑是文件命名冲突。批量生成时如果文件名只按类型命名后生成的会覆盖先生成的。加上时间戳或 ID 后缀就能避免。我现在的命名规则是{类型}_{ID}_{日期}.step比如flange_001_20250101.step一目了然。这个方向后续还可以这样扩展把生成脚本包装成命令行工具用argparse接收参数这样不写 Python 的人也能用或者接一个简单的 Web 界面输入参数点按钮就下载 STEP。再远一点结合参数优化算法自动搜索满足强度要求的最轻量化结构。不过那是另一个话题了先把基础流程跑通比什么都重要。
