Руководство по Blender Python API: автоматизация объектов и операторов сцены

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

Python API Blender позволяет описывать некоторые действия со сценой в коде и повторять их. В этом руководстве вы узнаете, как создать блок данных источника света и использующий его объект, связать объект с активной коллекцией и задать его положение. Также мы рассмотрим вызов операторов через bpy.ops, проверку с помощью poll() перед вызовом и оценку состояния, возвращаемого оператором.

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

Требования и примечание о версии

Для работы с этими примерами нужен Python API Blender. В документации не указана конкретная версия Blender, поэтому здесь также нельзя назвать точную версию, с которой примеры совместимы. При запуске кода сверяйтесь с документацией API для установленной версии Blender. В источниках не указаны требования к учётной записи, стоимость или особые требования к оборудованию.

В коде используется модуль bpy. Названия API и параметры в примерах соответствуют использованию, описанному в официальной документации Blender. Операторы могут зависеть не только от параметров, но и от контекста, в котором их запускают. Поэтому перед вызовом оператора проверьте активный объект сцены и условия, необходимые для выполнения операции.

Пошагово: добавляем в сцену источник света

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

import bpy
view_layer = bpy.context.view_layer
# Create new light data-block.
light_data = bpy.data.lights.new(name="New Light", type='POINT')
# Create new object with our light data-block.
light_object = bpy.data.objects.new(name="New Light", object_data=light_data)
# Link light object to the active collection of current view layer,
# so it'll appear in the current scene.
view_layer.active_layer_collection.collection.objects.link(light_object)
# Place light to a specified location.
light_object.location = (5.0, 5.0, 5.0)
# And finally select it and make it active.
light_object.select_set(True)
view_layer.objects.active = light_object

Сначала из bpy.context.view_layer получают активный слой просмотра. В следующих строках создают блок данных источника света типа POINT и объект, использующий этот блок. После добавления объекта в активную коллекцию ему задают положение, а затем выделяют и назначают активным. Координаты взяты из примера в документации и не являются рекомендацией по размещению источника света в конкретном интерьере или архитектурной сцене.

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

Вызов операторов и проверка возможности их запуска

Согласно документации Blender, bpy.ops используется для вызова операторов, написанных на C++, Python или в виде макросов. Свойства оператора передаются как именованные параметры. Например, следующий вызов передаёт оператору mesh.subdivide два свойства:

import bpy
bpy.ops.mesh.subdivide(number_cuts=3, smoothness=0.5)

Это не означает, что вызов будет выполняться одинаково при любых условиях. Если оператор запущен в неподходящем контексте, может возникнуть RuntimeError. Один из способов, рекомендованных в документации, — проверить текущие условия с помощью poll() до запуска оператора. Пример смены режима:

import bpy
if bpy.ops.object.mode_set.poll():
    bpy.ops.object.mode_set(mode='EDIT')

Если poll() возвращает положительный результат, вызывается оператор смены режима. Эта проверка помогает определить, можно ли запустить оператор в текущем контексте, но не означает, что исключены все возможные ошибки. В документации также отмечено, что после выполнения оператора может возникнуть RuntimeError, если имеются сообщения об ошибках.

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

Изменение контекста и влияние на архитектурные процессы

Для изменения контекста, доступного оператору, в документации описано использование temp_override. Этот способ позволяет направить операцию на определённые данные вместо выбранных или активных данных. Например, к элементам контекста могут относиться активный объект или выбранные объекты. В источнике рекомендуется использовать подход, основанный на копии текущего контекста; иначе необходимые оператору сведения придётся искать отдельно.

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

Для архитекторов, дизайнеров интерьеров и специалистов по визуализации основы API показывают, как описывать повторяющиеся действия в сцене с помощью кода. Если разделить создание объекта, добавление в коллекцию и настройку положения на отдельные шаги, будет проще отслеживать изменения, которые вносит скрипт. Однако в источниках не утверждается, что эти примеры автоматизируют конкретный архитектурный процесс или повышают производительность.

При использовании скриптов в офисе или учебной среде проверьте целевую коллекцию и активный объект; эксперименты, изменяющие данные сцены, сначала проводите на копии файла. Если в команде используют разные версии Blender, отдельно проверьте код в каждой из установленных версий. Поскольку в документации нет точных требований к оборудованию, стоимости или совместимости версий, вместо предположений по этим вопросам протестируйте код в своей среде.

Типичные ошибки и дальнейшие шаги

Первая ошибка — считать, что вызовы bpy.ops не зависят от контекста. Перед запуском оператора проверьте, какие данные активны, и при необходимости используйте poll(), чтобы убедиться, что вызов допустим. Вторая ошибка — полагать, что вызов всегда завершается успешно. Проверяйте возвращаемые состояния, например FINISHED и CANCELLED, и учитывайте, что сообщения об ошибках могут привести к RuntimeError.

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

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

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

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