Blender-Python-API-Leitfaden: Szenenobjekte und Operatoren automatisieren

Was lernen Sie in diesem Leitfaden?

Mit der Blender-Python-API lassen sich bestimmte Vorgänge in einer Szene per Code definieren und wiederholen. In diesem Leitfaden erfahren Sie, wie Sie einen Licht-Datenblock und das dazugehörige Objekt erstellen und das Objekt mit der Collection der aktiven View Layer verknüpfen und positionieren. Außerdem behandeln wir den Aufruf von Operatoren über bpy.ops, die Verwendung von poll() vor dem Aufruf und die Auswertung des Rückgabestatus eines Operators.

Die Beispiele beruhen auf Erläuterungen in der offiziellen Blender-API-Dokumentation. Ziel ist es nicht, ein fertiges Automatisierungssystem für Architektur bereitzustellen, sondern die grundlegenden Bausteine von Skripten verständlich zu machen, die Szenen bearbeiten. Bevor Sie die Codebeispiele in eigenen Dateien verwenden, sollten Sie prüfen, was sie verändern, und sie in einer kleinen Testszenen ausprobieren.

Voraussetzungen und Versionshinweis

Für diese Beispiele benötigen Sie die Python-API von Blender. Da in der Dokumentation keine konkrete Blender-Versionsnummer genannt wird, lässt sich auch hier keine verbindliche Nummer zur Versionskompatibilität angeben. Prüfen Sie beim Ausführen des Codes die API-Dokumentation der verwendeten Blender-Installation. Die Quellen machen keine Angaben zu Kontoanforderungen, Kosten oder besonderen Hardwarevoraussetzungen.

Der Code verwendet das Modul bpy. Die API-Namen und Parameter in den Beispielen basieren auf der Verwendung in der offiziellen Blender-Dokumentation. Operatoren können insbesondere nicht nur von ihren Parametern, sondern auch vom Kontext abhängen, in dem sie ausgeführt werden. Prüfen Sie daher vor einem Operatoraufruf das aktive Objekt in der Szene und die relevanten Ausführungsbedingungen.

Schritt für Schritt: Ein Lichtobjekt zur Szene hinzufügen

Das folgende Beispiel zeigt den Ablauf zur Lichterstellung aus der offiziellen Blender-Dokumentation. Licht-Datenblock und Szenenobjekt werden getrennt angelegt; anschließend wird das Objekt mit der Collection der aktiven View Layer verknüpft.

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

Im ersten Teil des Ablaufs wird über bpy.context.view_layer die aktive View Layer abgerufen. In den folgenden Zeilen werden ein Licht-Datenblock vom Typ POINT und ein Objekt erstellt, das diese Daten verwendet. Nachdem das Objekt mit der aktiven Collection verknüpft wurde, wird ihm eine Position zugewiesen. Zum Schluss wird es ausgewählt und zum aktiven Objekt gemacht. Die Koordinaten stammen aus dem Dokumentationsbeispiel und sind keine empfohlene Platzierung für einen bestimmten Innenraum oder eine Architekturszene.

Bei diesen Schritten ist es hilfreich, das Erstellen eines Datenblocks nicht mit dem Hinzufügen des Objekts zur Szene zu verwechseln. Im Beispiel wird das Objekt mit einer Collection verknüpft, damit es in der aktuellen Szene vorhanden ist. Am Ende wird das Objekt ausgewählt und als aktives Objekt festgelegt. So wird bestimmt, auf welches Objekt sich nachfolgende Vorgänge beziehen.

Operatoren aufrufen und ihre Ausführbarkeit prüfen

Laut der Blender-Dokumentation dient bpy.ops dazu, Operatoren aufzurufen, die in C++, Python oder als Makros implementiert sind. Operator-Eigenschaften werden als Schlüsselwortargumente, also benannte Parameter, übergeben. Der folgende Aufruf übergibt beispielsweise zwei Eigenschaften an den Operator mesh.subdivide:

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

Das bedeutet nicht, dass dieser Aufruf in jeder Szene unter denselben Bedingungen funktioniert. Wird ein Operator in einem ungeeigneten Kontext aufgerufen, kann ein RuntimeError auftreten. Eine in der Dokumentation empfohlene Methode ist, die aktuellen Bedingungen vor der Ausführung mit poll() zu prüfen. Das Beispiel zum Wechsel des Modus sieht so aus:

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

Wenn poll() positiv ausfällt, wird der Operator zum Wechseln des Modus aufgerufen. Diese Prüfung hilft dabei festzustellen, ob der Operator im aktuellen Kontext ausgeführt werden kann; sie sollte nicht als Garantie verstanden werden, dass damit alle Fehler ausgeschlossen sind. Die Dokumentation weist außerdem darauf hin, dass nach Abschluss des Operators ein RuntimeError auftreten kann, wenn Fehlermeldungen vorliegen.

