Kurz gesagt
- Die Python Console eignet sich, um kurze Befehle auszuprobieren und die API mithilfe der Autovervollständigung zu erkunden.
- Über bpy.data greifen Sie auf Objekt-, Szenen- und Materialdaten der geöffneten Blender-Datei zu.
- Eigene Eigenschaften lassen sich Objekten hinzufügen und zusammen mit der blend-Datei speichern.
- Ein Operator kann in Blender registriert und über die Suchfunktion aufgerufen werden.
Was lernen Sie in diesem Leitfaden?
Die Blender Python API ermöglicht es, auf viele Daten zuzugreifen und sie zu bearbeiten, die sich auch über die Benutzeroberfläche ändern lassen. Für Architekturmodellierung und Visualisierung kann das bedeuten, Elemente in einer Szene zu untersuchen, Objekten Projektinformationen hinzuzufügen oder häufig wiederkehrende Aufgaben in ein Tool zu verwandeln. In diesem Leitfaden lesen Sie zunächst Szenendaten aus, fügen dann dem aktiven Objekt eine eigene Eigenschaft hinzu und erstellen schließlich einen einfachen Operator.
Die Beispiele basieren auf den Methoden aus dem offiziellen Schnellstartdokument für den Einstieg in die Blender Python API. Die API wird allgemein als stabil beschrieben, zugleich heißt es, dass einige Teile der Dokumentation noch weiterentwickelt werden. Es empfiehlt sich daher, Funktionen vor dem Einsatz in Produktionsdateien zunächst in einer kleinen Testszenen auszuprobieren.
Voraussetzungen
Blender muss installiert sein. Da das Quelldokument keine konkrete Blender-Version nennt, geben wir hier keine bestimmte Versionskompatibilität an.
Python muss nicht separat installiert werden; die Beispiele laufen in der Blender-internen Python Console oder im Text Editor.
In den Quellen werden weder ein Konto noch eine kostenpflichtige Lizenz als Voraussetzung genannt.
Es ist hilfreich, in den Blender-Einstellungen die Optionen Developer Extras und Python Tooltips zu aktivieren. Die Tooltips für Schaltflächen können dabei helfen, die zugehörigen Python-Attribute und Operator-Namen zu finden.
Für kurze Befehle und Tests können Sie die Python Console verwenden. Um mehrzeilige Skripte zu bearbeiten und zu speichern, eignen sich Blenders Scripting-Arbeitsbereich und der Text Editor besser. Sie erreichen diesen Arbeitsbereich über die Tabs in der oberen Leiste.
Schritt für Schritt: Szenendaten aufrufen und das erste Tool erstellen
1. Szenenobjekte mit Python auflisten
Öffnen Sie den Scripting-Arbeitsbereich und wechseln Sie zur Python Console. Dank der Autovervollständigung eignet sich die Console auch dazu, Daten- und Eigenschaftsnamen in bpy zu erkunden. Führen Sie diesen Code aus, um die Objekte der geöffneten Szene nacheinander auszugeben:
import bpy
for ob in bpy.context.scene.objects:
print(ob)Das Beispiel durchläuft die Objekt-Collection der aktuellen Szene und gibt jedes Objekt in der Console aus. In einer Architekturdatei ist dies ein guter Ausgangspunkt, um schnell zu prüfen, welche Objekte in der Szene vorhanden sind. Anschließend lassen sich in der Schleife weitere Schritte ergänzen, um etwa Namen, Daten oder andere Attribute mithilfe der in der Quelle dokumentierten Zugriffsmethoden zu untersuchen.
2. Daten über bpy.data aufrufen
Auf Datenblöcke in einer Blender-Datei greifen Sie über bpy.data zu. Das Dokument führt Collections für Objekte, Szenen und Materialien als Beispiele auf. Ein Element einer Collection lässt sich über seinen Namen aufrufen:
bpy.data.objects["Cube"]Der Zugriff auf dieselbe Collection über einen numerischen Index ist ebenfalls möglich. Das Dokument warnt jedoch, dass sich der Index eines Elements während der Arbeit ändern kann. Wenn Sie ein bestimmtes Szenenelement suchen, ist der Zugriff über den Namen daher verständlicher, als einen Indexwert als unveränderlich anzunehmen. Berücksichtigen Sie auch, dass der Name in Ihrer Datei abweichen kann: Cube ist lediglich der Name des Beispielobjekts im Dokument.
3. Dem aktiven Objekt eigene Informationen hinzufügen
Über die benutzerdefinierten Eigenschaften der Python API lassen sich Objekten, Szenen oder Collections eigene Werte hinzufügen. Das folgende Beispiel speichert einen Textwert am aktiven Objekt, sofern eines vorhanden ist:
import bpy
obj = bpy.context.object
if obj is not None:
obj["project_note"] = "interior study"bpy.context.object gibt hier das aktive Objekt zurück, abhängig vom jeweiligen Kontext. Die Bedingung verhindert, dass etwas ausgeführt wird, wenn kein aktives Objekt vorhanden ist. Laut Quelldokument werden solche benutzerdefinierten Eigenschaften mit der blend-Datei gespeichert und beim Kopieren eines Objekts mitübernommen. Sie eignen sich daher beispielsweise, um einem Objekt eine Projektnotiz oder eine einfache, im Team definierte Information hinzuzufügen. Einheitliche Eigenschaftsnamen erleichtern es, die Daten in mehreren Skripten und Dateien wiederzufinden.
Benutzerdefinierte Eigenschaften können nur grundlegende Python-Typen enthalten: Ganzzahlen, Fließkommazahlen, Text, Zahlen-Arrays und Dictionaries, die bestimmte Regeln erfüllen. Für verschachtelte Dictionaries nennt das Dokument eine Obergrenze von 1024 Ebenen; eine größere Verschachtelung kann zu Fehlern und Datenverlust führen. Da dieses Beispiel einen einfachen Textwert verwendet, ist keine solche Verschachtelung im Spiel.
4. Wiederkehrende Aufgaben in einen Operator umwandeln
Um einen Codeabschnitt wiederholt innerhalb von Blender auszuführen, können Sie einen Operator definieren. Das folgende Beispiel erstellt einen einfachen Operator, der Szenenobjekte ausgibt und nicht ausgeführt werden kann, wenn kein aktives Objekt vorhanden ist:
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()Wählen Sie im Scripting-Arbeitsbereich den Text Editor aus, erstellen Sie über die Schaltfläche New einen neuen Textdatenblock, fügen Sie den Code ein und klicken Sie auf Run Script. Im Beispiel des Quelldokuments können Sie nach der Registrierung des Operators über Operator Search nach Simple suchen. Die poll()-Prüfung verhindert, dass der Operator ohne aktives Objekt ausgeführt wird. Das ist wichtig, wenn das Skript vom Benutzerkontext abhängt.
5. Kontext von Console und Benutzeroberfläche beachten
Der Inhalt von bpy.context hängt davon ab, in welchem Bereich der Code ausgeführt wird. Python Console und 3D Viewport verfügen nicht unbedingt über dieselben Kontextmitglieder. Außerdem lassen sich Context-Werte nicht direkt ändern. Die Quelle erklärt, dass eine direkte Zuweisung des aktiven Objekts einen Fehler auslöst; stattdessen kann der Pfad bpy.context.view_layer.objects.active verwendet werden. Wenn ein Operator unerwartet nicht funktioniert, prüfen Sie zunächst, in welchem Bereich und Modus er ausgeführt wird.
Häufige Fehler
Den Index wie eine dauerhafte Kennung verwenden: Collection-Indizes können sich während der Ausführung ändern. Der Zugriff über den Namen ist bei der Auswahl eines bestimmten Elements verständlicher. Prüfen Sie, ob der Name in der Datei tatsächlich vorhanden ist.
Annehmen, dass jeder Operator überall funktioniert: Einige Operatoren erfordern einen bestimmten Bereich, Modus oder eine bestimmte Auswahl. Die Bedingung in
poll()prüft, ob diese Voraussetzungen erfüllt sind; ein Aufruf im falschen Kontext kann einen Fehler verursachen.Versuchen, den Context direkt zu ändern:
bpy.contextwird als schreibgeschützt beschrieben. Verwenden Sie für Änderungen die dokumentierte Daten-API oder eine geeignete API-Funktion.Komplexe Daten in benutzerdefinierte Eigenschaften packen: Die unterstützten Typen sind begrenzt; auch Dictionary-Werte müssen aus grundlegenden Typen bestehen. Bevorzugen Sie einfache und eindeutige Eigenschaften.
Die Skriptausgabe am falschen Ort suchen: Die
print-Ausgabe des Beispiels wird im Terminal ausgegeben. Wenn Sie das Ergebnis nicht sehen, prüfen Sie das Blender-Terminal.
Nächste Schritte: Workflows für Architektur und Visualisierung
Diese grundlegenden Methoden können Architektinnen und Architekten, Innenarchitektinnen und Innenarchitekten sowie Visualisierungsprofis als Ausgangspunkt dienen, wenn sie die Szenenstruktur prüfen oder Objekten zusätzliche Informationen zuordnen möchten. Beispielsweise kann eine Objektliste die Inhaltskontrolle in großen Szenen erleichtern. Benutzerdefinierte Eigenschaften wiederum eignen sich dazu, einfache, im Team vereinbarte Labels in der Datei zu speichern. Sie ersetzen für sich genommen weder einen bestimmten BIM-Standard noch eine automatisierte Projektmanagementlösung. Den Umfang bestimmen das Skript und die verwendeten Daten.
Probieren Sie die ersten Schritte in einer Kopie der blend-Datei aus. Verwenden Sie anschließend Python Tooltips und die Autovervollständigung der Console, um den gewünschten Datenpfad zu untersuchen. Übernehmen Sie ein Attribut erst dann in ein Produktionsskript, wenn Sie seine Funktion überprüft haben. Passen Sie den Operator später an eine tatsächlich wiederkehrende Aufgabe an und testen Sie ihn mit verschiedenen Auswahlen, aktiven Objekten und Kontexten. Bei Skripten, die im Büro geteilt werden, sollte außerdem die Kompatibilität mit der verwendeten Blender-Version geprüft werden; die Quellen bieten keine konkrete Kompatibilitätsmatrix.
Quelle und Lizenz
Dieser Leitfaden wurde auf Grundlage der Beispiele und Erläuterungen im Blender Python API-Schnellstartdokument erstellt. Das Dokument steht unter der Lizenz CC BY-SA 4.0. Der Entwicklerblog von Blender aus dem Jahr 2011 liefert historischen Kontext zur Erweiterung der API-Dokumentation, ersetzt jedoch nicht die aktuelle API-Dokumentation.
Quellen
2 QuellenQuelltexte werden nicht neu veröffentlicht; kurze Zitate sind gekennzeichnet, der Rest ist eigene Zusammenfassung und Einordnung.
Die Blender Python API kann für Architekturbüros und Visualisierungsteams in der Türkei besonders nützlich sein, um kleine wiederkehrende Prüfungen und die Organisation von Informationen innerhalb einer Datei zu automatisieren. Da sie in Blender läuft, das kostenlos genutzt werden kann, sind für erste Experimente keine zusätzlichen Softwarekosten erforderlich.
Der Nutzen der Automatisierung hängt jedoch davon ab, ob das Skript an die Dateistruktur des Teams und die verwendete Blender-Version angepasst wird. Wichtig ist, zunächst in einer Kopie der Szene zu testen, noch in Entwicklung befindliche Bereiche der API zu berücksichtigen und benutzerdefinierte Eigenschaften einfach zu halten. Auch für Studierende ist die API ein konkreter Weg, beim Lernen zu sehen, wie Szenendaten organisiert sind.
Häufige Fragen
Wo lässt sich Blender-Python-API-Code ausführen?
Kurze Befehle können Sie in der Python Console ausprobieren. Skripte lassen sich über den Text Editor im Scripting-Arbeitsbereich von Blender ausführen.
Wie fügt man einem Objekt in Blender eigene Informationen hinzu?
Die API unterstützt benutzerdefinierte Eigenschaften für Objekte. Sie können mit der blend-Datei gespeichert und beim Kopieren des Objekts mitübernommen werden.
Benötigt die Blender Python API eine bestimmte Version?
Das verwendete Quelldokument nennt keine konkrete Versionsnummer. Die API wird allgemein als stabil beschrieben, zugleich wird darauf hingewiesen, dass einige Teile noch weiterentwickelt werden.



