Dernières actualités
Réglages Lumen dans Unreal Engine : guide de l’éclairage intérieurIntel Nova Lake-S repéré dans un test avec 28 cœurs et 5,2 GHzCréer une vidéo d’architecture avec Veo 3.1 : du prompt à la mise en scènePréparer les UV de lightmap de Blender à Unreal Engine : guide pas à pasCADQuader passe en bêta : conversion des fichiers STEP et IGES en quad meshesPréparer une planche architecturale dans Rhino 8 : guide Layout, Detail et PDFCréer des visuels architecturaux avec Images 2.6 : du prompt aux retouches maîtriséesLe Théâtre Royal de Rabat achevé : un design inspiré des rives du BouregregTransférer une scène USD de Blender vers Unreal Engine : guide pas à pasInkling 2 Mini est disponible : une architecture bouclée pensée pour l’exécution locale
TutorielsBlenderOMAMari

Débuter avec l’API Python de Blender : premières automatisations pour les scènes architecturales

L’API Python de Blender permet d’explorer les données de scène, d’ajouter des propriétés personnalisées aux objets et de créer des outils simples. Ce guide pour débutants présente les premières étapes de l’automatisation dans les scènes de visualisation architecturale.

Bureau d’un studio de design travaillant sur un modèle d’intérieur architecturalImage IA
Image d’illustration générée par IA.Image : 3dsınıfı / FCA AI

En bref

  1. La Python Console permet de tester de courtes commandes et d’explorer l’API grâce à l’autocomplétion.
  2. bpy.data donne accès aux données des objets, des scènes et des matériaux du fichier Blender ouvert.
  3. Des propriétés personnalisées peuvent être ajoutées aux objets et enregistrées avec le fichier blend.
  4. Un opérateur peut être enregistré dans Blender et exécuté depuis le menu de recherche.

Ce que vous allez apprendre dans ce guide

L’API Python de Blender permet d’accéder, par Python, à de nombreuses données modifiables dans l’interface et de les modifier. En modélisation et en visualisation architecturales, cela peut servir à examiner les éléments d’une scène, à ajouter des informations de projet aux objets ou à transformer des tâches répétitives en outils. Dans ce guide, vous allez d’abord lire les données de scène, puis ajouter une propriété personnalisée à l’objet actif et enfin créer un opérateur simple.

Les exemples présentés ici s’appuient sur les méthodes du guide de démarrage rapide officiel de l’API Python de Blender. L’API est décrite comme globalement stable, même si certaines parties de la documentation continuent d’être développées. Il est donc recommandé de tester une fonctionnalité dans une petite scène avant de l’utiliser dans des fichiers de production.

Prérequis

  • Blender doit être installé. La documentation source ne mentionnant pas de numéro de version précis, nous n’indiquons ici aucune version compatible particulière.

  • Il n’est pas nécessaire d’installer Python séparément : les exemples s’exécutent dans la Python Console ou le Text Editor intégré à Blender.

  • Les sources ne précisent aucune exigence de compte ou de licence payante.

  • Pour explorer l’API, il est utile d’activer les options Developer Extras et Python Tooltips dans les préférences de Blender. Les infobulles des boutons peuvent aider à trouver les attributs Python et les noms des opérateurs associés.

La Python Console convient aux commandes courtes et aux essais. Pour modifier et enregistrer des scripts de plusieurs lignes, l’espace de travail Scripting et son Text Editor sont plus pratiques. Cet espace de travail est accessible depuis les onglets de la barre supérieure.

Étape par étape : accéder aux données de scène et créer un premier outil

1. Lister les objets de la scène avec Python

Ouvrez l’espace de travail Scripting et passez à la Python Console. Grâce à l’autocomplétion, la console est également pratique pour explorer les noms de données et de propriétés dans bpy. Exécutez le code suivant pour afficher les objets de la scène ouverte les uns après les autres :

python
import bpy

for ob in bpy.context.scene.objects:
    print(ob)

Cet exemple parcourt la collection d’objets de la scène courante et envoie chaque objet dans la sortie de la console. Dans un fichier architectural, cette méthode constitue un point de départ pour vérifier rapidement quels objets se trouvent dans la scène. Vous pouvez ensuite ajouter à la boucle des opérations qui examinent les noms, les données ou d’autres attributs, en vous appuyant sur les modes d’accès documentés dans la source.

2. Accéder aux données avec bpy.data

