Creación de Activos 3D de MuJoCo desde Cero en Blender (bpy / bmesh + PBR)
[!IMPORTANT]
Complemento de
rules/mujoco_asset_standards.md: Learules/mujoco_asset_standards.mdprimero para conocer el sistema de coordenadas obligatorio de MuJoCo (UP_POSZ_FORWARD_POSX_RIGHT_NEGY), las reglas de unidades SI, la separación de grupos (group="2"visual,group="3"colisión,group="4"sitios) y los requisitos de física/auditoría. Esta guía cubre cómo investigar, medir, modelar, esculpir, desenvolver UV, texturizar, hornear, exportar, verificar y previsualizar interactivamente nuevos activos desde cero usando Blender sin interfaz gráfica (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), ymujoco-studio-sidecar/SKILL.mdpara que se vean, comporten e inspeccionen con precisión en el renderizador PBR Filament de MuJoCo y en MuJoCo Studio.
1. Punto de Entrada, Orquestación de Subagentes, Configuración Local de Blender y Recepción de Referencias
1.0 Invocación, Valores Predeterminados y Orquestación de Subagentes
Los usuarios invocan esta habilidad en lenguaje natural con una URL de producto, imagen(es) de referencia o especificaciones de texto:
"Construye un activo 3D de MuJoCo para estas pinzas de cocina:
<url>" "Sigue blender-creation para modelar el objeto en<imagen/enlace>"
Valores Predeterminados y Anulaciones Opcionales: Por defecto, la habilidad ejecuta el pipeline completo de principio a fin: articulaciones detectadas automáticamente, renderizados de diagnóstico intermedios, simulación de física dinámica de 10 escenarios (§7.3) y un video de presentación giratorio 360° en Filament (§7.4). Los usuarios pueden solicitar anulaciones opcionalmente en inglés sencillo o viñetas:
Rápido/Sin Video Giratorio: Omite el paso 7.4 de renderizado de video de presentación (ahorra tiempo de renderizado).Solo Rígido: Fuerza0articulaciones, creando el objeto como un solo cuerpo rígido.Omitir Auditoría de Física/Auditoría Rápida: Omite la suite de simulación de física dinámica de 10 escenarios en el Paso 7.3 (confiando solo en el Paso 7.1 de higiene estática y verificación de alineación de colisiones).
-
Si usted es la conversación de nivel superior / padre:
- Genere un subagente
self(Modelo: "inherit") a través deinvoke_subagentpara construir y verificar el activo, pasando todas las instrucciones especificadas por el usuario, URL y anulaciones,ID de Conversación Padre: <parent_conv_id>, y el directorio padre de salida del activo de destino, e instruyendo al subagente para que lea esta habilidadblender-creation,rules/mujoco_asset_standards.md,mujoco-audit/SKILL.mdymujoco-showcase-shot/SKILL.md. No instruya al subagente para que escriba archivos provisionales/de entrada dentro del directoriobrain/<parent_conv_id>/de la conversación padre (el sandboxing de Seatbelt de macOS bloquea el acceso cruzado abrain/conPermissionError); permita que el subagente use su propio<ArtifactDir>/scratch/y devuelva las rutas del activo terminado y la vista previa. - Cuando el subagente termine: Siga el Paso 7.6 (
mujoco-studio-sidecar/SKILL.md) en la conversación de nivel superior para lanzar (o reutilizar) el daemon sidecar web de MuJoCo Studio (studiod.py) apuntando al directorio del activo terminado (--workspace_dir=<asset_dir>) y verificar/_studio/status("ok": true,"daemon_connected": true). Lancestudiod.pydesde la conversación de nivel superior en lugar de dentro del subagente constructor para que el daemon en segundo plano no sea eliminado cuando el subagente termine. En su respuesta final, presente primero la ruta del activo terminado, el resumen del modelo (dimensiones, masa, articulaciones, desglose visual/colisión, estado de auditoría), comparación lado a lado y video giratorio (a menos que se omita medianteRápido (Sin Video Giratorio), anotando brevemente en un subtítulo de 1 línea que el carrete muestra un giro visual texturizado completo de 360° seguido de una inspección translúcida del casco de colisión de física), y coloque[MuJoCo Studio](sidecar://robotics/mujoco_studio/)(máshttp://127.0.0.1:<http_port>/de$SESSION_FILEsi el proxy sidecar de Node no está activo) como el último elemento en la parte inferior de su respuesta para que el piloto del sidecar interactivo nunca se pierda en la parte superior.
- Genere un subagente
-
Si usted ya es el Subagente Constructor Principal generado:
- No genere un subagente constructor anidado: ejecute las Secciones 1.1 a 7.5 directamente (aún puede invocar el subagente
browserde solo lectura durante el Paso 1.1 si una URL de producto requiere renderizado JS del lado del cliente). Mantenga todos los archivos provisionales/de entrada en el propio<ArtifactDir>/scratch/de este subagente para que los pasos derun_commandcon sandboxing tengan acceso local de lectura/escritura sinPermissionError. No ejecute el Paso 7.6 (studiod.py) dentro del subagente; en su lugar, devuelva la ruta<asset_dir>terminada, el resumen del modelo, las imágenes de comparación y la ruta del video giratorio a la conversación padre para que la conversación padre lancestudiod.pyy presente el enlace de Studio. - Asegúrese de que
uvy Blender sin interfaz gráfica (4.2+) estén instalados localmente (macOS y Linux):Ejecute scripts de Blender conuv --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.pyy agregue<PLUGIN_DIR>/skills/blender-creation/scriptsasys.pathdentro del script de Blender paraimport blender_mesh_utils as bmu. - Compilación de MuJoCo, Renderizados de Presentación Filament y Recepción de Referencias (
uv run) :
Dentro de su script provisional, agregue los directorios de scripts del 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/scriptsy<PLUGIN_DIR>/skills/mujoco-showcase-shot/scripts) asys.pathpara importarasset_build_utils as abu,audit_scenariosyrender_showcase_shot. - Alcance e Higiene del Espacio de Trabajo:
- Ejecute las simulaciones de caída/inclinación/agarre de física de 10 escenarios de
audit_scenarios(Paso 7.3) por defecto, verificando que todos los escenarios pasen (o corrigiendo las comprobaciones fallidas siguiendomujoco-audit/SKILL.md). Solo omita las simulaciones dinámicas si el usuario especifica explícitamenteOmitir Auditoría de FísicaoAuditoría Rápida. No genere un segundo paquete<asset_name>_mechanical/a menos que se solicite. Verifique la compilaciónMjModelestática limpia, normales de retroceso cero (abu.render_blender_diagnostic_sheet), alineación de colisiones (audit_scenarios.compute_collision_alignment_summary), poses de articulaciones cinemáticas (Articulaciones: Auto) y todos los escenarios dinámicos de caída/inclinación/asentamiento de física. - Mantenga todos los scripts provisionales, fotos de referencia descargadas, mallas intermedias, hojas de diagnóstico
.jpg/.png, archivos.blend, entornos virtuales (.venv) y cachés en<ArtifactDir>/scratch/,~/.venvs/y~/.cache/mujoco_pbr_cache. Solo escriba los entregables finales del activo (model.xml,meshes/*.obj,textures/*.png) en el directorio de activos de destino, y nunca escriba.pyc/__pycache__,.venvo archivos scaffold/tiempo de ejecución destudioden el directorio de activos.
- Ejecute las simulaciones de caída/inclinación/agarre de física de 10 escenarios de
- Respete las anulaciones de perillas:
Articulaciones: Solo Rígido->0articulaciones;Profundidad: Rápido (Sin Video Giratorio)-> omita el Paso 7.4;Omitir Auditoría de Física/Auditoría Rápida-> omita el Paso 7.3.
- No genere un subagente constructor anidado: ejecute las Secciones 1.1 a 7.5 directamente (aún puede invocar el subagente
1.1 Recepción, Hojas de Contacto/Detalle de Referencia y Resumen del Formulario
- URL del Producto y Recepción de Referencias (
<= 8Lecturas de Imagen) :- Nunca adivine la identidad, categoría o dimensiones del producto a partir de un slug de ruta de URL (por ejemplo,
/Walnut-Elegant-Design-Coffee-Products/dp/...puede ser un slug SEO truncado en lugar de una mesa de café). - Cuando se proporciona una URL de producto:
- Invoque el subagente
browserde solo lectura para navegar a<product_url>en nombre del usuario. Inspeccione la página renderizada en vivo tal como lo haría un diseñador humano:- Extraiga el título verificado del producto, materiales, descripciones del mecanismo y especificaciones dimensionales (
L × W × Henmmy masa del producto desnudo enkg, verificando elPeso del Artículominorista vs el peso de envío empaquetado). - Identifique las URL de imágenes de la galería/carrusel de productos de alta resolución.
- Extraiga el título verificado del producto, materiales, descripciones del mecanismo y especificaciones dimensionales (
- Si el acceso está bloqueado por un CAPTCHA interactivo o una puerta de seguridad: deténgase sin intentar eludir la puerta y pida al usuario las dimensiones, especificaciones o fotos de referencia del producto directamente.
- Descargue las imágenes de galería de alta resolución recopiladas en
<ArtifactDir>/scratch/intake/ref_*.jpg(por ejemplo, usandocurlo un script de descarga en línea mínimo).
- Invoque el subagente
- Cuando no se proporciona URL (consulta solo de texto): Busque
L x W x H(mm) y masa (kg) del producto desnudo a través desearch_web(o invoque el subagentebrowsersisearch_webdevuelve solo enlaces de redirección desnudos sin fragmentos). Verifique elPeso del Artículominorista con las dimensiones y la densidad del material. - Hojas Compuestas (
<= 8Lecturas de Imagen): Nunca llame aread_fileen docenas de fotogramas individuales. Combine las fotosref_*.jpgdescargadas y los recortes de subcaracterísticas enref_contact_sheetyref_details_grida través deabu.build_ref_contact_and_detail_sheets, luego inspeccione esas hojas compuestas conread_file.
- Nunca adivine la identidad, categoría o dimensiones del producto a partir de un slug de ruta de URL (por ejemplo,
- Percentiles RGB Fotométricos de Muestra Directamente de Recortes de Referencia (
rgb_sample_boxes):- No invente valores
RGBa partir de nombres de categorías verbales ("plástico rojo", "caucho negro", "felpa verde"). Pasergb_sample_boxes=[('main_shell', ref_path, (x0, y0, x1, y1)), ...]aabu.build_ref_contact_and_detail_sheetspara medir tuplas sRGB[p25, p50, p75]directamente de parches de superficie interior uniformes (excluyendo puntos calientes especulares y sombras proyectadas).
- No invente valores
- Escriba un Resumen del Formulario de
<= 25Líneas y un Bloque de Parámetros NombradosP(<= 40Dimensiones Nombradas) :- Antes de escribir código
bmeshde Blender, escriba un Resumen del Formulario conciso y defina un diccionario de parámetros nombradosP = dict(...)(<= 40dimensiones nombradas enmm/mydegcon comentarios de procedencia) en lugar de codificar cientos de tuplas de coordenadas mágicas:- Superficies primarias nombradas y cómo se encuentran: facetas/ángulos de silueta lateral, conicidad en vista en planta, sección transversal de corona, espacios negativos / espacios de luz diurna abiertos entre partes y uniones al ras vs. escalonadas.
- Asimetría izquierda/derecha (
+Yvs.-Y) y delantera/trasera (+Xvs.-X): anote explícitamente qué palancas, clips, botones, etiquetas o puertos aparecen en cada lado. - Regiones de material y líneas de separación: por ejemplo, sobremolde de dos disparos donde el ABS rígido forma el núcleo interno y los bordes al ras expuestos mientras que el TPE mate forma la piel de agarre externa, o bolsillos de marca empotrados.
- Mecanismos y recorrido: subpartes móviles (tapas con bisagras, deslizadores, clips, cuchillas, botones, perillas) con pivote/eje físico real y recorrido en
morad.
- Antes de escribir código
2. Referencia de Herramientas y Reglas del Renderizador de Destino
2.1 Referencia Rápida de la API de Ayudantes (blender_mesh_utils, asset_build_utils, render_showcase_shot)
blender_mesh_utils as bmu(dentro de Blender sin interfaz gráfica"$BLENDER_BIN" -b -P, descripts/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(dentro de scriptsuv run, descripts/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, persistence=0.5, lacunarity=2.0, seed=0) -> np.ndarrayabu.export_baked_png_from_exr(exr_path, png_path, *, tonemap_clip=2.0, tonemap_method='reinhard', bit_depth='16') -> str- `abu.remesh_with_planar_merging(target_obj, *, angle_deg=30.0, max_distance_scale=0.01)
render_showcase_shot(demujoco-showcase-shot/SKILL.md): Vea la referencia completa de la API en el SKILL.md mencionado; el método principal esrender_turntable_video(asset_dir, out_video_path, ...).
2.2 Reglas del Renderizador de Destino: MuJoCo Filament PBR
- Sistema de coordenadas:
UP_POSZ_FORWARD_POSX_RIGHT_NEGY(eje Z hacia arriba, eje X hacia adelante, eje Y hacia la derecha). - Unidades: SI (metros, kilogramos, segundos). Las texturas PBR deben usar mapas de
base_color(sRGB),roughness,metallicynormal(OpenGL, eje Y hacia arriba). - Separación de grupos:
group="2"para mallas visuales,group="3"para mallas de colisión,group="4"para sitios. - Iluminación: El renderizador Filament de MuJoCo utiliza iluminación basada en imágenes (IBL) con un entorno HDR. Las texturas deben estar calibradas para este sistema.
3. Modelado y Esculpido en Blender
3.1 Configuración de la Escena
- Limpie la escena con
bmu.clear_scene(). - Configure las unidades de la escena en
Milímetrospara la precisión del modelado. - Aplique la escala (Ctrl+A > Escala) a todos los objetos importados o creados.
3.2 Modelado de Mallas Base
- Use
bmu.skin_skeleton(),bmu.metaball_sdf(),bmu.swept_tube()ybmu.voxel_smooth_union()para crear formas orgánicas y complejas. - Para formas mecánicas, use operaciones booleanas con
bmu.apply_boolean_cutter(). - Asegúrese de que todas las mallas sean manifold (sin agujeros, bordes no múltiples, etc.).
3.3 Desarrollo de UV y Texturizado
- Use
bmu.smart_seam_unwrap()para desenvolver UVs de forma inteligente. - Empaquete las UVs en un atlas compartido con
bmu.pack_shared_uv_atlas(). - Hornee mapas PBR con
bmu.bake_pbr_maps().
3.4 Exportación de Mallas
- Exporte mallas visuales como
.objconbmu.finalize_and_export_obj(). - Exporte cascos de colisión convexos con
bmu.export_convex_hull_col().
4. Síntesis de Colisiones Convexas
- Genere cascos convexos automáticamente para cada parte móvil.
- Use
bmu.export_convex_hull_col()con un máximo de 64 vértices por casco para un rendimiento óptimo. - Alinee los cascos de colisión con las mallas visuales usando
audit_scenarios.compute_collision_alignment_summary().
5. Ensamblaje del Archivo MJCF
5.1 Estructura del Archivo model.xml
<mujoco>: Raíz del documento.<compiler>: Configuración del compilador (por ejemplo,angle="radian",coordinate="local").<option>: Opciones de física (por ejemplo,gravity="0 0 -9.81").<default>: Valores predeterminados para clases, materiales, geometrías, etc.<asset>: Definiciones de mallas, materiales, texturas.<worldbody>: Cuerpos y articulaciones del mundo.<actuator>: Definiciones de actuadores (si es necesario).<tendon>: Definiciones de tendones (si es necesario).<equality>: Restricciones de igualdad (si es necesario).<contact>: Pares de contacto (si es necesario).<sensor>: Definiciones de sensores (si es necesario).
5.2 Convenciones de Nomenclatura
visual_<part>: Mallas visuales.col_<part>: Mallas de colisión.site_<part>: Sitios.
6. Creación de Texturas PBR
- Use mapas de
ambientCGdescargados conabu.fetch_ambientcg_maps(). - Combine múltiples mapas de materiales con
abu.triplanar_project_map(). - Genere mapas de normales a partir de mapas de altura con
abu.height_to_normal_rgb(). - Dilate los bordes de UV con
abu.dilate_uv_gutters()para evitar artefactos de bordes.
7. Auditoría, Presentación e Inspección Final
7.1 Higiene Estática y Verificación de Alineación de Colisiones
audit_scenarios.compute_collision_alignment_summary()verifica que las mallas de colisión estén alineadas correctamente con las mallas visuales.abu.render_blender_diagnostic_sheet()genera una hoja de diagnóstico con normales de superficie, cascos de colisión y mapa UV.
7.2 Simulación de Física Dinámica de 10 Escenarios
- Ejecute
audit_scenariospara simular 10 escenarios diferentes: caídas libres, inclinaciones, agarres, etc. - Verifique que todos los escenarios pasen (sin penetraciones, sin inestabilidades).
- Corrija cualquier problema siguiendo las instrucciones de
mujoco-audit/SKILL.md.
7.3 Video de Presentación Giratorio 360°
- Use
render_showcase_shot.render_turntable_video()para generar un video de 360° del activo. - El video muestra una rotación texturizada visual completa seguida de una inspección translúcida del casco de colisión.
7.4 Lanzamiento de MuJoCo Studio Sidecar
- Paso 7.6: Ejecute
studiod.pydesde la conversación de nivel superior apuntando al directorio del activo. - Verifique que el daemon esté conectado a través de
/_studio/status. - Incluya el enlace de MuJoCo Studio en la respuesta final.
8. Limpieza y Archivo
- Elimine todos los archivos provisionales en
<ArtifactDir>/scratch/. - Archivo final:
model.xml,meshes/*.obj,textures/*.png.