Automating Renders with V-Ray App SDK: Loading Scenes and Saving Output

V-Ray Application SDK (App SDK) lets third-party applications start and control the V-Ray engine. Chaos’s App SDK documentation covers converting a scene in memory into V-Ray plugins or loading it from a .vrscene file, starting a render and retrieving the result as an image. This guide walks through the SDK’s basic workflow for teams developing render integrations for architecture and visualization tools. The documentation does not specify a particular V-Ray or App SDK version, so these steps apply to the documented App SDK interface.

1. Prepare the SDK runtime environment

The core component of App SDK is the VRayRenderer class. It brings together tasks such as loading a scene, starting a render and accessing the image. Before you begin, the application must be able to locate the library files.

1. Set the VRAY_SDK environment variable to specify the SDK location. If you’re using the Python binding, the SDK’s python folder must be included in Python’s module search paths; the documentation gives PYTHONPATH as an example.

2. The documentation shows the setenv.bat script for Windows and the source setenv.sh command for Linux and macOS. These scripts set both environment variables.

3. When VRAY_SDK is defined, the binding looks for the VRaySDKLibrary binary and its dependencies in VRAY_SDK/bin. If the product’s folder structure does not include /bin, you can use the VRAY_APPSDK_BIN variable instead; in that case, binaries are searched for in the specified folder.

4. If environment variables are not available in your setup, you can set the library search path at runtime. The documentation gives vray.setSDKLibraryPath(bin_folder) for Python and the VRayInit constructor for C++ as examples.

This preparation is particularly important for integrations embedded in another piece of software or running independently: before rendering starts, the SDK binding must be able to find the V-Ray libraries and required dependencies. Consult the documentation for the relevant language binding for details on its initialization method.

2. Load a scene and render

The basic workflow consists of creating a VRayRenderer, preparing a scene or loading one from a file, starting the render, retrieving the image and releasing resources. A scene can be built in memory by setting V-Ray plugin parameters, or loaded from a .vrscene file. The example below shows how to load a file and save a PNG using Python:

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

start() runs asynchronously: the V-Ray engine continues rendering on a separate thread, so the main application flow is not entirely tied up by the render. getImage() can retrieve the current image data not only after processing is complete, but also while the render is in progress. This lets the application display an intermediate image or save it to a file using one of the supported compression formats. The documentation uses waitForRenderEnd() to wait for the render to finish; the unit of the parameter in the examples is not explained in the source, so no time unit should be assumed here.

When the application is done, the renderer should be closed and its allocated memory resources released. The Python context manager example handles the renderer’s lifecycle; for other language bindings, use the corresponding close operation in the relevant API.

3. Choose a mode for previews or final renders

App SDK offers two primary render modes. Interactive is designed for quickly previewing an image and seeing progress while testing content or scene settings. Production is for producing the intended final image after the scene has been carefully configured; it can take longer for the full image to be ready.

The documentation describes Interactive (CPU) as the default for the VRayRenderer class. For GPU rendering, CUDA and OptiX are listed for NVIDIA, while Metal and MetalRT are listed for Apple. This does not mean every render type is available on every computer: check whether the workstation and SDK installation support the selected option.

You can set the mode through the renderMode property of the VRayRenderer object. According to the documentation, you do not need to recreate or reload the scene to change modes between renders. This makes it possible to work in Interactive during design and switch to Production for the final stage within the same integration workflow.

4. Integrate status and error monitoring

The SDK emits events while rendering runs in the background. A status-change event can notify the application of transitions such as a render starting, finishing or stopping because of an error. The final image is ready when the status is IDLE_DONE; intermediate images can also be retrieved while processing continues.

The log-message event provides text and a severity level. The documentation lists the levels as info, warning, error and debug. The application can forward these messages to its own diagnostics workflow to make issues during scene loading and rendering visible.

Event callbacks run on a separate thread from the render thread. This design aims to prevent a slow callback from affecting render time, but slow user callbacks can delay other callbacks. Also, after the asynchronous start(), do not make changes to the scene or renderer until the renderer leaves the PREPARING state; the documentation notes that changes made during this period will be rejected.

What changes in architecture and archviz workflows?

App SDK is useful not so much for a specific menu setting in a modeling interface as for connecting V-Ray to another application’s workflow. For example, a team could bring together loading a .vrscene, starting a render, retrieving a progress image and saving the result in its own scene-preparation tool. The benefit is being able to control the render engine from within the application and run both previews and final renders through the same renderer.

Offices should first verify the language binding they use, the location of the V-Ray libraries and the CPU/GPU option available on the target machine. The sources do not explain licensing terms, pricing, compatibility with a specific host application or hardware requirements; no assumptions should be made about these. Monitoring scene status and logs helps build a more robust integration than simply offering users a render button.

Common mistakes

• Starting the SDK binding without setting VRAY_SDK or, when using Python, the module path. If a library or Python module cannot be found, first check the environment variables and folder paths.

• Treating the start() call as a synchronous operation and assuming the render finishes immediately. It runs in the background, so the application needs to monitor the completion status.

• Changing the scene or renderer during the PREPARING stage. Use the status-change event to defer edits until a safe stage.

• Running long operations inside a callback. The documentation notes that this can delay other callbacks; handle heavy work separately from the event handler.