--- name: blender-creation description: >- Creates physically calibrated, articulated, PBR-textured 3D MuJoCo assets (MJCF model.xml, .mjz, mjSpec) from scratch using headless Blender (bpy, bmesh, blender_mesh_utils, asset_build_utils), convex collision synthesis, 10-scenario auditing, and Studio preview. Use only when asked to create, model, or build a 3D MuJoCo object from a URL, image, or text description, or when blender-creation is named. Don't use for non-MuJoCo Blender/Cycles/CAD modeling. metadata: publisher: google --- # Authoring 3D MuJoCo Assets from Scratch in Blender (`bpy` / `bmesh` + PBR) > [!IMPORTANT] > > **Companion to [`rules/mujoco_asset_standards.md`][asset-standards]**: Read > [`rules/mujoco_asset_standards.md`][asset-standards] first for the mandatory > MuJoCo coordinate frame (`UP_POSZ_FORWARD_POSX_RIGHT_NEGY`), SI unit rules, > group separation (`group="2"` visual, `group="3"` collision, `group="4"` > sites), and physics/audit requirements. This guide covers how to research, > measure, model, sculpt, UV-unwrap, texture, bake, export, verify, and > interactively preview new assets from scratch using headless Blender > (`PYTHONDONTWRITEBYTECODE=1 "$BLENDER_BIN" -b -P ...`), > [`scripts/blender_mesh_utils.py`](scripts/blender_mesh_utils.py) (`bmu`), > [`scripts/asset_build_utils.py`](scripts/asset_build_utils.py) (`abu`), > [`mujoco-audit/SKILL.md`](../mujoco-audit/SKILL.md), > [`mujoco-showcase-shot/SKILL.md`](../mujoco-showcase-shot/SKILL.md) > ([`render_showcase_shot.py`](../mujoco-showcase-shot/scripts/render_showcase_shot.py)), > and [`mujoco-studio-sidecar/SKILL.md`](../mujoco-studio-sidecar/SKILL.md) > so they look, behave, and inspect accurately in **MuJoCo's Filament PBR > renderer** and **MuJoCo Studio**. --- ## 1. Entry Point, Subagent Orchestration, Local Blender Setup & Reference Intake ### 1.0 Invocation, Defaults & Subagent Orchestration Users invoke this skill in natural language with a product URL, reference image(s), or text specifications: > *"Build a 3D MuJoCo asset for these kitchen tongs: ``"* > *"Follow blender-creation to model the object in ``"* **Defaults & Optional Overrides**: By default, the skill executes the full end-to-end pipeline: auto-detected articulations, intermediate diagnostic renders, 10-scenario dynamic physics simulation auditing (§7.3), and a 360° Filament turntable showcase video (§7.4). Users can optionally request overrides in plain English or bullet points: - **`Fast` / `No Turntable`**: Skips Step 7.4 showcase video rendering (saves render time). - **`Rigid-Only`**: Forces `0` joints, authoring the object as a single rigid body. - **`Skip Physics Audit` / `Fast Audit`**: Skips the 10-scenario dynamic physics simulation suite in Step 7.3 (relying only on Step 7.1 static hygiene & collision alignment checks). 1. **If you are the top-level / parent conversation**: - Spawn a `self` subagent (`Model: "inherit"`) via `invoke_subagent` to build and verify the asset, passing all user-specified instructions, URLs, and overrides, `Parent Conversation ID: `, and the target asset output parent directory, and instructing the subagent to read this `blender-creation` skill, [`rules/mujoco_asset_standards.md`][asset-standards], [`mujoco-audit/SKILL.md`](../mujoco-audit/SKILL.md), and [`mujoco-showcase-shot/SKILL.md`](../mujoco-showcase-shot/SKILL.md). Do **not** instruct the subagent to write scratch/intake files inside the parent conversation's `brain//` directory (macOS Seatbelt sandboxing blocks cross-conversation `brain/` access with `PermissionError`); let the subagent use its own `/scratch/` and return the finished asset and preview paths. - **When the subagent finishes**: Follow **Step 7.6** ([`mujoco-studio-sidecar/SKILL.md`](../mujoco-studio-sidecar/SKILL.md)) in the top-level conversation to launch (or reuse) the MuJoCo Studio Web sidecar daemon (`studiod.py`) pointed at the finished asset directory (`--workspace_dir=`) and verify `/_studio/status` (`"ok": true`, `"daemon_connected": true`). Launch `studiod.py` from the top-level conversation rather than inside the builder subagent so the background daemon is not reaped when the subagent exits. In your final response, first present the finished asset path, model summary (dimensions, mass, joints, visual/collision breakdown, audit status), side-by-side comparison, and turntable video (unless skipped via `Fast (No Turntable)`, briefly noting in a 1-line caption that the reel shows a full 360° textured visual spin followed by translucent physics collision hull inspection), and **place `[MuJoCo Studio](sidecar://robotics/mujoco_studio/)` (plus `http://127.0.0.1:/` from `$SESSION_FILE` if the Node sidecar proxy is not active) as the very last item at the bottom of your response** so the interactive sidecar pill is never missed at the top. 2. **If you are already the spawned Main Builder Subagent**: - Do **not** spawn a nested build subagent—execute **Sections 1.1 through 7.5** directly (you may still invoke the read-only `browser` subagent during Step 1.1 if a product URL requires client-side JS rendering). Keep all scratch/intake files in **this subagent's own** `/scratch/` so sandboxed `run_command` steps have local read/write access without `PermissionError`. Do **not** run **Step 7.6** (`studiod.py`) inside the subagent; instead, return the finished `` path, model summary, comparison images, and turntable video path to the parent conversation so the parent conversation launches `studiod.py` and presents the Studio link. - **Ensure `uv` and Headless Blender (`4.2+`) Are Installed Locally (macOS & Linux)**: ```bash 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) ``` Run Blender scripts with `PYTHONDONTWRITEBYTECODE=1 "$BLENDER_BIN" -b -P /scratch/build_asset.py` and add `/skills/blender-creation/scripts` to `sys.path` inside the Blender script to `import blender_mesh_utils as bmu`. - **MuJoCo Compilation, Filament Showcase Renders & Reference Intake (`uv run`)**: ```bash uv run --with mujoco --with numpy --with scipy --with trimesh --with Pillow \ python3 /scratch/script.py ``` Inside your scratch script, add the plugin script directories (`/skills/blender-creation/scripts`, `/skills/mujoco-audit/scripts`, and `/skills/mujoco-showcase-shot/scripts`) to `sys.path` to import `asset_build_utils as abu`, `audit_scenarios`, and `render_showcase_shot`. - **Scope & Workspace Hygiene**: - Run `audit_scenarios` 10-scenario physics drop/tip/grasp simulations (**Step 7.3**) by default, verifying all scenarios pass (or remediate failing checks following [`mujoco-audit/SKILL.md`](../mujoco-audit/SKILL.md)). Only skip dynamic simulations if the user explicitly specifies `Skip Physics Audit` or `Fast Audit`. Do not generate a second `_mechanical/` bundle unless requested. Verify clean static `MjModel` compilation, zero-backface normals (`abu.render_blender_diagnostic_sheet`), collision alignment (`audit_scenarios.compute_collision_alignment_summary`), kinematic joint poses (`Articulations: Auto`), and all dynamic physics drop/tip/settle scenarios. - Keep all scratch scripts, downloaded reference photos, intermediate meshes, diagnostic `.jpg`/`.png` sheets, `.blend` files, virtual environments (`.venv`), and caches in `/scratch/`, `~/.venvs/`, and `~/.cache/mujoco_pbr_cache`. Only write final asset deliverables (`model.xml`, `meshes/*.obj`, `textures/*.png`) into the target asset directory, and never write `.pyc` / `__pycache__`, `.venv`, or `studiod` scaffold/runtime files into the asset directory. - Honor knob overrides: `Articulations: Rigid-Only` -> `0` joints; `Depth: Fast (No Turntable)` -> skip Step 7.4; `Skip Physics Audit` / `Fast Audit` -> skip Step 7.3. ### 1.1 Intake, Reference Contact/Detail Sheets & Form Brief 1. **Product URL & Reference Intake (`<= 8` Image Reads)**: - Never guess product identity, category, or dimensions from a URL path slug (e.g., `/Walnut-Elegant-Design-Coffee-Products/dp/...` may be a truncated SEO slug rather than a coffee table). - **When a product URL is provided**: 1. Invoke the read-only `browser` subagent to navigate to `` on behalf of the user. Inspect the live rendered page just as a human designer would: - Extract the verified product title, materials, mechanism descriptions, and dimensional specs (`L × W × H` in `mm` and bare-product mass in `kg`, cross-checking retail `Item Weight` vs packaged shipping weight). - Identify high-resolution product gallery / carousel image URLs. 2. **If access is blocked by an interactive CAPTCHA or security gate**: stop without attempting to circumvent the gate and ask the user for the product dimensions, specifications, or reference photos directly. 3. Download the collected high-resolution gallery images into `/scratch/intake/ref_*.jpg` (e.g. using `curl` or a minimal inline download script). - **When no URL is provided (text-only query)**: Look up bare-product `L x W x H` (`mm`) and mass (`kg`) via `search_web` (or invoke the `browser` subagent if `search_web` returns only bare redirect links without snippets). Cross-check retail `Item Weight` against dimensions and material density. - **Composite Sheets (`<= 8` Image Reads)**: Never call `read_file` on dozens of individual frames. Stitch the downloaded `ref_*.jpg` photos and sub-feature crops into `ref_contact_sheet` and `ref_details_grid` via `abu.build_ref_contact_and_detail_sheets`, then inspect those composite sheets with `read_file`. 2. **Sample Photometric RGB Percentiles Directly from Reference Crops (`rgb_sample_boxes`)**: - Do **not** invent `RGB` values from verbal category names (*"red plastic"*, *"black rubber"*, *"green plush"*). Pass `rgb_sample_boxes=[('main_shell', ref_path, (x0, y0, x1, y1)), ...]` to `abu.build_ref_contact_and_detail_sheets` to measure `[p25, p50, p75]` sRGB tuples directly from uniform interior surface patches (excluding specular hotspots and cast shadows). 3. **Write a `<= 25`-Line Form Brief & Named Parameter Block `P` (`<= 40` Named Dimensions)**: - Before writing Blender `bmesh` code, write a concise **Form Brief** and define a named parameter dictionary `P = dict(...)` (`<= 40` named dimensions in `mm` / `m` and `deg` with provenance comments) rather than hard-coding hundreds of magic coordinate tuples: - **Named primary surfaces & how they meet**: side silhouette facets/angles, plan-view taper, crown cross-section, negative space / open daylight gaps between parts, and flush vs. stepped junctions. - **Left/right (`+Y` vs. `-Y`) and front/back (`+X` vs. `-X`) asymmetry**: explicitly note which levers, clips, buttons, labels, or ports appear on each side. - **Material regions & parting lines**: e.g., two-shot overmold where rigid ABS forms the inner core and exposed flush rims while matte TPE forms the outer grip skin, or recessed branding pockets. - **Mechanisms & travel**: moving sub-parts (hinged lids, sliders, clips, blades, buttons, knobs) with true physical pivot/axis and travel in `m` or `rad`. --- ## 2. Tool Reference & Target Renderer Rules ### 2.1 Quick Helper API Reference (`blender_mesh_utils`, `asset_build_utils`, `render_showcase_shot`) - **`blender_mesh_utils as bmu`** *(inside headless Blender `"$BLENDER_BIN" -b -P`, from [`scripts/blender_mesh_utils.py`](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`** *(inside `uv run` scripts, from [`scripts/asset_build_utils.py`](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, persistence=0.5, seed=42) -> (...,) float32` - `abu.compute_volume_weighted_hull_masses(mesh_dir, col_names, total_mass_kg, *, density_weights=None) -> {col_name: mass_kg}` - `abu.render_blender_diagnostic_sheet(blend_path, out_png, *, xml_path=None, part_pivots=None, panel_size=420) -> {'out_png', 'has_backfaces', 'backface_pixels_per_view'}` - `abu.build_variant_bundles(base_asset_dir, parent_assets_dir, base_name, variants, render_variant_textures_fn) -> list[str]` - **`render_showcase_shot`** *(inside `uv run` scripts, from [`../mujoco-showcase-shot/scripts/render_showcase_shot.py`](../mujoco-showcase-shot/scripts/render_showcase_shot.py))*: - `render_side_by_side_comparison(asset_path, ref_specs, out_png, *, detail_crops_out_png=None, six_view_out_png=None, six_view_panel_size=420, six_view_qpos=None, fovy=35.0, white_bg=True, clay_only=False) -> {'comparison_png', 'detail_crops_png', 'six_view_png'}` - `render_filament_still(asset_path, views, *, width=800, height=800, fovy=None, white_bg=False, show_plinth=False) -> list[np.ndarray]` - `render_6view_inspection_sheet(asset_path, out_png, *, panel_size=420, qpos=None) -> out_png` - `render_wireframe_and_uv_sheet(asset_path, out_png, *, panel_size=440) -> out_png` - `render_showcase_shot_video(asset_path, output_mp4, width=960, height=720, fps=30, duration=8.0, articulation_cycles=2.0) -> dict` --- ### 2.2 Target Renderer: Optimize for MuJoCo Filament (Not Standalone Cycles) 1. **Get into MuJoCo Filament Early & Render Intermediate Diagnostics**: - Do **not** build an entire asset blind and only render at the very end. After blocking out primary 3D geometry in Blender (saving `/scratch/.blend` and exporting `.obj` meshes), immediately run **intermediate diagnostic renders**: - `abu.render_blender_diagnostic_sheet(blend_path, out_png=..., xml_path=...)` to inspect 6-view clay/wireframe shading, backface orientation (`has_backfaces == False`), and joint pivots. - `render_showcase_shot.render_side_by_side_comparison(..., clay_only=True)` to compare your untextured 3D form directly against the reference photos at matched camera angles before spending time on textures and decals. 2. **MuJoCo Filament Normal Handling (`model_resources.cc`) — Smooth Curves vs. Crisp Creases**: - In MuJoCo's Filament backend (`FillMeshBuffer`), if the angle between a triangle's geometric `face_normal` and its exported vertex normal `mesh_normal` exceeds $\sim 36.87^\circ$ ($\cos\theta < 0.8$), Filament may fall back to the flat `face_normal` (`UseFaceNormal`). - **For smooth curved surfaces, bevels & domes**: 1. Always call `bmesh.ops.recalc_face_normals(bm, faces=bm.faces[:])` on every closed mesh before setting smooth shading or exporting `.obj`. 2. Set `f.smooth = True` on smoothly curved/beveled faces and keep adjacent bevel/fillet step angles $\le 15^\circ\text{–}22^\circ$ so `dot(face_normal, vertex_normal) > 0.8`. - **For crisp industrial-design creases, chamfers & faceted parts**: 1. Do **not** blindly set `f.smooth = True` across sharp ridges, flat-topped prismatic facets, or distinct chamfer bevels. 2. Use `bmu.finalize_and_export_obj(obj, out_obj_path, crease_deg=35.0, body_pos=...)` (which marks crease edges above `crease_deg` sharp and applies `WEIGHTED_NORMAL(keep_sharp=True)`) or keep flat facets `f.smooth = False` so Filament preserves crisp specular transitions. --- ## 3. Pure-Blender Geometry Authoring, Modular `bmu` Helpers & Topology Rules ### 3.1 Freedom of Geometry & Modular `blender_mesh_utils` (`bmu`) Builders You have full freedom in Python (`bpy` / `bmesh` / `mathutils` / modifiers) plus the zero-magic builders in [`scripts/blender_mesh_utils.py`](scripts/blender_mesh_utils.py) (`bmu`) to construct whatever geometry faithfully captures each component: - **Profile Lofting, Extrusion, Bevels & Boolean Split Shells (`bmesh` + `bmu.apply_boolean_cutter`)**: - For faceted or contoured industrial housings (e.g., an ergonomic tool housing with shoulder chamfers, plan-view taper, and two-shot elastomer/ABS overmold parting lines), drive cross-sections from your named parameter dictionary `P`. - Use `bmu.apply_boolean_cutter(target_obj, cutter_obj, operation='DIFFERENCE' | 'INTERSECT' | 'UNION')` (which safely runs Blender's `MANIFOLD` boolean solver with an automatic welded `EXACT` fallback) to carve recessed pockets, moat grooves, actuator slots, and flush two-shot material splits from a shared outer envelope. - **Declarative Organic & Tubular Builders (`bmu`)**: - `bmu.skin_skeleton(name, nodes_xyzr, edges=None, *, subsurf_levels=2)`: branching organic limbs, frames, or handles from `(x, y, z, r)` or `(x, y, z, (rx, ry))` skeleton graphs. - `bmu.metaball_sdf(name, elements, *, resolution=0.002)`: analytical implicit SDF blends (`BALL`, `CAPSULE`, `ELLIPSOID`, `CUBE`, with `use_negative=True` for ergonomic thumb indents or cavities). - `bmu.swept_tube(name, points_xyzr, *, bevel_resolution=6)`: 3D `NURBS` tubes, cords, straps, wire loops, or bent rods with per-point radius and end caps. - `bmu.voxel_smooth_union(name, objects, *, voxel_size=0.0015, smooth_iterations=6)`: watertight voxel-remeshed fillets across intersecting sub-parts. ### 3.2 Kinematic Root Selection & Mesh Splitting by Link / Material Role 1. **Kinematic Root Body Selection**: - Choose the **root ``** to be the **primary stationary base or primary grasped housing** during normal operation, and make components that move relative to that housing the child `` elements. 2. **Split into Separate Meshes by Articulation Link & Material Role**: - Export separate `.obj` files in `meshes/` for each articulated `` (link) and each distinct `` within a body. ### 3.3 Sensible Polycount Budgets & `bmesh` Topology Rules - **Polycount Budgets**: - Simple flat/beveled component: $100\text{–}1,500\text{ tris}$. - Contoured housing with rounded corners, fillets & cutouts: $1,500\text{–}6,500\text{ tris}$. - Complete multi-part prop/appliance: **$5,000\text{–}20,000\text{ tris}$ total** across all visual meshes. - **`bmesh` Topology Rules**: 1. **Subdivide straight edges before carving localized edge features** and add an inner rim loop so cutouts stay confined cleanly to the outer lip. 2. **Keep planar hole loops strictly inside the outer perimeter ($\ge 2\text{ mm}$ clearance)** before calling `bmesh.ops.triangle_fill`. 3. **Prevent coplanar Z-fighting between layered parts**: separate layered surfaces by $\ge 0.2\text{ mm}$ or cut an interior pocket. 4. **Uniform metric edge offsets**: inset perimeter bevels by a constant metric distance $d$ (in meters) along $X$ and $Y$ rather than radial fractions on elongated parts, and never pinch top/bottom rings into a zero-thickness knife-edge equator. 5. **Watertight thickness + `inertia="shell"` on thin visual meshes**: extrude thin plaques, labels, blades, and lenses to $\ge 1.5\text{–}3\text{ mm}$ watertight thickness and declare `` so `mjCMesh::Compile` never fails with `mesh volume is too small`. --- ## 4. Canonical MuJoCo Coordinate Frame, Camera Angles & `model.xml` 1. **World Coordinate Frame (`UP_POSZ_FORWARD_POSX_RIGHT_NEGY`, `1 unit = 1.0 m`)**: - **`+Z`** Up (resting base at $z = 0.000\text{ m}$), **`+X`** Front, **`-X`** Back, **`+Y`** Left, **`-Y`** Right. - Looking at **`+X` Front** toward `-X`, viewer-left is **`-Y`** and viewer-right is **`+Y`**. Looking at **`-Y` Right** toward `+Y`, viewer-left is **`-X`** and viewer-right is **`+X`**. 2. **MuJoCo `mjvCamera` Azimuth & Elevation Convention**: - **`azimuth = 180°`**: Views **`Front (+X)`** | **`azimuth = 0°`**: Views **`Back (-X)`** | **`azimuth = 90°`**: Views **`Right (-Y)`** | **`azimuth = 270°`**: Views **`Left (+Y)`**. - **`elevation < 0°`**: Camera above looking downward (`-25°..-45°` = tabletop 3/4 view; `-88°` = overhead `Top (+Z)` view). 3. **Articulated Child Bodies & Non-Destructive Identity-Axis Export (`bmu.finalize_and_export_obj`)**: - Keep scene objects at their assembled world poses in `.blend`, and pass `body_pos=(px, py, pz)` to `bmu.finalize_and_export_obj(obj, out_obj_path, crease_deg=..., body_pos=(px, py, pz))` so `.obj` vertices export around each child body's local joint origin `(0, 0, 0)` with `forward_axis='Y', up_axis='Z', export_materials=False` without mutating live `.blend` positions. 4. **Canonical `model.xml` Skeleton** (`/model.xml`, no `scene.xml`, no `