Organiser les collections et les View Layers avec Blender Python

Ce que vous apprendrez dans ce guide

Les scènes d’archviz peuvent réunir l’enveloppe du bâtiment, des éléments d’intérieur, du mobilier et de nombreux autres objets. À mesure que le contenu s’étoffe, il devient important de regrouper les éléments de la scène et de gérer différentes vues de travail. L’API Python de Blender permet de lier des objets à des collections et de déterminer, à l’aide des View Layers, quelles parties de la hiérarchie des collections sont actives.

Dans ce guide, vous apprendrez à créer une collection avec Python, à la lier à la scène, à ajouter l’objet actif à cette collection et à exclure la collection du View Layer actif. Nous examinerons également les différences entre les réglages de visibilité des objets et l’organisation des collections et des View Layers. Les exemples s’appuient sur la documentation officielle de l’API Python de Blender ainsi que sur les explications de l’API de scène et d’objet publiées pour Blender 2.80.

Prérequis

Exécutez les exemples dans un environnement Blender permettant d’utiliser l’API Python de Blender. Le code accède à la scène active via bpy et, si nécessaire, à l’objet actif. Le premier exemple crée une nouvelle collection directement avec bpy.data.collections.new et la lie à la collection racine de la scène ; aucune collection active préalable n’est nécessaire. Dans l’exemple distinct qui lie l’objet actif à la nouvelle collection, cette étape est ignorée si aucun objet n’est actif.

La documentation ne précise pas de version spécifique de Blender, de compte utilisateur ni de logiciel supplémentaire requis. Vérifiez donc le comportement de l’API dans la version de Blender installée avant d’utiliser le code. La documentation destinée aux développeurs de Blender 2.80 décrit les changements d’API de la période 2.8x, tandis que les pages actuelles de l’API documentent les propriétés Scene et Object. Tenez compte de ces différences si vous travaillez avec des scripts conçus pour d’anciennes versions.

Organiser les collections étape par étape

1. Distinguez le rôle des collections de celui des View Layers

À l’époque de Blender 2.7x, les scènes pouvaient être organisées à l’aide de 20 couches fixes. Avec les changements apportés à l’API en 2.8x, l’organisation des objets a été confiée aux collections, tandis que les View Layers ont pris en charge le contrôle de la visibilité et du contexte de rendu de la hiérarchie des collections. Il faut donc éviter de confondre les anciennes propriétés de couches de scène des scripts avec le nouveau système de collections.

Les collections regroupent des objets et d’autres collections de manière hiérarchique. Les View Layers déterminent quelles parties de cette organisation sont actives. Créer une collection ne déplace pas automatiquement les objets vers celle-ci : il faut les lier séparément.

2. Ajoutez une nouvelle collection à la scène

L’exemple ci-dessous lie une nouvelle collection nommée Mimari_Govde sous la collection racine de la scène active. Le code crée la collection, puis l’ajoute à la hiérarchie de la scène :

import bpy

scene = bpy.context.scene
collection = bpy.data.collections.new("Mimari_Govde")
scene.collection.children.link(collection)

bpy.data.collections.new crée une nouvelle collection. scene.collection.children.link lie ensuite cette collection à la collection racine de la scène. Cet exemple n’utilise ni objet actif ni collection active préexistante. Si une collection portant déjà le même nom existe dans le fichier, vérifiez l’organisation de la scène avant de relancer le script.

3. Liez l’objet actif à la nouvelle collection

Après avoir créé la collection, vous pouvez utiliser l’exemple suivant pour y lier l’objet actif :

obj = bpy.context.object

if obj is not None:
    collection.objects.link(obj)

Si un objet est actif, un lien est ajouté à la collection ; sinon, le bloc conditionnel n’est pas exécuté. Cette opération ne duplique pas l’objet. Selon la documentation destinée aux développeurs de Blender, un même objet peut appartenir à plusieurs collections tout en restant un objet unique.

Dans les scènes d’architecture, cette distinction permet de structurer les groupes sans dupliquer les données des objets. Toutefois, le code de l’exemple ne retire pas l’objet de ses collections existantes : il le lie simplement aussi à la nouvelle collection. Pensez donc à vérifier séparément ses autres liens de collection dans la scène.

4. Excluez la collection du View Layer actif

Si la collection est directement sous la collection racine de la scène, vous pouvez l’exclure en accédant au LayerCollection correspondant dans le View Layer actif :