Auch der Rückgabewert von Operatoren ist zu beachten. Statt eines einzelnen Werts in der erwarteten Form geben sie eine Menge von Statuswerten zurück. In der Dokumentation werden FINISHED und CANCELLED als häufige Statuswerte aufgeführt. CANCELLED kann bedeuten, dass der Vorgang abgebrochen und keine Änderung vorgenommen wurde. Verlassen Sie sich in einem Skript daher nicht allein darauf, dass die Operatorzeile ausgeführt wurde, sondern werten Sie auch den zurückgegebenen Status aus.

Kontext überschreiben und Auswirkungen auf architektonische Workflows

Um den Kontext zu ändern, den ein Operator sieht, beschreibt die Dokumentation die Verwendung von temp_override. Damit kann ein Operator mit bestimmten Daten statt mit den ausgewählten oder aktiven Daten arbeiten. Zu den Kontextelementen können beispielsweise das aktive Objekt oder ausgewählte Objekte gehören. Die Quelle empfiehlt, von einer Kopie des aktuellen Kontexts auszugehen; andernfalls müssen die vom Operator benötigten Informationen separat ermittelt werden.

Wichtig ist, einen temporären Kontext nicht dadurch einzurichten, dass nur eine einzelne Variable geändert wird und andere Voraussetzungen unbeachtet bleiben. Berücksichtigen Sie bei der Verwendung von temp_override gemeinsam alle Kontextelemente, die der Operator möglicherweise benötigt. Vom aktuellen Kontext auszugehen, ist ein kontrollierterer Start, als die nötigen Daten von Grund auf zusammenzustellen.

Für Architekten, Innenarchitekten und Visualisierungskünstler zeigen diese Grundlagen der API, wie sich wiederkehrende Szenenoperationen per Code beschreiben lassen. Wenn Sie die Schritte zum Erstellen eines Objekts, zum Verknüpfen mit einer Collection und zum Festlegen seiner Position einzeln betrachten, lässt sich leichter nachvollziehen, was ein Skript verändert. Die Quellen behaupten jedoch nicht, dass diese Beispiele einen bestimmten Architektur-Workflow automatisieren oder die Leistung steigern.

Prüfen Sie beim Einsatz von Skripten im Büro oder in der Ausbildung die Ziel-Collection und das aktive Objekt. Führen Sie Versuche, die Szenendaten verändern, zunächst in einer Dateikopie durch. Wenn im Team unterschiedliche Blender-Versionen verwendet werden, sollten Sie den Code in den jeweiligen Installationen separat überprüfen. Da die Dokumentation keine verbindlichen Angaben zu Hardware, Kosten oder Versionskompatibilität macht, sollten Sie in diesen Punkten keine Annahmen treffen, sondern den Code in der vorhandenen Installation testen.

Häufige Fehler und nächste Schritte

Ein häufiger Fehler ist die Annahme, dass bpy.ops-Aufrufe unabhängig vom Kontext funktionieren. Prüfen Sie vor der Verwendung eines Operators, welche Daten aktiv sind, und kontrollieren Sie mit poll(), ob er aufgerufen werden kann, sofern dies möglich ist. Ein weiterer Fehler ist die Annahme, dass der Aufruf immer erfolgreich ist. Prüfen Sie Rückgabewerte wie FINISHED und CANCELLED und berücksichtigen Sie, dass Fehlermeldungen einen RuntimeError auslösen können.

Gehen Sie beim Erstellen eines Objekts die Schritte zum Anlegen des Datenblocks, Erstellen des Objekts, Verknüpfen mit einer Collection, Festlegen der Position und Aktivieren des Objekts der Reihe nach durch. So lässt sich leichter feststellen, an welcher Stelle ein Problem auftritt, wenn das erwartete Ergebnis ausbleibt. Lesen Sie beim Wechsel zu einem neuen Operator in der offiziellen API-Dokumentation die Parameter und Hinweise zum Kontext nach und überprüfen Sie anschließend das Ergebnis in einer kleinen Testszenen.

Als Nächstes können Sie sich Beispiele zu temp_override ansehen und testen, wie Kontextelemente übergeben werden. Ermitteln Sie dabei, welche Kontextinformationen der Operator benötigt. Skripte, die umfangreiche Änderungen an einer Szene vornehmen, zunächst in einer Dateikopie auszuführen, ist eine kontrollierte Möglichkeit, die Ergebnisse zu überprüfen, bevor Sie sie in einer echten Projektdatei testen.

Quelle und Lizenz

Dieser Leitfaden wurde anhand der Erläuterungen und Beispiele in der Blender-Dokumentation zu den APIs bpy.ops und bpy.types.Object ins Türkische übertragen und angepasst. Beide Quellen stehen unter der Lizenz CC BY-SA 4.0.