Les blocs de données du fichier Blender sont accessibles via bpy.data. La documentation présente notamment les collections d’objets, de scènes et de matériaux. Il est possible d’accéder à un élément d’une collection par son nom :

python
bpy.data.objects["Cube"]

La même collection est également accessible à l’aide d’un index numérique. Toutefois, la documentation avertit que l’index d’un élément peut changer pendant l’exécution. Pour rechercher un élément précis d’une scène, l’accès par son nom est donc plus explicite que de considérer un index comme fixe. Tenez également compte du fait que le nom dans votre fichier peut être différent : Cube est uniquement le nom de l’objet utilisé dans l’exemple de la documentation.

3. Ajouter une information personnalisée à l’objet actif

Les propriétés personnalisées de l’API Python permettent d’ajouter des informations à un objet, une scène ou une collection. L’exemple ci-dessous enregistre une valeur textuelle sur l’objet actif, s’il y en a un :

python
import bpy

obj = bpy.context.object
if obj is not None:
    obj["project_note"] = "interior study"

Ici, bpy.context.object renvoie l’objet actif en fonction du contexte. Une condition évite toute opération lorsqu’aucun objet actif n’est présent. Selon la documentation source, ces propriétés personnalisées sont enregistrées avec le fichier blend et sont conservées lors de la copie des objets. Elles peuvent donc servir à associer une note de projet ou une information simple définie par l’équipe à un objet. Choisir des noms de propriétés cohérents facilite la recherche des données dans plusieurs scripts et fichiers.

Seuls les types Python de base peuvent être affectés aux propriétés personnalisées : nombres entiers, nombres à virgule flottante, chaînes de texte, tableaux de nombres et dictionnaires répondant à certaines règles. Pour les dictionnaires imbriqués, la documentation indique une limite maximale de 1024 niveaux ; la dépasser peut entraîner des erreurs et une perte de données. L’exemple utilise ici une simple chaîne de texte et ne comporte donc pas de structure imbriquée.

4. Transformer une tâche répétitive en opérateur

Il est possible de définir un opérateur pour relancer un morceau de code depuis Blender. L’exemple suivant crée un opérateur simple qui affiche les objets de la scène et ne peut pas être exécuté en l’absence d’objet actif :

python
import bpy

def main(context):
    for ob in context.scene.objects:
        print(ob)

class SimpleOperator(bpy.types.Operator):
    """Tooltip"""
    bl_idname = "object.simple_operator"
    bl_label = "Simple Object Operator"

    @classmethod
    def poll(cls, context):
        return context.active_object is not None

    def execute(self, context):
        main(context)
        return {'FINISHED'}

def menu_func(self, context):
    self.layout.operator(
        SimpleOperator.bl_idname,
        text=SimpleOperator.bl_label
    )

def register():
    bpy.utils.register_class(SimpleOperator)
    bpy.types.VIEW3D_MT_object.append(menu_func)

def unregister():
    bpy.utils.unregister_class(SimpleOperator)
    bpy.types.VIEW3D_MT_object.remove(menu_func)

if __name__ == "__main__":
    register()

Dans l’espace de travail Scripting, sélectionnez le Text Editor, ouvrez un nouveau bloc de texte avec le bouton New, collez le code, puis cliquez sur Run Script. Dans l’exemple de la documentation source, une fois l’opérateur enregistré, il est possible de le trouver en recherchant Simple via Operator Search. La vérification poll() empêche l’exécution de l’opérateur lorsqu’il n’y a pas d’objet actif. Ce point est important lorsque le script dépend du contexte de l’utilisateur.

5. Tenir compte du contexte de la console et de l’interface

Le contenu de bpy.context varie selon l’espace depuis lequel le code est exécuté. La Python Console et le 3D Viewport ne disposent pas nécessairement des mêmes membres de contexte. De plus, les valeurs de contexte ne peuvent pas être modifiées directement : la source explique qu’affecter directement l’objet actif provoque une erreur et que le chemin bpy.context.view_layer.objects.active peut être utilisé à la place. Si un opérateur ne fonctionne pas comme prévu, vérifiez d’abord dans quel espace et dans quel mode il est exécuté.

