markoboskoauroville/blender-control

Blender 控制技能（即時 GUI + 無頭 CLI）

此工作區以兩種互補模式控制 Blender 5.2.1 LTS（/Applications/Blender.app/Contents/MacOS/Blender，Python 3.13，Apple M1 Pro 16 核心 Metal GPU）：

1. 即時 GUI 模式（預設且建議使用）：透過 127.0.0.1:9876 將指令傳送給在已開啟的 Blender.app 視窗內執行的 blender_control_bridge.py。物件、著色器、動畫與相機畫面會立即呈現在使用者面前。
2. 無頭 CLI 模式：執行 /Applications/Blender.app/Contents/MacOS/Blender --background 來進行隔離批次渲染或大量背景作業，不影響活躍的 GUI 工作階段。

在為 Blender 5.2 撰寫 bpy 腳本之前，請先查閱 blender_5_2_api_guide.md，了解 5.2 版本的關鍵 API 變更（Principled BSDF 插槽名稱、Slotted Actions channelbag、media_type = 'VIDEO' 與 Metal GPU 設定）。

---

步驟 1：驗證或連線至已開啟的 Blender 應用程式

永遠先驗證即時橋接連線：

python3 .agents/skills/blender-control/scripts/blender_cli.py ping

如果 ping 失敗（例如 Blender 尚未開啟，或是在安裝啟動橋接之前就已啟動），請執行安裝/連線腳本：

bash .agents/skills/blender-control/scripts/install_bridge.sh

• 將 blender_control_bridge.py 複製到 ~/Library/Application Support/Blender/5.2/scripts/startup/，如此一來每次 GUI 啟動時，橋接就會自動在 127.0.0.1:9876 上啟動。
• 安全地連線至或啟動 Blender.app（open -g -a Blender），不會搶走視窗焦點。
• 如果 Blender.app 已開啟一個未儲存的 .blend 檔案，但未載入橋接，請要求使用者點擊 macOS 選單列的 Blender -> System -> Reload Scripts。

---

步驟 2：透過 blender_cli.py 檢視與控制即時場景

所有即時操作皆使用 blender_cli.py：

# 1. 檢視目前的物件、相機、材質、影格範圍與渲染引擎
python3 .agents/skills/blender-control/scripts/blender_cli.py info

# 2. 乾淨地清除即時場景（移除所有物件與孤立的資料區塊）
python3 .agents/skills/blender-control/scripts/blender_cli.py reset

# 3. 在 Blender 的主 UI 執行緒上即時執行場景建構 Python 腳本
python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py

# 4. 執行快速內嵌 Python 表達式/片段
python3 .agents/skills/blender-control/scripts/blender_cli.py exec "RESULT = [o.name for o in bpy.data.objects]"

# 5. 將使用者的即時 Blender 3D 視埠切換為材質預覽或渲染相機畫面
python3 .agents/skills/blender-control/scripts/blender_cli.py viewport --shading MATERIAL

# 6. 在即時 GUI 中儲存或開啟 .blend 專案檔
python3 .agents/skills/blender-control/scripts/blender_cli.py save projects/my_scene/scene.blend
python3 .agents/skills/blender-control/scripts/blender_cli.py open projects/my_scene/scene.blend

---

步驟 3：渲染靜態圖、視埠預覽與動畫

快速視埠預覽（<0.2 秒）

在執行完整光線追蹤渲染之前，先使用視埠螢幕截圖來確認相機畫面、物件擺放與裁剪：

python3 .agents/skills/blender-control/scripts/blender_cli.py screenshot /tmp/preview.png

使用 read_file 檢視 /tmp/preview.png，以視覺方式檢查構圖與照明！

高品質靜態渲染（Cycles Metal GPU 或 EEVEE）

# Cycles 搭配自動 Apple M1 Pro 16 核心 Metal GPU 加速
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine CYCLES --samples 64 --width 1920 --height 1080

# 使用 EEVEE 快速即時 PBR 渲染
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine BLENDER_EEVEE --samples 32 --width 1920 --height 1080

MP4（H.264）動畫渲染

python3 .agents/skills/blender-control/scripts/blender_cli.py render-anim projects/my_scene/animation.mp4 \
  --engine BLENDER_EEVEE --samples 32 --width 1280 --height 720 --start 1 --end 120 --fps 30

無頭批次模式（隔離程序）

當渲染大量作業且不想阻塞即時 GUI 視埠時：

python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py --headless

---

步驟 4：場景建構與驗證檢查清單

1. 自包含建構腳本：將每個專案儲存在 projects/<project_name>/build.py 中，如此場景便可 100% 重現，並與渲染輸出和 .blend 檔案一起友善地進行 Git 版本管理。
2. 相機瞄準（TRACK_TO 或四元數）：一律使用 (target - cam.location).to_track_quat('-Z', 'Y') 將相機可靠地指向目標空白物件或世界座標，並設定 scene.camera = cam。
3. 三點式/工作室照明與世界：永遠不要留下黑暗的預設灰色背景；應設定世界著色器節點與面光/太陽光，並使用實際的瓦特數（依場景比例為 100W–1500W）以及 AgX 或 Filmic 色彩管理（scene.view_settings.view_transform = 'AgX'，look = 'AgX - Medium High Contrast'）。
4. 視覺驗證：在完成前，務必使用 read_file 檢視渲染後的 .png 或 .mp4 輸出，以確認構圖、曝光、材質與動態。
5. GitHub 同步：在建立或更新專案/技能後，執行 ./scripts/sync_github.sh "<commit message>" 以保持本地端與 origin/main 同步。