Guía de V-Ray App SDK: cargar escenas y renderizar con Python

V-Ray App SDK ofrece una API para desarrolladores que quieren integrar el motor de renderizado de V-Ray en una aplicación. La documentación oficial indica que el renderizado puede ejecutarse dentro del proceso de la aplicación principal o fuera de este mediante renderizado distribuido. El SDK incluye bindings para C++, C#, Python y Node.js, y abarca la carga de escenas, la selección de modos de renderizado y el seguimiento del estado del proceso. La guía siguiente se basa en el ejemplo de Python de la documentación; como la fuente no especifica una versión concreta del SDK, los pasos no están ligados a un número de versión.

1. Configure las rutas de los archivos del SDK y del módulo de Python

Para que V-Ray App SDK encuentre las bibliotecas necesarias, la documentación señala como opción prioritaria la variable de entorno VRAY_SDK. Cuando se configura esta variable, el binding del SDK busca la biblioteca de V-Ray y sus dependencias en VRAY_SDK/bin. Si la estructura de carpetas del producto no incluye el directorio /bin, se puede indicar directamente la carpeta que contiene los archivos binarios mediante VRAY_APPSDK_BIN. Cuando no es posible usar variables de entorno, también se puede definir la ruta de búsqueda en tiempo de ejecución.

Para que funcione el binding de Python, hay que añadir la carpeta python del SDK a las rutas de búsqueda de módulos de Python. La documentación indica que esto puede hacerse mediante PYTHONPATH. El script setenv de Chaos puede configurar las variables de entorno necesarias: en Windows se usa setenv.bat, y en Linux y MacOS, source setenv.sh. Si es necesario especificar en tiempo de ejecución el directorio de las bibliotecas en Python, se puede usar el método vray.setSDKLibraryPath(bin_folder).

Compruebe por separado estos dos requisitos de rutas: que Python encuentre el módulo vray no es lo mismo que encontrar los archivos binarios de V-Ray. Si usa VRAY_SDK, revise la ubicación /bin indicada en la documentación; si la estructura de carpetas es distinta, considere la opción VRAY_APPSDK_BIN o la ruta de búsqueda en tiempo de ejecución.

2. Cargue la escena e inicie el renderizado

En el flujo básico, primero se crea un objeto VRayRenderer que se puede configurar. La escena se puede cargar desde un archivo .vrscene, el formato de escena nativo de V-Ray, o preparar en memoria convirtiendo la definición de la escena de la aplicación en plugins de V-Ray. A continuación, el renderizado se inicia con la llamada start(), se obtiene la imagen, se guarda en un archivo y se liberan los recursos.

El siguiente ejemplo de Python muestra el flujo básico de la documentación:

import vray

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

start() devuelve el control sin esperar a que termine: el motor de V-Ray ejecuta el renderizado en un hilo independiente. En el ejemplo, waitForRenderEnd(6000) es la llamada que espera a que termine el render. El valor 6000 aparece en el ejemplo de la documentación; no representa una duración de render recomendada ni garantizada para todas las escenas. getImage() obtiene los datos de la imagen en ese momento y save() guarda la imagen como archivo PNG en el ejemplo. El flujo general de la documentación también incluye liberar los recursos del renderer una vez finalizado el proceso.

3. Elija un modo para la vista previa o el resultado final

V-Ray App SDK ofrece dos modos de renderizado: Interactive y Production. Interactive permite hacer pruebas con los ajustes de la escena y obtener vistas previas rápidas cuya calidad mejora de forma progresiva. Production es adecuado para obtener la imagen final de una escena ya configurada. La documentación indica que el modo predeterminado de la clase VRayRenderer es Interactive (CPU).

Ambos modos pueden funcionar con CPU o GPU. Para GPU, la documentación enumera CUDA y OptiX en sistemas NVIDIA, y Metal y MetalRT en sistemas Apple. La opción adecuada depende del hardware disponible y del entorno de ejecución; la fuente no recomienda una única opción válida para todas las escenas.

El modo de renderizado se puede cambiar mediante la propiedad renderMode del objeto VRayRenderer. La documentación indica que no es necesario volver a cargar la escena ni crear de nuevo el renderer al cambiar de un tipo de renderizado a otro. Así, se puede revisar primero la misma escena en modo Interactive y luego pasarla a Production.

4. Supervise el progreso del renderizado y los problemas

La aplicación puede seguir eventos como el inicio, la finalización o la interrupción del renderizado por un error escuchando el evento de cambio de estado del renderer. La imagen final está disponible en el estado IDLE_DONE; también se puede obtener la imagen generada hasta ese momento mientras el renderizado continúa.

En la llamada asíncrona start(), el estado PREPARING es importante. La documentación advierte que no se debe modificar la escena ni el renderer antes de salir de esta fase; estos intentos serán rechazados. Los mensajes que V-Ray genera al cargar y renderizar la escena también se pueden capturar mediante el evento de log. Este evento transmite tanto el texto del mensaje como su nivel: información, advertencia, error o depuración.

Las funciones de callback de los eventos se ejecutan en un hilo distinto del hilo de renderizado. Esta disposición busca evitar que las operaciones de callback añadan carga al proceso de renderizado; sin embargo, las callbacks lentas pueden retrasar la ejecución de otras. Por eso conviene mantener breves los controladores de eventos y no ejecutar tareas pesadas directamente dentro de ellos.

Impacto en los flujos de trabajo de arquitectura y visualización

App SDK es relevante para desarrolladores y equipos técnicos que quieren integrar el renderizado de V-Ray en otro software o gestionar el proceso desde una aplicación propia. En los ámbitos de la arquitectura, el diseño de interiores y la visualización arquitectónica, el flujo de carga de archivos .vrscene y renderizado puede incorporarse a un proceso de trabajo más amplio. Sin embargo, la documentación no afirma que el SDK incluya una integración lista para usar con software de arquitectura ni una interfaz de usuario: utilizarlo requiere trabajo de desarrollo de software.

Antes de implementarlo, se debe comprobar que la ruta del módulo de Python, el directorio de las bibliotecas de V-Ray y el modo CPU/GPU elegido sean compatibles con el entorno de ejecución. Las fuentes no incluyen información sobre precios, condiciones de licencia ni compatibilidad entre versiones; estos aspectos deben verificarse por separado. También es importante probar que el modo de renderizado elegido funciona con el hardware disponible antes de pasar a producción.

Errores frecuentes

• Configurar solo VRAY_SDK sin comprobar la estructura de carpetas y no considerar, cuando sea necesario, VRAY_APPSDK_BIN o las opciones de ruta de búsqueda en tiempo de ejecución.

• Confundir la ruta del módulo de Python con la ruta de búsqueda de los archivos binarios de V-Ray.

• Intentar cambiar la escena o los ajustes del renderer durante la fase PREPARING después de llamar a start().

• Interpretar el valor 6000 del ejemplo como un tiempo de espera exacto para todos los renderizados.

• Pasar por alto que se pueden obtener imágenes intermedias durante el renderizado y que la imagen final está lista en el estado IDLE_DONE.