Controle do Blender

Skill de Controle do Blender (GUI Ativa + CLI Headless)

Este workspace controla o Blender 5.2.1 LTS (/Applications/Blender.app/Contents/MacOS/Blender, Python 3.13, Apple M1 Pro 16-core Metal GPU) em dois modos complementares:

1. Modo GUI Ativa (Padrão e Preferido): Envia comandos via 127.0.0.1:9876 para o blender_control_bridge.py executando dentro da janela aberta do Blender.app. Objetos, shaders, animações e enquadramento de câmera aparecem imediatamente na frente do usuário.
2. Modo Headless CLI: Executa /Applications/Blender.app/Contents/MacOS/Blender --background para renderização em lote isolada ou tarefas pesadas em segundo plano sem tocar na sessão GUI ativa.

Antes de escrever scripts bpy para o Blender 5.2, revise o blender_5_2_api_guide.md para alterações críticas da API 5.2 (nomes de sockets do Principled BSDF, Slotted Actions channelbag, media_type = 'VIDEO' e configuração da GPU Metal).

---

Etapa 1: Verificar ou Conectar-se ao Aplicativo Blender Aberto

Sempre verifique a conexão da ponte ativa primeiro:

python3 .agents/skills/blender-control/scripts/blender_cli.py ping

Se o ping falhar (por exemplo, o Blender ainda não está aberto ou foi iniciado antes de instalar a ponte de inicialização), execute o script de instalação/conexão:

bash .agents/skills/blender-control/scripts/install_bridge.sh

• Copia blender_control_bridge.py para ~/Library/Application Support/Blender/5.2/scripts/startup/ para que toda inicialização da GUI inicie a ponte automaticamente em 127.0.0.1:9876.
• Conecta-se ou inicia o Blender.app com segurança (open -g -a Blender) sem roubar o foco da janela.
• Se o Blender.app já tiver um arquivo .blend não salvo aberto sem a ponte carregada, peça ao usuário para clicar em Blender -> Sistema -> Recarregar Scripts na barra de menus do macOS.

---

Etapa 2: Inspecionar e Controlar a Cena Ativa via blender_cli.py

Use blender_cli.py para todas as operações ao vivo:

# 1. Inspecionar objetos, câmeras, materiais, intervalo de quadros e mecanismo de renderização atuais
python3 .agents/skills/blender-control/scripts/blender_cli.py info

# 2. Limpar a cena ativa completamente (remove todos os objetos e blocos de dados órfãos)
python3 .agents/skills/blender-control/scripts/blender_cli.py reset

# 3. Executar um script Python construtor de cena ao vivo na thread principal da interface do Blender
python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py

# 4. Executar expressões/trechos Python inline rápidos
python3 .agents/skills/blender-control/scripts/blender_cli.py exec "RESULT = [o.name for o in bpy.data.objects]"

# 5. Alternar a viewport 3D ativa do Blender para Pré-visualização de Material ou Visualização de Câmera Renderizada
python3 .agents/skills/blender-control/scripts/blender_cli.py viewport --shading MATERIAL

# 6. Salvar ou abrir arquivos de projeto .blend na GUI ativa
python3 .agents/skills/blender-control/scripts/blender_cli.py save projects/my_scene/scene.blend
python3 .agents/skills/blender-control/scripts/blender_cli.py open projects/my_scene/scene.blend

---

Etapa 3: Renderizar Imagens Estáticas, Pré-visualizações da Viewport e Animações

Pré-visualização Rápida da Viewport (<0,2s)

Use uma captura de tela da viewport primeiro para verificar o enquadramento da câmera, o posicionamento dos objetos e o clipping antes de executar uma renderização completa com ray tracing:

python3 .agents/skills/blender-control/scripts/blender_cli.py screenshot /tmp/preview.png

Inspecione /tmp/preview.png com read_file para verificar visualmente a composição e a iluminação!

Renderização de Imagem Estática de Alta Qualidade (Cycles GPU Metal ou EEVEE)

# Cycles com aceleração automática da GPU Metal Apple M1 Pro 16-core
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine CYCLES --samples 64 --width 1920 --height 1080

# Renderização PBR em tempo real rápida com EEVEE
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine BLENDER_EEVEE --samples 32 --width 1920 --height 1080

Renderização de Animação MP4 (H.264)

python3 .agents/skills/blender-control/scripts/blender_cli.py render-anim projects/my_scene/animation.mp4 \
  --engine BLENDER_EEVEE --samples 32 --width 1280 --height 720 --start 1 --end 120 --fps 30

Modo Headless em Lote (Processo Isolado)

Ao renderizar tarefas pesadas sem bloquear a viewport da GUI ativa:

python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py --headless

---

Etapa 4: Checklist de Construção e Validação de Cena

1. Scripts Construtores Autocontidos: Armazene cada projeto em projects/<nome_do_projeto>/build.py para que as cenas sejam 100% reproduzíveis e amigáveis ao Git, juntamente com as saídas renderizadas e arquivos .blend.
2. Apontamento de Câmera (TRACK_TO ou Quaternion): Sempre aponte a câmera de forma confiável para um Empty alvo ou coordenada mundial usando (target - cam.location).to_track_quat('-Z', 'Y') e defina scene.camera = cam.
3. Iluminação de Três Pontos/Estúdio e Mundo: Nunca deixe um fundo cinza escuro padrão; configure nós de shader do Mundo + luzes de Área/Sol com potência realista (100W–1500W dependendo da escala da cena) e gerenciamento de cor AgX ou Filmic (scene.view_settings.view_transform = 'AgX', look = 'AgX - Medium High Contrast').
4. Verificação Visual: Sempre inspecione as saídas renderizadas .png ou .mp4 usando read_file para confirmar enquadramento, exposição, materiais e movimento antes de finalizar.
5. Sincronização com GitHub: Após criar ou atualizar projetos/skills, execute ./scripts/sync_github.sh "<mensagem de commit>" para manter o repositório local e origin/main sincronizados.