Automatización del render con V-Ray App SDK: cargar escenas y exportar resultados

V-Ray Application SDK (App SDK) permite iniciar y controlar el motor de V-Ray desde aplicaciones de terceros. La documentación de App SDK de Chaos explica cómo convertir una escena en complementos de V-Ray en memoria o cargarla desde un archivo .vrscene, iniciar el render y obtener el resultado como imagen. Esta guía aborda el flujo básico del SDK para equipos que desarrollan integraciones de render en herramientas de arquitectura y visualización. Como la documentación no especifica una versión concreta de V-Ray o App SDK, los pasos se aplican a la interfaz de App SDK documentada.

1. Prepare el entorno de ejecución del SDK

El componente principal de App SDK es la clase VRayRenderer. Esta reúne operaciones como cargar escenas, iniciar renders y acceder a imágenes. Antes de empezar, la aplicación debe poder acceder a la ubicación de los archivos de biblioteca.

1. Configure la variable de entorno VRAY_SDK para indicar la ubicación del SDK. Si va a usar el binding de Python, la carpeta python del SDK debe estar en las rutas de búsqueda de módulos de Python; la documentación muestra el uso de PYTHONPATH para este fin.

2. La documentación muestra los scripts setenv.bat para Windows y source setenv.sh para Linux y macOS. Estos scripts configuran ambas variables de entorno.

3. Cuando se define VRAY_SDK, el binding busca el binario VRaySDKLibrary y sus dependencias en VRAY_SDK/bin. Si la estructura de carpetas del producto no incluye /bin, se puede usar la variable VRAY_APPSDK_BIN; en ese caso, los binarios se buscan en la carpeta indicada.

4. Si la instalación no permite usar variables de entorno, la ruta de búsqueda de bibliotecas se puede configurar durante la ejecución. La documentación muestra vray.setSDKLibraryPath(bin_folder) para Python y el constructor VRayInit para C++.

Esta preparación es especialmente importante en una integración que se ejecuta de forma independiente o integrada en otro software: el binding del SDK debe poder encontrar las bibliotecas de V-Ray y las dependencias necesarias antes de que comience el render. También conviene consultar la documentación del binding del lenguaje utilizado para conocer los detalles del método de inicialización correspondiente.

2. Cargue la escena y renderice

El flujo de trabajo básico consiste en crear un VRayRenderer, preparar una escena o cargarla desde un archivo, iniciar el render, obtener la imagen y liberar los recursos. La escena se puede construir en memoria configurando los parámetros de los complementos de V-Ray, o cargar desde un archivo .vrscene. El ejemplo muestra cómo cargar un archivo y obtener una salida PNG con 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() se ejecuta de forma asíncrona: el motor de V-Ray continúa renderizando en un hilo independiente, sin que el flujo de la aplicación principal quede completamente bloqueado por el render. getImage() permite obtener los datos de la imagen en ese momento, no solo cuando el proceso ha terminado, sino también mientras el render está en curso. Así, la aplicación puede mostrar una imagen intermedia o guardarla en un archivo usando uno de los formatos de compresión compatibles. La documentación utiliza waitForRenderEnd() para esperar a que termine el render; no explica la unidad del parámetro que aparece en los ejemplos, por lo que no se debe presuponer una unidad de tiempo.

Cuando la aplicación termina su trabajo, se debe cerrar el renderer y liberar la memoria asignada. El ejemplo de Python con un gestor de contexto se ocupa del ciclo de vida del renderer; en los bindings de otros lenguajes, se debe utilizar el método equivalente de la API correspondiente.

3. Elija el modo para la previsualización y el render final

App SDK ofrece dos modos de render principales. Interactive está diseñado para previsualizar imágenes con rapidez y ver el progreso mientras se prueban cambios en el contenido o en los ajustes de la escena. Production se utiliza para obtener la imagen final deseada una vez configurada cuidadosamente la escena; puede tardar más en generar la imagen completa.

La documentación indica que el modo predeterminado de la clase VRayRenderer es Interactive (CPU). En cuanto a la GPU, CUDA y OptiX figuran para NVIDIA, mientras que Metal y MetalRT aparecen para Apple. Esto no significa que todos los tipos de render estén disponibles en todos los equipos: hay que comprobar si la estación de trabajo y la instalación del SDK son compatibles con la opción elegida.

El modo se puede establecer mediante la propiedad renderMode del objeto VRayRenderer. Según la documentación, no es necesario volver a crear ni cargar la escena para cambiar de modo entre renders. Esto permite trabajar con Interactive durante el diseño y pasar a Production en la etapa final dentro del mismo flujo de integración.

4. Incorpore el seguimiento del estado y los errores a la integración

Mientras el render se ejecuta en segundo plano, el SDK emite eventos. El evento de cambio de estado se puede usar para notificar a la aplicación transiciones como el inicio o la finalización del render, o su detención debido a un error. El estado que indica que la imagen final está lista es IDLE_DONE; también se pueden obtener imágenes intermedias mientras el proceso sigue en curso.

El evento de mensaje de log proporciona el texto y la información del nivel. La documentación enumera los niveles info, warning, error y debug. La aplicación puede transferir estos mensajes a su propio flujo de diagnóstico para que los problemas durante la carga de escenas y el render sean visibles.

Las funciones de callback de los eventos se ejecutan en un hilo independiente del hilo de render. Este diseño busca evitar que una callback lenta afecte al tiempo de render, pero las callbacks de usuario lentas pueden retrasar la ejecución de las demás. Además, después de una llamada asíncrona a start(), no se debe modificar la escena ni el renderer hasta que el renderer salga del estado PREPARING; la documentación señala que los cambios realizados durante ese periodo serán rechazados.

¿Qué cambia en los flujos de trabajo de arquitectura y archviz?

App SDK resulta útil para conectar V-Ray al flujo de trabajo de otra aplicación, más que para cambiar un ajuste de menú concreto en una interfaz de modelado. Por ejemplo, un equipo puede reunir en su propia herramienta de preparación de escenas los pasos de carga de archivos .vrscene, inicio del render, obtención de imágenes de progreso y guardado del resultado. La ventaja es que el motor de render se puede controlar desde la aplicación y que la previsualización y el render final pueden gestionarse a través del mismo renderer.

Los estudios deben verificar primero el binding del lenguaje que utilizan, la ubicación de las bibliotecas de V-Ray y la opción de CPU/GPU disponible en la máquina de destino. Las fuentes no explican las condiciones de licencia, el precio, la compatibilidad con un software host concreto ni los requisitos de hardware; no se deben hacer suposiciones al respecto. Supervisar el estado de la escena y los logs ayuda a crear una integración más sólida que limitarse a ofrecer al usuario un botón de render.

Errores frecuentes

• Iniciar el binding del SDK sin configurar VRAY_SDK o, si se usa Python, la ruta del módulo. Si no se encuentra la biblioteca o el módulo de Python, compruebe primero las variables de entorno y las rutas de las carpetas.

• Tratar la llamada a start() como una operación síncrona y asumir que el render termina de inmediato. La llamada se ejecuta en segundo plano; la aplicación debe supervisar cuándo finaliza.

• Modificar la escena o el renderer durante el estado PREPARING. Use el evento de cambio de estado para aplazar las modificaciones hasta que sea seguro realizarlas.

• Ejecutar operaciones prolongadas dentro de una callback. La documentación indica que esto puede retrasar otras callbacks; gestione las tareas pesadas fuera del controlador de eventos.