Руководство по V-Ray App SDK: загрузка сцены и рендеринг на Python

V-Ray App SDK предоставляет API для разработчиков, которые хотят интегрировать движок рендеринга V-Ray в приложение. В официальной документации указано, что рендеринг можно выполнять в процессе основного приложения или за его пределами, используя распределённый рендеринг. SDK с привязками для C++, C#, Python и Node.js охватывает загрузку сцены, выбор режима рендеринга и отслеживание состояния процесса. Это руководство основано на примере Python из документации; поскольку в источнике не указана конкретная версия SDK, шаги не привязаны к номеру версии.

1. Настройте пути к файлам SDK и модулю Python

Чтобы V-Ray App SDK мог найти необходимые библиотеки, в документации в первую очередь предлагается задать переменную окружения VRAY_SDK. Если эта переменная настроена, привязка SDK ищет библиотеку V-Ray и её зависимости в VRAY_SDK/bin. Если в структуре каталогов продукта нет папки /bin, каталог с исполняемыми файлами можно указать напрямую через VRAY_APPSDK_BIN. Если переменные окружения использовать нельзя, путь поиска также можно задать во время выполнения.

Чтобы привязка Python работала, папку python внутри SDK необходимо добавить в пути поиска модулей Python. Согласно документации, это можно сделать через PYTHONPATH. Скрипт setenv от Chaos может настроить необходимые переменные окружения: в Windows используется setenv.bat, а в Linux и MacOS — source setenv.sh. Если в Python нужно указать каталог библиотек во время выполнения, доступен метод vray.setSDKLibraryPath(bin_folder).

Проверяйте эти два требования к путям по отдельности: поиск модуля vray в Python — не то же самое, что поиск исполняемых файлов V-Ray. При использовании VRAY_SDK проверьте расположение /bin, указанное в документации; если структура каталогов отличается, рассмотрите VRAY_APPSDK_BIN или настройку пути поиска во время выполнения.

2. Загрузите сцену и запустите рендеринг

В базовом сценарии сначала создаётся настраиваемый объект VRayRenderer. Сцену можно загрузить из файла .vrscene — собственного формата сцен V-Ray — или подготовить в памяти, преобразовав описание сцены из приложения в плагины V-Ray. Затем рендеринг запускается вызовом start(), изображение извлекается и сохраняется в файл, после чего освобождаются ресурсы.

Пример 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() возвращает управление, не дожидаясь завершения: движок V-Ray выполняет рендеринг в отдельном потоке. В примере вызов waitForRenderEnd(6000) ожидает завершения рендеринга. Значение 6000 приведено в примере документации; это не рекомендуемая и не гарантированная длительность рендеринга для любой сцены. getImage() получает изображение в текущем состоянии, а save() в примере записывает его в файл PNG. Общий рабочий процесс из документации также предусматривает закрытие ресурсов renderer после завершения процесса.

3. Выберите режим для предпросмотра и финального изображения

V-Ray App SDK предлагает два режима рендеринга: Interactive и Production. Interactive обеспечивает быстрый предпросмотр и постепенное повышение качества при настройке параметров сцены. Production подходит для получения финального изображения из полностью настроенной сцены. В документации режимом по умолчанию для класса VRayRenderer указан Interactive (CPU).

Оба режима поддерживают CPU и GPU. Для GPU в документации перечислены CUDA и OptiX для систем NVIDIA, а также Metal и MetalRT для систем Apple. Выбор зависит от имеющегося оборудования и рабочей среды; источник не рекомендует один вариант для всех сцен.

Режим рендеринга можно изменить через свойство renderMode объекта VRayRenderer. В документации сказано, что при переключении между разными рендерами не нужно заново загружать сцену или создавать renderer. Поэтому одну и ту же сцену можно сначала проверить в режиме Interactive, а затем переключить в Production.

4. Отслеживайте ход рендеринга и возникающие проблемы

Приложение может отслеживать такие события, как начало рендеринга, его завершение или остановка из-за ошибки, подписавшись на событие изменения состояния renderer. Финальное изображение готово в состоянии IDLE_DONE; во время рендеринга также можно получить изображение, сформированное к текущему моменту.

При асинхронном вызове start() важно учитывать состояние PREPARING. В документации указано, что до выхода из этого состояния не следует изменять сцену или renderer: такие попытки будут отклонены. Сообщения, которые V-Ray создаёт при загрузке сцены и рендеринге, также можно перехватывать через событие log. Оно передаёт не только текст сообщения, но и уровень: информационный, предупреждение, ошибка или отладка.

Обработчики событий выполняются в отдельном от потока рендеринга потоке. Такая схема позволяет не нагружать процесс рендеринга работой callback-функций, однако медленные callback-функции могут задерживать выполнение других обработчиков. Поэтому обработчики событий стоит делать короткими и не запускать в них напрямую ресурсоёмкие задачи.

Влияние на рабочие процессы в архитектуре и визуализации

App SDK может быть полезен разработчикам и техническим командам, которые хотят встроить рендеринг V-Ray в другое программное обеспечение или управлять им из собственного приложения. В архитектуре, дизайне интерьеров и archviz загрузку .vrscene и рендеринг можно включить в более широкий рабочий процесс. Однако в документации не говорится о наличии готовой интеграции с архитектурным ПО или пользовательского интерфейса: для работы с SDK потребуются разработки.

Перед внедрением следует проверить совместимость пути к модулю Python, каталога библиотек V-Ray и выбранного режима CPU/GPU с рабочей средой. В источниках не приводятся сведения о ценах, условиях лицензирования или совместимости между версиями; эти вопросы нужно проверять отдельно. Также важно до начала производственного процесса протестировать работу выбранного режима рендеринга на имеющемся оборудовании.

Распространённые ошибки

• Задать только VRAY_SDK, не проверив структуру каталогов, и не рассмотреть при необходимости VRAY_APPSDK_BIN или настройку пути поиска во время выполнения.

• Считать путь к модулю Python и путь поиска исполняемых файлов V-Ray одной и той же настройкой.

• Пытаться изменить параметры сцены или renderer после вызова start(), пока процесс находится в состоянии PREPARING.

• Считать значение 6000 из примера гарантированным временем ожидания для любого рендеринга.

• Забыть, что во время рендеринга можно получать промежуточные изображения, а готовое изображение доступно в состоянии IDLE_DONE.