Blender-Python-Add-on schreiben: erster Operator und Installation

Was lernen Sie in diesem Leitfaden?

In diesem Leitfaden erfahren Sie, wie Sie ein einfaches Python-Skript in Blender in einen Operator und anschließend in ein installierbares Add-on umwandeln. Das Beispiel-Tool erhöht die X-Position jedes Objekts in der aktiven Szene um 1,0. Es geht nicht darum, diesen Vorgang in jedem Architekturprojekt einzusetzen, sondern die grundlegenden Bausteine der Tool-Entwicklung in Blender zu zeigen: wie der Code gespeichert und über die Benutzeroberfläche aufgerufen wird.

Außerdem behandeln wir einige Optionen, mit denen sich Renderings über die Kommandozeile im Hintergrund starten lassen. Add-on-Entwicklung und Rendering sind getrennte Arbeitsabläufe. Gemeinsam ist ihnen, dass sie wiederkehrende Aufgaben in klar definierte, nachvollziehbare Schritte überführen. Bevor Sie die Beispiele in einer wichtigen Projektdatei verwenden, sollten Sie sie am besten in einer Kopie ausprobieren.

Voraussetzungen

Sie sollten mit den Grundlagen von Blender vertraut sein und wissen, wie man im Text Editor ein Skript ausführt. Blenders Add-on-Leitfaden setzt außerdem Grundkenntnisse über Python-Datentypen, Module und Klassen voraus. Um Fehlermeldungen besser untersuchen zu können, empfiehlt das offizielle Handbuch auch, Blender über ein Terminal zu starten.

Der Wert (2, 80, 0) im bl_info-Dictionary des folgenden Add-on-Beispiels gibt die Mindestversion von Blender an, die für die Ausführung des Add-ons erforderlich ist. Das bedeutet nicht, dass das Add-on automatisch mit neueren Versionen kompatibel ist; der Code sollte in der Version getestet werden, in der er zum Einsatz kommen soll. Die Dokumentation zu Kommandozeilenoptionen ist im Handbuch zu Blender 5.2 LTS enthalten.

Schritt für Schritt zum ersten Add-on

1. Öffnen Sie im Text Editor von Blender einen neuen Text und fügen Sie den folgenden Code ein. Der Code definiert einen Operator namens ObjectMoveX. Bei seiner Ausführung durchläuft der Operator die Objekte der aktiven Szene und erhöht die X-Position jedes Objekts um 1,0. Die Option UNDO aktiviert die Rückgängig-Funktion für den Operator.

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 stellt Blender Informationen wie den Namen und die Kategorie des Add-ons bereit. Das Versionsfeld im Beispiel gibt die Mindestanforderung an. execute() enthält die Aktion, die beim Ausführen des Operators stattfindet. Der Szenenkontext wird hier über den Parameter context abgerufen. Das offizielle Handbuch empfiehlt, diesen Parameter bei Operatoren nach Möglichkeit zu verwenden.

1. Führen Sie den Code über die Schaltfläche Run Script im Text Editor aus. In diesem Schritt wird der Operator registriert; die Objekte werden noch nicht verschoben. Öffnen Sie das Operator Search-Menü, suchen Sie nach Move X by One und drücken Sie Enter. Im Handbuchbeispiel wird dieser angezeigte Name im Feld bl_label festgelegt.

2. Um das Skript als Add-on zu installieren, speichern Sie es unter einem Dateinamen mit der Endung .py, der den Namensregeln für Python-Module entspricht. Öffnen Sie in Blender Preferences > Add-ons > Install… und wählen Sie die Datei aus. Sobald das Add-on in der Liste erscheint, aktivieren Sie es. Wenn es auch nach einem Neustart aktiviert bleiben soll, verwenden Sie die im Handbuch beschriebene Option Save as Default.

Wird das Add-on aktiviert, ruft Blender register() auf; beim Deaktivieren wird unregister() ausgeführt. In diesem Code registrieren beziehungsweise entfernen die Funktionen die Operator-Klasse. Während der Entwicklung lässt sich das Skript schnell direkt ausführen. Durch die Installation kann Blender das Add-on hingegen in der Add-on-Liste der Einstellungen verwalten.

Einsatz in Architektur- und Visualisierungs-Workflows

