Criação de Ativos 3D MuJoCo do Zero no Blender (bpy / bmesh + PBR)
[!IMPORTANTE]
Complemento de [
rules/mujoco_asset_standards.md][asset-standards]: Leia [rules/mujoco_asset_standards.md][asset-standards] primeiro para as regras obrigatórias de coordenadas MuJoCo (UP_POSZ_FORWARD_POSX_RIGHT_NEGY), unidades SI, separação de grupos (group="2"visual,group="3"colisão,group="4"sites), e requisitos de física/auditoria. Este guia aborda como pesquisar, medir, modelar, esculpir, UV-unwrap, texturizar, cozinhar, exportar, verificar e visualizar interativamente novos ativos do zero usando Blender headless (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.mdrender_showcase_shot.py), emujoco-studio-sidecar/SKILL.mdpara que eles pareçam, se comportem e sejam inspecionados com precisão no Renderizador Filament PBR do MuJoCo e no MuJoCo Studio.
1. Ponto de Entrada, Orquestração de Subagentes, Configuração Local do Blender e Captação de Referências
1.0 Invocação, Padrões e Orquestração de Subagentes
Usuários invocam este skill em linguagem natural com uma URL de produto, imagem(is) de referência ou especificações em texto:
"Construa um ativo MuJoCo 3D para esta pinça de cozinha:
<url>" "Siga blender-creation para modelar o objeto em<image/link>"
Padrões e Sobrescritas Opcionais: Por padrão, o skill executa o pipeline completo: articulações auto-detectadas, renders diagnósticos intermediários, auditoria de simulação física dinâmica de 10 cenários (§7.3) e um vídeo de showcase de 360° no Filament (§7.4). Os usuários podem solicitar sobrescritas em linguagem natural:
Rápido/Sem Turntable: Pula o Step 7.4 (vídeo showcase) (economiza tempo de render).Apenas Corpo Rígido: Força0juntas, criando o objeto como um único corpo rígido.Pular Auditoria Física/Auditoria Rápida: Pula a suíte de simulação física dinâmica de 10 cenários no Step 7.3 (confiando apenas na higiene estática e verificações de alinhamento de colisão do Step 7.1).
-
Se você é a conversa de nível superior / pai:
- Crie um subagente
self(Model: "inherit") viainvoke_subagentpara construir e verificar o ativo, passando todas as instruções, URLs e sobrescritas especificadas pelo usuário,Parent Conversation ID: <parent_conv_id>, e o diretório pai de saída do ativo alvo, e instruindo o subagente a ler este skillblender-creation, [rules/mujoco_asset_standards.md][asset-standards],mujoco-audit/SKILL.md, emujoco-showcase-shot/SKILL.md. Não instrua o subagente a escrever arquivos temporários dentro do diretóriobrain/<parent_conv_id>/da conversa pai (o sandbox do macOS impede acessobrain/entre conversas comPermissionError); deixe o subagente usar seu próprio<ArtifactDir>/scratch/e retornar o ativo finalizado e os caminhos das visualizações. - Quando o subagente terminar: Siga o Step 7.6 (
mujoco-studio-sidecar/SKILL.md) na conversa de nível superior para iniciar (ou reutilizar) o daemon sidecar MuJoCo Studio Web (studiod.py) apontando para o diretório do ativo finalizado (--workspace_dir=<asset_dir>) e verifique/_studio/status("ok": true,"daemon_connected": true). Iniciestudiod.pyda conversa de nível superior, não dentro do subagente construtor, para que o daemon em segundo plano não seja eliminado quando o subagente sair. Na sua resposta final, apresente primeiro o caminho do ativo finalizado, um resumo do modelo (dimensões, massa, articulações, quebra visual/colisão, status da auditoria), comparação lado a lado e o vídeo turntable (a menos que seja pulado viaRápido (Sem Turntable), notando brevemente em uma linha de legenda que o vídeo mostra uma rotação visual texturizada completa de 360° seguida por inspeção translúcida do invólucro de colisão física), e coloque[MuJoCo Studio](sidecar://robotics/mujoco_studio/)(maishttp://127.0.0.1:<http_port>/de$SESSION_FILEse o proxy sidecar Node não estiver ativo) como o último item no final da sua resposta para que a pílula sidecar interativa nunca seja perdida no topo.
- Crie um subagente
-
Se você já é o Subagente Construtor Principal criado:
- Não crie um subagente de construção aninhado—execute as Seções 1.1 a 7.5 diretamente (você ainda pode invocar o subagente
browsersomente leitura durante o Step 1.1 se uma URL de produto exigir renderização JS no lado do cliente). Mantenha todos os arquivos temporários no próprio<ArtifactDir>/scratch/deste subagente para querun_commandnão sofra comPermissionError. Não execute o Step 7.6 (studiod.py) dentro do subagente; em vez disso, retorne o caminho<asset_dir>finalizado, resumo do modelo, imagens de comparação e caminho do vídeo turntable para a conversa pai para que a conversa pai inicie ostudiod.pye apresente o link do Studio. - Garanta que
uve Blender Headless (4.2+) estejam instalados localmente (macOS & Linux):Execute scripts Blender comuv --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.pye adicione<PLUGIN_DIR>/skills/blender-creation/scriptsaosys.pathdentro do script Blender paraimport blender_mesh_utils as bmu. - Compilação MuJoCo, Renders Filament Showcase e Captação de Referências (
uv run):
Dentro do seu script temporário, adicione os diretórios de script do 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, e<PLUGIN_DIR>/skills/mujoco-showcase-shot/scripts) aosys.pathpara importarasset_build_utils as abu,audit_scenarios, erender_showcase_shot. - Escopo e Higiene do Workspace:
- Execute as simulações físicas de queda/inclinação/agarramento de 10 cenários do
audit_scenarios(Step 7.3) por padrão, verificando se todos os cenários passam (ou corrija as verificações com falha seguindomujoco-audit/SKILL.md). Pule as simulações físicas dinâmicas somente se o usuário especificar explicitamentePular Auditoria FísicaouAuditoria Rápida. Não gere um segundo pacote<asset_name>_mechanical/a menos que solicitado. Verifique a compilaçãoMjModelestática limpa, normais reversas zero (abu.render_blender_diagnostic_sheet), alinhamento de colisão (audit_scenarios.compute_collision_alignment_summary), poses de juntas cinemáticas (Articulações: Auto), e todos os cenários físicos dinâmicos de queda/inclinação/estabilização. - Mantenha todos os scripts temporários, fotos de referência baixadas, malhas intermediárias, folhas
.jpg/.pngde diagnóstico, arquivos.blend, ambientes virtuais (.venv), e caches em<ArtifactDir>/scratch/,~/.venvs/, e~/.cache/mujoco_pbr_cache. Apenas escreva os entregáveis finais do ativo (model.xml,meshes/*.obj,textures/*.png) no diretório do ativo alvo, e nunca escreva.pyc/__pycache__,.venv, ou arquivos de scaffold/runtimestudiodno diretório do ativo.
- Execute as simulações físicas de queda/inclinação/agarramento de 10 cenários do
- Honre as sobrescritas:
Articulações: Apenas Corpo Rígido->0juntas;Profundidade: Rápido (Sem Turntable)-> pule Step 7.4;Pular Auditoria Física/Auditoria Rápida-> pule Step 7.3.
- Não crie um subagente de construção aninhado—execute as Seções 1.1 a 7.5 diretamente (você ainda pode invocar o subagente
1.1 Captação, Folhas de Contato/Detalhes de Referência e Brief do Formulário
- Captação de URL de Produto e Referência (
<= 8Leituras de Imagem):- Nunca adivinhe a identidade do produto, categoria ou dimensões a partir de um slug de caminho de URL (por exemplo,
/Walnut-Elegant-Design-Coffee-Products/dp/...pode ser um slug SEO truncado em vez de uma mesa de centro). - Quando uma URL de produto é fornecida:
- Invoque o subagente
browsersomente leitura para navegar até<product_url>em nome do usuário. Inspecione a página renderizada ao vivo como um designer humano faria:- Extraia o título verificado do produto, materiais, descrições de mecanismos e especificações dimensionais (
L × W × Hemmme massa do produto sem embalagem emkg, verificando oItem Weightdo varejo vs. peso de envio embalado). - Identifique URLs de galeria de imagens de alta resolução do produto.
- Extraia o título verificado do produto, materiais, descrições de mecanismos e especificações dimensionais (
- Se o acesso for bloqueado por um CAPTCHA interativo ou gate de segurança: pare sem tentar contornar o gate e peça ao usuário as dimensões, especificações ou fotos de referência do produto diretamente.
- Baixe as imagens da galeria de alta resolução coletadas para
<ArtifactDir>/scratch/intake/ref_*.jpg(por exemplo, usandocurlou um script de download mínimo).
- Invoque o subagente
- Quando nenhuma URL é fornecida (consulta apenas em texto): Pesquise as dimensões do produto sem embalagem
L x W x H(mm) e massa (kg) viasearch_web(ou invoque o subagentebrowsersesearch_webretornar apenas links de redirecionamento sem snippets). Verifique oItem Weightdo varejo contra as dimensões e a densidade do material. - Folhas Compostas (
<= 8Leituras de Imagem): Nunca chameread_fileem dezenas de quadros individuais. Monte as fotosref_*.jpgbaixadas e recortes de sub-características emref_contact_sheeteref_details_gridviaabu.build_ref_contact_and_detail_sheets, depois inspecione essas folhas compostas comread_file.
- Nunca adivinhe a identidade do produto, categoria ou dimensões a partir de um slug de caminho de URL (por exemplo,
- Amostragem de Percentis RGB Fotométricos Diretamente de Recortes de Referência (
rgb_sample_boxes):- Não invente valores
RGBa partir de nomes de categorias verbais ("plástico vermelho", "borracha preta", "pelúcia verde"). Passergb_sample_boxes=[('main_shell', ref_path, (x0, y0, x1, y1)), ...]paraabu.build_ref_contact_and_detail_sheetspara medir tuplas sRGB[p25, p50, p75]diretamente de patches de superfície interior uniformes (excluindo hotspots especulares e sombras projetadas).
- Não invente valores
- Escreva um Brief de Formulário de
<= 25Linhas e um Bloco de Parâmetros NomeadosP(<= 40Dimensões Nomeadas):- Antes de escrever código
bmeshdo Blender, escreva um Brief de Formulário conciso e defina um dicionário de parâmetros nomeadosP = dict(...)(<= 40dimensões nomeadas emmm/medegcom comentários de proveniência) em vez de codificar centenas de tuplas de coordenadas mágicas:- Superfícies primárias nomeadas e como elas se encontram: facetas/ângulos de silhueta lateral, conicidade em vista de planta, seção transversal da coroa, espaço negativo / lacunas abertas entre as partes e junções niveladas vs. escalonadas.
- Assimetria esquerda/direita (
+Yvs.-Y) e frente/trás (+Xvs.-X): observe explicitamente quais alavancas, clipes, botões, etiquetas ou portas aparecem em cada lado. - Regiões de material e linhas de partição: por exemplo, overmold de dois disparos onde o ABS rígido forma o núcleo interno e os aros nivelados expostos, enquanto o TPE fosco forma a pele de aderência externa, ou bolsos de marca recuados.
- Mecanismos e curso: sub-partes móveis (tampas articuladas, controles deslizantes, clipes, lâminas, botões, maçanetas) com pivô/eixo físico real e curso em
mourad.
- Antes de escrever código
2. Referência de Ferramentas e Regras do Renderizador Alvo
2.1 Referência Rápida da API Helper (blender_mesh_utils, asset_build_utils, render_showcase_shot)
blender_mesh_utils as bmu(dentro do Blender headless"$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, pers
[...truncado para tradução]