Render-Automatisierung mit dem V-Ray App SDK: Szene laden und Ausgabe erstellen

Das V-Ray Application SDK (App SDK) ermöglicht Drittanbieter-Anwendungen, die V-Ray-Engine zu starten und zu steuern. Die App-SDK-Dokumentation von Chaos beschreibt, wie eine Szene im Speicher in V-Ray-Plugins umgewandelt oder aus einer .vrscene-Datei geladen, der Render gestartet und das Ergebnis als Bild ausgegeben wird. Dieser Leitfaden behandelt den grundlegenden Ablauf des SDK für Teams, die Render-Integrationen in Architektur- und Visualisierungswerkzeuge einbauen. Da die Dokumentation keine bestimmte Version von V-Ray oder dem App SDK nennt, gelten die Schritte für die dokumentierte App-SDK-Schnittstelle.

1. Die SDK-Laufzeitumgebung vorbereiten

Die zentrale Komponente des App SDK ist die Klasse VRayRenderer. Sie bündelt Aufgaben wie das Laden einer Szene, das Starten des Renders und den Zugriff auf das Bild. Bevor Sie beginnen, muss die Anwendung auf den Speicherort der Bibliotheksdateien zugreifen können.

1. Legen Sie die Umgebungsvariable VRAY_SDK so fest, dass sie auf den Speicherort des SDK verweist. Wenn Sie das Python-Binding verwenden, muss sich der Ordner python des SDK im Python-Modulsuchpfad befinden. Die Dokumentation führt hierfür PYTHONPATH als Beispiel an.

2. Für Windows zeigt die Dokumentation das Skript setenv.bat, für Linux und macOS den Befehl source setenv.sh. Diese Skripte setzen beide Umgebungsvariablen.

3. Wenn VRAY_SDK definiert ist, sucht das Binding nach der VRaySDKLibrary-Binärdatei und ihren Abhängigkeiten in VRAY_SDK/bin. Falls die Produktordnerstruktur kein /bin enthält, kann die Variable VRAY_APPSDK_BIN verwendet werden; in diesem Fall werden die Binärdateien im angegebenen Ordner gesucht.

4. Wenn Umgebungsvariablen bei der Installation nicht verfügbar sind, lässt sich der Bibliothekssuchpfad zur Laufzeit festlegen. Die Dokumentation nennt dafür vray.setSDKLibraryPath(bin_folder) für Python und den Konstruktor VRayInit für C++ als Beispiele.

Diese Vorbereitung ist besonders wichtig für Integrationen, die in eine andere Software eingebettet sind oder eigenständig laufen: Das SDK-Binding muss die V-Ray-Bibliotheken und die erforderlichen Abhängigkeiten finden, bevor der Render startet. Die Dokumentation des Bindings für die jeweilige Sprache sollte zusätzlich zu den Details der entsprechenden Initialisierungsmethode konsultiert werden.

2. Szene laden und rendern

Der grundlegende Ablauf besteht darin, VRayRenderer zu erstellen, eine Szene vorzubereiten oder aus einer Datei zu laden, den Render zu starten, das Bild abzurufen und die Ressourcen freizugeben. Die Szene lässt sich im Speicher einrichten, indem die Parameter der V-Ray-Plugins festgelegt werden, oder aus einer .vrscene-Datei laden. Das folgende Beispiel zeigt, wie Sie mit Python eine Datei laden und eine PNG-Ausgabe erstellen:

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

start() läuft asynchron: Während die V-Ray-Engine in einem separaten Thread weiter rendert, wird der Hauptablauf der Anwendung nicht vollständig durch den Render blockiert. getImage() kann die aktuellen Bilddaten nicht nur nach Abschluss des Vorgangs, sondern auch während des laufenden Renders abrufen. So kann die Anwendung ein Zwischenbild anzeigen oder es in einem der unterstützten Komprimierungsformate in einer Datei speichern. Um auf den Abschluss des Renders zu warten, verwendet die Dokumentation waitForRenderEnd(); die Einheit des Parameters in den Beispielen wird in der Quelle nicht erläutert, daher sollte hier keine Zeiteinheit angenommen werden.

Wenn die Anwendung ihre Arbeit beendet hat, sollte der Renderer geschlossen und der belegte Speicher freigegeben werden. Das Beispiel mit dem Python-Kontextmanager verwaltet den Lebenszyklus des Renderers; in anderen Sprachbindungen sollte dafür das entsprechende Pendant der jeweiligen API verwendet werden.

3. Modus für Vorschau und finalen Render wählen

