blender-control (Control de Blender)

Habilidad de Control de Blender (GUI en vivo + CLI sin cabeza)

Este espacio de trabajo controla Blender 5.2.1 LTS (/Applications/Blender.app/Contents/MacOS/Blender, Python 3.13, Apple M1 Pro 16-core Metal GPU) en dos modos complementarios:

1. Modo GUI en vivo (predeterminado y preferido): Envía comandos a través de 127.0.0.1:9876 a blender_control_bridge.py ejecutándose dentro de la ventana abierta de Blender.app. Los objetos, shaders, animaciones y el encuadre de la cámara aparecen inmediatamente frente al usuario.
2. Modo CLI sin cabeza: Ejecuta /Applications/Blender.app/Contents/MacOS/Blender --background para renderizados por lotes aislados o trabajos pesados en segundo plano sin tocar la sesión GUI activa.

Antes de escribir scripts bpy para Blender 5.2, revisa blender_5_2_api_guide.md para conocer los cambios críticos de la API 5.2 (nombres de sockets de Principled BSDF, Slotted Actions channelbag, media_type = 'VIDEO', y configuración de GPU Metal).

---

Paso 1: Verificar o conectar la aplicación Blender abierta

Siempre verifica primero la conexión del puente en vivo:

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

Si ping falla (por ejemplo, Blender no está abierto o se inició antes de instalar el puente de inicio), ejecuta el script instalador/conector:

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

• Copia blender_control_bridge.py en ~/Library/Application Support/Blender/5.2/scripts/startup/ para que cada inicio de GUI active automáticamente el puente en 127.0.0.1:9876.
• Se conecta de forma segura a Blender.app o lo inicia (open -g -a Blender) sin robar el foco de la ventana.
• Si Blender.app ya tiene un archivo .blend sin guardar abierto sin el puente cargado, pide al usuario que haga clic en Blender -> Sistema -> Recargar Scripts en la barra de menú de macOS.

---

Paso 2: Inspeccionar y controlar la escena en vivo mediante blender_cli.py

Usa blender_cli.py para todas las operaciones en vivo:

# 1. Inspeccionar objetos, cámaras, materiales, rango de fotogramas y motor de renderizado actuales
python3 .agents/skills/blender-control/scripts/blender_cli.py info

# 2. Limpiar la escena en vivo correctamente (elimina todos los objetos y bloques de datos huérfanos)
python3 .agents/skills/blender-control/scripts/blender_cli.py reset

# 3. Ejecutar un script de construcción de escena Python en vivo en el hilo principal de la UI de Blender
python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/mi_escena/build.py

# 4. Ejecutar expresiones/fragmentos de código Python rápidos en línea
python3 .agents/skills/blender-control/scripts/blender_cli.py exec "RESULT = [o.name for o in bpy.data.objects]"

# 5. Cambiar la vista 3D en vivo de Blender a Previsualización de Materiales o Vista de Cámara Renderizada
python3 .agents/skills/blender-control/scripts/blender_cli.py viewport --shading MATERIAL

# 6. Guardar o abrir archivos de proyecto .blend en la GUI en vivo
python3 .agents/skills/blender-control/scripts/blender_cli.py save projects/mi_escena/escena.blend
python3 .agents/skills/blender-control/scripts/blender_cli.py open projects/mi_escena/escena.blend

---

Paso 3: Renderizar imágenes fijas, previsualizaciones de viewport y animaciones

Previsualización rápida de viewport (<0.2s)

Usa una captura de pantalla del viewport primero para verificar el encuadre de la cámara, la colocación de objetos y el recorte antes de ejecutar un renderizado completo con trazado de rayos:

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

¡Inspecciona /tmp/preview.png con read_file para verificar visualmente la composición y la iluminación!

Renderizado de imagen fija de alta calidad (Cycles GPU Metal o EEVEE)

# Cycles con aceleración automática de GPU Metal Apple M1 Pro 16 núcleos
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/mi_escena/render.png \
  --engine CYCLES --samples 64 --width 1920 --height 1080

# Renderizado PBR rápido en tiempo real con EEVEE
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/mi_escena/render.png \
  --engine BLENDER_EEVEE --samples 32 --width 1920 --height 1080

Renderizado de animación MP4 (H.264)

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

Modo por lotes sin cabeza (proceso aislado)

Al renderizar trabajos pesados sin bloquear el viewport GUI en vivo:

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

---

Paso 4: Lista de verificación de construcción y validación de escenas

1. Scripts de construcción autocontenidos: Almacena cada proyecto en projects/<nombre_del_proyecto>/build.py para que las escenas sean 100% reproducibles y compatibles con Git junto con las salidas renderizadas y los archivos .blend.
2. Apunta la cámara (TRACK_TO o Quaternion): Siempre apunta la cámara de manera confiable a un Empty de destino o coordenada mundial usando (target - cam.location).to_track_quat('-Z', 'Y') y establece scene.camera = cam.
3. Iluminación de tres puntos / estudio y mundo: Nunca dejes un fondo gris oscuro predeterminado; configura nodos de shader del Mundo + luces de Área/Sol con potencia realista (100W–1500W según la escala de la escena) y gestión de color AgX o Filmic (scene.view_settings.view_transform = 'AgX', look = 'AgX - Medium High Contrast').
4. Verificación visual: Siempre inspecciona las salidas renderizadas .png o .mp4 usando read_file para confirmar el encuadre, la exposición, los materiales y el movimiento antes de finalizar.
5. Sincronización con GitHub: Después de crear o actualizar proyectos/habilidades, ejecuta ./scripts/sync_github.sh "<mensaje del commit>" para mantener sincronizados el repositorio local y origin/main.