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