Erreurs fréquentes

  • Utiliser l’index comme identifiant permanent : les indices d’une collection peuvent changer pendant l’exécution. L’accès par nom est plus explicite pour sélectionner un élément précis ; vérifiez que ce nom existe bien dans le fichier.

  • Supposer que chaque opérateur fonctionne partout : certains opérateurs exigent un espace, un mode ou une sélection adaptés. La condition poll() vérifie ces prérequis ; un appel dans un contexte invalide peut générer une erreur.

  • Essayer de modifier directement le contexte : bpy.context est décrit comme étant en lecture seule. Si une modification est nécessaire, utilisez l’API de données documentée ou la fonction API appropriée.

  • Stocker des données complexes dans les propriétés personnalisées : les types pris en charge sont limités ; les valeurs des dictionnaires doivent également être de types de base. Privilégiez des propriétés simples et explicites.

  • Chercher la sortie du script au mauvais endroit : dans l’exemple, la sortie de print est envoyée au terminal. Si vous ne voyez pas le résultat de l’exécution, vérifiez le terminal de Blender.

Pour aller plus loin : flux de travail en architecture et en visualisation

Ces méthodes de base peuvent servir de point de départ aux architectes, architectes d’intérieur et artistes 3D qui souhaitent vérifier l’organisation d’une scène ou associer des informations supplémentaires à des objets. Par exemple, lister les objets d’un fichier peut faciliter le contrôle du contenu des grandes scènes ; les propriétés personnalisées peuvent, quant à elles, servir à enregistrer des étiquettes simples définies par l’équipe. À elles seules, ces méthodes ne constituent ni une norme BIM particulière ni une solution automatisée de gestion de projet : leur portée dépend du script écrit et des données utilisées.

Effectuez vos premiers essais sur une copie du fichier blend. Utilisez ensuite les Python Tooltips et l’autocomplétion de la console pour examiner le chemin de données recherché ; ne l’ajoutez pas à un script de production sans vérifier le rôle de l’attribut. Adaptez ensuite l’opérateur à une tâche réellement répétitive et testez-le avec différentes sélections, différents objets actifs et différents contextes. Pour les scripts partagés au sein d’un bureau, il faut également vérifier leur compatibilité avec la version de Blender ; les sources ne fournissent pas de matrice de compatibilité précise.

Source et licence

Ce guide a été préparé en adaptant les exemples et les explications du guide de démarrage rapide de l’API Python de Blender. La documentation est sous licence CC BY-SA 4.0. L’article de blog des développeurs Blender publié en 2011 apporte un éclairage historique sur l’enrichissement de la documentation de l’API ; il ne remplace pas les recommandations actuelles d’utilisation de l’API.

Sources

2 sources
C
code.blender.orgcode.blender.org/2011/02/blenderpython-api-docs
Contexte
D(
docs.blender.org (CC BY-SA 4.0)docs.blender.org/api/current/info_quickstart.html
Résumé

Les textes sources ne sont pas republiés ; les courtes citations sont signalées, le reste est notre propre résumé et commentaire.

L’avis de 3dsınıfı
3dL’analyse de la rédaction

L’API Python de Blender peut être particulièrement utile aux bureaux d’architecture et aux équipes de visualisation en Turquie pour automatiser de petits contrôles répétitifs et organiser les informations au sein des fichiers. Comme elle fonctionne dans Blender, qui peut être utilisé gratuitement, il est pratique de pouvoir commencer à l’explorer sans coût logiciel supplémentaire.

Cependant, l’intérêt de l’automatisation dépend de l’adaptation du script à l’organisation des fichiers de l’équipe et à la version de Blender utilisée. Il est important de commencer par des tests sur une scène dupliquée, de tenir compte des parties de l’API encore en développement et de garder les propriétés personnalisées simples. Pour les étudiants également, l’API offre un moyen concret de comprendre comment les données de scène sont organisées.

Questions fréquentes

Où exécuter du code avec l’API Python de Blender ?

Vous pouvez tester de courtes commandes dans la Python Console. Les scripts peuvent être exécutés dans le Text Editor de l’espace de travail Scripting de Blender.

Comment ajouter une information personnalisée à un objet dans Blender ?

L’API permet d’ajouter des propriétés personnalisées aux objets. Elles peuvent être enregistrées avec le fichier blend et conservées lors de la copie de l’objet.

L’API Python de Blender nécessite-t-elle une version particulière ?

La documentation utilisée comme source n’indique pas de numéro de version précis. L’API est décrite comme globalement stable, tout en précisant que certaines parties continuent d’être développées.

Les commentaires et le forum sont en turc.Rejoindre la discussion
+

À lire aussi