V-Ray App SDK: Szenen mit Python laden und rendern

Das V-Ray App SDK bietet Entwicklern eine API, um die V-Ray-Render-Engine in eine Anwendung zu integrieren. Laut offizieller Dokumentation kann der Renderprozess innerhalb des Prozesses der Hauptanwendung oder mithilfe von Distributed Rendering außerhalb dieses Prozesses ausgeführt werden. Das SDK umfasst Bindings für C++, C#, Python und Node.js und deckt das Laden von Szenen, die Auswahl von Render-Modi und die Überwachung des Prozessstatus ab. Der folgende Leitfaden orientiert sich am Python-Beispiel aus der Dokumentation. Da die Quelle keine bestimmte SDK-Version nennt, sind die Schritte nicht an eine Versionsnummer gebunden.

1. Pfade zu den SDK-Dateien und zum Python-Modul einrichten

Damit das V-Ray App SDK die benötigten Bibliotheken findet, wird in der Dokumentation vorrangig die Umgebungsvariable VRAY_SDK angegeben. Wenn diese Variable gesetzt ist, sucht das SDK-Binding die V-Ray-Bibliothek und ihre Abhängigkeiten in VRAY_SDK/bin. Falls die Ordnerstruktur des Produkts kein Verzeichnis /bin enthält, kann mit VRAY_APPSDK_BIN direkt der Ordner mit den Binärdateien angegeben werden. Wenn sich keine Umgebungsvariablen verwenden lassen, kann der Suchpfad auch zur Laufzeit festgelegt werden.

Damit das Python-Binding funktioniert, muss der Ordner python im SDK zu den Python-Modulsuchpfaden hinzugefügt werden. Laut Dokumentation ist dies über PYTHONPATH möglich. Das setenv-Skript von Chaos kann die erforderlichen Umgebungsvariablen setzen: Unter Windows kommt setenv.bat zum Einsatz, unter Linux und MacOS source setenv.sh. Wenn der Bibliotheksordner in Python zur Laufzeit angegeben werden muss, steht die Methode vray.setSDKLibraryPath(bin_folder) zur Verfügung.

Prüfen Sie diese beiden Pfadanforderungen getrennt: Dass Python das Modul vray findet, ist nicht dasselbe wie das Auffinden der V-Ray-Binärdateien. Bei Verwendung von VRAY_SDK sollte der in der Dokumentation angegebene Speicherort /bin überprüft werden. Weicht die Ordnerstruktur davon ab, sollten VRAY_APPSDK_BIN oder die Option zur Festlegung des Suchpfads zur Laufzeit in Betracht gezogen werden.

2. Szene laden und Rendering starten

Im grundlegenden Ablauf wird zunächst ein konfigurierbares VRayRenderer-Objekt erstellt. Die Szene kann aus einer .vrscene-Datei geladen werden, dem nativen Szenenformat von V-Ray. Alternativ lässt sich die Szenendefinition aus der Anwendung in V-Ray-Plugins umwandeln und im Speicher vorbereiten. Anschließend startet der Aufruf von start() den Renderprozess; das Bild wird abgerufen und in einer Datei gespeichert, bevor die Ressourcen geschlossen werden.

Das folgende Python-Beispiel zeigt den grundlegenden Ablauf aus der Dokumentation:

import vray

with vray.VRayRenderer() as renderer:
    renderer.load('./intro.vrscene')
    renderer.start()
    renderer.waitForRenderEnd(6000)
    image = renderer.getImage()
    image.save('intro.png')

start() kehrt zurück, ohne auf den Abschluss zu warten; die V-Ray-Engine führt den Renderprozess in einem separaten Thread aus. Im Beispiel wartet der Aufruf waitForRenderEnd(6000) auf das Ende des Renderings. Der Wert 6000 stammt aus dem Dokumentationsbeispiel und bedeutet weder eine empfohlene noch eine garantierte Renderdauer für jede Szene. getImage() ruft die zu diesem Zeitpunkt verfügbaren Bilddaten ab, während save() das Bild im Beispiel als PNG-Datei speichert. Zum allgemeinen Ablauf in der Dokumentation gehört außerdem, die Renderer-Ressourcen nach Abschluss des Prozesses zu schließen.

3. Modus für Vorschau und finales Ergebnis auswählen

