：從自然語言到三維 CAD 模型的 Python 實現)
1. 從一句話到三維模型text-to-cad 到底在解決什么問題第一次聽到 text-to-cad 這個詞很多人腦子里冒出來的畫面是對著電腦敲一句“給我畫一個長寬高 100×60×40 的帶孔法蘭盤”然后屏幕上就自動出現一個可以旋轉、可以導出、可以進仿真軟件的三維模型。這個畫面放在幾年前還屬于科幻范疇但現在已經有一批開源項目和工具鏈把它做成了能跑通的流程。我自己是從機械設計轉過來的早些年畫一個標準件要開 CAD 軟件、建草圖、拉伸、打孔、倒角一套下來十幾分鐘就沒了重復勞動特別多。后來接觸到用代碼生成 CAD 的思路再往后看到 text-to-cad 這類方向第一反應就是這東西要是穩(wěn)定了能省掉大量重復建模的時間。先把概念說清楚。text-to-cad 不是一個具體的軟件而是一類“用自然語言描述幾何體由程序自動生成 CAD 模型文件”的技術路線。它的輸入是一段文本比如“一個外徑 80、內徑 40、厚度 10 的圓環(huán)”輸出通常是 STEP、STL、URDF 這類標準格式文件。STEP 是通用三維交換格式幾乎所有主流 CAD 軟件都能打開URDF 是機器人領域描述連桿和關節(jié)的格式常用于仿真STL 則是 3D 打印最常用的網格格式。這幾個格式對應了 text-to-cad 的三條主要落地路徑機械零件出圖、機器人模型搭建、3D 打印快速驗證。為什么這件事值得單獨拿出來講因為傳統(tǒng) CAD 建模是“手工活”而 text-to-cad 把它變成了“可編程、可批量、可版本管理”的工程流程。舉個最直接的例子你需要 20 個不同孔徑的法蘭盤傳統(tǒng)做法是一個個改參數重畫用代碼生成的話寫一個循環(huán)就出來了。再比如機器人仿真URDF 文件里全是數字手寫容易出錯用文本描述生成再校驗效率完全不一樣。適合看這篇內容的人有三類一是做機械設計、想擺脫重復建模的工程師二是做機器人仿真、需要批量生成 URDF 的同學三是想用 Python 玩三維建模、但不想學復雜 CAD 軟件的開發(fā)者。我下面會按“整體設計思路—核心細節(jié)—實操流程—問題排查”這條線展開把 text-to-cad 從原理到能跑起來的代碼都講一遍。文中涉及的代碼都是 Python依賴主要是 CadQuery 和 build123d 這類基于 OpenCASCADE 的建模庫環(huán)境配置我會給到具體命令。你不需要有很深的 CAD 背景但最好有一點 Python 基礎能看懂函數調用和列表循環(huán)就夠了。2. 整體設計思路為什么是“文本→代碼→幾何”這條鏈路2.1 三種技術路線的取舍邏輯text-to-cad 聽起來是一步到位實際上中間隔著好幾層。目前主流實現可以歸為三類理解這三類的區(qū)別你就知道該選哪條路。第一類是規(guī)則解析型。程序里預定義了一套語法模板比如“圓柱”“長方體”“圓環(huán)”“打孔”這些關鍵詞用戶輸入文本后用正則或簡單分詞提取參數再調用建模庫生成幾何。優(yōu)點是穩(wěn)定、可控、不依賴大模型缺點是只能處理預定義的句式稍微換個說法就識別不了。適合固定場景的批量出圖。第二類是大模型驅動型。用語言模型把自然語言翻譯成建模代碼通常是 CadQuery 或 OpenSCAD 的腳本再執(zhí)行代碼生成模型。優(yōu)點是靈活能處理復雜描述缺點是模型可能“胡說”生成的代碼語法錯誤或幾何不合理需要加校驗和重試機制。第三類是混合型。先用規(guī)則處理高頻簡單指令復雜描述再交給大模型同時用幾何校驗兜底。這是目前工程上最靠譜的做法也是我實際項目里采用的方案。選型的時候我踩過一個坑一開始想純靠大模型結果生成十個模型有三個打不開排查半天發(fā)現是布爾運算的順序錯了導致實體自相交。后來加了“生成后必須通過體積和包圍盒校驗”這一步問題才壓下去。所以我的建議是不管走哪條路幾何校驗環(huán)節(jié)不能省。2.2 為什么輸出格式首選 STEP很多人會問為什么不直接輸出 STL 就完事了這里要解釋一下。STL 是三角網格只記錄表面三角形沒有“圓柱面”“平面”這些幾何語義也沒有參數歷史。你拿到一個 STL想改孔徑只能重新生成沒法在 CAD 里直接編輯特征。STEP 不一樣它保留了幾何實體的拓撲關系是 B-rep邊界表示格式能被 FreeCAD、SolidWorks、中望 CAD 這些軟件識別為可編輯實體。所以 text-to-cad 的輸出策略通常是主輸出 STEP按需轉 STL 和 URDF。STEP 作為“源文件”STL 用于 3D 打印URDF 用于機器人仿真。轉換用 CadQuery 自帶的導出函數就能搞定不需要額外裝軟件。這個設計的好處是你的文本描述和生成的 STEP 之間是一一對應的改文本重新生成版本管理用 Git 就能做比手動改 CAD 文件靠譜得多。2.3 整體架構拆解一個能用的 text-to-cad 流程我把它拆成四層輸入層接收自然語言做基礎清洗比如統(tǒng)一單位、去掉口語化詞匯。解析層把文本轉成結構化的參數或者轉成建模代碼。建模層調用 CadQuery/build123d 執(zhí)行幾何構建輸出實體對象。校驗與導出層檢查實體是否有效體積大于零、無自相交然后導出 STEP/STL/URDF。這四層里解析層是最容易出問題的建模層是最需要經驗的。下面我會重點講這兩層。整個流程用 Python 串起來核心依賴就兩個cadquery和build123d前者成熟穩(wěn)定后者 API 更現代我兩個都用過后面會給對比。3. 核心細節(jié)解析文本怎么變成幾何參數3.1 自然語言到參數的映射規(guī)則文本轉幾何第一步是把“人話”翻譯成數字。這里面有幾個關鍵點。單位統(tǒng)一。用戶可能說“直徑 5 厘米”也可能說“半徑 25 毫米”程序必須統(tǒng)一到毫米。我的做法是在解析前先做單位歸一化識別“厘米”“米”“英寸”這些詞統(tǒng)一換算成毫米。英寸換算系數是 25.4這個別記錯。尺寸指代消歧?！耙粋€ 100 的方塊”這種描述100 到底是邊長還是對角線工程上默認是邊長。但“一個 100 的圓”就默認是直徑。這些約定要在解析規(guī)則里寫死否則大模型也會犯迷糊。特征順序。文本里說“帶兩個孔的板”孔的位置和孔徑如果沒給就得有默認值。我的默認策略是孔徑取板厚的 0.5 倍孔位對稱分布。這些默認值不是拍腦袋是參考了常見機械件的比例。下面這張表是我整理的常見描述到參數的映射可以直接拿去用文本描述解析結果默認值策略長方體/方塊length, width, height缺失項取已給項的 1 倍圓柱diameter/radius, height半徑缺失取高度 0.5 倍圓環(huán)outer_d, inner_d, thickness內徑取外徑 0.5 倍打孔hole_d, count, position孔徑取板厚 0.5 倍對稱分布倒角radius取最小邊長的 0.05 倍3.2 建模庫選型CadQuery 還是 build123d這兩個庫都是基于 OpenCASCADE 的 Python 封裝但風格差別很大。CadQuery 用的是鏈式調用寫起來像這樣import cadquery as cq result (cq.Workplane(XY) .box(100, 60, 40) .faces(Z) .workplane() .hole(10))build123d 用的是上下文管理器更接近傳統(tǒng) CAD 的操作邏輯from build123d import * with BuildPart() as p: Box(100, 60, 40) with Locations((0, 0, 20)): Hole(radius5)我的實際體驗是CadQuery 生態(tài)更成熟文檔多遇到問題好搜build123d 代碼更直觀適合復雜裝配體。如果你是新手建議從 CadQuery 入手因為網上例子多。如果你要做機器人 URDFbuild123d 對裝配和坐標系的支持更順手。注意兩個庫不能混用同一個進程OpenCASCADE 的底層句柄會沖突。選一個就用到底。3.3 幾何有效性校驗的三個指標生成完實體別急著導出先校驗。我用的三個指標體積大于零。solid.Volume() 0如果等于零說明實體是空的或者退化了。包圍盒合理。solid.BoundingBox()的尺寸應該和輸入參數吻合偏差超過 10% 就說明解析或建模有問題。實體數量正確。len(solid.Solids())應該等于預期比如一個帶孔的板應該還是一個實體如果變成兩個說明布爾運算失敗了。這三個檢查加起來不到十行代碼但能攔下八成以上的錯誤輸出。我見過太多人跳過校驗結果導出的 STEP 在 CAD 里打開是空文件白白浪費時間。4. 實操過程從零搭一個能跑的 text-to-cad 腳本4.1 環(huán)境準備與依賴安裝先把環(huán)境弄干凈。我推薦用 conda 建虛擬環(huán)境避免和系統(tǒng) Python 沖突。conda create -n text2cad python3.10 conda activate text2cad pip install cadquery build123d這里有個坑CadQuery 在 Windows 上裝的時候如果之前裝過其他版本的 OpenCASCADE可能會報 DLL 沖突。解決辦法是先卸載干凈再重裝。Linux 上一般沒這個問題但要注意libGL這類系統(tǒng)庫要裝全否則導入會報錯。驗證安裝import cadquery as cq print(cq.__version__)能打印出版本號就說明環(huán)境 OK。如果報ImportError八成是 OpenCASCADE 的動態(tài)庫沒找到Windows 上檢查 PATHLinux 上用ldd看依賴。4.2 一個最小可用的文本解析器先寫一個規(guī)則版的解析器處理最常見的幾種形狀。這段代碼可以直接抄import re def parse_text(text): text text.lower().replace( , ) # 單位歸一化 if 厘米 in text or cm in text: factor 10 elif 米 in text and 毫米 not in text: factor 1000 else: factor 1 # 提取所有數字 nums [float(n) * factor for n in re.findall(r\d\.?\d*, text)] if 圓柱 in text or 圓 in text: if len(nums) 2: return {type: cylinder, d: nums[0], h: nums[1]} if 方塊 in text or 長方體 in text or 板 in text: if len(nums) 3: return {type: box, l: nums[0], w: nums[1], h: nums[2]} return None這個解析器很粗糙但能覆蓋“直徑 50 高 100 的圓柱”這類描述。實測下來對于格式規(guī)整的輸入識別率能到七成以上。剩下的復雜描述就得靠大模型或者更細的規(guī)則。4.3 建模函數與導出拿到參數字典后調用 CadQuery 建模import cadquery as cq def build_model(params): if params[type] cylinder: solid cq.Workplane(XY).circle(params[d]/2).extrude(params[h]) elif params[type] box: solid cq.Workplane(XY).box(params[l], params[w], params[h]) else: raise ValueError(unsupported type) # 校驗 shape solid.val() assert shape.Volume() 0, 體積為零 bb shape.BoundingBox() print(f包圍盒: {bb.xlen:.1f} x {bb.ylen:.1f} x {bb.zlen:.1f}) return solid def export(solid, name): cq.exporters.export(solid, f{name}.step) cq.exporters.export(solid, f{name}.stl)跑一遍params parse_text(直徑 50 高 100 的圓柱) solid build_model(params) export(solid, test_cylinder)如果一切正常當前目錄下會出現test_cylinder.step和test_cylinder.stl。用 FreeCAD 打開 STEP應該能看到一個圓柱體。這一步跑通整個鏈路就活了。4.4 批量生成與參數掃描text-to-cad 真正的價值在批量。比如你要生成一系列不同孔徑的法蘭盤for d in [20, 30, 40, 50]: params {type: cylinder, d: d, h: 10} solid build_model(params) export(solid, fflange_dcpe4elpci5g)這段代碼幾秒鐘就能生成四個模型手動畫的話至少半小時。參數掃描在優(yōu)化設計里特別有用比如你想看不同壁厚對重量的影響寫個循環(huán)把體積打出來就行。4.5 URDF 導出與機器人仿真對接如果你做機器人URDF 是繞不開的。URDF 本質是 XML描述連桿的幾何、質量、慣性矩陣和關節(jié)。text-to-cad 生成的 STEP 可以轉成 URDF 里的 mesh 引用也可以直接用基本幾何體box、cylinder描述。一個簡單的連桿 URDF 片段link namelink1 visual geometry cylinder radius0.05 length0.2/ /geometry /visual collision geometry cylinder radius0.05 length0.2/ /geometry /collision inertial mass value1.0/ inertia ixx0.001 ixy0 ixz0 iyy0.001 iyz0 izz0.0005/ /inertial /link用 Python 生成這段 XML 不難難的是慣性矩陣的計算。對于圓柱繞中心軸的轉動慣量是0.5*m*r^2繞徑向是m*(3r^2h^2)/12。這些公式我建議直接寫成函數別每次手算。導入 CoppeliaSim 的時候注意 URDF 里的單位是米而 CAD 里通常是毫米導出前記得除以 1000否則模型會大一千倍在仿真里根本看不見。5. 常見問題與排查技巧實錄5.1 建模階段的典型報錯問題一布爾運算后實體消失。這通常是因為兩個實體沒有實際相交或者相減時把整個實體減沒了。排查方法是先分別導出兩個實體確認它們的位置關系。CadQuery 里可以用translate調整位置后再運算。問題二導出的 STEP 打不開。先檢查文件大小如果是 0 字節(jié)說明導出失敗如果幾 KB 但打不開可能是幾何無效。用shape.isValid()檢查返回 False 就說明有自相交或退化面。修復辦法是加clean()或者調整建模順序。問題三圓角報錯。倒圓角是最容易失敗的操 text-to-cad 實戰(zhàn)：從自然語言到三維 CAD 模型的 Python 實現
1. 從一句話到三維模型text-to-cad 到底在解決什么問題第一次聽到 text-to-cad 這個詞很多人腦子里冒出來的畫面是對著電腦敲一句“給我畫一個長寬高 100×60×40 的帶孔法蘭盤”然后屏幕上就自動出現一個可以旋轉、可以導出、可以進仿真軟件的三維模型。這個畫面放在幾年前還屬于科幻范疇但現在已經有一批開源項目和工具鏈把它做成了能跑通的流程。我自己是從機械設計轉過來的早些年畫一個標準件要開 CAD 軟件、建草圖、拉伸、打孔、倒角一套下來十幾分鐘就沒了重復勞動特別多。后來接觸到用代碼生成 CAD 的思路再往后看到 text-to-cad 這類方向第一反應就是這東西要是穩(wěn)定了能省掉大量重復建模的時間。先把概念說清楚。text-to-cad 不是一個具體的軟件而是一類“用自然語言描述幾何體由程序自動生成 CAD 模型文件”的技術路線。它的輸入是一段文本比如“一個外徑 80、內徑 40、厚度 10 的圓環(huán)”輸出通常是 STEP、STL、URDF 這類標準格式文件。STEP 是通用三維交換格式幾乎所有主流 CAD 軟件都能打開URDF 是機器人領域描述連桿和關節(jié)的格式常用于仿真STL 則是 3D 打印最常用的網格格式。這幾個格式對應了 text-to-cad 的三條主要落地路徑機械零件出圖、機器人模型搭建、3D 打印快速驗證。為什么這件事值得單獨拿出來講因為傳統(tǒng) CAD 建模是“手工活”而 text-to-cad 把它變成了“可編程、可批量、可版本管理”的工程流程。舉個最直接的例子你需要 20 個不同孔徑的法蘭盤傳統(tǒng)做法是一個個改參數重畫用代碼生成的話寫一個循環(huán)就出來了。再比如機器人仿真URDF 文件里全是數字手寫容易出錯用文本描述生成再校驗效率完全不一樣。適合看這篇內容的人有三類一是做機械設計、想擺脫重復建模的工程師二是做機器人仿真、需要批量生成 URDF 的同學三是想用 Python 玩三維建模、但不想學復雜 CAD 軟件的開發(fā)者。我下面會按“整體設計思路—核心細節(jié)—實操流程—問題排查”這條線展開把 text-to-cad 從原理到能跑起來的代碼都講一遍。文中涉及的代碼都是 Python依賴主要是 CadQuery 和 build123d 這類基于 OpenCASCADE 的建模庫環(huán)境配置我會給到具體命令。你不需要有很深的 CAD 背景但最好有一點 Python 基礎能看懂函數調用和列表循環(huán)就夠了。2. 整體設計思路為什么是“文本→代碼→幾何”這條鏈路2.1 三種技術路線的取舍邏輯text-to-cad 聽起來是一步到位實際上中間隔著好幾層。目前主流實現可以歸為三類理解這三類的區(qū)別你就知道該選哪條路。第一類是規(guī)則解析型。程序里預定義了一套語法模板比如“圓柱”“長方體”“圓環(huán)”“打孔”這些關鍵詞用戶輸入文本后用正則或簡單分詞提取參數再調用建模庫生成幾何。優(yōu)點是穩(wěn)定、可控、不依賴大模型缺點是只能處理預定義的句式稍微換個說法就識別不了。適合固定場景的批量出圖。第二類是大模型驅動型。用語言模型把自然語言翻譯成建模代碼通常是 CadQuery 或 OpenSCAD 的腳本再執(zhí)行代碼生成模型。優(yōu)點是靈活能處理復雜描述缺點是模型可能“胡說”生成的代碼語法錯誤或幾何不合理需要加校驗和重試機制。第三類是混合型。先用規(guī)則處理高頻簡單指令復雜描述再交給大模型同時用幾何校驗兜底。這是目前工程上最靠譜的做法也是我實際項目里采用的方案。選型的時候我踩過一個坑一開始想純靠大模型結果生成十個模型有三個打不開排查半天發(fā)現是布爾運算的順序錯了導致實體自相交。后來加了“生成后必須通過體積和包圍盒校驗”這一步問題才壓下去。所以我的建議是不管走哪條路幾何校驗環(huán)節(jié)不能省。2.2 為什么輸出格式首選 STEP很多人會問為什么不直接輸出 STL 就完事了這里要解釋一下。STL 是三角網格只記錄表面三角形沒有“圓柱面”“平面”這些幾何語義也沒有參數歷史。你拿到一個 STL想改孔徑只能重新生成沒法在 CAD 里直接編輯特征。STEP 不一樣它保留了幾何實體的拓撲關系是 B-rep邊界表示格式能被 FreeCAD、SolidWorks、中望 CAD 這些軟件識別為可編輯實體。所以 text-to-cad 的輸出策略通常是主輸出 STEP按需轉 STL 和 URDF。STEP 作為“源文件”STL 用于 3D 打印URDF 用于機器人仿真。轉換用 CadQuery 自帶的導出函數就能搞定不需要額外裝軟件。這個設計的好處是你的文本描述和生成的 STEP 之間是一一對應的改文本重新生成版本管理用 Git 就能做比手動改 CAD 文件靠譜得多。2.3 整體架構拆解一個能用的 text-to-cad 流程我把它拆成四層輸入層接收自然語言做基礎清洗比如統(tǒng)一單位、去掉口語化詞匯。解析層把文本轉成結構化的參數或者轉成建模代碼。建模層調用 CadQuery/build123d 執(zhí)行幾何構建輸出實體對象。校驗與導出層檢查實體是否有效體積大于零、無自相交然后導出 STEP/STL/URDF。這四層里解析層是最容易出問題的建模層是最需要經驗的。下面我會重點講這兩層。整個流程用 Python 串起來核心依賴就兩個cadquery和build123d前者成熟穩(wěn)定后者 API 更現代我兩個都用過后面會給對比。3. 核心細節(jié)解析文本怎么變成幾何參數3.1 自然語言到參數的映射規(guī)則文本轉幾何第一步是把“人話”翻譯成數字。這里面有幾個關鍵點。單位統(tǒng)一。用戶可能說“直徑 5 厘米”也可能說“半徑 25 毫米”程序必須統(tǒng)一到毫米。我的做法是在解析前先做單位歸一化識別“厘米”“米”“英寸”這些詞統(tǒng)一換算成毫米。英寸換算系數是 25.4這個別記錯。尺寸指代消歧?！耙粋€ 100 的方塊”這種描述100 到底是邊長還是對角線工程上默認是邊長。但“一個 100 的圓”就默認是直徑。這些約定要在解析規(guī)則里寫死否則大模型也會犯迷糊。特征順序。文本里說“帶兩個孔的板”孔的位置和孔徑如果沒給就得有默認值。我的默認策略是孔徑取板厚的 0.5 倍孔位對稱分布。這些默認值不是拍腦袋是參考了常見機械件的比例。下面這張表是我整理的常見描述到參數的映射可以直接拿去用文本描述解析結果默認值策略長方體/方塊length, width, height缺失項取已給項的 1 倍圓柱diameter/radius, height半徑缺失取高度 0.5 倍圓環(huán)outer_d, inner_d, thickness內徑取外徑 0.5 倍打孔hole_d, count, position孔徑取板厚 0.5 倍對稱分布倒角radius取最小邊長的 0.05 倍3.2 建模庫選型CadQuery 還是 build123d這兩個庫都是基于 OpenCASCADE 的 Python 封裝但風格差別很大。CadQuery 用的是鏈式調用寫起來像這樣import cadquery as cq result (cq.Workplane(XY) .box(100, 60, 40) .faces(Z) .workplane() .hole(10))build123d 用的是上下文管理器更接近傳統(tǒng) CAD 的操作邏輯from build123d import * with BuildPart() as p: Box(100, 60, 40) with Locations((0, 0, 20)): Hole(radius5)我的實際體驗是CadQuery 生態(tài)更成熟文檔多遇到問題好搜build123d 代碼更直觀適合復雜裝配體。如果你是新手建議從 CadQuery 入手因為網上例子多。如果你要做機器人 URDFbuild123d 對裝配和坐標系的支持更順手。注意兩個庫不能混用同一個進程OpenCASCADE 的底層句柄會沖突。選一個就用到底。3.3 幾何有效性校驗的三個指標生成完實體別急著導出先校驗。我用的三個指標體積大于零。solid.Volume() 0如果等于零說明實體是空的或者退化了。包圍盒合理。solid.BoundingBox()的尺寸應該和輸入參數吻合偏差超過 10% 就說明解析或建模有問題。實體數量正確。len(solid.Solids())應該等于預期比如一個帶孔的板應該還是一個實體如果變成兩個說明布爾運算失敗了。這三個檢查加起來不到十行代碼但能攔下八成以上的錯誤輸出。我見過太多人跳過校驗結果導出的 STEP 在 CAD 里打開是空文件白白浪費時間。4. 實操過程從零搭一個能跑的 text-to-cad 腳本4.1 環(huán)境準備與依賴安裝先把環(huán)境弄干凈。我推薦用 conda 建虛擬環(huán)境避免和系統(tǒng) Python 沖突。conda create -n text2cad python3.10 conda activate text2cad pip install cadquery build123d這里有個坑CadQuery 在 Windows 上裝的時候如果之前裝過其他版本的 OpenCASCADE可能會報 DLL 沖突。解決辦法是先卸載干凈再重裝。Linux 上一般沒這個問題但要注意libGL這類系統(tǒng)庫要裝全否則導入會報錯。驗證安裝import cadquery as cq print(cq.__version__)能打印出版本號就說明環(huán)境 OK。如果報ImportError八成是 OpenCASCADE 的動態(tài)庫沒找到Windows 上檢查 PATHLinux 上用ldd看依賴。4.2 一個最小可用的文本解析器先寫一個規(guī)則版的解析器處理最常見的幾種形狀。這段代碼可以直接抄import re def parse_text(text): text text.lower().replace( , ) # 單位歸一化 if 厘米 in text or cm in text: factor 10 elif 米 in text and 毫米 not in text: factor 1000 else: factor 1 # 提取所有數字 nums [float(n) * factor for n in re.findall(r\d\.?\d*, text)] if 圓柱 in text or 圓 in text: if len(nums) 2: return {type: cylinder, d: nums[0], h: nums[1]} if 方塊 in text or 長方體 in text or 板 in text: if len(nums) 3: return {type: box, l: nums[0], w: nums[1], h: nums[2]} return None這個解析器很粗糙但能覆蓋“直徑 50 高 100 的圓柱”這類描述。實測下來對于格式規(guī)整的輸入識別率能到七成以上。剩下的復雜描述就得靠大模型或者更細的規(guī)則。4.3 建模函數與導出拿到參數字典后調用 CadQuery 建模import cadquery as cq def build_model(params): if params[type] cylinder: solid cq.Workplane(XY).circle(params[d]/2).extrude(params[h]) elif params[type] box: solid cq.Workplane(XY).box(params[l], params[w], params[h]) else: raise ValueError(unsupported type) # 校驗 shape solid.val() assert shape.Volume() 0, 體積為零 bb shape.BoundingBox() print(f包圍盒: {bb.xlen:.1f} x {bb.ylen:.1f} x {bb.zlen:.1f}) return solid def export(solid, name): cq.exporters.export(solid, f{name}.step) cq.exporters.export(solid, f{name}.stl)跑一遍params parse_text(直徑 50 高 100 的圓柱) solid build_model(params) export(solid, test_cylinder)如果一切正常當前目錄下會出現test_cylinder.step和test_cylinder.stl。用 FreeCAD 打開 STEP應該能看到一個圓柱體。這一步跑通整個鏈路就活了。4.4 批量生成與參數掃描text-to-cad 真正的價值在批量。比如你要生成一系列不同孔徑的法蘭盤for d in [20, 30, 40, 50]: params {type: cylinder, d: d, h: 10} solid build_model(params) export(solid, fflange_dcpe4elpci5g)這段代碼幾秒鐘就能生成四個模型手動畫的話至少半小時。參數掃描在優(yōu)化設計里特別有用比如你想看不同壁厚對重量的影響寫個循環(huán)把體積打出來就行。4.5 URDF 導出與機器人仿真對接如果你做機器人URDF 是繞不開的。URDF 本質是 XML描述連桿的幾何、質量、慣性矩陣和關節(jié)。text-to-cad 生成的 STEP 可以轉成 URDF 里的 mesh 引用也可以直接用基本幾何體box、cylinder描述。一個簡單的連桿 URDF 片段link namelink1 visual geometry cylinder radius0.05 length0.2/ /geometry /visual collision geometry cylinder radius0.05 length0.2/ /geometry /collision inertial mass value1.0/ inertia ixx0.001 ixy0 ixz0 iyy0.001 iyz0 izz0.0005/ /inertial /link用 Python 生成這段 XML 不難難的是慣性矩陣的計算。對于圓柱繞中心軸的轉動慣量是0.5*m*r^2繞徑向是m*(3r^2h^2)/12。這些公式我建議直接寫成函數別每次手算。導入 CoppeliaSim 的時候注意 URDF 里的單位是米而 CAD 里通常是毫米導出前記得除以 1000否則模型會大一千倍在仿真里根本看不見。5. 常見問題與排查技巧實錄5.1 建模階段的典型報錯問題一布爾運算后實體消失。這通常是因為兩個實體沒有實際相交或者相減時把整個實體減沒了。排查方法是先分別導出兩個實體確認它們的位置關系。CadQuery 里可以用translate調整位置后再運算。問題二導出的 STEP 打不開。先檢查文件大小如果是 0 字節(jié)說明導出失敗如果幾 KB 但打不開可能是幾何無效。用shape.isValid()檢查返回 False 就說明有自相交或退化面。修復辦法是加clean()或者調整建模順序。問題三圓角報錯。倒圓角是最容易失敗的操