Как организовать коллекции и рендерить в Blender с помощью Python API

Чему вы научитесь в этом руководстве?

По мере роста сцен в Blender становится сложнее поддерживать порядок в архитектурной модели, мебели, освещении и элементах окружения, а также отслеживать, какие части сцены видны или попадают в итоговый файл. Структура Collection в Blender Python API помогает организовывать объекты в группы и выстраивать иерархию из вложенных коллекций. В этом руководстве мы шаг за шагом разберём, как создать коллекцию и связать её со сценой, настроить видимость коллекций, разобраться с параметрами Line Art и использовать операторы рендеринга.

Примеры основаны на свойствах и операциях, перечисленных в актуальной документации API Blender. Поскольку в документации не указана конкретная версия Blender, перед использованием примеров проверьте их в своей рабочей среде. Адаптируйте названия коллекций и структуру сцены в коде под свой проект.

Требования

• Необходим Blender и доступ к Python API. Источником служит актуальная документация Blender API; конкретная версия не указана.

• В источниках не упоминаются требования к аккаунту или подписке. В документации также нет сведений об аппаратных требованиях для Blender или времени рендеринга.

• Примеры работают с коллекциями и объектами сцены. Перед применением рекомендуется сохранить копию важных файлов проекта и проверить код на небольшой тестовой сцене.

Пошаговая организация сцены с помощью коллекций

1. Создайте коллекцию и свяжите её со сценой

Следующий код создаёт коллекцию и связывает её с основной коллекцией активной сцены. В документации Blender API перечислены операции создания коллекций и привязки дочерних коллекций. Название «Мебель» в примере может использоваться для группировки предметов мебели в проекте интерьера.

collection = bpy.data.collections.new("Mobilya")
bpy.context.scene.collection.children.link(collection)

Создание коллекции не означает, что объекты сцены автоматически перемещаются в неё. Членство объектов нужно настраивать отдельно. Свойство objects коллекции содержит объекты, входящие непосредственно в неё, а all_objects — объекты как самой коллекции, так и её вложенных коллекций. Понимание этой разницы помогает правильно оценивать общее содержимое сцен с основной коллекцией и вложенными группами.

2. Постройте иерархию из вложенных коллекций

В файле для архитектурной визуализации можно создать группы вроде мебели и освещения внутри основной коллекции «Интерьер». В документации Blender API свойство children определено как список непосредственных дочерних коллекций, а children_recursive — как список всех вложенных коллекций. При анализе иерархии учитывайте, содержимое какого уровня вам нужно.

Свойство all_objects включает объекты коллекции и её вложенных коллекций и доступно только для чтения. Поэтому для управления содержимым используйте не это свойство, а операции с объектами коллекции и её дочерними коллекциями. Кроме того, документация указывает, что создание списка children_recursive требует времени, зависящего от количества дочерних коллекций. Учитывайте это при работе с многоуровневой иерархией.

3. Настраивайте видимость в области просмотра и при рендеринге отдельно

hide_viewport отключает отображение коллекции в области просмотра, а hide_render — при рендеринге. Эти настройки не взаимозаменяемы. Например, чтобы скрыть группу в рабочей области просмотра, но оставить видимой при рендеринге, задайте значения отдельно:

collection.hide_viewport = True
collection.hide_render = False

В этом примере коллекция скрыта в области просмотра, но не отключена при рендеринге. Если вам нужно другое поведение, измените значения соответствующим образом. Проверять результат только в одном месте недостаточно: отдельно просмотрите область просмотра и итоговый рендер.

4. Выберите поведение Line Art на уровне коллекции

В документации Blender описаны параметры, определяющие, как коллекции участвуют в расчёте Line Art. Среди режимов — INCLUDE, OCCLUSION_ONLY, EXCLUDE, INTERSECTION_ONLY, NO_INTERSECTION и FORCE_INTERSECTION. Они задают разные варианты поведения: создание линий для коллекции, создание только перекрытий, исключение из расчёта или обработку линий пересечения.

В следующем примере для коллекции выбран режим, при котором она создаёт только перекрытия:

collection.lineart_usage = 'OCCLUSION_ONLY'

Если нужен дополнительный контроль пересечений, в документации также описаны свойства lineart_use_intersection_mask и use_lineart_intersection_priority. Приоритет пересечений можно задать с помощью lineart_intersection_priority; в документации API для этого значения указан диапазон от 0 до 255. Используйте эти параметры, если в сцене применяется расчёт Line Art и нужное поведение определено.

Получение изображения активного вида и рендеринг

Оператор bpy.ops.render.opengl описан как средство получения изображения активной области просмотра. Параметр write_still сохраняет изображение по пути вывода, если анимация отключена:

bpy.ops.render.opengl(write_still=True)

Это не то же самое, что обычный рендеринг сцены. Для запуска рендеринга сцены можно использовать оператор bpy.ops.render.render, указанный в API. В примере включено сохранение одного изображения:

bpy.ops.render.render(write_still=True)

Среди документированных параметров оператора рендеринга — анимация, использование области просмотра, выбор сцены, а также начальный и конечный кадры анимации. Параметры диапазона кадров предназначены для рендеринга анимации. Страница API описывает эти операции и параметры, но не указывает все настройки вывода, необходимые для конкретного проекта; перед рендерингом проверьте настройки сцены.

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

• Считать настройки viewport и рендеринга одинаковыми: hide_viewport и hide_render — разные свойства. Проверьте нужную видимость в обоих режимах.

• Не учитывать вложенные коллекции: objects показывает непосредственные объекты; чтобы учесть и вложенные коллекции, обратите внимание на область действия свойства all_objects.

• Выбирать режим Line Art наугад: параметры задают разное поведение линий и пересечений. Выберите подходящий режим и проверьте результат на небольшой тестовой сцене.

• Принимать изображение viewport за рендер сцены: bpy.ops.render.opengl отображает активный вид; для общего рендеринга предусмотрен отдельный оператор.

• Предполагать поведение, не описанное в документации API: источники не объясняют конкретные настройки проекта, скорость рендеринга или аппаратные требования. Проверяйте эти детали в своей сцене и рабочей среде.

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

Архитектурные бюро и команды визуализации могут группировать модели, мебель, освещение и элементы окружения в коллекции, чтобы сделать иерархию сцены понятнее. Раздельное управление видимостью в области просмотра и при рендеринге позволяет скрывать ненужные во время работы элементы, не меняя состав итогового изображения. Для презентаций с акцентом на рисунок, где используется Line Art, режимы на уровне коллекции помогают определить, как группы участвуют в расчёте линий.

Документация API не гарантирует совместимость с определённым аддоном, аппаратным обеспечением или версией Blender. Прежде чем автоматизировать работу с общими файлами в студии, проверьте код в используемой среде Blender и на небольшом тестовом файле. Также учитывайте лицензию CC BY-SA 4.0, указанную для исходной документации: она распространяется на использование содержимого документации.

Следующие шаги

Для начала создайте иерархию коллекций в небольшой тестовой сцене и сравните результат, отдельно меняя настройки видимости в области просмотра и при рендеринге. Затем, если используется Line Art, выберите подходящий режим и проверьте линии в итоговом изображении. Перед запуском операторов рендеринга проверьте настройки вывода сцены. В документации API также перечислены операции создания и очистки кэша текстур Cycles; это отдельные операторы, не связанные с организацией коллекций и базовым процессом рендеринга.

Источник и лицензия

Это руководство адаптировано на турецкий язык на основе документации Blender Python API по Collection и операторам рендеринга. Оба источника доступны по лицензии CC BY-SA 4.0.