V-Ray App SDK guide: Load scenes and render with Python

V-Ray App SDK provides an API for developers who want to integrate the V-Ray rendering engine into an application. The official documentation says rendering can run within the main application’s process or outside it using distributed rendering. With bindings for C++, C#, Python, and Node.js, the SDK covers loading scenes, selecting render modes, and monitoring the process. The guide below is based on the Python example in the documentation; since the source does not specify a particular SDK version, these steps are not tied to a version number.

1. Set the paths for the SDK files and Python module

The documentation identifies the VRAY_SDK environment variable as the primary way to help V-Ray App SDK locate the required libraries. When this variable is set, the SDK binding looks for the V-Ray library and its dependencies in VRAY_SDK/bin. If the product’s folder structure does not include a /bin directory, VRAY_APPSDK_BIN can point directly to the folder containing the binaries. If environment variables cannot be used, the search path can also be defined at runtime.

For the Python binding to work, the SDK’s python folder must be added to Python’s module search paths. The documentation says this can be done through PYTHONPATH. Chaos’s setenv script can set the required environment variables: use setenv.bat on Windows and source setenv.sh on Linux and MacOS. If you need to specify the library directory at runtime in Python, use vray.setSDKLibraryPath(bin_folder).

Check these two path requirements separately: Python finding the vray module is not the same as finding the V-Ray binaries. If you use VRAY_SDK, check the /bin location specified in the documentation; if the folder structure differs, consider using VRAY_APPSDK_BIN or setting the search path at runtime.

2. Load a scene and start rendering

The basic workflow starts by creating a configurable VRayRenderer object. You can load a scene from a .vrscene file, V-Ray’s native scene format, or prepare one in memory by converting the scene definition in your application into V-Ray plugins. Then, call start() to begin rendering, retrieve and save the image, and close the resources.

The following Python example shows the basic workflow from the documentation:

import vray

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

start() returns without waiting; the V-Ray engine runs the rendering process in a separate thread. In the example, waitForRenderEnd(6000) is the call that waits for rendering to finish. The value 6000 is from the documentation example; it does not represent a recommended or guaranteed render time for every scene. getImage() retrieves the image data available at that moment, and save() writes it to a PNG file in the example. The general workflow in the documentation also includes closing the renderer’s resources when processing is complete.

3. Choose a mode for previews and final output

V-Ray App SDK offers two render modes: Interactive and Production. Interactive provides quick previews and progressively improves image quality while you test scene settings. Production is suitable for creating a final image from a fully configured scene. The documentation lists Interactive (CPU) as the default mode for the VRayRenderer class.

Both modes can run on CPU or GPU. For GPU rendering, the documentation lists CUDA and OptiX for NVIDIA systems, and Metal and MetalRT for Apple systems. Choose an option based on the available hardware and runtime environment; the source does not recommend one option for every scene.

You can change the render mode through the renderMode property of the VRayRenderer object. The documentation says there is no need to reload the scene or recreate the renderer when switching between renders. This lets you check the same scene in Interactive mode first and then switch to Production.

4. Track render progress and issues

An application can monitor events such as rendering starting, finishing, or stopping due to an error by listening for renderer state changes. The final image is ready when the renderer reaches the IDLE_DONE state; you can also retrieve the image available so far while rendering is in progress.

The PREPARING state is important when using the asynchronous start() call. The documentation says not to modify the scene or renderer until this state has ended; attempts to do so will be rejected. You can also capture messages generated by V-Ray while loading and rendering a scene through the log event. This event provides the message text along with its level: information, warning, error, or debug.

Event callbacks run on a thread separate from the rendering thread. This setup is intended to keep callback processing from adding overhead to rendering, but slow callbacks can delay other callbacks. Keep event handlers short and avoid running time-consuming tasks directly inside them.

Impact on architecture and visualization workflows

App SDK is relevant to developers and technical teams looking to integrate V-Ray rendering into another piece of software or manage the rendering process through a custom application. In architecture, interior design, and archviz, the workflow for loading .vrscene files and rendering can be incorporated into a broader pipeline. However, the documentation does not say that the SDK includes a ready-made architecture software integration or user interface; using the SDK requires software development work.

Before implementation, verify that the Python module path, V-Ray library directory, and selected CPU/GPU mode are compatible with the runtime environment. The source does not include pricing, licensing terms, or cross-version compatibility information; these should be checked separately. It is also important to test that the selected render mode works with the available hardware before moving into production.

Common mistakes

• Setting only VRAY_SDK without checking the folder structure, and not considering VRAY_APPSDK_BIN or runtime search path options when needed.

• Treating the Python module path and the V-Ray binary search path as the same setting.

• Trying to change scene or renderer settings during the PREPARING state after calling start().

• Treating the example’s 6000 value as a guaranteed wait time for every render.

• Overlooking that you can capture intermediate images during rendering, while the completed image is ready in the IDLE_DONE state.