patch
Об эффекте
patch служит для добавления текстур на плоскости к маске. Добавляемая текстура может быть привязана к определённым точкам головы или экрана.
Совет: размещайте файлы текстур в подпапке
Texturesпапки с файлами маски.
Пример
JSON
{
"preview": "mask-icon.png",
"effects": [
{
"name": "patch",
"anchor": "fullscreen",
"texture": "Textures/patch-image.png"
}
]
}
Параметры эффекта
| Параметр | Описание |
|---|---|
name | Название эффекта. Должно быть "patch".
Тип данных: string. |
anchor | Точка привязки, относительно которой текстура будет располагаться в пространстве. Возможно одно из следующих строковых значений:
• fullscreen — весь экран;
• right_eye — правый глаз;
• left_eye — левый глаз;
• middle_eyes — переносица;
• forehead — лоб;
• nose — нос;
• mouth — центр рта;
• right_cheek — центр правой щеки;
• left_cheek — центр левой щеки;
• lower_lip — нижняя губа;
• upper_lip — верхняя губа;
• lt_corner — левый верхний край;
• lb_corner — левый нижний край;
• rt_corner — правый верхний край;
• rb_corner — правый нижний край;
• free — центр экрана;
• top_center — центр верхней стороны;
• left_center — центр левой стороны;
• right_center — центр правой стороны;
• bottom_center — центр нижней стороны.
Тип данных: string. |
texture | Путь к файлу текстуры либо набор параметров текстуры.
Если текстура представляет собой статичное изображение, то укажите в параметре путь к .png файлу текстуры относительно конфигурационного файла mask.json, например, "texture": "Textures/texture-file.png".
Если необходимы сложные режимы наложения текстуры, манипуляции с alpha-каналом или анимация, то вам нужно объявить texture как набор параметров и использовать их для задания свойств наложения. См. Параметры texture.
Тип данных: string или obj. |
size | Размер плоскости, на которую накладывается текстура, по осям X и Y. Как правило, размер задаётся в единицах измерения сцены как число с плавающей точкой, но возможно его указание в процентах от ширины или высоты экрана.
Тип данных: array<(float или obj)>[2]. |
offset | Смещение плоскости относительно точки привязки в трёхмерном пространстве XYZ. Как правило, смещение указывают в единицах измерения сцены как число с плавающей точкой, но возможно его указание в процентах от ширины или высоты экрана.
Тип данных: array<(float или obj)>[3]. |
rotation | 3 числа с плавающей точкой, которые определяют углы вращения плоскости в трёхмерном пространстве XYZ.
Будьте внимательны: если используется точка привязки "anchor": "free", то некоторые значения rotation могут привести к тому, что текстура выйдет за границы области отрисовки полностью или частично.
Тип данных: array<float>[3]. |
allow_rotation | Параметр указывает, будет ли текстура вращаться вместе с головой (true) или нет (false). Работает только в случае, когда точка привязки (anchor) находится на голове (щёки, нос, уши и т.п.). Значение по умолчанию: true.
Тип данных: bool. |
visible | Устанавливает режимы видимости накладываемой текстуры:
• "always" — показывать всегда;
• "face" — показывать только при найденном лице;
• "mouth_open" — показывать, когда рот открыт;
• "animation" — показывать, пока работает анимация, заданная в texture.
Значение по умолчанию "face".
Тип данных: string. |
show_delay | Задержка появления текстуры в секундах. По умолчанию текстура показывается без задержек. Параметр используется только в случае "visible": "mouth_open".
Обратите внимание, что задержка указывается в секундах. Если нужны доли секунды, указывайте дробную часть после запятой.
Тип данных: float. |
hide_delay | Задержка исчезновения текстуры в секундах. По умолчанию текстура скрывается без задержек. Параметр используется только в случае "visible": "mouth_open".
Обратите внимание, что задержка указывается в секундах. Если нужны доли секунды, указывайте дробную часть после запятой.
Тип данных: float. |
fit | Метод растягивания текстуры для случая, когда используется anchor: "fullscreen". Возможные значения:
• "stretch" — растягивать во весь экран;
• "crop" — растягивать с сохранением соотношения сторон, но с выходом за экран;
• "pad" — растягивать с сохранением соотношения сторон без выхода за экран.
Значение по умолчанию "stretch".
Тип данных: string. |
Способы указания размера и смещения
Параметры size и offset используются для изменения размера и позиционирования плоскости в результирующем изображении. При задании значений этих параметров используются специальные соглашения. Пример ниже демонстрирует возможные способы указания значений:
JSON
{
"preview": "my-mask-icon.png",
"effects": [
{
"name": "patch",
"anchor": "free",
"texture": "Textures/texture-file.png",
"size": [{ "w": 1.0 }, { "h": 0.3 }],
"offset": [{ "pix": 10.0 }, { "h": -0.2 }, 0.0]
}
]
}
В примере используются следующие константы для указания, как должна рассчитываться величина того или иного параметра:
| Константа | Описание |
|---|---|
w | Значение в процентах от ширины экрана. |
h | Значение в процентах от высоты экрана. |
pix | Значение в пикселях. |
max | Значение в процентах от максимальной стороны экрана. |
min | Значение в процентах от минимальной стороны экрана. |
Во всех приведенных случаях проценты указываются, как число в диапазоне от 0.0 до 1.0.
Процентные значения от ширины или высоты можно использовать для указания как горизонтальных, так и вертикальных размеров и смещений.
Особенности и ограничения
- •Параметр
sizeигнорируется, если используется"anchor": "fullscreen"в сочетании с"fit" : "stretch". - •В случае, если
"fit" : "crop"или"fit" : "pad", параметрsizeиспользуется для вычисления соотношения сторон изображения. - •Параметр
offsetигнорируется, если используется"anchor" : "fullscreen". - •Если указан
"anchor" : "free", то некоторые значения в параметреrotationмогут приводить к частичному или полному выходу текстура из области отрисовки. - •
show_delayиhide_delayиспользуются только при"visible" : "mouth_open".
Параметры texture
JSON
{
"preview": "mask-icon.png",
"effects": [
{
"name": "patch",
"texture": {
"texture": "Textures/my-texture.png",
"color": [1, 1, 1, 0.75],
"blend_mode": "Multiply",
"UseAlphaMask": true
}
}
]
}
| Параметр | Описание |
|---|---|
texture | Путь к .png файлу текстуры относительно конфигурационного файла mask.json, например, "texture": "Textures/my-texture.png".
Если параметр texture не указан или при загрузке текстуры произошла ошибка, то будет использована «шахматная» заливка в бело-серую клетку.
Тип данных: string. |
blend_mode | Способ наложения текстуры на изображение за ней (фон). Допустимые значения:
• "replace" — текстура непрозрачна, ее alpha-канал не используется.
• "alpha" — смешивание фона с текстурой, используя alpha-канал текстуры. Это значение используется по умолчанию.
• "add" — результирующий цвет пикселя в изображения равен сумме цвета фона и текстуры (alpha-канал не используется).
• "addalpha" — результирующий цвет пикселя равен сумме фона и текстуры, при комбинировании учитывается значения alpha-канала текстуры.
Также можно использовать один из следующих расширенных режимов наложения. Названия совпадают с терминами, которые обычно используют графические редакторы:
• "Multiply" – умножение цветов;
• "Lighten" – замена светлым;
• "Darken" – замена тёмным;
• "LinearLight" – линейное затемнение;
• "Screen" – режим ширмы;
• "Overlay" – перекрытие;
• "SoftLight" – мягкий свет;
• "SoftLight2" – мягкий свет (еще один вариант);
• "ColorDodge" – осветление основы;
• "ColorBurn" – затемнение основы;
• "VividLight" – яркий свет;
• "PinLight" – точечный свет;
• "HardMix" – жесткий свет;
• "Difference" – разница;
• "Exclusion" – исключение;
• "Hue" – цветовой тон;
• "Saturаtion" – насыщенность;
• "Color" – цветность;
• "Luminosity" – свечение.
Значение по умолчанию: "alpha".
Тип данных: string. |
color | Коэффициенты RGBA, которые будут дополнительно применены к точкам накладываемой текстуры. Чем выше коэффициент, тем сильнее представлен цветовой канал текстуры. 0.0 соответствует отключению цветового канала, 1.0 — то же значение, которое используется в текстуре. Для «усиления» канала используйте значения больше 1.0. По умолчанию используется "color": [1.0, 1.0, 1.0, 1.0].
Тип данных: array<float>[4]. |
auto_mirror | Указывает, надо ли автоматически отрисовывать текстуру зеркально в случае, когда изображение поступает с задней камеры: true (отзеркаливать) или false (текстура остаётся без изменений). Параметр важен для текстур, содержащих логотип или текст. Тип данных: bool. |
u_transform | Используется для UV-преобразования координат текстуры. Значение по умолчанию: "u_transform": [1.0, 0.0, 0.0]. Примеры использования рассмотрены ниже в разделе Преобразование UV-координат.
Тип данных: array<float>[3]. |
v_transform | Используется для UV-преобразования координат текстуры. Значение по умолчанию: "v_transform": [0.0, 1.0, 0.0]. Примеры использования рассмотрены ниже в разделе Преобразование UV-координат.
Тип данных: array<float>[3]. |
animation | Набор параметров, описывающих анимацию накладываемой текстуры. Присутствие этих параметров в texture сигнализирует движку масок, что текстура является анимированной, т.е. состоящей из нескольких кадров, хранящихся в отдельных .png файлах и воспроизводящихся последовательно. Настройки анимации описаны в разделе animation.
Тип данных: obj. |
Преобразование UV-координат
- •
Зеркальное отображение относительно вертикальной оси:
"u_transform" : [-1.0, 0.0, 1.0] - •
Зеркальное отображение относительно горизонтальной оси:
"v_transform" : [0.0, -1.0, 1.0] - •
Поворот на 90 градусов по часовой стрелке:
"u_transform" : [0.0, 1.0, 0.0], "v_transform" : [1.0, 0.0, 0.0] - •
Поворот на 180 градусов:
"u_transform" : [-1.0, 0.0, 1.0], "v_transform" : [0.0, -1.0, 1.0] - •
Поворот на 90 градусов против часовой стрелки:
"u_transform" : [0.0, -1.0, 1.0], "v_transform" : [-1.0, 0.0, 1.0]
Параметры animation
JSON
{
"preview": "mask-icon.png",
"effects": [
{
"name": "patch",
"texture": {
"texture": "Textures/frame.png",
"blend_mode": "Multiply",
"UseAlphaMask": true,
"animation": {
"type": "once",
"timeline": [50, 50, 50, 100]
}
}
}
]
}
| Параметр | Описание |
|---|---|
type | Тип воспроизведения. Возможное значение — одна из следующих строковых констант:
• "once" — однократное проигрывание, потом остановка на 1 кадре, или
• "loop" — зацикленное проигрывание.
По умолчанию используется "loop".
Тип данных: string. |
trigger_start | Событие для запуска анимации:
• "mouth_open" — открытие рта;
• "mouth_close" — закрытие рта;
• "face_found" — начало трекинга лица;
• "face_lost" — потеря трекинга лица;
• "tap" — касание экрана.
До запуска анимации триггером, текстура будет отображать первый кадр.
Тип данных: string. |
trigger_stop | Событие для остановки анимации:
• "mouth_open" — открытие рта;
• "mouth_close" — закрытие рта;
• "face_found" — начало трекинга лица;
• "face_lost" — потеря трекинга лица;
• "tap" — касание экрана.
Тип данных: string. |
fps | Число кадров в секунду при отображении анимации, другими словами, это скорость воспроизведения.
Тип данных: int. |
timeline | Ещё один параметр, который указывает скорость воспроизведения. Задаётся в виде массива, например, "timeline": [200, 100, 40], где каждый элемент — это длительность воспроизведения соответствующего кадра в миллисекундах. В приведённом примере первый кадр будет показан в течение 200 миллисекунд, второй — 100 миллисекунд, а третий и остальные кадры (если они есть) будут иметь длительность 40 миллисекунд. Число элементов должно быть равно или меньше количества кадров.
Тип данных: array<int>[]. |
timeline_ex | Параметр, который даёт возможность задать произвольный порядок следования кадров и указать длительность воспроизведения каждого кадра. Примеры использования см. ниже.
Обратите внимание, что при использовании timeline_ex проигрывается только заданная последовательность кадров (при использовании timeline проигрываются все доступные кадры).
Тип данных: array<( int или array<int>[2] )>[]. |
Важно! Параметры
fps,timelineиtimeline_exдают возможность настроить скорость воспроизведения различными способами. Используйте только один из них.
Задание кадров
Параметр texture указывает на PNG изображение первого кадра (в нашем примере, это "frame.png"). Последующие кадры должны иметь подобное имя файла и числовой индекс (1, 2, 3 и так далее). Например, анимация из примера выше, содержащая 4 кадра, будет состоять из такой последовательности файлов:
- •frame.png - Имя файла в
texture, первый кадр. - •frame1.png - Второй кадр.
- •frame2.png - Третий кадр.
- •frame3.png - Четвертый кадр.
При использовании параметров fps или timeline кадры воспроизводятся последовательно в порядке возрастания индексов. Чтобы переопределить порядок, используйте параметр timeline_ex.
Примеры использования timeline_ex
- •
"timeline_ex" : [50, 50, 60]— проиграет 1-ый в течение 50 миллисекунд, 2-ой кадры — столько же, а 3-ий — в течение 60 миллисекунд. Остальные кадры проиграны не будут, так как при использованииtimeline_exпроигрывается только заданная последовательность кадров (в этом его отличие от"timeline"). - •
"timeline_ex" : [50, 50, [5, 100], 40, 40, [0, 900], 100]— проиграет следующую последовательность:- •1-й кадр, 50 миллисекунд;
- •2-й кадр, 50 миллисекунд;
- •6-й кадр, 100 миллисекунд (6-ому кадру соответствует индекс 5);
- •7-й кадр, 40 миллисекунд (обратите внимание, что после прыжка на 6-ой кадр, проигрывание продолжится с 7-го кадра. При этом специально указывать 7-ой кадр не нужно);
- •8-й кадр, 40 миллисекунд;
- •1-й кадр, 900 миллисекунд (опять прыжок);
- •2-й кадр, 100 миллисекунд (после прыжка на 1-ый кадр проигрывание продолжится со 2-го кадра).
- •
Обратите внимание, что первый кадр имеет индекс 0, второй — 1, и так далее.