Comment écrire une extension Python pour Blender ? Créer son premier opérateur

Ce que vous allez apprendre dans ce guide

Dans ce guide, vous allez transformer un simple script Python fonctionnant dans Blender en opérateur, puis en extension installable. L’outil présenté déplace tous les objets de la scène active de 1 unité sur l’axe X. L’objectif n’est pas de proposer un outil prêt pour la production, mais d’expliquer pas à pas comment Blender définit, enregistre et exécute les opérateurs.

Une extension est un module Python qui contient les informations supplémentaires nécessaires pour que Blender la reconnaisse et l’affiche dans sa liste. Le dictionnaire bl_info indique notamment le nom et la catégorie de l’extension, ainsi que la version minimale de Blender requise. Un opérateur permet quant à lui d’appeler une action depuis Blender. Dans cet exemple, nous le lancerons depuis la recherche d’opérateurs.

Point important : l’exemple agit sur tous les objets de la scène active, et pas seulement sur les objets sélectionnés. Il est donc plus prudent d’effectuer les premiers tests dans une scène de test ou sur une copie du fichier, plutôt que dans un projet important.

Prérequis

Vous devez connaître les bases de Blender et savoir exécuter un script dans l’éditeur de texte. Il est également recommandé de connaître les types de données Python courants, comme les nombres, les booléens, les chaînes de caractères, les listes, les tuples, les dictionnaires et les ensembles. Le guide conseille aussi d’avoir des notions de base sur les modules et les classes Python.

Dans les métadonnées de l’extension présentée en exemple, la version de Blender est indiquée comme (2, 80, 0). Il s’agit de la version minimale mentionnée dans les métadonnées de l’exemple ; cela ne signifie pas que le code a été testé avec les versions récentes de Blender. Il faut vérifier le comportement de l’API dans la version que vous utilisez. Aucun compte utilisateur, matériel particulier ou abonnement payant n’est indiqué comme prérequis.

Lancer Blender depuis un terminal est une possibilité pour déboguer. Le guide précise également que l’activation des Extras développeur dans les préférences peut faciliter le développement d’extensions.

Étape par étape : écrire son premier opérateur

1. Ajoutez le code dans l’éditeur de texte

Dans l’exemple ci-dessous, la classe ObjectMoveX définit l’opérateur. Lorsque execute() est exécutée, les objets de la scène active sont traités un par un et la valeur de la position X de chacun est augmentée de 1.0. L’option UNDO dans bl_options permet d’utiliser l’opérateur avec la fonction d’annulation.

bl_info = {
    "name": "Move X Axis",
    "blender": (2, 80, 0),
    "category": "Object",
}

import bpy

class ObjectMoveX(bpy.types.Operator):
    """My Object Moving Script"""
    bl_idname = "object.move_x"
    bl_label = "Move X by One"
    bl_options = {'REGISTER', 'UNDO'}

    def execute(self, context):
        scene = context.scene
        for obj in scene.objects:
            obj.location.x += 1.0
        return {'FINISHED'}

def register():
    bpy.utils.register_class(ObjectMoveX)

def unregister():
    bpy.utils.unregister_class(ObjectMoveX)

if __name__ == "__main__":
    register()

Cet exemple minimal enregistre la classe de l’opérateur, mais n’ajoute aucun élément à l’interface d’un menu. unregister() supprime également la classe enregistrée. bl_idname définit l’identifiant unique de l’opérateur, tandis que bl_label indique le nom affiché dans l’interface de Blender et dans les résultats de recherche. Lorsque l’action réussit, la fonction execute() renvoie le résultat FINISHED.

2. Exécutez le script et appelez l’opérateur

Collez le code dans l’éditeur de texte de Blender et exécutez-le. Le script enregistre l’opérateur ; il ne déplace pas automatiquement les objets à ce stade. Ouvrez ensuite la recherche d’opérateurs, recherchez Move X by One et lancez l’opérateur. Celui-ci déplace tous les objets de la scène active de 1 unité sur l’axe X.

