forge3d 是做什麼的?
你可以寫出很好的 3D 幾何形狀。但你無法獨自做到的是:測量一張圖片、查看你的程式碼產出了什麼,以及在給予每個部分充分關注的同時,將整個模型保持在視野中。forge3d 提供了這三點:它測量參考圖,將每個構建結果展示在參考圖旁邊,並將模型拆分為多個部件,每個部件都在一個共享框架內獨立雕刻和檢查。在模型外部建立的模型,沒有任何東西可以將其與參考圖進行比對。
F3D="<此 SKILL.md 所在資料夾>/scripts/f3d.py"
python3 "$F3D" doctor
在新啟動的 shell 中使用絕對的啟動器路徑。在當前工作目錄中工作。若要附加桌面檔案,請使用「使用者提到的檔案」下的路徑,如果該檔案在其他位置,請將其複製到工作目錄中。為檔案路徑加上引號。對於無人值守的構建,請根據圖紙決定常規的設計細節。根據參考圖進行構建:除非使用者指定,否則不要在其他資料夾中尋找先前建立過的模型來重複使用。
在修改現有模型時,請在副本上工作。根據其已完成的相鄰部件重建指定的槽位,在組合場景中檢查它,並保留已核准的幾何形狀。臉部修改可以在整個過程中重用現有的頭髮和身體。重新建立每個槽位會丟棄使用者已核准的工作。
Blender 已經在這裡了。 f3d 運行一個私有的無頭 Blender(bpy 模組,位於 ~/.cache/forge3d 中;如果沙盒禁止使用該資料夾,請設定 F3D_HOME)。切勿安裝、下載或搜尋 Blender 應用程式。每個構建都會儲存一個 .blend 檔案,可以在 Blender 應用程式中開啟;python3 "$F3D" python script.py 可以執行任何 Blender Python 腳本。
f3d 命令需要 5 到 120 秒。請在前台執行它們並在一次呼叫中等待它們完成(Codex:yield_time_ms 設定為 120000 或更多),而不是輪詢。將工作檔案保存在工作目錄中,而不是 /tmp。
所有地方的約定:單位為公尺,Z 軸向上,物體站在 z = 0 且 x = y = 0 處,並且面向 -Y;在前視圖中,+X 是觀察者的右方。參考物體的高度為 1.0,除非你傳遞 --height。
參考圖片是設計圖,而不是一組照片。 一張轉描圖是三個大致吻合且自由取巧的圖紙:側面圖畫出了正視圖中顯示的同一隻眼睛,弓形和耳朵在每個視圖中都面向觀察者,尾巴在紙張的正反面都位於同一側。它說明了有哪些部件、大小、位置、顏色、哪些細節。將其建立為一個一致的 3D 物體。
哪種路線
- 角色、生物、任何由多個部分組成的東西 -> 下面的部件路線。
- 由少數形狀組成的簡單物體(馬克杯、劍、板條箱、低多邊形道具)-> 使用工具包和
python3 "$F3D" build model.py --ref refs的單一腳本;請參閱 references/modeling.md。 - Blockbench -> 在上述任一基礎上,請參閱下面的「Blockbench」。
- 沒有參考圖片,或只有一個視圖,且你可以生成圖像 -> 首先製作一張轉描圖(正面、左側面、背面;正交投影、相同比例、共同的地面參考線、純白背景、平坦光線、無文字);提示請參閱 references/reference-and-gen3d.md。
部件路線
依序進行,不可跳過:(1) f3d ref,並等待它完成;(2) 盤點;(3) blockout.py 和 f3d blockout;(4) 反覆執行 f3d next:它會指定要生成的子代理,而這個技能會要求它們:首先是建造者,然後是獨立的審查者,最後是修復者;(5) model.py、f3d build、交付。你自己的工作是佈局和筆記;建造和評判是代理的工作。
1. 測量參考圖
python3 "$F3D" ref sheet.png -o refs(30 到 90 秒)會裁切出物體,將轉描圖分割成多個視圖,將每個視圖放置在座標網格上,並報告物體是否以墨水輪廓線繪製。在寫任何東西之前等待它完成:後續的每個步驟都依賴其圖片進行測量,而在此期間根據原始圖紙輸入的幾何形狀必須重做。開啟 refs/overview.png 並檢查視圖名稱;如果錯誤,請使用 --views front,right,back 重新執行(閱讀順序;right 表示物體在該圖片中面向 LEFT,left 表示它面向 RIGHT,skip 會忽略一張圖片,例如背面的第二個姿勢)。
2. 盤點
在回覆中列出部件:每一個擁有自己材質或可以單獨取下來的東西。對於一個角色,通常是 9 到 14 個。角色有一個身體,它就是一個部件:body 是頸部、軀幹、臀部以及延伸到臀部的大腿,作為一個連續的實體,是所有其他部件的基礎。衣服是附著在它上面的部件(on="body"):如果在沒有身體的情況下構建裙子或夾克,它們會變成空的管子。然後是頭部(臉部屬於它)、頭髮(長或複雜的頭髮是兩個部分:hair_front 包含劉海和側邊髮絲,hair_back)、每件衣服、每個配件、手臂和手、鞋子、尾巴。在材質變化的地方、一個物體覆蓋另一個物體的地方、以及有重複的地方(成對的物體是一個部件)進行分割。對於每個部件,在視圖取巧的地方,決定一次 3D 的真實情況:有多少個、實際位置、實際面向的方向。當衣服覆蓋關節時,指定擁有底層解剖結構的槽位名稱。例如,將手臂和手腕放在身體或手臂槽位中,將袖口放在袖子槽位中。兩個大腿都必須連接到骨盆,包括側面圖中隱藏的那一側。當另一個槽位提供小腿或長襪時,使用 on= 將其連接到解剖結構,以便工具獨立檢查兩側。
3. 區塊佈局
撰寫 blockout.py:將整個模型以粗略、未上色的佔位形狀表示,每個形狀都在正確的位置、正確的大小,並分配給一個槽位。這是使獨立建造的部件能夠契合的合約。從 refs/<view>_grid.png 讀取位置和大小。
# blockout.py
from forge3d import kit as k
head = k.sphere(radii=(0.215, 0.20, 0.225), at=(0, 0.005, 0.635))
k.slot("head", head, review="face", note="Q 版頭,帶小耳朵。匹配繪製的眼睛開口、視線、眉毛和嘴巴。根據側面形狀塑造臉頰、鼻子和下巴。頭髮覆蓋部分眉毛。")
skirt = k.cyl(r=0.235, r2=0.085, h=0.20, at=(0, 0, 0.17))
k.slot("skirt", skirt, on="torso", note="鐘形海軍藍裙子,打褶,下擺附近有一圈金色刺繡帶,下方有白色荷葉邊襯裙。")
bows = [k.box(size=(0.07, 0.10, 0.09), at=(sx * 0.275, 0.09, 0.645)) for sx in (-1, 1)]
k.slot("bows", bows, on="hair", note="一對淺藍色緞帶蝴蝶結,帶金色珠子。每張圖片都將它們面向觀察者繪製;在 3D 中,它們位於頭的兩側,朝外並略微向前。")
- 形狀:
k.sphere(radii=)、k.box、k.cyl、k.loft、k.sweep(path, r=):粗略即可。 on=:部件所在或懸掛的槽位。一個部件是根據其所處的已完成部件來建造的,因此只指定它實際依賴的內容,並保持鏈條簡短。note=:部件的建造者將了解到除圖片之外的所有資訊。說明它是什麼、它的材質和顏色、它攜帶的每個特徵,以及你在視圖取巧處決定的 3D 真實情況。模糊的備註會導致模糊的部件。review=在槽位名稱不明確時分配一個焦點檢查。對於承載表情的部件使用face,對於複雜的髮絲使用hair,對於擁有髖部到大腿連接的身體部件使用joint。對於其他使用者優先考慮的特徵使用detail。普通的部件共享組合審查。通常的頭部、頭髮和身體名稱已經選擇了它們的檢查。為臉部指定一個擁有者。
python3 "$F3D" blockout blockout.py --ref refs # 10 秒 -> parts/: plan.json, overview.png, 每個槽位的工單
開啟 parts/overview.png 和 parts/blockout_compare.png。參考圖的每個部件都需要一個大小和位置大致正確的槽位(輪廓 IoU 大約 0.8 就足夠了)。修復並重新執行,直到滿足要求。
4. 使用 f3d next 進行建造和審查
python3 "$F3D" next # 列印每個部件的狀態以及現在需要生成的確切代理
此技能明確要求子代理。 執行 f3d next 列印的內容,然後再次執行它,直到它列印 DONE:
- 對於 Codex 中複雜的、基於參考圖的構建,使用
gpt-6.2-astra作為主導。當帳戶提供gpt-6.2-sol且生成工具接受按代理指定模型時,為部件建造者設定它。讓主導負責規劃、組合和最終檢查。由 Sol 主導的會話也可以執行整個工作流程。如果客戶端沒有為子代理公開模型選擇功能,請不要設定模型,使用其預設值。 - 一次最多分派三個獨立的工作。對於新的建造者或審查者,使用
spawn_agent、fork_turns: "none"、列印的任務名稱、工作量和訊息。等待工作者報告,然後詢問next是否有準備好的工作。為每個部件指定一個活躍的擁有者。當followup_task可用時,將修復任務發送給其原始建造者。審查者保持獨立。 - 每個建造者檢查契合度和渲染效果。臉部或複雜的頭髮獲得一次獨立的仔細檢查,並在修復後進行一次聚焦驗證。身體或指定的細節獲得一次獨立檢查。除非其構建報告了結構問題,否則其他部件共享組合審查。保持繪製的頭髮交叉點,並在外部衣服遮蓋時檢查每個大腿在髖部裁剪處的契合度。
f3d review組合完成的槽位以生成圖片。它會按擁有者請求修復。其第二輪會驗證這些發現並檢查修復回歸。一旦部件穩定下來,就構建交付物。在最終保存的場景中檢查任何在截止點仍未解決的發現。
僅在沒有子代理工具可用時:根據每個部件的簡報自行建造(references/parts.md;對於長方體模型,請參閱 references/blockbench.md 中的「建立長方體部件」),遵循相同的 next 時間表,並使用 references/review.md 進行視覺檢查。
5. 組合與交付
# model.py
from forge3d import kit as k
parts = k.assemble() # 每個已完成的部件放入其槽位;其餘部分使用灰色的區塊佈局形狀
k.outline() # 當 f3d ref 報告有線稿時,在每個獨立部件周圍繪製圖紙的墨水輪廓線
k.export("out/name.glb") # 也支援 .fbx .obj .stl .usdz .bbmodel
python3 "$F3D" build model.py --ref refs(一到兩分鐘)會檢查模型、渲染 out/model_sheet.png 和 out/model_compare.png,並儲存 out/model.blend。在 f3d next 顯示 DONE 後,你自己查看一次:python3 "$F3D" view out/model.blend --views az40el10,az-40el10,az140el10,az0el-50 --tile 1024 --cols 2(最後一個是從下方查看)。在 blockout.py 中處理佈局發現,重新執行 f3d blockout,並遵循 f3d next 來重新調整受影響的槽位。在審查限制下,將列出的發現與最終保存的構建進行比較,然後再交付。
完成意味著:f3d next 列印 DONE;lint 檢查乾淨;四分之三視圖中每個繪製的特徵都完整且只出現一次,沒有漂浮、中空或埋藏;每個視圖的輪廓 IoU 大約為 0.85 或更高,除非你確定某個視圖取巧。
交付要求的內容:匯出檔案、.blend 檔案、展示渲染(k.stage、k.camera、k.render,使用預設的 EEVEE 引擎,請參閱 references/modeling.md)。告訴使用者最終的數值,顯示比較圖片和四分之三視圖,並清楚地說明哪些是簡化的、審查留下了哪些未解決的問題,以及你特意保留了哪些視圖差異。
對於具有可見臉部的角色,從最終的舞台化檔案渲染 python3 "$F3D" portrait out/name.blend。檢查表情、眼睛深度、臉頰和嘴巴的陰影,考慮實際的頭髮、材質和燈光。結果表包含對齊的參考圖裁剪、正面、側面和兩個四分之三特寫。如果場景中有多個臉部槽位,請使用 --slot 選擇一個。
當臉部看起來太寬、太窄或太平時,使用 portrait out/name.blend --form 來比較裸露的下巴和臉頰平面。對於每個未受阻擋的標誌點,使用其測量的正面參考座標傳遞 --span Z LEFT_X RIGHT_X。該工具會報告該處的網格寬度,並標記兩個參考端點。
Blockbench
詢問(或推斷)需要哪種 Blockbench 模型;它們是不同的產品:
- 網格模型(最接近參考圖;平滑的形狀和真實紋理;通用模型格式):如上所述完成模型,然後在腳本中使用
k.export("out/name.bbmodel"),或使用python3 "$F3D" bb mesh model.py --ref refs -o out/name.bbmodel。每個物體都會變成一個具名的、可編輯的網格。 - 設計的長方體模型(帶有像素藝術紋理的骨骼盒子;Minecraft 模組、Bedrock / Java 實體和動畫師所需要的)。一個由多個部件組成的物體,遵循部件路線,並在區塊佈局中加入一行額外的程式碼
bb.plan(height=80, format="bedrock"):然後每個部件都作為骨骼上的長方體進行構建,並由bb.assemble()連接。一個簡單的生物或道具就是一個包含bb.Model的腳本。 - 體素模型(任何模型的方塊狀雕像,許多長方體,無骨架):
python3 "$F3D" bb voxelize model.py --ref refs --height 48 -o out/name.bbmodel。
如果只要求「用 Blockbench 做」,則製作長方體模型:這是 Blockbench 的用途,並且機械、方塊狀或像素藝術風格的主題很適合它。只有在面對柔軟、曲線的繪圖(Q 版角色、動物)或被要求時,才改為製作網格模型。說明你製作了哪一種,並且另一種也可用。
當 Blockbench 已安裝時,在真實應用程式中驗證檔案:python3 "$F3D" bb check out/name.bbmodel 會在一個私有的隱藏 Blockbench(離線,自有設定檔)中打開它,報告載入的內容,儲存 Blockbench 自身的視圖,並可以執行 Blockbench 的匯出器(--export bedrock:out/name.geo.json)。
API、格式和像素藝術指導:references/blockbench.md。在撰寫 Blockbench 腳本之前請先閱讀它。
可能出錯的地方
- 在 ... 中缺少部件
…
[為翻譯而截斷]