blender-control

Compétence Blender Control (GUI en direct + CLI headless)

Cet espace de travail contrôle Blender 5.2.1 LTS (/Applications/Blender.app/Contents/MacOS/Blender, Python 3.13, Apple M1 Pro 16 cœurs GPU Metal) selon deux modes complémentaires :

1. Mode GUI en direct (par défaut et préféré) : envoie des commandes via 127.0.0.1:9876 à blender_control_bridge.py tournant dans la fenêtre ouverte de Blender.app. Les objets, shaders, animations et cadrages de caméra apparaissent immédiatement devant l'utilisateur.
2. Mode CLI headless : exécute /Applications/Blender.app/Contents/MacOS/Blender --background pour des rendus par lots isolés ou des tâches lourdes en arrière-plan sans toucher à la session GUI active.

Avant d'écrire des scripts bpy pour Blender 5.2, consultez blender_5_2_api_guide.md pour les changements importants de l'API 5.2 (noms de sockets Principled BSDF, channelbag des Actions à slots, media_type = 'VIDEO', et configuration GPU Metal).

---

Étape 1 : Vérifier ou se connecter à l'application Blender ouverte

Vérifiez toujours d'abord la connexion du pont en direct :

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

Si ping échoue (par exemple, Blender n'est pas encore ouvert ou a été démarré avant l'installation du pont de démarrage), exécutez le script d'installation/connexion :

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

• Copie blender_control_bridge.py dans ~/Library/Application Support/Blender/5.2/scripts/startup/ pour que chaque lancement de l'interface graphique démarre automatiquement le pont sur 127.0.0.1:9876.
• Se connecte en toute sécurité à Blender.app ou le lance (open -g -a Blender) sans voler le focus de la fenêtre.
• Si Blender.app a déjà un fichier .blend non sauvegardé ouvert sans le pont chargé, demandez à l'utilisateur de cliquer sur Blender -> Système -> Recharger les scripts dans la barre de menus macOS.

---

Étape 2 : Inspecter et contrôler la scène en direct via blender_cli.py

Utilisez blender_cli.py pour toutes les opérations en direct :

# 1. Inspecter les objets, caméras, matériaux, plage d'images et moteur de rendu actuels
python3 .agents/skills/blender-control/scripts/blender_cli.py info

# 2. Effacer proprement la scène en direct (supprime tous les objets et blocs de données orphelins)
python3 .agents/skills/blender-control/scripts/blender_cli.py reset

# 3. Exécuter un script Python de construction de scène en direct sur le thread principal de l'interface Blender
python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py

# 4. Exécuter rapidement des expressions/extraits Python en ligne
python3 .agents/skills/blender-control/scripts/blender_cli.py exec "RESULT = [o.name for o in bpy.data.objects]"

# 5. Basculer la vue 3D en direct de Blender vers l'aperçu des matériaux ou la vue caméra rendue
python3 .agents/skills/blender-control/scripts/blender_cli.py viewport --shading MATERIAL

# 6. Sauvegarder ou ouvrir des fichiers de projet .blend dans l'interface graphique en direct
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

---

Étape 3 : Rendu d'images fixes, aperçus de la vue et animations

Aperçu rapide de la vue (moins de 0,2s)

Utilisez d'abord une capture d'écran de la vue pour vérifier le cadrage de la caméra, le placement des objets et le clipping avant de lancer un rendu complet avec lancer de rayons :

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

Inspectez /tmp/preview.png avec read_file pour vérifier visuellement la composition et l'éclairage !

Rendu d'image fixe haute qualité (Cycles GPU Metal ou EEVEE)

# Cycles avec accélération GPU Metal automatique Apple M1 Pro 16 cœurs
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine CYCLES --samples 64 --width 1920 --height 1080

# Rendu PBR temps réel rapide avec 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

Rendu d'animation 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

Mode batch headless (processus isolé)

Pour le rendu de tâches lourdes sans bloquer la vue GUI en direct :

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

---

Étape 4 : Construction de scène et liste de vérification de validation

1. Scripts de construction autonomes : stockez chaque projet dans projects/<nom_du_projet>/build.py afin que les scènes soient 100% reproductibles et compatibles Git avec les sorties rendues et les fichiers .blend.
2. Visée de la caméra (TRACK_TO ou Quaternion) : pointez toujours la caméra de manière fiable vers un objet vide cible ou une coordonnée mondiale en utilisant (target - cam.location).to_track_quat('-Z', 'Y') et définissez scene.camera = cam.
3. Éclairage trois points / studio et monde : ne laissez jamais un arrière-plan gris foncé par défaut ; configurez les nœuds de shader du monde + des lumières Area/Sun avec une puissance réaliste (100W–1500W selon l'échelle de la scène) et une gestion des couleurs AgX ou Filmic (scene.view_settings.view_transform = 'AgX', look = 'AgX - Medium High Contrast').
4. Vérification visuelle : inspectez toujours les sorties rendues .png ou .mp4 avec read_file pour confirmer le cadrage, l'exposition, les matériaux et le mouvement avant de terminer.
5. Synchronisation GitHub : après avoir créé ou mis à jour des projets/compétences, exécutez ./scripts/sync_github.sh "<message de commit>" pour maintenir la synchronisation entre le répertoire local et origin/main.