bpy.context.view_layer.layer_collection.children["Mimari_Govde"].exclude = True

Cette ligne exclut la collection Mimari_Govde du View Layer actif. Pour la réactiver, définissez exclude sur False. Le code suppose que la collection est un enfant direct de la hiérarchie du View Layer. Si elle se trouve à l’intérieur d’une autre collection, il faut y accéder par le chemin correspondant dans la hiérarchie.

Les View Layers permettent de contrôler quelles parties de l’organisation des collections sont actives. Cette opération n’équivaut pas à modifier individuellement les propriétés de visibilité de chaque objet. Pour évaluer le résultat, tenez compte des éventuels liens des objets à d’autres collections et de la structure du View Layer utilisé.

5. Gérez séparément la visibilité des objets

Si vous devez contrôler un objet précis plutôt que la visibilité d’une collection, vous pouvez utiliser les propriétés de l’objet. hide_viewport affecte la visibilité de l’objet dans le viewport, tandis que hide_render agit sur sa visibilité au rendu. Par exemple, pour masquer l’objet actif au rendu :

obj = bpy.context.object

if obj is not None:
    obj.hide_render = True

Ici, seule la visibilité au rendu est modifiée. Pour masquer l’objet dans le viewport, la propriété distincte documentée est hide_viewport. Choisissez la propriété adaptée au résultat souhaité ; ne les utilisez pas l’une à la place de l’autre.

Erreurs fréquentes

Penser que les objets sont ajoutés automatiquement à la création d’une collection : créer une collection et y lier un objet sont deux opérations distinctes. Liez séparément l’objet concerné à la collection.

Utiliser les anciennes méthodes de couches de scène avec la nouvelle API : les collections et les View Layers ont évolué avec la version 2.8x. Ne réutilisez pas des propriétés comme object.layers présentes dans d’anciens scripts sans les comparer à la structure actuelle des collections.

Confondre le lien à une collection avec la copie d’un objet : un même objet peut appartenir à plusieurs collections. Le lien à une collection ne crée ni nouvel objet ni copie de géométrie.

Chercher au mauvais niveau de la hiérarchie du View Layer : la ligne d’exclusion de l’exemple suppose que la collection est un enfant direct du layer actif. Pour les collections imbriquées, le chemin d’accès doit correspondre à la hiérarchie réelle de la scène.

Considérer que la visibilité dans le viewport et celle au rendu sont le même réglage : hide_viewport et hide_render sont des propriétés distinctes. Déterminez si le problème concerne le viewport ou l’image rendue, puis modifiez la propriété correspondante.

Effets sur les workflows d’architecture et de visualisation

Les collections peuvent servir à regrouper l’enveloppe du bâtiment, le mobilier ou d’autres éléments de la scène qui doivent être contrôlés ensemble. Les View Layers permettent, quant à eux, de gérer les parties de cette hiérarchie de collections qui sont actives. Cette structure peut aider à garder les scènes organisées et à gérer la visibilité par groupes, en particulier dans les projets complexes.

Cette approche peut être utile aux cabinets d’architecture, aux architectes d’intérieur et aux artistes archviz qui souhaitent mettre en place une organisation reproductible de leurs scènes Blender avec Python. Les sources ne promettent toutefois ni compatibilité avec un moteur de rendu particulier, ni gain de performances, ni avantage matériel. Dans vos projets, vérifiez la version de Blender, la hiérarchie réelle des collections et le workflow prévu pour le partage du fichier avec d’autres personnes.

Étapes suivantes

Commencez par exécuter l’exemple de création de collection dans une copie du fichier. Essayez ensuite l’étape de liaison avec un objet actif et vérifiez qu’un objet peut appartenir à plusieurs collections. Avant d’exécuter le code d’exclusion d’un View Layer, vérifiez la position de la collection dans le layer actif.

Examinez ensuite séparément les propriétés hide_viewport et hide_render pour déterminer quel niveau de visibilité répond à vos besoins. Si vous utilisez les scripts avec différentes versions de Blender, consultez la documentation de l’API correspondant à la version concernée et testez les changements avant de les appliquer au fichier du projet.

Sources et licence

Le document « Blender 2.80: Scene and Object API » (K2) de Blender Developer explique les changements apportés aux collections et à la structure des View Layers. La documentation de l’API Python de Blender pour Scene (K1) et Object (K4) est sous licence CC BY-SA 4.0. Ce guide adapte en turc les informations techniques de ces sources et les explique à l’aide d’exemples originaux.