Guide de l’API Python de Blender : automatiser objets et opérateurs de scène

Ce que vous allez apprendre dans ce guide

L’API Python de Blender permet de définir par le code certaines opérations effectuées dans une scène, puis de les reproduire. Dans ce guide, vous verrez comment créer un bloc de données de lumière et l’objet qui l’utilise, puis comment lier cet objet à la collection active et le positionner. Nous aborderons également l’appel d’opérateurs via bpy.ops, l’utilisation de poll() avant l’appel et l’évaluation de l’état renvoyé par l’opérateur.

Les exemples s’appuient sur les explications de la documentation officielle de Blender. L’objectif n’est pas de fournir un système d’automatisation architecturale prêt à l’emploi, mais de présenter clairement les éléments fondamentaux des scripts qui interviennent sur une scène. Avant d’utiliser ces extraits de code dans vos propres fichiers, examinez ce qu’ils modifient et testez-les dans une petite scène.

Prérequis et remarque sur la version

Ces exemples nécessitent l’utilisation de l’API Python de Blender. La documentation ne précisant pas de numéro de version Blender particulier, nous ne pouvons pas non plus indiquer ici de version exacte pour la compatibilité. Lorsque vous exécutez le code, consultez la documentation de l’API correspondant à votre installation de Blender. Les sources ne précisent aucune exigence liée à un compte, à des frais ou à un matériel particulier.

Le code utilise le module bpy. Les noms d’API et les paramètres figurant dans les exemples sont conformes aux usages de la documentation officielle de Blender. Les opérateurs peuvent notamment dépendre non seulement de leurs paramètres, mais aussi du contexte dans lequel ils sont exécutés. Avant d’appeler un opérateur, vérifiez donc l’objet actif dans la scène et les conditions pertinentes pour l’opération.

Étape par étape : ajouter un objet lumière à la scène

L’exemple ci-dessous présente la procédure de création d’une lumière décrite dans la documentation officielle de Blender. Le bloc de données de la lumière et l’objet présent dans la scène sont créés séparément ; l’objet est ensuite ajouté à la collection du calque de vue actif.

import bpy
view_layer = bpy.context.view_layer
# Create new light data-block.
light_data = bpy.data.lights.new(name="New Light", type='POINT')
# Create new object with our light data-block.
light_object = bpy.data.objects.new(name="New Light", object_data=light_data)
# Link light object to the active collection of current view layer,
# so it'll appear in the current scene.
view_layer.active_layer_collection.collection.objects.link(light_object)
# Place light to a specified location.
light_object.location = (5.0, 5.0, 5.0)
# And finally select it and make it active.
light_object.select_set(True)
view_layer.objects.active = light_object

La première partie récupère le calque de vue actif via bpy.context.view_layer. Les lignes suivantes créent un bloc de données de lumière de type POINT, puis un objet qui utilise ces données. Après avoir lié l’objet à la collection active, on lui attribue une position ; enfin, on le sélectionne et on en fait l’objet actif. Les coordonnées présentées ici proviennent de l’exemple de la documentation et ne constituent pas une recommandation de placement pour un intérieur ou une scène architecturale en particulier.

Il est utile de distinguer la création du bloc de données de l’ajout de l’objet à la scène. Dans cet exemple, lier l’objet à une collection est l’étape qui lui permet d’apparaître dans la scène actuelle. À la fin du code, la sélection de l’objet et sa désignation comme objet actif déterminent avec quel objet les opérations suivantes seront associées.

Appeler un opérateur et vérifier qu’il peut être exécuté

Selon la documentation de Blender, bpy.ops sert à appeler des opérateurs écrits en C++, en Python ou sous forme de macro. Leurs propriétés sont transmises sous forme d’arguments nommés. Par exemple, l’appel ci-dessous transmet deux propriétés à l’opérateur mesh.subdivide :

import bpy
bpy.ops.mesh.subdivide(number_cuts=3, smoothness=0.5)

Cela ne signifie pas que l’appel fonctionnera dans les mêmes conditions pour toutes les scènes. Si un opérateur est appelé dans un contexte inadapté, une RuntimeError peut se produire. Parmi les méthodes préconisées dans la documentation figure l’utilisation de poll() avant l’exécution, afin de vérifier les conditions présentes. Voici un exemple de changement de mode :

import bpy
if bpy.ops.object.mode_set.poll():
    bpy.ops.object.mode_set(mode='EDIT')

