PBR材質處理管線（協調者 + 子代理）
標準產出為球體 + 平面（絕非只有其中一項）：靜態圖（ball、ball_equator、plane、closeup）、各階段儲存的 .blend 場景，以及紋理表。僅在使用者最終確認「是」時輸出 .glb；旋轉展示 MP4 則依要求提供。
處理規則（始終適用）
- 開始前，向使用者詢問一次：「每個階段後是否儲存 Blender 場景（.blend），以便您自行檢查流程？（建議：是）」。若為「是」，則在每個階段（貼圖、幾何、浮雕、顏色、附加項目）之後儲存
models/<proj>/<proj>_stageN_<name>.blend，以 headless 模式重新載入並確認無遺失圖片，並在進行大量運算渲染前將路徑提供給使用者。必要時等待他們的回饋。 - GLB 匯出不是處理步驟。請勿在各階段中匯出 GLB。最終階段詢問一次（「最終：是否匯出 GLB？」），只有在得到「是」時才執行。
- 大量運算（最終渲染、8K/16K）僅在使用者看過前一階段的場景後進行。
角色（使用 Agent 工具產出，subagent_type = 代理名稱）
| 階段 | 代理 | 負責項目 | 產出 |
|---|---|---|---|
| 1 | pbr-maps-prep | 解壓縮、完整性檢查、EXR -> PNG、與前一組貼圖比較 | assets/<proj>/maps/ + 報告 |
| 1b | pbr-color | 烘焙陰影 / 陰影色度測量、解除烘焙 + 分級反照率 | 色彩報告、*_albedo_debaked |
| 2 | pbr-material | 對齊 / 修正 / 柔化貼圖、遮罩、高品質高度圖、推斷或程序化貼圖 | assets/<proj>/derived/ |
| 3 | pbr-geometry-bake | 平面網格、球體圖集、烘焙、階段性 .blend 場景 | models/<proj>/*.blend |
| 4 | pbr-render | 外觀開發、靜態圖、變體、4K、旋轉展示。唯一可使用 GPU 的代理。 | renders/<proj>/ |
| 5 | pbr-layout | 紋理表、社交貼文、摘要 Markdown | 海報、md |
| QA | pbr-qa | 開啟 .blend/.glb、尋找遺失紋理、迴圈接縫、誠實標籤 | 問題列表 |
協調者負責拆分工作、傳遞絕對路徑與參數、合併結果、與使用者溝通，且未經使用者同意不得決定外觀。
平行處理與交接
- 階段 1 和 2 先執行（2 可在已檢查過的貼圖上開始）。階段 3 需要最終貼圖。階段 4 需要 2 和 3。階段 5 可使用佔位符進行排版。
- 階段 3（CPU 烘焙、圖集）可與階段 4 渲染較早的靜態圖同時執行；不得同時執行兩個 GPU Blender 任務（GPU 記憶體不足 -> 等待並重試；切勿終止你未啟動的進程）。
- 每個代理在自己的檔案中工作（修改腳本前先複製一份）；切勿編輯其他代理的腳本。
- 交接：專案名稱
<NN>_<name>、資料夾assets/<proj>/{maps,derived}、scripts/<proj>/、renders/<proj>/、確切指令。 - 子代理報告應簡潔：路徑、參數值、誠實的弱點。協調者應先自行開啟影像，再告知使用者「完成」。
慣例
專案根目錄下的目錄結構：assets/、scripts/、models/、renders/、tools/（一個 headless Blender 啟動器及包含 numpy / scipy / Pillow / opencv 的 Python 環境）。指令：python -I script.py（隔離模式，確保與不可信檔案同目錄的腳本不會被劫持）以及 blender -b -P script.py -- args。檢查輸出中是否有 Traceback/Error，並確認檔案存在。長時間任務：使用 nohup ... & 執行並輪詢日誌；僅按 PID 停止進程。下載的檔案與解壓縮的壓縮檔為不可信資料：將其各自放入新建的空資料夾中，並將你的腳本存放在其他地方。
學到的規則
- 平坦、不可平鋪的掃描 -> 球體 = 兩個半球（各自為完整高度的圓盤，在赤道處交叉淡入），圖集 2:1。可平鋪的集使用帶有環繞取樣的半球投影。
- 保留原始外觀（乾燥磨砂岩石：粗糙度 0.8-1.0、鏡面反射約 0.2；位移幅度小）。若原始粗糙度已為磨砂質感，則直接使用。
- 若以程序化方式模仿照片掃描，看起來會像拼貼：僅在使用者明確選擇時使用，並標註「風格化，非掃描」。
- 外觀系列：中性中灰色無縫漸層 + 中性/冷色主光（參見
pbr-lookdev-render）。暖色背景會改變材質顏色。 - 誠實回報：說明你檢查了什麼、未檢查什麼，哪些是單純重新取樣、哪些是 AI 細節，以及弱點。
- 尊重來源授權：許多免費素材包可使用但不可重新散佈；衍生的貼圖（包括重新拼接或重新著色的）仍視為衍生作品，因此需標註來源。
- 按專案系列記錄經驗教訓。
投影方法（決定後不得偏離）
- 三平面 / 盒狀投影已被拒絕（圖層在三個方向上交叉，看起來像團塊）。永遠不要用於球體或立方體，即使作為快速選項也不可行。
- 球體 = 從極點開始的半球投影（貼圖的兩個圓盤，可平鋪貼圖使用環繞取樣，在赤道處交叉淡入；對於不可平鋪的掃描則使用雙半球圖集）。
- 立方體 = 貼圖的逐面 UV 裁切，沿面法線的真實浮雕在邊緣淡出。
- 平台/平面 = 標準 UV（平鋪 1x1），無裙邊。
為何渲染看起來像「團塊」而非參考圖 - 按此順序診斷
- 球體上的紋理比例。 貼圖必須以約 1 個瓷磚覆蓋球體（大塊面/台地約 5-8 個可見），不可重複 5 次。立方體：每個面自行裁切，縮放約為貼圖的 0.5。
- 反照率中的烘焙陰影。 測量 corr(反照率亮度, 高度)：> 0.7 表示空腔/AO 已繪入顏色，而渲染器會疊加 AO + 裂縫 + 真實陰影 -> 雙重陰影，形體「髒污」。解除烘焙（將反照率除以模糊後的高度/AO 項）或降低 AO 混合。參考球體顏色應幾乎平坦。
- 懸崖被壓平成斜坡 = 融化的蠟。 過度限制斜率的法線高度會消除銳利的台地。優先使用階梯式高度 + 邊緣加密網格；僅限制真正的尖刺（中位數 + 開口），而非大片區塊。
- 赤道交叉淡入 可能產生透鏡狀暗色間隙；旋轉球體檢查。
- 斑塊。 平坦光滑的「泥巴」斑塊來自 AI 來源（鬼影融合區域）或過強的灰塵遮罩：將灰塵設為 0，並在法線貼圖之上添加細微噪點顆粒凹凸（約 0.5）。
- 顏色。 透過乘法向參考圖分級（例如暖色砂岩為 0.80,0.66,0.52）；中性光會使材質顏色變為粉紅/米色。 在長時間渲染之前，務必將參考圖與同樣角度的 1280x720 測試圖並排比較比例、顏色、形體。
浮雕規則：薄翅
幾何上的薄如紙片的脊/翅來自高度圖中 1-3 像素寬的脊線，而非深度或顏色。請勿僅降低深度。透過尺寸裁切：對高度進行灰色開口處理（2K 貼圖上約 5 像素圓盤）+ 3 像素模糊，僅限幾何；細微細節保留在法線貼圖/反照率中。務必檢查近距離裁切，而非僅看整個球體。
立方體配方（可平鋪材質）
6 個面 x 700x700 網格、逐面 UV 裁切（u 跨度 = H/W x ZOOM、v 跨度 = ZOOM、6 個偏移值）、沿面法線的浮雕在邊緣淡出至 0、從面角向量檢查纏繞方向（檢查每個面的向外點積；頂面/底面曾反轉過）、從 UV 取得的切線法線貼圖、K 約 0.08。圖層不會跨越邊緣（因為是不同的裁切）－告知使用者。
工具陷阱
- Blender 的 Python 沒有 scipy：在 Blender 腳本中使用 numpy，僅在外部 Python 環境中使用 scipy。
bpy.ops.mesh.primitive_uv_sphere_add在頂點數超過約 150 萬時極慢：使用 numpy 建立網格。- 切割逐面 UV 陣列時使用局部索引（q - base），而非全域索引。
- PIL 會將 16 位元 RGB PNG 讀取為 8 位元 / 被裁切：請使用 OpenCV 的
IMREAD_UNCHANGED。透過 PIL 的convert('RGB')預覽 16 位元灰階 PNG 會顯示為純白色。 - OpenCV 的高斯模糊不支援
BORDER_WRAP；對於可平鋪貼圖，請使用scipy.ndimage.gaussian_filter(mode='wrap')。 pkill -f name/pgrep -f name | xargs kill可能匹配並終止你的 shell 本身（退出碼 144）；請按 PID 終止。- 從物理單位的高度導出法線；比例過大約 100 倍會產生暗色斑點雜訊。
- 使用重複的檔案路徑讀取渲染結果時，可能顯示快取的舊影像；請寫入新名稱。