Guide Blender Python API : organiser les collections et lancer un rendu

Ce que vous apprendrez dans ce guide

À mesure que les scènes Blender s’étoffent, il devient plus difficile de garder en ordre les modèles architecturaux, le mobilier, l’éclairage et les éléments d’environnement, ainsi que de suivre les éléments visibles ou inclus dans le rendu. La structure Collection de Blender Python API aide à organiser les objets sous forme de groupes et de sous-collections hiérarchisés. Dans ce guide, nous expliquons pas à pas comment créer une collection et la rattacher à une scène, régler sa visibilité, découvrir les options Line Art et utiliser les opérateurs de rendu.

Les exemples s’appuient sur les propriétés et les opérations répertoriées dans la documentation actuelle de l’API Blender. Comme la documentation ne précise pas de numéro de version de Blender, il est conseillé de tester les exemples dans l’environnement utilisé avant de les appliquer. Adaptez les noms de collections et l’organisation de la scène à votre projet.

Prérequis

• Blender et l’accès à Python API sont nécessaires. Les sources sont la documentation actuelle de l’API Blender, qui ne précise aucun numéro de version.

• Les sources ne mentionnent aucune condition de compte ou d’abonnement. La documentation ne fournit pas non plus d’informations sur la configuration matérielle requise pour utiliser Blender ni sur la durée du rendu.

• Les exemples agissent sur les collections et les objets présents dans la scène. Avant de les appliquer, il est préférable de conserver une copie des fichiers de projet importants et de tester le code dans une petite scène dédiée.

Étape par étape : organiser une scène avec des collections

1. Créez une collection et rattachez-la à la scène

Le code ci-dessous crée une collection et la rattache à la collection principale de la scène active. La documentation de l’API Blender répertorie la création de collections et le rattachement de collections enfants. Le nom « Mobilya » de l’exemple peut servir à regrouper le mobilier d’un projet d’intérieur.

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

La création d’une collection ne signifie pas que les objets de la scène y sont automatiquement déplacés. Il faut gérer séparément leur appartenance. La propriété objects d’une collection désigne les objets qui lui appartiennent directement, tandis que all_objects inclut également ceux des sous-collections. Cette distinction aide à évaluer correctement le contenu total d’une scène organisée en collection principale et en sous-groupes.

2. Créez une hiérarchie avec des sous-collections

Dans un fichier de visualisation architecturale, vous pouvez créer des groupes tels que le mobilier et l’éclairage sous une collection principale « İç Mekân ». La documentation de Blender Python API définit children comme la liste des sous-collections directes et children_recursive comme celle de toutes les sous-collections. Lorsque vous examinez la hiérarchie, déterminez le niveau dont vous avez besoin.

La propriété all_objects inclut les objets de la collection et de ses sous-collections et est en lecture seule. Pour modifier le contenu, utilisez donc les opérations portant sur les objets de la collection et ses sous-collections, et non cette propriété. La documentation précise également que la création de la liste children_recursive prend un temps proportionnel au nombre de sous-collections ; gardez ce point à l’esprit lorsque vous l’utilisez dans une hiérarchie profonde.

3. Gérez séparément la visibilité dans la vue 3D et dans le rendu

hide_viewport désactive une collection dans la vue 3D, tandis que hide_render la désactive dans le rendu. Ces deux paramètres ne sont pas interchangeables. Par exemple, pour masquer un groupe dans la vue de travail tout en le laissant visible au rendu, définissez des valeurs distinctes comme ci-dessous :

collection.hide_viewport = True
collection.hide_render = False

Dans cet exemple, la collection est masquée dans la vue 3D, mais reste active pour le rendu. Modifiez les valeurs selon vos besoins. Ne vous contentez pas de vérifier le résultat à un seul endroit : examinez séparément la vue 3D et le rendu.

4. Choisissez le comportement de Line Art au niveau de la collection

La documentation de Blender propose des options qui déterminent la manière dont les collections sont prises en compte dans le calcul Line Art. Les modes disponibles sont INCLUDE, OCCLUSION_ONLY, EXCLUDE, INTERSECTION_ONLY, NO_INTERSECTION et FORCE_INTERSECTION. Ils correspondent à différents comportements : générer des traits à partir de la collection, ne créer que de l’occlusion, l’exclure du calcul ou gérer les lignes d’intersection.

