Écrire une extension Python pour Blender : premier opérateur et installation

Ce que vous allez apprendre dans ce guide

Ce guide vous présente les étapes pour transformer un simple script Python en opérateur dans Blender, puis en extension installable. L’outil d’exemple ajoute 1,0 à la coordonnée X de chaque objet de la scène active. L’objectif n’est pas d’utiliser cette opération dans tous les projets architecturaux, mais de présenter les éléments fondamentaux du développement d’outils dans Blender, la manière d’enregistrer le code et de l’appeler depuis l’interface utilisateur.

Nous aborderons également quelques options permettant de lancer un rendu en arrière-plan depuis la ligne de commande. Le développement d’extensions et le rendu sont des flux de travail distincts ; ils ont en commun de transformer des tâches répétitives en étapes précises et faciles à suivre. Avant d’utiliser les opérations présentées dans un fichier de projet important, mieux vaut les tester sur une copie.

Prérequis

Il faut connaître les fonctions de base de Blender et savoir exécuter un script dans l’espace de travail Text Editor. Le guide des extensions de Blender recommande également de maîtriser les types de données, les modules et les classes de base de Python. Pour examiner plus facilement les messages d’erreur, le guide officiel conseille aussi de lancer Blender depuis un terminal.

Dans le dictionnaire bl_info de l’exemple d’extension ci-dessous, la valeur (2, 80, 0) indique la version minimale de Blender requise pour exécuter l’extension. Cela ne signifie pas que l’extension est automatiquement compatible avec les versions ultérieures : il faut tester le code dans la version prévue. La documentation de la ligne de commande figure, quant à elle, dans le manuel Blender 5.2 LTS.

Créer sa première extension étape par étape

1. Dans Blender, ouvrez un nouveau texte dans l’espace de travail Text Editor et ajoutez le code ci-dessous. Il définit un opérateur nommé ObjectMoveX. Lorsqu’il est exécuté, cet opérateur parcourt les objets de la scène active et augmente de 1,0 la coordonnée X de chacun d’eux. L’option UNDO active la possibilité d’annuler l’opération.

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

import bpy

class ObjectMoveX(bpy.types.Operator):
    """Move every scene object along the X axis."""
    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()

bl_info fournit à Blender des informations comme le nom et la catégorie de l’extension ; le champ de version de l’exemple indique également la version minimale requise. execute() contient l’opération effectuée à l’exécution de l’opérateur. Ici, le contexte de la scène est récupéré par le paramètre context transmis à la fonction. Le guide officiel recommande d’utiliser ce paramètre dans les opérateurs chaque fois que possible.

1. Cliquez sur le bouton Run Script dans Text Editor pour exécuter le code. À ce stade, l’opérateur est enregistré, mais les objets ne sont pas encore déplacés. Ouvrez le menu Operator Search, recherchez Move X by One, puis appuyez sur Entrée. Dans l’exemple du guide, ce nom affiché est défini dans le champ bl_label.

2. Pour installer le script comme extension, enregistrez-le dans un fichier doté de l’extension .py et dont le nom respecte les règles de nommage des modules Python. Dans Blender, ouvrez Preferences > Add-ons > Install… et sélectionnez le fichier. Une fois l’extension affichée dans la liste, activez-la. Pour qu’elle reste activée après le redémarrage, utilisez l’option Save as Default indiquée dans le guide.

Lorsque l’extension est activée, Blender appelle la fonction register() ; lorsqu’elle est désactivée, il appelle unregister(). Dans le code, ces fonctions servent respectivement à enregistrer et à désenregistrer la classe de l’opérateur. Pendant le développement, exécuter directement le script permet de faire rapidement un essai ; installer l’extension permet à Blender de la gérer dans la liste des extensions des préférences.

Utilisation dans un flux de travail architectural et de visualisation