Das App SDK bietet zwei grundlegende Render-Modi. Interactive ist für schnelle Vorschauen und dafür gedacht, den Fortschritt beim Testen von Inhalten oder Szeneneinstellungen zu verfolgen. Production dient dazu, nach sorgfältiger Konfiguration der Szene das gewünschte finale Bild zu erstellen; dabei kann es länger dauern, bis das gesamte Bild fertig ist.

Laut Dokumentation ist Interactive (CPU) der Standardmodus der Klasse VRayRenderer. Für GPU werden CUDA und OptiX für NVIDIA sowie Metal und MetalRT für Apple aufgeführt. Das bedeutet nicht, dass jeder Render-Typ auf jedem Computer verfügbar ist: Es sollte geprüft werden, ob Workstation und SDK-Installation den ausgewählten Pfad unterstützen.

Der Modus lässt sich über die Eigenschaft renderMode des VRayRenderer-Objekts festlegen. Laut Dokumentation muss die Szene nicht neu erstellt oder geladen werden, um zwischen Rendern den Modus zu wechseln. So kann während des Entwurfs mit Interactive gearbeitet und in der Endphase im selben Integrationsablauf zu Production gewechselt werden.

4. Status- und Fehlerverfolgung in die Integration einbauen

Während der Render im Hintergrund läuft, gibt das SDK Ereignisse aus. Das Ereignis zur Statusänderung kann die Anwendung über Übergänge informieren, etwa wenn der Render startet, abgeschlossen wird oder aufgrund eines Fehlers abbricht. Der Status für ein fertiges finales Bild ist IDLE_DONE; während des Vorgangs können auch Zwischenbilder abgerufen werden.

Das Ereignis für Logmeldungen stellt Text und eine Information zur Protokollebene bereit. Die Dokumentation führt die Stufen info, warning, error und debug auf. Die Anwendung kann diese Meldungen in ihren eigenen Diagnoseablauf übernehmen und so Probleme beim Laden der Szene und während des Renderns sichtbar machen.

Ereignis-Callbacks werden in einem anderen Thread als dem Render-Thread ausgeführt. Dieses Design soll verhindern, dass ein langsamer Callback die Renderzeit beeinflusst; langsame Nutzer-Callbacks können jedoch die Ausführung anderer Callbacks verzögern. Außerdem sollten nach dem asynchronen Aufruf start() keine Änderungen an der Szene oder am Renderer vorgenommen werden, bis der Renderer den Status PREPARING verlassen hat. Die Dokumentation weist darauf hin, dass Änderungen während dieser Phase abgelehnt werden.

Was ändert sich für Architektur- und Archviz-Workflows?

Das App SDK ist weniger für eine einzelne Menüeinstellung in einer Modellierungsoberfläche gedacht, sondern vor allem dafür, V-Ray in den Workflow einer anderen Anwendung einzubinden. Ein Team kann beispielsweise in einem eigenen Tool zur Szenenvorbereitung das Laden einer .vrscene, das Starten des Renders, den Abruf des Fortschrittsbildes und das Speichern des Ergebnisses bündeln. Der Vorteil: Die Render-Engine lässt sich aus der Anwendung heraus steuern, und Vorschau sowie finaler Render können über denselben Renderer laufen.

Büros sollten zunächst das Binding für die verwendete Sprache, den Speicherort der V-Ray-Bibliotheken sowie die CPU-/GPU-Option auf dem Zielrechner prüfen. Die Quellen erläutern weder Lizenzbedingungen und Preise noch die Kompatibilität mit bestimmter Host-Software oder Hardwareanforderungen; dazu sollten keine Annahmen getroffen werden. Die Überwachung des Szenenstatus und der Logs trägt zu einer solideren Integration bei, als den Nutzern lediglich eine Render-Schaltfläche anzubieten.

Häufige Fehler

• Das SDK-Binding starten, ohne VRAY_SDK oder – bei Verwendung von Python – den Modulpfad festzulegen. Wenn die Bibliothek oder das Python-Modul nicht gefunden wird, sollten zuerst Umgebungsvariablen und Ordnerpfade überprüft werden.

• start() wie einen synchronen Vorgang behandeln und davon ausgehen, dass der Render sofort abgeschlossen ist. Der Aufruf läuft im Hintergrund; die Anwendung muss den Abschlussstatus überwachen.

• Während der Phase PREPARING Änderungen an der Szene oder am Renderer vornehmen. Verwenden Sie das Ereignis zur Statusänderung, um Anpassungen auf einen sicheren Zeitpunkt zu verschieben.

• Im Callback lang laufende Vorgänge ausführen. Laut Dokumentation kann dies andere Callbacks verzögern; aufwendige Aufgaben sollten daher getrennt vom Ereignis-Handler verarbeitet werden.