在 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 的靜態衛生與碰撞對齊檢查)。
-
如果你是頂層 / 父對話:
- 透過
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>/)作為你回應的最後一項,確保頂部的互動式側車藥丸不會被遺漏。
- 透過
-
如果你已經是生成的主要建構子代理:
- 不要生成巢狀的建構子代理——直接執行 第 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 節到第 7.5 節(如果在步驟 1.1 中產品 URL 需要用戶端 JS 渲染,你仍然可以調用唯讀的
1.1 攝取、參考聯絡/細節圖表與形式簡報
- 產品 URL 與參考資料攝取(
<= 8次圖片讀取):- 切勿從 URL 路徑片段猜測產品身份、類別或尺寸(例如,
/Walnut-Elegant-Design-Coffee-Products/dp/...可能是一個截斷的 SEO 片段,而不是真正的咖啡桌)。 - 當提供了產品 URL 時:
- 調用唯讀的
browser子代理,代表使用者導航到<product_url>。像人類設計師一樣檢查即時渲染的頁面:- 提取驗證過的產品名稱、材質、機構描述和尺寸規格(以
mm為單位的長 × 寬 × 高和以kg為單位的裸產品質量,交叉比對零售商品重量與包裝運輸重量)。 - 識別高解析度產品圖庫 / 輪播圖片 URL。
- 提取驗證過的產品名稱、材質、機構描述和尺寸規格(以
- 如果存取被互動式 CAPTCHA 或安全閘門阻止:停止,不要嘗試繞過該閘門,並直接向使用者詢問產品尺寸、規格或參考照片。
- 將收集到的高解析度圖庫圖片下載到
<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檢查這些複合圖表。
- 切勿從 URL 路徑片段猜測產品身份、類別或尺寸(例如,
- 直接從參考裁剪中取樣光度 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 元組。
- 不要從口頭類別名稱("紅色塑膠"、"黑色橡膠"、"綠色毛絨")憑空發明
- 撰寫一個
<= 25行的形式簡報與命名參數區塊P(<= 40個命名尺寸):- 在撰寫 Blender
bmesh程式碼之前,撰寫一個簡潔的 形式簡報 並定義一個命名參數字典P = dict(...)(<= 40個以mm/m和deg為單位並附有來源說明的命名尺寸),而不是硬編碼數百個魔術座標元組:- 命名的主要表面及其交匯方式:側面輪廓面/角度、平面圖錐度、頂部橫截面、零件之間的負空間/開放間隙,以及齊平與階梯式連接。
- 左/右(
+Y與-Y)和前/後(+X與-X)不對稱性:明確指出哪些操縱桿、夾子、按鈕、標籤或埠出現在每一側。 - 材料區域與分模線:例如,雙射包覆成型,其中剛性 ABS 形成內核並暴露齊平邊緣,而霧面 TPE 形成外部握把皮膚,或凹陷的品牌口袋。
- 機構與行程:活動子零件(鉸鏈蓋、滑塊、夾子、刀片、按鈕、旋鈕)具有真實的物理樞軸/軸線,並以
m或rad為單位的行程。
- 在撰寫 Blender
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() -> Nonebmu.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.Materialbmu.skin_skeleton(name, nodes_xyzr, edges=None, *, subsurf_levels=2) -> objbmu.metaball_sdf(name, elements, *, resolution=0.002) -> objbmu.swept_tube(name, points_xyzr, *, bevel_resolution=6) -> objbmu.voxel_smooth_union(name, objects, *, voxel_size=0.0015, smooth_iterations=6) -> objbmu.apply_boolean_cutter(target_obj, cutter_obj, *, operation='DIFFERENCE', solver='MANIFOLD') -> objbmu.smart_seam_unwrap(target_obj, *, angle_limit_deg=66.0, margin=0.005) -> objbmu.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) -> Nonebmu.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_objbmu.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) -> dictabu.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) -> dictabu.dilate_uv_gutters(arr, valid_mask, *, max_dist_px=12) -> np.ndarrayabu.triplanar_project_map(map_2d, xyz, world_normal, *, texels_per_meter=4000.0, sharpness=4.0) -> np.ndarrayabu.height_to_normal_rgb(height_map, strength=3.5, *, smooth_sigma=0.0, valid_mask=None) -> (H,W,3) uint8abu.normal_rgb_from_3d_height_fn(height_fn, uv_world_fields, *, step_mm=0.15, strength=1.0) -> (H,W,3) uint8abu.fbm_noise_3d(xyz, *, base_freq=25.0, wavelength_mm=None, octaves=4, per