在 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)。用户可以选择使用纯英文文本或要点请求覆盖:
Fast/No Turntable:跳过第 7.4 步的展示视频渲染(节省渲染时间)。Rigid-Only:强制为0个关节,将对象创作为单一刚体。Skip Physics Audit/Fast Audit:跳过第 7.3 步中的 10 场景动态物理仿真套件(仅依赖于第 7.1 步的静态清洁度和碰撞对齐检查)。
-
如果你是顶层/父对话:
- 通过
invoke_subagent生成一个self子代理 (Model: "inherit") 来构建和验证资产,传递所有用户指定的指令、URL 和覆盖、Parent Conversation 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) 来启动(或重用)指向已完成的资产目录 (--workspace_dir=<asset_dir>) 的 MuJoCo Studio Web sidecar 守护进程 (studiod.py) 并验证/_studio/status("ok": true,"daemon_connected": true)。从顶层对话启动studiod.py而不是在构建子代理内部,这样后台守护进程不会在子代理退出时被回收。在你的最终响应中,首先展示完成的资产路径、模型摘要(尺寸、质量、关节、视觉/碰撞分解、审核状态)、并排比较和转盘视频(除非通过Fast (No Turntable)跳过,简要地用一行说明该视频展示了完整的 360° 纹理视觉旋转,随后是半透明物理碰撞外壳检查),并且将[MuJoCo Studio](sidecar://robotics/mujoco_studio/)(如果 Node sidecar 代理未激活,则加上来自$SESSION_FILE的http://127.0.0.1:<http_port>/) 作为响应中最后一项放在底部,这样交互式 sidecar 按钮永远不会在顶部被错过。
- 通过
-
如果你已经是生成的构建主子代理:
- 不要生成嵌套的构建子代理——直接执行 第 1.1 节至第 7.5 节(如果在第 1.1 步中产品 URL 需要客户端 JS 渲染,你仍然可以调用只读的
browser子代理)。将所有暂存/输入文件保留在此子代理自己的<ArtifactDir>/scratch/中,以便沙箱化的run_command步骤具有本地读写访问权限,而不会出现PermissionError。不要在子代理内部运行第 7.6 步 (studiod.py);而是将完成的<asset_dir>路径、模型摘要、比较图像和转盘视频路径返回给父对话,以便父对话启动studiod.py并呈现 Studio 链接。 - 确保本地安装了
uv和无头 Blender (4.2+) (macOS & Linux):使用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修复失败的检查)。仅当用户明确指定Skip Physics Audit或Fast Audit时才跳过动态仿真。除非被要求,否则不要生成第二个<asset_name>_mechanical/包。验证干净的静态MjModel编译、零背面法线 (abu.render_blender_diagnostic_sheet)、碰撞对齐 (audit_scenarios.compute_collision_alignment_summary)、运动学关节位姿 (Articulations: Auto) 以及所有动态物理掉落/倾斜/稳定场景。 - 将所有暂存脚本、下载的参考照片、中间网格、诊断
.jpg/.png表、.blend文件、虚拟环境 (.venv) 和缓存保留在<ArtifactDir>/scratch/、~/.venvs/和~/.cache/mujoco_pbr_cache中。仅将最终资产交付件(model.xml、meshes/*.obj、textures/*.png)写入目标资产目录,并且永远不要将.pyc/__pycache__、.venv或studiod脚手架/运行时文件写入资产目录。
- 默认运行
- 尊重旋钮覆盖:
Articulations: Rigid-Only->0个关节;Depth: Fast (No Turntable)-> 跳过第 7.4 步;Skip Physics Audit/Fast Audit-> 跳过第 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为单位的裸产品重量,交叉核对零售Item Weight与包装运输重量)。 - 识别高分辨率产品图库/轮播图像 URL。
- 提取已验证的产品标题、材料、机构描述和尺寸规格(以
- 如果访问被交互式 CAPTCHA 或安全门阻止:停止,不要尝试绕过该门,直接要求用户提供产品尺寸、规格或参考照片。
- 将收集到的高分辨率图库图像下载到
<ArtifactDir>/scratch/intake/ref_*.jpg(例如,使用curl或一个最小的内联下载脚本)。
- 调用只读的
- 当未提供 URL 时(纯文本查询):通过
search_web查找裸产品长 x 宽 x 高(mm)和重量(kg)(如果search_web仅返回没有摘要的裸重定向链接,则调用browser子代理)。交叉核对零售Item Weight与尺寸和材料密度。 - 复合表(
<= 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为单位的命名尺寸,带有出处注释),而不是对数百个魔数坐标元组进行硬编码:- 命名主要表面及其相交方式:侧面轮廓面/角度、平面视图锥度、顶部横截面、零件之间的负空间/开放间隙,以及齐平 vs. 阶梯式连接处。
- 左/右(
+Y与-Y)和前/后(+X与-X)不对称性:明确指出哪些杠杆、夹子、按钮、标签或端口出现在每侧。 - 材料区域与分型线:例如,双射包覆成型,其中刚性 ABS 形成内核和外露的齐平边缘,而哑光 TPE 形成外部握柄表皮,或凹陷的品牌口袋。
- 机构与行程:具有真实物理枢轴/轴和以
m或rad为单位的行程的运动子部件(铰链盖、滑块、夹子、刀片、按钮、旋钮)。
- 在编写 Blender
2. 工具参考与目标渲染器规则
2.1 快速助手指令参考 (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
…
[因翻译而截断]