Как написать Python-дополнение для Blender: создаём первый оператор

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

В этом руководстве вы превратите простой скрипт Python, работающий в Blender, в оператор, а затем — в загружаемое дополнение. Инструмент из примера перемещает все объекты активной сцены на 1 единицу по оси X. Цель — не предложить готовый производственный инструмент, а пошагово объяснить, как Blender определяет, регистрирует и запускает операторы.

Дополнение — это модуль Python с дополнительными сведениями, необходимыми Blender, чтобы распознать его и показать в списке. Словарь bl_info указывает, помимо прочего, название и категорию дополнения, а также минимальную версию Blender, необходимую для его работы. Оператор позволяет вызывать действие из Blender. В этом примере мы запустим его через окно поиска операторов.

Важно: пример воздействует не только на выделенные объекты, но и на все объекты активной сцены. Поэтому первые проверки безопаснее проводить не в важном проекте, а в тестовой сцене или копии файла.

Требования

Предполагается, что вы знакомы с основами Blender и умеете запускать скрипт в текстовом редакторе. Также рекомендуется знать базовые типы данных Python, например числа, Boolean, строки, списки, кортежи, словари и множества. Руководство советует также иметь базовое представление о модулях и классах Python.

В сведениях о дополнении из примера руководства указана версия Blender (2, 80, 0). Это минимальная версия, записанная в метаданных примера; это не означает, что код отдельно проверялся в актуальных версиях Blender. Необходимо убедиться, что API работает в используемой вами версии. Требования к учётной записи, аппаратным функциям или платной лицензии не указаны.

Для отладки Blender можно запустить из терминала. Руководство также отмечает, что включение Developer Extras в настройках может помочь в разработке дополнений.

Пошагово: напишите первый оператор

1. Добавьте код в текстовый редактор

В примере ниже класс ObjectMoveX определяет оператор. При вызове execute() объекты активной сцены обрабатываются по очереди, и к координате X каждого из них прибавляется 1.0. Параметр UNDO в bl_options позволяет отменить действие оператора.

bl_info = {
    "name": "Move X Axis",
    "blender": (2, 80, 0),
    "category": "Object",
}

import bpy

class ObjectMoveX(bpy.types.Operator):
    """My Object Moving Script"""
    bl_idname = "object.move_x"
    bl_label = "Move X by One"
    bl_options = {'REGISTER', 'UNDO'}

    def execute(self, context):
        scene = context.scene
        for obj in scene.objects:
            obj.location.x += 1.0
        return {'FINISHED'}

def register():
    bpy.utils.register_class(ObjectMoveX)

def unregister():
    bpy.utils.unregister_class(ObjectMoveX)

if __name__ == "__main__":
    register()

Этот простой пример регистрирует класс оператора, но не добавляет пункт в меню. Функция unregister() снимает регистрацию класса. bl_idname задаёт уникальный идентификатор оператора, а bl_label — его имя, отображаемое в интерфейсе Blender и результатах поиска. Если действие завершилось успешно, функция execute() возвращает FINISHED.

2. Запустите скрипт и вызовите оператор

Вставьте код в текстовый редактор Blender и запустите его. Скрипт зарегистрирует оператор, но сам по себе не переместит объекты. Затем откройте окно поиска операторов, найдите Move X by One и запустите оператор. Он переместит все объекты активной сцены на 1 единицу по оси X.

Важно использовать параметр context в execute(self, context). В некоторых случаях Blender может запускать операторы в специальном контексте. Поэтому руководство рекомендует обращаться к переданному оператору значению context, а не напрямую к глобальному контексту.

3. Сохраните файл и загрузите его как дополнение

Сохраните проверенный скрипт в файл. Выберите имя, подходящее для модуля Python, и добавьте расширение .py. В настройках Blender откройте раздел Add-ons, выберите опцию установки, укажите файл и включите дополнение в списке. Если дополнение должно оставаться активным после перезапуска, воспользуйтесь опцией Save as Default, указанной в руководстве.

При включении дополнения Blender запускает модуль и выполняет регистрацию, указанную в register(). При отключении Blender вызывает функцию unregister(); в данном примере она снимает регистрацию класса оператора. Во время установки пути к исходной и целевой папкам могут отображаться в консоли. Руководство также объясняет, как просматривать пути дополнений с помощью addon_utils.paths() в консоли Python.

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

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

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

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

• Ожидать, что объекты переместятся сразу после запуска скрипта: при первом запуске регистрируется оператор. Чтобы изменить объекты, нужно выбрать Move X by One в окне поиска операторов.

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

• Забыть о формате файла: сохраните файл дополнения с расширением .py и выберите имя, подходящее для модуля Python.

• Считать сохранение и включение одним действием: сохранение файла само по себе не включает дополнение. Его необходимо установить через настройки и включить в списке.

Что делать дальше

Сначала запустите пример в тестовой сцене и изучите результат работы оператора. Затем разберитесь отдельно с назначением bl_info, класса оператора, execute() и функций регистрации. На следующем этапе разработки можно исследовать, как превратить фиксированные значения в свойства оператора, настраиваемые пользователем; в продолжении руководства Blender рассматривается эта тема и другой пример, создающий копии связанных объектов.

Если возникли ошибки, консольный вывод Blender поможет выяснить, на каком этапе появилась проблема. Обзор Blender API, документация bpy.context и bpy.types.Operator также входят в число справочных материалов, на которые ссылается руководство для более подробного изучения используемых понятий.

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

Это руководство адаптировано на турецкий язык на основе примера дополнения и оператора из официальной документации Blender «Add-on Tutorial». Источник распространяется по лицензии CC BY-SA 4.0.