Community程式設計與開發github.com

blender-creation

從頭開始使用無頭 Blender(bpy、bmesh)建立物理校準、可關節化、PBR 紋理的 3D MuJoCo 資產(MJCF model.xml、.mjz、mjSpec),包括凸面碰撞合成、10 種情境審計與 Studio 預覽。

blender-creation 是什麼?

此技能(blender-creation)使 AI 代理能從頭開始建立、建模或構建 3D MuJoCo 資產,輸入方式可為 URL、圖片或文字描述。它利用無頭 Blender(bpy、bmesh)和輔助腳本(blender_mesh_utils、asset_build_utils)進行建模、UV 展開、PBR 紋理烘焙和匯出為 MuJoCo 格式(MJCF model.xml、.mjz、mjSpec)。該技能強制遵守特定的物理和座標系規則(如 rules/mujoco_asset_standards.md 中所述),包括 SI 單位、群組分離以及正確的 MuJoCo 座標框架。主要功能包括:自動化關節檢測與合成、凸面碰撞幾何生成、使用 10 種動態物理模擬情境進行全面審計,以及透過 MuJoCo Studio 側車進行互動式預覽。工作流程設計為在頂層對話和專用建構子代理之間進行協調,以處理大規模任務,同時維持適當的沙箱和跨對話檔案存取。輸出包括最終資產、診斷渲染圖、比較圖像和 360 度 Filament 轉盤展示影片,所有這些都旨在在 MuJoCo 的 Filament PBR 渲染器和 MuJoCo Studio 中準確呈現。

相容平台✓Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/google-deepmind/robotics-antigravity-plugin/tree/HEAD/plugins/robotics/skills/blender-creation

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

在 Blender 中從頭開始建立 3D MuJoCo 資產 (bpy / bmesh + PBR)

[!IMPORTANT]

與 [rules/mujoco_asset_standards.md][asset-standards] 搭配使用:請先閱讀 [rules/mujoco_asset_standards.md][asset-standards] 以了解強制性的 MuJoCo 座標系 (UP_POSZ_FORWARD_POSX_RIGHT_NEGY)、SI 單位規則、 群組分離 (group="2" 視覺、group="3" 碰撞、group="4" 站點) 以及物理/審計要求。本指南涵蓋如何使用無頭 Blender (PYTHONDONTWRITEBYTECODE=1 "$BLENDER_BIN" -b -P ...)、 scripts/blender_mesh_utils.py (bmu)、 scripts/asset_build_utils.py (abu)、 mujoco-audit/SKILL.md、 mujoco-showcase-shot/SKILL.md (render_showcase_shot.py), 和 mujoco-studio-sidecar/SKILL.md 來研究、測量、建模、雕刻、UV 展開、紋理化、烘焙、匯出、驗證和 從頭開始互動預覽新資產,使其在 MuJoCo 的 Filament PBR 渲染器 和 MuJoCo Studio 中看起來、行為和檢查都準確。


1. 入口點、子代理編排、本地 Blender 設定與參考資料攝取

1.0 調用、預設值與子代理編排

使用者以自然語言輸入產品 URL、參考圖片或文字規格來調用此技能:

"為這個廚房夾子建立一個 3D MuJoCo 資產:<url>" "按照 blender-creation 為 <image/link> 中的物體建模"

