Image и текстуры ImageTexture в Blender Python API

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

Вы узнаете, как с помощью Blender Python API создавать блок данных Image, масштабировать буфер изображения и менять значения пикселей. Также рассмотрим, зачем вызывать update(), чтобы изменения отобразились на изображении, и что учитывать при копировании блока данных Image, связанного с буфером. В заключительной части разберём связь параметров ImageTexture с повторением текстуры, альфа-каналом и границами изображения.

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

Требования

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

• В примерах кода используется модуль bpy в среде Python Blender. В источниках не упоминаются требования к внешней учётной записи.

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

Работа с блоком данных Image: пошагово

1. Создайте блок графических данных

Создать блок данных Image можно с помощью bpy.data.images.new(). В примере ниже используется начальный размер из исходной документации. Свойство size позволяет получить ширину и высоту буфера изображения в пикселях.

import bpy

image_src = bpy.data.images.new("Mimari_Kontrol", 1024, 102)
print(image_src.size)

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

2. Масштабируйте буфер и примените изменения к изображению

Метод scale() меняет размер буфера изображения. Свойство pixels даёт доступ к пиксельному буферу, состоящему из чисел с плавающей точкой. В примере ниже изображение масштабируется до 1024 × 720, меняются первые четыре значения буфера, после чего изображение обновляется.

image_src.scale(1024, 720)
image_src.pixels[0:4] = (0.5, 0.5, 0.5, 0.5)
image_src.update()

print(image_src.size)
print(image_src.pixels[0:4])

Этот код присваивает значения только первым четырём элементам буфера — он не заполняет всё изображение. Вызов update() обновляет отображение изображения после изменений буфера с числами с плавающей точкой. Если результат отличается от ожидаемого, сначала проверьте, что переменная указывает на нужный блок данных Image и что вызов обновления выполнился.

3. Проверьте поведение при копировании

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

image_dest = image_src.copy()
image_dest.update()

print(image_dest.size)
print(image_dest.pixels[0:4])

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

4. Сохраните изображение или упакуйте его в файл проекта

Image API предоставляет функцию save() для сохранения изображения и save_render() — для сохранения по заданному пути с использованием настроек рендера сцены. Метод pack() позволяет добавить изображение в файл .blend как встроенные данные.

image_src.pack()

Упаковка, сохранение и повторная загрузка — разные операции. В API метод unpack() предназначен для извлечения упакованного изображения на диск, а reload() — для повторной загрузки изображения из исходного пути. Выбор метода зависит от того, как вы хотите управлять путём к изображению и данными в проекте. Перед передачей проекта проверьте, что изображение находится в нужном месте и правильно хранится в файле проекта.

Как выбрать настройки ImageTexture?

Параметры ImageTexture определяют, как изображение будет использоваться в качестве текстуры. Свойство extension задаёт поведение за пределами границ изображения. REPEAT повторяет изображение по горизонтали и вертикали; EXTEND растягивает пиксели по краям; CLIP делает область за пределами изображения прозрачной. В документации среди вариантов также перечислены CLIP_CUBE и CHECKER.

Параметры repeat_x и repeat_y задают множители повторения по горизонтали и вертикали по отдельности. Для работы с альфа-каналом предусмотрен use_alpha, а для инвертирования альфа-значений — invert_alpha. Параметр use_interpolation управляет интерполяцией, а filter_size — размером фильтра, используемого при интерполяции. Выбирая настройки, учитывайте наличие альфа-канала в исходном изображении и способ применения текстуры.

В Image API для отображения альфа-канала перечислены варианты STRAIGHT, PREMUL, CHANNEL_PACKED и NONE. В документации CHANNEL_PACKED описан как режим для изображений, в которых данные упакованы в RGB- и альфа-каналы, не влияющие друг на друга. Если структура каналов исходного файла неизвестна, перед изменением параметров альфа-канала выясните, как было подготовлено изображение.

Частые ошибки

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

• Не вызывать update() после редактирования: после изменения буфера обновите изображение.

• Не проверять поведение за границами текстуры: REPEAT, EXTEND и CLIP дают разные результаты. Определите, как должны обрабатываться края изображения.

• Менять параметры альфа-канала, не учитывая исходное изображение: проверьте, используется ли альфа-канал и какой режим подходит.

• Считать сохранение и упаковку одной операцией: save(), pack(), unpack() и reload() решают разные задачи. Отдельно проверьте состояние изображения в файле проекта и на диске.

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

Сначала выполните операции в небольшом тестовом файле. После создания изображения выведите его размер; после масштабирования и изменения пикселей обновите буфер и проверьте значения ещё раз. Чтобы проверить поведение при копировании, сравните значения исходного изображения и копии. Затем контролируемо протестируйте поведение за границами и параметры повторения ImageTexture. Прежде чем переходить к сцене архитектурной визуализации, проверьте путь к исходному изображению, использование альфа-канала и необходимость упаковать изображение в проект.

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

Руководство основано на официальной документации Blender Python API для bpy.types.Image и bpy.types.ImageTexture. Оба источника распространяются по лицензии CC BY-SA 4.0; материал адаптирован на турецкий язык.