Dans l’exemple suivant, le mode qui ne produit que de l’occlusion est sélectionné pour la collection :

collection.lineart_usage = 'OCCLUSION_ONLY'

Si vous avez besoin de contrôles supplémentaires sur les intersections, la documentation répertorie également les propriétés lineart_use_intersection_mask et use_lineart_intersection_priority. La priorité des intersections se définit avec lineart_intersection_priority ; la documentation de l’API indique une plage de 0 à 255 pour cette valeur. Utilisez ces options lorsque le calcul Line Art est activé dans la scène et que le comportement souhaité est clairement défini.

Capturer la vue active et lancer un rendu

L’opérateur bpy.ops.render.opengl est documenté pour capturer l’image de la vue active. L’option write_still enregistre l’image dans le chemin de sortie lorsque l’animation est désactivée :

bpy.ops.render.opengl(write_still=True)

Cette opération n’est pas équivalente au rendu général de la scène. L’opérateur répertorié dans l’API sous le nom bpy.ops.render.render peut être utilisé pour lancer le rendu de la scène. L’exemple ci-dessous active l’enregistrement d’une image fixe :

bpy.ops.render.render(write_still=True)

Parmi les paramètres documentés de l’opérateur de rendu figurent l’animation, l’utilisation de la vue 3D, le choix de la scène, ainsi que les images de début et de fin pour l’animation. Les options de plage d’images s’appliquent au rendu d’animation. La page de l’API décrit ces opérations et paramètres, mais ne précise pas tous les réglages de sortie nécessaires à chaque projet ; vérifiez les paramètres de votre scène avant le rendu.

Erreurs fréquentes

• Confondre les réglages de la vue 3D et du rendu : hide_viewport et hide_render sont deux propriétés distinctes. Vérifiez la visibilité souhaitée dans les deux contextes.

• Oublier les sous-collections : objects ne répertorie que les membres directs ; pour inclure les sous-collections, tenez compte de la portée de la propriété all_objects.

• Choisir un mode Line Art au hasard : les options définissent différents comportements de tracé et d’intersection. Choisissez le mode en fonction du résultat recherché et vérifiez-le dans une petite scène de test.

• Prendre une capture de la vue 3D pour un rendu de scène : bpy.ops.render.opengl capture la vue active ; un opérateur distinct sert au rendu général.

• Supposer des comportements absents de la documentation de l’API : les sources ne précisent pas les réglages propres à un projet, la vitesse de rendu ni les besoins matériels. Testez ces aspects dans votre scène et votre environnement de travail.

Conséquences pour les workflows d’architecture et de visualisation

Les cabinets d’architecture et les équipes de visualisation peuvent regrouper modèles, mobilier, éclairage et éléments d’environnement dans des collections afin de rendre la hiérarchie de la scène plus lisible. Gérer séparément la visibilité dans la vue 3D et dans le rendu permet de masquer les éléments inutiles pendant le travail tout en conservant un contenu différent dans l’image finale. Pour les présentations axées sur le dessin qui utilisent Line Art, les modes définis au niveau des collections peuvent aider à contrôler la participation des groupes au calcul des traits.

Cette documentation de l’API ne garantit ni la compatibilité avec un module complémentaire particulier, ni un niveau de performances, ni la compatibilité avec une version spécifique de Blender. Avant de mettre en place une automatisation sur des fichiers partagés au bureau, testez le code dans l’environnement Blender utilisé et sur un petit fichier de test. Tenez également compte de la licence CC BY-SA 4.0 des documents sources, qui s’applique à leur contenu.

Étapes suivantes

Commencez par créer une hiérarchie de collections dans une petite scène de test, puis modifiez séparément les réglages de la vue 3D et du rendu pour comparer les résultats. Si vous utilisez Line Art, choisissez ensuite le mode approprié et vérifiez les traits obtenus. Avant de passer aux opérateurs de rendu, vérifiez les paramètres de sortie de la scène. La documentation de l’API répertorie également des opérations de création et de nettoyage du cache de textures Cycles ; il s’agit d’opérateurs distincts de l’organisation des collections et du workflow de rendu de base.

Sources et licence

Ce guide est adapté en turc à partir de la documentation Blender Python API sur Collection et les opérateurs de rendu. Les deux sources sont proposées sous licence CC BY-SA 4.0.