Der Beispieloperator wirkt sich auf alle Objekte in der aktiven Szene aus. Deshalb ist es beim direkten Einsatz in einer Architekturszene wichtig zu wissen, welche Objekte bewegt werden. Wenn ein solches Tool im Büro entwickelt wird, sollte sein Wirkungsbereich an die Projektstruktur angepasst und zunächst in einer Testszenen-Datei geprüft werden. Das Beispiel ist kein fertiges Tool für Architektur-Workflows, sondern eine Einstiegsübung zur Funktionsweise von Operatoren.

Ein zweites Beispiel im Blender-Add-on-Leitfaden platziert verknüpfte Duplikate des aktiven Objekts zwischen dem 3D-Cursor und dem Objekt. Die Duplikate werden der Szenen-Collection hinzugefügt; ihre Positionen werden anhand der Beziehung zwischen Objekt und Cursor berechnet. In der ersten Version ist die Gesamtzahl der Duplikate auf 10 festgelegt. Das Beispiel zeigt, wie sich Tools für wiederkehrende Elemente aufbauen lassen und dass sich auch vom Benutzer veränderbare Einstellungen ergänzen lassen.

Um über die Kommandozeile zu rendern, können Sie Blender mit der Option -b oder --background im Hintergrundmodus starten. Das Cycles-Beispiel in der offiziellen Dokumentation wählt ein bestimmtes Einzelbild und ein Rendergerät aus:

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

Dieser Befehl rendert Einzelbild 20 und wählt das Gerät OPTIX. Im Handbuch werden CPU, CUDA, OPTIX, HIP, ONEAPI und METAL als gültige Cycles-Geräteoptionen aufgeführt. Das gewählte Gerät muss mit dem verwendeten System kompatibel sein.

Die Dokumentation enthält außerdem ein separates Beispiel, mit dem Animationsbilder als PNG ausgegeben werden:

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

In diesem Befehl legt -o den Ausgabepfad fest, -F das Dateiformat, -x das Hinzufügen der Dateiendung und -a das Rendern der Animationsbilder. Ein Pfad mit // wird relativ zur .blend-Datei ausgewertet. Werden im Dateinamen #-Zeichen verwendet, dienen sie als Platzhalter für die Bildnummer. Die beiden Beispiele decken unterschiedliche Anforderungen ab; Optionen wie Bildnummer, Dateiformat, Ausgabepfad und Gerät sollten je nach gewünschtem Render angepasst werden.

Dieser Ansatz kann Blender-Anwendern helfen, wiederkehrende Szenenaufgaben zu automatisieren, und Teams zugutekommen, die Renderings außerhalb der Benutzeroberfläche ausführen möchten. Die Quellen nennen jedoch weder bestimmte Hardwareanforderungen noch Lizenzkosten. Bei Add-ons sollte die Kompatibilität mit der Blender-Version geprüft werden. Beim Rendering sind das ausgewählte Gerät und klar definierte Ausgabeeinstellungen zu kontrollieren.

Häufige Fehler und nächste Schritte

• Verwechseln Sie das Ausführen des Skripts nicht mit dem Ausführen des Operators. Im Beispiel registriert der erste Schritt den Operator; um die Szene zu ändern, muss der Operator anschließend separat aufgerufen werden.

• Prüfen Sie den Wirkungsbereich des Operators. Im Beispiel wird die X-Position aller Objekte in der aktiven Szene verändert.

• Lesen Sie den Wert (2, 80, 0) in bl_info als Mindestversionsanforderung und nicht als Kompatibilitätsgarantie für neuere Blender-Versionen.

• Geben Sie beim Rendern im Hintergrund Dateipfad, Ausgabeformat, Bildbereich und Cycles-Gerät passend zum Bedarf an. Die Beispielbefehle können unterschiedliche Optionen enthalten.

Als nächsten Schritt können Sie die Blender-API-Dokumentation zu bpy.context und bpy.types.Operator lesen. Der offizielle Add-on-Leitfaden behandelt auch Operator-Eigenschaften und die Umwandlung fester Werte in vom Benutzer einstellbare Optionen. Wenn ein Tool umfangreicher wird, können veränderbare Einstellungen wie die Anzahl der Duplikate dabei helfen, unterschiedliche Szenenanforderungen abzudecken.

Quellen und Lizenz

Dieser Leitfaden wurde anhand der Dokumente „Add-on Tutorial“ und „Command Line Arguments“ im Blender Manual erstellt und angepasst. Beide Quellen sind unter der Lizenz CC BY-SA 4.0 veröffentlicht; die Inhalte wurden gemäß den Lizenzbedingungen ins Türkische übertragen.