Il est important d’utiliser le paramètre context dans execute(self, context). Blender peut exécuter les opérateurs dans un contexte spécifique. C’est pourquoi le guide recommande d’utiliser la valeur context transmise à l’opérateur, plutôt que de faire directement référence au contexte global.

3. Enregistrez le fichier et chargez-le comme extension

Enregistrez le script testé dans un fichier. Choisissez un nom compatible avec un module Python et ajoutez l’extension .py. Dans les préférences de Blender, ouvrez l’option de chargement dans la section Extensions, sélectionnez le fichier et activez l’extension dans la liste. Pour qu’elle reste activée après un redémarrage, vous pouvez utiliser l’option Enregistrer par défaut mentionnée dans le guide.

L’activation de l’extension permet à Blender d’exécuter le module et d’effectuer les opérations d’enregistrement dans register(). Lorsque vous désactivez l’extension, Blender appelle cette fois la fonction unregister() ; dans cet exemple, la classe de l’opérateur est alors supprimée. Les dossiers source et cible peuvent s’afficher dans la console pendant l’installation. Le guide explique également comment afficher les chemins des extensions dans la console Python à l’aide de addon_utils.paths().

Utilisation dans un flux de travail d’architecture et de visualisation

Cet exemple présente le principe de base : transformer des tâches répétitives en opérateurs Blender, une approche utile aux artistes techniques et aux développeurs. Dans une scène architecturale, une méthode similaire peut servir de point de départ à la création d’outils dédiés aux opérations clairement définies et répétées. Toutefois, ce code n’est pas un outil prêt à l’emploi pour une scène de production ou un bureau : il modifie la position de tous les objets de la scène active.

Pour les premiers tests, utilisez une copie de la scène et vérifiez quels objets sont affectés par l’opérateur. Avant de partager l’extension avec une équipe, vérifiez également la version de Blender ciblée et la compatibilité des éléments de l’API utilisés. La source ne précise aucune exigence matérielle ; il n’est donc pas possible d’en déduire des recommandations à ce sujet. Les conditions de licence et la compatibilité des versions doivent aussi être évaluées avant la distribution.

Erreurs fréquentes

• S’attendre à ce que les objets bougent dès l’exécution du script : la première exécution enregistre l’opérateur. Pour modifier les objets, il faut sélectionner Move X by One dans la recherche d’opérateurs.

• Négliger le périmètre d’action : le code ne se limite pas aux objets sélectionnés ; il traite tous les objets de la scène active.

• Oublier le format du fichier : enregistrez le fichier de l’extension avec l’extension .py et choisissez un nom compatible avec un module Python.

• Confondre l’enregistrement du fichier et l’activation de l’extension : enregistrer le fichier ne suffit pas à activer l’extension. Il faut la charger depuis les préférences, puis l’activer dans la liste.

Pour aller plus loin

Commencez par exécuter l’exemple dans une scène de test et observez le résultat de l’opérateur. Examinez ensuite séparément le rôle de bl_info, de la classe de l’opérateur, de execute() et des fonctions d’enregistrement. Pour la suite, vous pouvez étudier comment remplacer les valeurs fixes par des propriétés d’opérateur configurables par l’utilisateur ; la suite du guide Blender aborde ce sujet, ainsi qu’un autre exemple de création de copies d’objets liés.

En cas de message d’erreur, consulter la sortie de la console Blender peut aider à déterminer à quelle étape le problème se produit. La vue d’ensemble de l’API Blender et la documentation de bpy.context et de bpy.types.Operator font également partie des ressources de référence indiquées dans le guide pour approfondir les notions utilisées.

Source et licence

Ce guide est une adaptation en turc fondée sur le document officiel « Add-on Tutorial » de Blender et son exemple d’extension et d’opérateur. La source est sous licence CC BY-SA 4.0.