Création d'Actifs 3D MuJoCo à partir de Zéro dans Blender (bpy / bmesh + PBR)
[!IMPORTANT]
Document complémentaire à
rules/mujoco_asset_standards.md: Lisez d'abordrules/mujoco_asset_standards.mdpour les règles obligatoires concernant le repère de coordonnées MuJoCo (UP_POSZ_FORWARD_POSX_RIGHT_NEGY), les unités SI, la séparation des groupes (group="2"visuel,group="3"collision,group="4"sites), et les exigences de physique/audit. Ce guide couvre la façon de rechercher, mesurer, modéliser, sculpter, déplier UV, texturer, cuire, exporter, vérifier et prévisualiser de nouveaux actifs à partir de zéro en utilisant Blender sans interface graphique (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), etmujoco-studio-sidecar/SKILL.mdafin qu'ils aient un aspect, un comportement et une inspection précis dans le rendu Filament PBR de MuJoCo et MuJoCo Studio.
1. Point d'Entrée, Orchestration des Sous-Agents, Configuration Locale de Blender & Réception des Références
1.0 Invocation, Paramètres par Défaut & Orchestration des Sous-Agents
Les utilisateurs invoquent cette compétence en langage naturel avec une URL de produit, une(des) image(s) de référence ou des spécifications textuelles :
"Construis un actif 3D MuJoCo pour ces pinces de cuisine :
<url>" "Suis blender-creation pour modéliser l'objet dans<image/lien>"
Paramètres par Défaut & Surcharges Optionnelles : Par défaut, la compétence exécute le pipeline complet de bout en bout : détection automatique des articulations, rendus de diagnostic intermédiaires, simulation physique dynamique sur 10 scénarios (§7.3) et une vidéo de présentation tournante Filament à 360° (§7.4). Les utilisateurs peuvent éventuellement demander des surcharges en anglais simple ou par points :
Fast/No Turntable: Ignore l'étape 7.4 de rendu vidéo de présentation (économise du temps de rendu).Rigid-Only: Force0articulations, créant l'objet comme un seul corps rigide.Skip Physics Audit/Fast Audit: Ignore la suite de simulation physique dynamique sur 10 scénarios de l'étape 7.3 (en se fiant uniquement aux vérifications d'hygiène statique et d'alignement des collisions de l'étape 7.1).
-
Si vous êtes la conversation parente / de premier niveau :
- Créez un sous-agent
self(Model: "inherit") viainvoke_subagentpour construire et vérifier l'actif, en transmettant toutes les instructions, URLs et surcharges spécifiées par l'utilisateur, l'ID de la conversation parente : <parent_conv_id>, et le répertoire parent de sortie de l'actif cible, et en instruisant le sous-agent de lire cette compétenceblender-creation,rules/mujoco_asset_standards.md,mujoco-audit/SKILL.md, etmujoco-showcase-shot/SKILL.md. N'instruisez pas le sous-agent d'écrire des fichiers d'ébauche/d'entrée dans le répertoirebrain/<parent_conv_id>/de la conversation parente (le sandboxing macOS Seatbelt bloque l'accèsbrain/entre conversations avecPermissionError) ; laissez le sous-agent utiliser son propre<ArtifactDir>/scratch/et renvoyer les chemins de l'actif fini et de l'aperçu. - Quand le sous-agent a terminé : Suivez l'étape 7.6 (
mujoco-studio-sidecar/SKILL.md) dans la conversation de premier niveau pour lancer (ou réutiliser) le démon sidecar Web MuJoCo Studio (studiod.py) pointant vers le répertoire de l'actif terminé (--workspace_dir=<asset_dir>) et vérifiez/_studio/status("ok": true,"daemon_connected": true). Lancezstudiod.pydepuis la conversation de premier niveau plutôt qu'à l'intérieur du sous-agent constructeur afin que le démon d'arrière-plan ne soit pas terminé lorsque le sous-agent se ferme. Dans votre réponse finale, présentez d'abord le chemin de l'actif terminé, le résumé du modèle (dimensions, masse, articulations, répartition visuelle/collision, statut d'audit), la comparaison côte à côte et la vidéo de présentation (sauf si ignorée viaFast (No Turntable), en notant brièvement dans une légende d'une ligne que la bobine montre une rotation visuelle texturée complète à 360° suivie d'une inspection translucide de l'enveloppe de collision physique), et placez[MuJoCo Studio](sidecar://robotics/mujoco_studio/)(plushttp://127.0.0.1:<http_port>/depuis$SESSION_FILEsi le proxy sidecar Node n'est pas actif) comme tout dernier élément en bas de votre réponse afin que la pilule sidecar interactive ne soit jamais manquée en haut.
- Créez un sous-agent
-
Si vous êtes déjà le Sous-Agent Constructeur Principal créé :
- Ne créez pas de sous-agent constructeur imbriqué—exécutez les sections 1.1 à 7.5 directement (vous pouvez toujours invoquer le sous-agent
browseren lecture seule pendant l'étape 1.1 si une URL de produit nécessite un rendu JS côté client). Conservez tous les fichiers d'ébauche/d'entrée dans le propre<ArtifactDir>/scratch/de ce sous-agent afin que les étapesrun_commandsandboxées aient un accès local en lecture/écriture sansPermissionError. N'exécutez pas l'étape 7.6 (studiod.py) à l'intérieur du sous-agent ; renvoyez plutôt le chemin<asset_dir>de l'actif terminé, le résumé du modèle, les images de comparaison et le chemin de la vidéo de présentation à la conversation parente afin que la conversation parente lancestudiod.pyet présente le lien Studio. - Assurez-vous que
uvet Blender sans interface graphique (4.2+) sont installés localement (macOS et Linux) :Exécutez les scripts Blender avecuv --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.pyet ajoutez<PLUGIN_DIR>/skills/blender-creation/scriptsàsys.pathà l'intérieur du script Blender pourimport blender_mesh_utils as bmu. - Compilation MuJoCo, Rendu de Présentation Filament & Réception des Références (
uv run) :
À l'intérieur de votre script d'ébauche, ajoutez les répertoires des scripts du plugin (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, et<PLUGIN_DIR>/skills/mujoco-showcase-shot/scripts) àsys.pathpour importerasset_build_utils as abu,audit_scenarios, etrender_showcase_shot. - Périmètre & Hygiène de l'Espace de Travail :
- Exécutez les simulations physiques de chute/bascule/préhension sur 10 scénarios
audit_scenarios(Étape 7.3) par défaut, en vérifiant que tous les scénarios réussissent (ou en corrigeant les vérifications échouées en suivantmujoco-audit/SKILL.md). Ne sautez les simulations dynamiques que si l'utilisateur spécifie explicitementSkip Physics AuditouFast Audit. Ne générez pas de deuxième bundle<asset_name>_mechanical/sauf demande explicite. Vérifiez la compilationMjModelstatique propre, les normales arrière nulles (abu.render_blender_diagnostic_sheet), l'alignement des collisions (audit_scenarios.compute_collision_alignment_summary), les poses d'articulation cinématiques (Articulations: Auto), et tous les scénarios dynamiques de chute/bascule/établissement. - Conservez tous les scripts d'ébauche, photos de référence téléchargées, maillages intermédiaires, feuilles de diagnostic
.jpg/.png, fichiers.blend, environnements virtuels (.venv), et caches dans<ArtifactDir>/scratch/,~/.venvs/, et~/.cache/mujoco_pbr_cache. Écrivez uniquement les livrables finaux de l'actif (model.xml,meshes/*.obj,textures/*.png) dans le répertoire de l'actif cible, et n'écrivez jamais.pyc/__pycache__,.venv, ou les fichiers d'échafaudage/d'exécutionstudioddans le répertoire de l'actif.
- Exécutez les simulations physiques de chute/bascule/préhension sur 10 scénarios
- Honorez les surcharges de réglage :
Articulations: Rigid-Only->0articulations ;Depth: Fast (No Turntable)-> ignorez l'étape 7.4 ;Skip Physics Audit/Fast Audit-> ignorez l'étape 7.3.
- Ne créez pas de sous-agent constructeur imbriqué—exécutez les sections 1.1 à 7.5 directement (vous pouvez toujours invoquer le sous-agent
1.1 Réception, Fiches de Contact/Référence & Cahier des Charges
- Réception URL Produit & Références (
<= 8Lectures d'Images) :- Ne devinez jamais l'identité, la catégorie ou les dimensions du produit à partir d'un slug de chemin d'URL (par exemple,
/Walnut-Elegant-Design-Coffee-Products/dp/...peut être un slug SEO tronqué plutôt qu'une table basse). - Lorsqu'une URL de produit est fournie :
- Invoquez le sous-agent
browseren lecture seule pour naviguer vers<product_url>au nom de l'utilisateur. Inspectez la page rendue en direct comme le ferait un designer humain :- Extrayez le titre vérifié du produit, les matériaux, les descriptions de mécanisme et les spécifications dimensionnelles (
L × l × Henmmet masse nue du produit enkg, en recoupant lePoids de l'articledu commerce de détail par rapport au poids d'expédition emballé). - Identifiez les URLs des images de la galerie / du carrousel haute résolution du produit.
- Extrayez le titre vérifié du produit, les matériaux, les descriptions de mécanisme et les spécifications dimensionnelles (
- Si l'accès est bloqué par un CAPTCHA interactif ou une passerelle de sécurité : arrêtez-vous sans tenter de contourner la passerelle et demandez directement à l'utilisateur les dimensions, spécifications ou photos de référence du produit.
- Téléchargez les images de galerie haute résolution collectées dans
<ArtifactDir>/scratch/intake/ref_*.jpg(par exemple en utilisantcurlou un script de téléchargement minimal en ligne).
- Invoquez le sous-agent
- Lorsqu'aucune URL n'est fournie (requête textuelle uniquement) : Recherchez les dimensions
L x l x H(mm) et la masse (kg) nues du produit viasearch_web(ou invoquez le sous-agentbrowsersisearch_webrenvoie uniquement des liens de redirection sans extraits). Recoupez lePoids de l'articledu commerce de détail par rapport aux dimensions et à la densité du matériau. - Fiches composites (
<= 8Lectures d'Images) : N'appelez jamaisread_filesur des dizaines d'images individuelles. Assemblez les photosref_*.jpgtéléchargées et les recadrages de sous-caractéristiques enref_contact_sheetetref_details_gridviaabu.build_ref_contact_and_detail_sheets, puis inspectez ces fiches composites avecread_file.
- Ne devinez jamais l'identité, la catégorie ou les dimensions du produit à partir d'un slug de chemin d'URL (par exemple,
- Échantillonnez directement les centiles RVB photométriques à partir des recadrages de référence (
rgb_sample_boxes) :- N'inventez pas de valeurs
RVBà partir de noms de catégories verbaux ("plastique rouge", "caoutchouc noir", "peluche verte"). Passezrgb_sample_boxes=[('main_shell', ref_path, (x0, y0, x1, y1)), ...]àabu.build_ref_contact_and_detail_sheetspour mesurer les tuples sRGB[p25, p50, p75]directement à partir de patchs de surface intérieure uniformes (en excluant les points chauds spéculaires et les ombres projetées).
- N'inventez pas de valeurs
- Rédigez un Cahier des Charges de
<= 25Lignes & un Bloc de Paramètres NommésP(<= 40Dimensions Nommées) :- Avant d'écrire du code Blender
bmesh, rédigez un Cahier des Charges concis et définissez un dictionnaire de paramètres nommésP = dict(...)(<= 40dimensions nommées enmm/metdegavec des commentaires de provenance) plutôt que de coder en dur des centaines de tuples de coordonnées magiques :- Surfaces primaires nommées et leur jonction : facettes/angles de silhouette latérale, inclinaison en vue de dessus, section transversale de la couronne, espaces négatifs / interstices de lumière du jour entre les pièces, et jonctions affleurantes ou étagées.
- Asymétrie gauche/droite (
+Yvs.-Y) et avant/arrière (+Xvs.-X) : notez explicitement quels leviers, clips, boutons, étiquettes ou ports apparaissent de chaque côté. - Régions de matériau et lignes de séparation : par exemple, surmoulage bi-matière où l'ABS rigide forme le noyau interne et les bords affleurants exposés tandis que le TPE mat forme la peau de préhension externe, ou les poches de marquage en retrait.
- Mécanismes et course : sous-parties mobiles (couvercles articulés, curseurs, clips, lames, boutons, molettes) avec un véritable pivot/axe physique et une course en
mourad.
- Avant d'écrire du code Blender
2. Référence des Outils & Règles du Rendu Cible
2.1 Référence Rapide de l'API des Assistants (blender_mesh_utils, asset_build_utils, render_showcase_shot)
blender_mesh_utils as bmu(à l'intérieur de Blender sans interface graphique"$BLENDER_BIN" -b -P, depuisscripts/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(à l'intérieur des scriptsuv run, depuisscripts/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