預設值與可選覆寫: 預設情況下,此技能會執行完整的端到端流程:自動檢測關節、中間診斷渲染、10 種情境動態物理模擬審計(§7.3),以及 360° Filament 轉盤展示影片(§7.4)。使用者可以選擇以純英文或項目符號請求覆寫:

  • 快速 / 無轉盤:跳過步驟 7.4 的展示影片渲染(節省渲染時間)。
  • 僅剛體:強制使用 0 個關節,將物體作為單一剛體處理。
  • 跳過物理審計 / 快速審計:跳過步驟 7.3 中的 10 種情境動態物理模擬套件(僅依賴步驟 7.1 的靜態衛生與碰撞對齊檢查)。
  1. 如果你是頂層 / 父對話:

    • 透過 invoke_subagent 生成一個 self 子代理(Model: "inherit")來建立和驗證資產,傳遞所有使用者指定的指令、URL 和覆寫、父對話 ID: <parent_conv_id>,以及目標資產輸出父目錄,並指示子代理閱讀此 blender-creation 技能、[rules/mujoco_asset_standards.md][asset-standards]、mujoco-audit/SKILL.md 和 mujoco-showcase-shot/SKILL.md。不要指示子代理在父對話的 brain/<parent_conv_id>/ 目錄內寫入暫存/攝取檔案(macOS Seatbelt 沙箱會因 PermissionError 阻止跨對話的 brain/ 存取);讓子代理使用自己的 <ArtifactDir>/scratch/ 並傳回完成的資產和預覽路徑。
    • 子代理完成後:在頂層對話中遵循 步驟 7.6(mujoco-studio-sidecar/SKILL.md)來啟動(或重複使用)指向已完成資產目錄的 MuJoCo Studio Web 側車守護行程 (studiod.py)(--workspace_dir=<asset_dir>)並驗證 /_studio/status("ok": true、"daemon_connected": true)。從頂層對話啟動 studiod.py,而不是在建構子代理內部,這樣當子代理退出時背景守護行程不會被終止。在你的最終回應中,首先呈現完成的資產路徑、模型摘要(尺寸、質量、關節、視覺/碰撞細項、審計狀態)、並排比較圖和轉盤影片(除非透過 快速(無轉盤) 跳過,則簡短地用一行說明該展示是完整的 360° 紋理視覺旋轉,接著是半透明物理碰撞外殼檢查),並將 [MuJoCo Studio](sidecar://robotics/mujoco_studio/)(如果 Node 側車代理未啟用,則加上來自 $SESSION_FILE 的 http://127.0.0.1:<http_port>/)作為你回應的最後一項,確保頂部的互動式側車藥丸不會被遺漏。
  2. 如果你已經是生成的主要建構子代理:

    • 不要生成巢狀的建構子代理——直接執行 第 1.1 節到第 7.5 節(如果在步驟 1.1 中產品 URL 需要用戶端 JS 渲染,你仍然可以調用唯讀的 browser 子代理)。將所有暫存/攝取檔案保存在 此子代理自己的 <ArtifactDir>/scratch/ 中,以便沙箱化的 run_command 步驟具有本地讀取/寫入存取權限,而不會出現 PermissionError。不要在子代理內部執行 步驟 7.6(studiod.py);而是將完成的 <asset_dir> 路徑、模型摘要、比較圖像和轉盤影片路徑傳回給父對話,以便父對話啟動 studiod.py 並呈現 Studio 連結。
    • 確保本地(macOS 和 Linux)已安裝 uv 和無頭 Blender(4.2+):
      uv --version
      if [ -x "/Applications/Blender.app/Contents/MacOS/Blender" ]; then
        BLENDER_BIN="/Applications/Blender.app/Contents/MacOS/Blender"
      else
        BLENDER_BIN="blender"
      fi
      "$BLENDER_BIN" --version || (sudo apt-get update && sudo apt-get install -y blender)
      
      使用 PYTHONDONTWRITEBYTECODE=1 "$BLENDER_BIN" -b -P <ArtifactDir>/scratch/build_asset.py 執行 Blender 腳本,並在 Blender 腳本內部將 <PLUGIN_DIR>/skills/blender-creation/scripts 添加到 sys.path 以 import blender_mesh_utils as bmu。
    • MuJoCo 編譯、Filament 展示渲染與參考資料攝取(uv run):
      uv run --with mujoco --with numpy --with scipy --with trimesh --with Pillow \
        python3 <ArtifactDir>/scratch/script.py
      
      在你的暫存腳本內部,將外掛腳本目錄(<PLUGIN_DIR>/skills/blender-creation/scripts、<PLUGIN_DIR>/skills/mujoco-audit/scripts 和 <PLUGIN_DIR>/skills/mujoco-showcase-shot/scripts)添加到 sys.path 以匯入 asset_build_utils as abu、audit_scenarios 和 render_showcase_shot。
    • 範圍與工作區衛生:
      • 預設情況下執行 audit_scenarios 的 10 種情境物理掉落/傾斜/抓取模擬(步驟 7.3),驗證所有情境通過(或按照 mujoco-audit/SKILL.md 修復失敗的檢查)。僅在使用者明確指定 跳過物理審計 或 快速審計 時才跳過動態模擬。除非要求,否則不要生成第二個 <asset_name>_mechanical/ 套件。驗證乾淨的靜態 MjModel 編譯、零背面法線(abu.render_blender_diagnostic_sheet)、碰撞對齊(audit_scenarios.compute_collision_alignment_summary)、運動學關節姿勢(關節:自動)以及所有動態物理掉落/傾斜/穩定情境。
      • 將所有暫存腳本、下載的參考照片、中間網格、診斷 .jpg/.png 圖表、.blend 檔案、虛擬環境(.venv)和快取保存在 <ArtifactDir>/scratch/、~/.venvs/ 和 ~/.cache/mujoco_pbr_cache 中。僅將最終資產交付件(model.xml、meshes/*.obj、textures/*.png)寫入目標資產目錄,並且永遠不要將 .pyc / __pycache__、.venv 或 studiod 支架/執行時期檔案寫入資產目錄。
    • 遵循開關覆寫:關節:僅剛體 -> 0 個關節;深度:快速(無轉盤) -> 跳過步驟 7.4;跳過物理審計 / 快速審計 -> 跳過步驟 7.3。

1.1 攝取、參考聯絡/細節圖表與形式簡報

  1. 產品 URL 與參考資料攝取(<= 8 次圖片讀取):
    • 切勿從 URL 路徑片段猜測產品身份、類別或尺寸(例如,/Walnut-Elegant-Design-Coffee-Products/dp/... 可能是一個截斷的 SEO 片段,而不是真正的咖啡桌)。
    • 當提供了產品 URL 時:
      1. 調用唯讀的 browser 子代理,代表使用者導航到 <product_url>。像人類設計師一樣檢查即時渲染的頁面:
        • 提取驗證過的產品名稱、材質、機構描述和尺寸規格(以 mm 為單位的 長 × 寬 × 高 和以 kg 為單位的裸產品質量,交叉比對零售 商品重量 與包裝運輸重量)。
        • 識別高解析度產品圖庫 / 輪播圖片 URL。
      2. 如果存取被互動式 CAPTCHA 或安全閘門阻止:停止,不要嘗試繞過該閘門,並直接向使用者詢問產品尺寸、規格或參考照片。
      3. 將收集到的高解析度圖庫圖片下載到 <ArtifactDir>/scratch/intake/ref_*.jpg(例如,使用 curl 或最小的內聯下載腳本)。
    • 當未提供 URL(純文字查詢)時:透過 search_web 查找裸產品的 長 x 寬 x 高(mm)和質量(kg)(如果 search_web 僅回傳沒有摘要的原始重新導向連結,則調用 browser 子代理)。交叉比對零售 商品重量 與尺寸和材料密度。
    • 複合圖表(<= 8 次圖片讀取):絕不要對數十個單獨的幀調用 read_file。透過 abu.build_ref_contact_and_detail_sheets 將下載的 ref_*.jpg 照片和子特徵裁剪拼接成 ref_contact_sheet 和 ref_details_grid,然後使用 read_file 檢查這些複合圖表。
  2. 直接從參考裁剪中取樣光度 RGB 百分位數(rgb_sample_boxes):
    • 不要從口頭類別名稱("紅色塑膠"、"黑色橡膠"、"綠色毛絨")憑空發明 RGB 值。將 rgb_sample_boxes=[('main_shell', ref_path, (x0, y0, x1, y1)), ...] 傳遞給 abu.build_ref_contact_and_detail_sheets,以直接從均勻的內部表面貼片(排除高光反射點和投影陰影)測量 [p25, p50, p75] sRGB 元組。
  3. 撰寫一個 <= 25 行的形式簡報與命名參數區塊 P(<= 40 個命名尺寸):
    • 在撰寫 Blender bmesh 程式碼之前,撰寫一個簡潔的 形式簡報 並定義一個命名參數字典 P = dict(...)(<= 40 個以 mm / m 和 deg 為單位並附有來源說明的命名尺寸),而不是硬編碼數百個魔術座標元組:
      • 命名的主要表面及其交匯方式:側面輪廓面/角度、平面圖錐度、頂部橫截面、零件之間的負空間/開放間隙,以及齊平與階梯式連接。
      • 左/右(+Y 與 -Y)和前/後(+X 與 -X)不對稱性:明確指出哪些操縱桿、夾子、按鈕、標籤或埠出現在每一側。
      • 材料區域與分模線:例如,雙射包覆成型,其中剛性 ABS 形成內核並暴露齊平邊緣,而霧面 TPE 形成外部握把皮膚,或凹陷的品牌口袋。
      • 機構與行程:活動子零件(鉸鏈蓋、滑塊、夾子、刀片、按鈕、旋鈕)具有真實的物理樞軸/軸線,並以 m 或 rad 為單位的行程。

2. 工具參考與目標渲染器規則

2.1 快速輔助 API 參考(blender_mesh_utils、asset_build_utils、render_showcase_shot)

  • blender_mesh_utils as bmu (在無頭 Blender "$BLENDER_BIN" -b -P 內部,來自 scripts/blender_mesh_utils.py):
    • bmu.clear_scene() -> None
    • bmu.assign_pbr_material(objects, name=None, *, base_color=None, base_color_srgb=(200, 200, 200), roughness=0.4, metallic=0.0, normal_bump_mm=0.0, bump_height_mm=0.0, bump_scale=250.0) -> bpy.types.Material
    • bmu.skin_skeleton(name, nodes_xyzr, edges=None, *, subsurf_levels=2) -> obj
    • bmu.metaball_sdf(name, elements, *, resolution=0.002) -> obj
    • bmu.swept_tube(name, points_xyzr, *, bevel_resolution=6) -> obj
    • bmu.voxel_smooth_union(name, objects, *, voxel_size=0.0015, smooth_iterations=6) -> obj
    • bmu.apply_boolean_cutter(target_obj, cutter_obj, *, operation='DIFFERENCE', solver='MANIFOLD') -> obj
    • bmu.smart_seam_unwrap(target_obj, *, angle_limit_deg=66.0, margin=0.005) -> obj
    • bmu.smart_uv_project(objects, *, angle_limit_deg=66.0, island_margin=0.01, margin=None) -> list[obj]
    • bmu.pack_shared_uv_atlas(objs, *, margin=0.005, rotate=True, align_minimal_bbox=True, match_3d_area=True) -> None
    • bmu.finalize_and_export_obj(target_obj, out_obj_path, *, crease_deg=None, world_pos=None, body_pos=None, ensure_uvs=True) -> {'verts', 'quads', 'tris', 'earclipped_ngons'}
    • bmu.export_convex_hull_col(source_obj_or_points, out_obj_path, *, clip_bounds_world_m=None, clip_bounds_m=None, max_verts=64, name=None, world_pos=(0,0,0), body_pos=None) -> col_obj
    • bmu.bake_pbr_maps(out_dir, *, material_groups=None, resolution=1024, samples=8) -> {key: {'basecolor', 'roughness', 'metallic', 'normal'}}
  • asset_build_utils as abu (在 uv run 腳本內部,來自 scripts/asset_build_utils.py):
    • abu.build_ref_contact_and_detail_sheets(ref_paths, detail_crops, out_contact_png, out_details_png, *, raw_crops_dir=None, rgb_sample_boxes=None, cols=3, cell_size=440, include_shadow_lift=False) -> dict
    • abu.fetch_ambientcg_maps(asset_id, *, cache_dir=None, resolution='1K') -> {'color', 'roughness', 'normal_gl', 'metallic', 'ao', 'opacity', ...}
    • abu.rasterize_uv_world_fields(obj_paths, canvas_size=1024, *, part_offsets=None) -> dict
    • abu.dilate_uv_gutters(arr, valid_mask, *, max_dist_px=12) -> np.ndarray
    • abu.triplanar_project_map(map_2d, xyz, world_normal, *, texels_per_meter=4000.0, sharpness=4.0) -> np.ndarray
    • abu.height_to_normal_rgb(height_map, strength=3.5, *, smooth_sigma=0.0, valid_mask=None) -> (H,W,3) uint8
    • abu.normal_rgb_from_3d_height_fn(height_fn, uv_world_fields, *, step_mm=0.15, strength=1.0) -> (H,W,3) uint8
    • abu.fbm_noise_3d(xyz, *, base_freq=25.0, wavelength_mm=None, octaves=4, per

相關技能