Si poll() renvoie un résultat positif, l’opérateur de changement de mode est appelé. Ce contrôle aide à déterminer si l’opérateur peut être exécuté dans le contexte actuel ; il ne faut pas en conclure qu’il élimine tout risque d’erreur. La documentation précise également qu’une RuntimeError peut survenir après l’exécution d’un opérateur si des rapports d’erreur sont présents.

Il faut aussi tenir compte de la valeur renvoyée par les opérateurs. Au lieu d’une valeur de résultat unique, ils renvoient un ensemble d’états. La documentation cite FINISHED et CANCELLED parmi les états courants. CANCELLED peut indiquer que l’opération a été annulée et qu’aucune modification n’a été effectuée. Dans un script, il est donc préférable d’évaluer également l’état renvoyé plutôt que de se fier uniquement au fait que la ligne de l’opérateur a été exécutée.

Modifier le contexte et conséquences pour les flux de travail architecturaux

La documentation décrit l’utilisation de temp_override pour modifier le contexte pris en compte par un opérateur. Cette méthode permet de faire travailler l’opérateur sur des données précises plutôt que sur les données sélectionnées ou actives. Parmi les membres du contexte, on peut trouver, par exemple, l’objet actif ou les objets sélectionnés. La source indique qu’il est préférable de partir d’une copie du contexte actuel ; autrement, il faudrait récupérer séparément les informations nécessaires à l’opérateur.

L’essentiel est de ne pas définir un contexte temporaire en ne modifiant qu’une seule variable, au risque d’oublier d’autres exigences. Lorsque vous utilisez temp_override, examinez ensemble les membres du contexte dont l’opérateur pourrait avoir besoin. Partir du contexte actuel constitue un point de départ plus maîtrisé que d’essayer de rassembler toutes les données nécessaires depuis zéro.

Pour les architectes, les architectes d’intérieur et les artistes en visualisation, ces notions fondamentales de l’API montrent comment décrire par le code des opérations répétitives sur une scène. Examiner séparément les étapes de création d’un objet, de liaison à une collection et de positionnement peut faciliter le suivi des modifications apportées par un script. Toutefois, les sources n’affirment pas que ces exemples automatisent un flux de travail architectural particulier ou améliorent les performances.

Lors de l’utilisation de scripts au bureau ou dans un cadre de formation, vérifiez la collection cible et l’objet actif ; effectuez d’abord les essais qui modifient les données de la scène dans une copie du fichier. Si l’équipe utilise différentes versions de Blender, validez le code séparément sur chaque installation concernée. Comme la documentation ne fournit pas de conditions précises concernant le matériel, les frais ou la compatibilité des versions, mieux vaut tester sur l’installation disponible plutôt que de faire des suppositions.

Erreurs fréquentes et prochaines étapes

La première erreur consiste à supposer que les appels bpy.ops fonctionnent indépendamment du contexte. Avant d’utiliser un opérateur, vérifiez quelles données sont actives et, lorsque c’est pertinent, utilisez poll() pour vérifier s’il peut être appelé. La deuxième erreur est de croire que l’appel réussira dans tous les cas. Examinez les états renvoyés, comme FINISHED et CANCELLED, et tenez compte du fait que des rapports d’erreur peuvent provoquer une RuntimeError.

Lors de la création d’un objet, suivez les étapes de préparation du bloc de données, de création de l’objet, de liaison à la collection, d’attribution de sa position et d’activation. Si le résultat attendu n’apparaît pas, cette méthode permet d’identifier plus facilement l’étape à l’origine du problème. Lorsque vous passez à un nouvel opérateur, consultez sa documentation officielle pour examiner ses paramètres et les explications relatives au contexte, puis vérifiez le résultat dans une petite scène de test.

Pour aller plus loin, vous pouvez étudier les exemples de temp_override et tester la transmission des membres du contexte. Avant d’utiliser cette méthode, déterminez les informations contextuelles dont l’opérateur a besoin. Exécuter les scripts qui apportent des modifications importantes à une scène dans une copie du fichier avant de les essayer sur un vrai projet permet de contrôler les résultats plus sereinement.

Sources et licence

Ce guide est une adaptation en turc des explications et exemples de la documentation de l’API bpy.ops et bpy.types.Object de Blender. Les deux sources sont sous licence CC BY-SA 4.0.