L’opérateur de l’exemple agit sur tous les objets de la scène active. Dans une scène architecturale, il est donc important de savoir quels objets seront déplacés avant de l’exécuter. Si un bureau décide de développer un outil de ce type, il doit en définir la portée en fonction de la structure du projet et commencer par le tester dans une scène d’essai. Cet exemple est un exercice d’initiation qui explique la logique des opérateurs, et non un outil prêt à l’emploi pour l’agencement architectural.

Le guide des extensions de Blender propose un deuxième exemple qui place des copies liées de l’objet actif entre le curseur 3D et l’objet. Les copies sont rattachées à la collection de la scène ; leur position est calculée en fonction de la relation entre l’objet et le curseur. Dans la première version, le nombre total de copies est fixé à 10. Cet exemple montre comment créer des outils destinés aux éléments répétitifs et comment ajouter des paramètres modifiables par l’utilisateur.

Pour lancer un rendu depuis la ligne de commande, vous pouvez exécuter Blender en arrière-plan avec l’option -b ou --background. L’exemple Cycles de la documentation officielle sélectionne une image et un périphérique précis :

blender -b file.blend -f 20 -- --cycles-device OPTIX

Cette commande effectue le rendu de l’image 20 et sélectionne le périphérique OPTIX. Le guide répertorie les options de périphérique Cycles suivantes : CPU, CUDA, OPTIX, HIP, ONEAPI et METAL. Le périphérique choisi doit être compatible avec le système utilisé.

La documentation donne également un exemple de commande distincte pour exporter les images d’une animation au format PNG :

blender -b animation.blend -o //render_ -F PNG -x 1 -a

Dans cette commande, -o définit le chemin de sortie, -F le format de fichier, -x l’ajout de l’extension et -a le rendu des images de l’animation. Un chemin commençant par // est interprété comme relatif au fichier .blend. Si le nom de fichier contient des caractères #, ils servent d’espace réservé au numéro de l’image. Les deux exemples répondent à des besoins différents ; il faut adapter les options d’image, de format de fichier, de dossier de sortie et de périphérique au type de rendu souhaité.

Cette approche peut être utile aux utilisateurs de Blender qui souhaitent automatiser des opérations répétitives dans une scène, ainsi qu’aux équipes qui prévoient de lancer le rendu sans passer par l’interface. Toutefois, les sources ne précisent aucune exigence matérielle ni aucun coût de licence. Pour les extensions, il faut vérifier la compatibilité avec la version de Blender ; pour le rendu, contrôler le périphérique choisi et définir clairement les paramètres de sortie.

Erreurs fréquentes et prochaines étapes

• Ne confondez pas l’exécution du script avec celle de l’opérateur. Dans l’exemple, la première étape enregistre l’opérateur ; il faut ensuite l’appeler séparément pour modifier la scène.

• Vérifiez la portée de l’opérateur. Dans l’exemple, la coordonnée X de tous les objets de la scène active est modifiée.

• Interprétez la valeur (2, 80, 0) de bl_info comme la version minimale requise ; ne la considérez pas comme une garantie de compatibilité avec les versions récentes de Blender.

• Pour un rendu en arrière-plan, définissez le chemin de sortie, le format, la plage d’images et le périphérique Cycles en fonction de vos besoins. Les exemples de commandes peuvent comporter des paramètres différents.

Pour aller plus loin, vous pouvez consulter les rubriques bpy.context et bpy.types.Operator de la documentation de l’API Blender. Le guide officiel des extensions aborde également les propriétés des opérateurs et la façon de rendre les valeurs fixes modifiables par l’utilisateur. À mesure que l’outil évolue, transformer des valeurs comme le nombre de copies en options réglables peut aider à répondre aux besoins de différentes scènes.

Sources et licence

Ce guide est une adaptation des documents « Add-on Tutorial » et « Command Line Arguments » du Blender Manual. Les deux sources sont publiées sous licence CC BY-SA 4.0 ; le contenu a été adapté en turc conformément aux conditions de cette licence.