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

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

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

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

Требования

Необходимо знать основы работы в Blender и уметь запускать скрипты в редакторе Text Editor. В руководстве Blender по разработке аддонов также предполагается знакомство с базовыми типами данных, модулями и классами Python. Для удобного анализа сообщений об ошибках в официальном руководстве рекомендуется запускать Blender из терминала.

Значение (2, 80, 0) в словаре bl_info приведённого ниже примера указывает минимальную версию Blender, необходимую для запуска аддона. Это не означает, что аддон автоматически совместим с более новыми версиями: код нужно проверить в той версии, где планируется его использовать. Документация по командной строке опубликована в руководстве Blender 5.2 LTS.

Создание первого аддона: пошаговая инструкция

1. В Blender откройте новый текст в области Text Editor и вставьте код ниже. Он определяет оператор ObjectMoveX. При запуске оператор проходит по объектам активной сцены и увеличивает координату X каждого из них на 1,0. Параметр UNDO включает возможность отменить действие оператора.

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

import bpy

class ObjectMoveX(bpy.types.Operator):
    """Move every scene object along the X axis."""
    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()

bl_info передаёт Blender сведения об аддоне, например его название и категорию; поле версии в примере задаёт минимальное требование. В execute() описано действие, которое выполняется при запуске оператора. Контекст сцены здесь передаётся через параметр context. Официальное руководство рекомендует по возможности использовать этот параметр в операторах.

1. Нажмите Run Script в Text Editor, чтобы выполнить код. На этом этапе оператор регистрируется, но объекты ещё не перемещаются. Откройте меню Operator Search, найдите Move X by One и нажмите Enter. В примере из руководства отображаемое название задаётся в поле bl_label.

2. Чтобы установить скрипт как аддон, сохраните его в файл с расширением .py, используя имя, соответствующее правилам именования модулей Python. В Blender откройте Preferences > Add-ons > Install… и выберите файл. Когда аддон появится в списке, включите его. Чтобы он оставался активным после перезапуска, используйте пункт Save as Default, как указано в руководстве.

При включении аддона Blender вызывает функцию register(), а при отключении — unregister(). В этом коде эти функции отвечают за регистрацию и снятие регистрации класса оператора. На этапе разработки запуск скрипта напрямую позволяет быстро проверить его работу; установка аддона даёт возможность управлять им в списке аддонов в настройках Blender.

Использование в архитектурном и визуализационном рабочих процессах

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

Во втором примере из руководства Blender по аддонам связанные дубликаты активного объекта размещаются между 3D-курсором и объектом. Дубликаты связываются с коллекцией сцены, а их расположение рассчитывается относительно объекта и курсора. В первой версии общее число дубликатов задано фиксированным значением 10. Этот пример показывает, как устроить инструмент для работы с повторяющимися элементами и как добавить настройки, изменяемые пользователем.

Для рендеринга из командной строки запустите Blender с параметром -b или --background. В примере для Cycles из официальной документации задаются конкретный кадр и устройство:

blender -b file.blend -f 20 -- --cycles-device OPTIX

Эта команда рендерит 20-й кадр и выбирает устройство OPTIX. В руководстве перечислены следующие допустимые устройства Cycles: CPU, CUDA, OPTIX, HIP, ONEAPI и METAL. Выбирайте устройство, совместимое с используемой системой.

В документации есть и отдельный пример команды для вывода кадров анимации в формате PNG:

blender -b animation.blend -o //render_ -F PNG -x 1 -a

В этой команде -o задаёт путь вывода, -F — формат файла, -x включает добавление расширения, а -a запускает рендеринг кадров анимации. Путь, начинающийся с //, считается относительно файла .blend. Если в имени файла используются символы #, они служат заполнителем для номера кадра. Эти два примера предназначены для разных задач: кадр, формат файла, путь вывода и устройство нужно настраивать в соответствии с нужным типом рендера.

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

Типичные ошибки и следующие шаги

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

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

• Считайте значение (2, 80, 0) в bl_info минимальным требованием к версии, а не гарантией совместимости с новыми версиями Blender.

• При фоновом рендеринге задайте путь к файлам, формат вывода, диапазон кадров и устройство Cycles в соответствии с задачей. В одном примере могут быть параметры, которых нет в другом.

На следующем этапе можно изучить разделы bpy.context и bpy.types.Operator в документации Blender API. Официальное руководство по аддонам также показывает, как сделать свойства операторов и фиксированные значения настраиваемыми пользователем. По мере развития инструмента можно, например, превратить количество дубликатов в изменяемый параметр — это поможет учитывать разные требования сцены.

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

Это руководство адаптировано на основе документов Blender Manual «Add-on Tutorial» и «Command Line Arguments». Оба источника опубликованы по лицензии CC BY-SA 4.0; материал адаптирован на турецкий язык в соответствии с условиями этой лицензии.