Das V-Ray App SDK bietet zwei Render-Modi: Interactive und Production. Interactive ermöglicht schnelle Vorschauen und eine schrittweise Qualitätssteigerung beim Ausprobieren der Szeneneinstellungen. Production eignet sich, um das finale Bild einer vollständig konfigurierten Szene zu erzeugen. Laut Dokumentation ist Interactive (CPU) der Standardmodus der Klasse VRayRenderer.

Beide Modi können mit CPU oder GPU ausgeführt werden. Für GPU listet die Dokumentation CUDA und OptiX für NVIDIA-Systeme sowie Metal und MetalRT für Apple-Systeme auf. Die Wahl hängt von der vorhandenen Hardware und der Laufzeitumgebung ab; die Quelle empfiehlt keine einzelne Option für alle Szenen.

Der Render-Modus lässt sich über die Eigenschaft renderMode des VRayRenderer-Objekts ändern. Laut Dokumentation muss die Szene beim Wechsel zwischen verschiedenen Renderings weder neu geladen noch der Renderer neu erstellt werden. So kann dieselbe Szene zunächst im Interactive-Modus geprüft und anschließend in den Production-Modus versetzt werden.

4. Renderfortschritt und Probleme überwachen

Eine Anwendung kann Änderungen des Renderer-Status über ein Ereignis verfolgen und so beispielsweise erkennen, wann das Rendering beginnt, abgeschlossen ist oder aufgrund eines Fehlers abgebrochen wird. Das finale Bild ist im Status IDLE_DONE verfügbar; während des Renderns lässt sich auch der bis dahin erreichte Bildstand abrufen.

Beim asynchronen Aufruf von start() ist der Status PREPARING wichtig. Laut Dokumentation dürfen Szene oder Renderer nicht geändert werden, bevor dieser Status verlassen wurde; entsprechende Änderungsversuche werden abgelehnt. Auch die Meldungen, die V-Ray beim Laden der Szene und während des Renderns erzeugt, können über ein Log-Ereignis abgefangen werden. Das Ereignis übermittelt neben dem Nachrichtentext auch die jeweilige Stufe: Information, Warnung, Fehler oder Debugging.

Ereignis-Callbacks werden in einem anderen Thread als dem Render-Thread ausgeführt. Dadurch sollen Callback-Aufgaben erledigt werden, ohne den Renderprozess zusätzlich zu belasten. Langsame Callbacks können jedoch die Ausführung anderer Callbacks verzögern. Daher empfiehlt es sich, Ereignis-Handler kurz zu halten und aufwendige Aufgaben nicht direkt im Callback auszuführen.

Auswirkungen auf den Workflow in Architektur und Visualisierung

Das App SDK ist für Entwickler und technische Teams relevant, die V-Ray-Rendering in andere Software integrieren oder den Renderprozess über eine eigene Anwendung steuern möchten. In den Bereichen Architektur, Innenarchitektur und Architekturvisualisierung lässt sich der Ablauf zum Laden und Rendern von .vrscene-Dateien in einen umfassenderen Workflow einbinden. Die Dokumentation weist jedoch nicht auf eine fertige Integration in Architektur-Software oder eine Benutzeroberfläche hin; für die Nutzung des SDK ist Entwicklungsarbeit erforderlich.

Vor der Umsetzung sollte geprüft werden, ob der Python-Modulpfad, das Verzeichnis der V-Ray-Bibliotheken und der gewählte CPU-/GPU-Modus mit der Laufzeitumgebung kompatibel sind. Die Quellen enthalten keine Angaben zu Preisen, Lizenzbedingungen oder zur Kompatibilität zwischen Versionen; diese Punkte müssen gesondert geprüft werden. Wichtig ist außerdem, vor dem Einsatz in der Produktion zu testen, ob der gewünschte Render-Modus mit der vorhandenen Hardware funktioniert.

Häufige Fehler

• Nur VRAY_SDK einzurichten, ohne die Ordnerstruktur zu prüfen, und bei Bedarf VRAY_APPSDK_BIN oder Optionen für den Suchpfad zur Laufzeit nicht in Betracht zu ziehen.

• Den Python-Modulpfad mit dem Suchpfad für V-Ray-Binärdateien zu verwechseln.

• Nach start() zu versuchen, Szene oder Renderer-Einstellungen im Status PREPARING zu ändern.

• Den Wert 6000 aus dem Beispiel als feste Wartezeit für jedes Rendering zu verstehen.

• Zu übersehen, dass sich während des Renderns Zwischenbilder abrufen lassen, das fertige Bild aber erst im Status IDLE_DONE verfügbar ist.