model3d

Об эффекте

model3d добавляет в маску трёхмерную модель.

Поддерживаются модели в формате .mdl либо анимации в формате .ani. Перед добавлением этих файлов в маску, их надо предварительно сгенерировать или экспортировать из соответствующего инструмента разработки. Подробное описание экспорта есть в разделе Экспорт 3D-модели.

Совет: чтобы скрыть некоторую часть 3D-модели, используйте инструмент Invisible Occluder.

Пример

JSON

{
    "preview": "Icon.png",
    "effects": [
        {
            "name": "model3d",
            "anchor": "forehead",
            "model": "Models/Cap.mdl",
            "material": {
                "technique": "Techniques/DiffUnlit.xml",
                "textures": {
                    "diffuse": "Textures/Cap_diffuse.png"
                }
            },
            "position": [0, 45, 10],
            "rotation": [10, 0, 0],
            "scale": [28, 28, 28]
        }
    ]
}

Параметры эффекта

Параметр	Описание
`name`	Название эффекта. Должно быть `"model3d"`. Тип данных: `string`.
`anchor`	Точка привязки 3D-модели: • `"face"` — центр лица; • `"right_eye"` — правый глаз; • `"left_eye"` — левый глаз; • `"middle_eyes"` — переносица; • `"forehead"` — лоб; • `"nose"` — нос; • `"mouth"` — центр рта; • `"right_cheek"` — центр правой щеки; • `"left_cheek"` — центр левой щеки; • `"lower_lip"` — нижняя губа; • `"upper_lip"` — верхняя губа. Тип данных: `string`.
`model`	Путь к файлу 3D-модели относительно конфигурационного файла маски `mask.json`. Тип данных: `string`.
`material`	Описание материала модели. Материалы отвечают за то, как будет отображаться поверхность 3D-модели во время отрисовки. В модели может быть один или несколько материалов. Если в модели один материал, то этот параметр представлен одним набором параметров, описывающих этот материал. Если при разработке модели было заложено несколько материалов, то параметр представлен последовательностью (массивом) наборов, по одному на каждый материал. Важно: материалы в массиве нужно указать в том же порядке, в котором они были определены до экспорта файла модели. Полная информация об описании материалов — в разделе Параметры материалов. Тип данных: `obj` или `array<obj>`.
`animation`	Набор параметров, описывающих анимацию 3D-модели. Подробности см. в разделе Параметры animation. Тип данных: `obj`.
`position`	3 числа с плавающей точкой, которые определяют позицию накладываемой модели в трёхмерном пространстве XYZ относительно точки привязки `anchor`. Тип данных: `array<float>[3]`.
`rotation`	3 числа с плавающей точкой, которые указывают углы вращения в трёхмерном пространстве XYZ в градусах относительно центра модели. Тип данных: `array<float>[3]`.
`scale`	3 числа с плавающей точкой, указывающих масштаб модели в трёхмерном пространстве XYZ. Если модель не видно, то проверьте, что вы не выставили слишком большой или слишком маленький масштаб. Тип данных: `array<float>[3]`.
`visible`	Режим видимости 3D-модели. Одно из следующих значений: • `"always"` — показывать всегда; • `"face"` — показывать только при обнаруженном лице; • `"mouth_open"` — показывать, когда открыт рот. По умолчанию модель отображается при обнаруженном лице. Тип данных: `string`.
`show_delay`	Задержка появления модели в секундах после того, как движок масок определит открытый рот пользователя. Параметр работает только при `"visible": "mouth_open"`. По умолчанию модель появляется без задержек. Обратите внимание, что задержка указывается в секундах. Если нужны доли секунды, указывайте дробную часть после запятой. Тип данных: `float`.
`hide_delay`	Задержка исчезновения модели в секундах, после того как движок масок определит, что пользователь закрыл рот. Параметр работает только при `"visible": "mouth_open"`. По умолчанию модель скрывается мгновенно. Обратите внимание, что задержка указывается в секундах. Если нужны доли секунды, указывайте дробную часть после запятой. Тип данных: `float`.

Параметры материалов

material

Материалы отвечают за отображение поверхности 3D-модели при отрисовке. Модель может использовать один или несколько материалов. Их описание находится в поле material.

Каждый материал содержит одну или несколько текстурных карт:

•
diffuse — Информация о цвете и alpha-канале.
•
normal — Информация о рельефе.
•
specular — Информация об интенсивности и цвете блика.
•
environment — Информацию о цвете окружения.
•
emissive — Информация о самосвечении.

Пример объявления одного материала в модели

JSON

{
    "preview": "Icon.png",
    "effects": [
        {
            "name": "model3d",
            "anchor": "forehead",
            "model": "Models/Cap.mdl",
            "material": {
                "technique": "Techniques/DiffUnlit.xml",
                "textures": {
                    "diffuse": "Textures/Cap_diffuse.png"
                }
            },
            "position": [0, 45, 10],
            "rotation": [10, 0, 0],
            "scale": [28, 28, 28]
        }
    ]
}

Пример объявления нескольких материалов

JSON

{
    "preview": "Icon.png",
    "effects": [
        {
            "name": "model3d",
            "anchor": "forehead",
            "model": "Models/Cap.mdl",
            "material": [
                {
                    "technique": "Techniques/DiffUnlit.xml",
                    "textures": {
                        "diffuse": "Textures/Cap/Body_diffuse.png"
                    }
                },
                {
                    "technique": "Techniques/DiffEnvCube.xml",
                    "textures": {
                        "diffuse": "Textures/Cap/Logo_diffuse.png",
                        "environment": "Textures/Cap/Environment.xml"
                    },
                    "parameters": {
                        "MatEnvMapColor": [0.6, 0.6, 0.6]
                    }
                }
            ],
            "position": [0, 45, 10],
            "rotation": [10, 0, 0],
            "scale": [28, 28, 28]
        }
    ]
}

Параметр	Описание
`technique`	Путь к файлу с данными о технике материала относительно конфигурационного файла `mask.json`, например, `"technique": "Techniques/DiffEnvCube.xml"`. Техника материала определяет, какие проходы отрисовки будет выполнять движок масок для отображения материала. Файлы с базовыми техниками материалов не обязательно помещать в папку, содержащую файлы маски. Они могут подгружаться из встроенных ресурсов. Подробнее о доступных файлах техник, см. раздел technique. Тип данных: `string`.
`textures`	Набор параметров для сопоставления текстурных карт (`diffuse`, `normal`, `specular`, `environment`, `emissive`). Подробнее см. textures. Тип данных: `obj`.
`parameters`	Набор параметров для задания цветовых настроек для отображения текстур. См. parameters. Тип данных: `obj`.
`renderorder`	Порядковый номер материала во время отрисовки. Значение по умолчанию: `128`. Тип данных: `int`.
`cull`	Сторона материала для отрисовки: • `"ccw"` — только внешняя; • `"cw"` — только внутренняя; • `"none"` — и внешняя, и внутренняя. По умолчанию отрисовывается внешняя сторона материала. Тип данных: `string`.

technique

Термин «техника» применительно к отрисовке материалов означает порядок и правила отрисовки. Параметр technique указывает на файл, который описывает технику отрисовки.

Во встроенных ресурсах доступны следующие файлы техник:

•
NoTexture.xml
•
NoTextureAlpha.xml
•
NoTextureEnvCube.xml
•
NoTextureEnvCubeAlpha.xml
•
NoTextureNormal.xml
•
NoTextureNormalAlpha.xml
•
NoTextureUnlit.xml
•
NoTextureUnlitAlpha.xml
•
Diff.xml
•
DiffMultiply.xml
•
DiffEmissive.xml
•
DiffEmissiveAlpha.xml
•
DiffEnvCube.xml
•
DiffEnvCubeAlpha.xml
•
DiffNormal.xml
•
DiffNormalAlpha.xml
•
DiffNormalAlphaMask.xml
•
DiffNormalEmissive.xml
•
DiffNormalEmissiveAlpha.xml
•
DiffNormalEnvCube.xml
•
DiffNormalEnvCubeAlpha.xml
•
DiffNormalSpec.xml
•
DiffNormalSpecAlpha.xml
•
DiffNormalSpecAlphaMask.xml
•
DiffSpec.xml
•
DiffSpecAlpha.xml
•
DiffSpecAlphaMask.xml
•
DiffUnlit.xml
•
DiffUnlitAlpha.xml
•
DiffUnlitAlphaMask.xml

Каждое имя включает нескольких подстрок (Diff, Alpha, Unlit и других). Они отражают наличие или отсутствие определенных свойств материала:

Подстрока	Значение
NoTexture	У материала отсутствует `diffuse` текстура. С помощью параметра `MatDiffColor` можно задать цвет материала, выставив необходимые коэффициенты RGB.
Diff	У материала имеется `diffuse` текстура. С помощью параметра `MatDiffColor` можно задать коэффициенты RGB пропускающего текстурой цвета.
Normal	У материала имеется `normal` текстура.
Spec	У материала имеется `specular` текстура. С помощью параметра `MatSpecColor` тремя первыми значениями можно задать коэффициенты RGB отражающего цвета, а четвёртым — значение силы затухания блика. При этом, если не задать строку `"Spec"` в названии техники материала, то по-прежнему можно управлять бликом через параметр `MatSpecColor`.
EnvCube	У материала имеется `environment` текстура. С помощью параметра `MatEnvMapColor` можно задать коэффициенты RGB отражённого от окружения цвета.
Emissive	У материала имеется `emissive` текстура. С помощью параметра `MatEmissiveColor` можете задать коэффициенты RGB яркости самосвечения. При этом, если не задать строку `"Emissive"` в названии технике материала, то можно управлять самосвечением материала в целом через параметр `MatEmissiveColor`.
Unlit	Цвет материала не зависит от источников света.
Alpha	Материал полупрозрачный. Прозрачность отдельных пикселей определяется alphа-каналом `diffuse` текстуры. С помощью параметра `MatDiffColor` в поле `value` тремя первыми значениями вы можете задать коэффициенты RGB пропускающего текстурой цвета, а четвёртым — коэффициент прозрачности материала в целом. Обратите внимание: движок масок отрисовывает объекты с подстрокой `"Alpha"` в названии техники материала после всех остальных объектов.
AlphaMask	Материал в каких-то местах полностью прозрачный, а в каких-то – нет. При этом, в отличие техники `"Alpha"`, прозрачность у `"AlphaMask"` определяется следующим образом: если значение alpha-канала у пикселя `diffuse` текстуры меньше или равно `0.5`, то материал полностью прозрачный, если более `0.5`, то материал в этом месте не прозрачный.
Multiply	Материал будет накладываться на фон в режиме `Multiply` — режим «умножение» (термин соответствует терминам, используемым графическими редакторами).

textures

Параметр textures служит для указания файлов текстурных карт материала. Пример декларации:

JSON

{
    "preview": "Icon.png",
    "effects": [
        {
            "name": "model3d",
            "anchor": "forehead",
            "model": "Models/Cap.mdl",
            "material": {
                "technique": "Techniques/DiffUnlit.xml",
                "textures": {
                    "diffuse": "Textures/Cap/Logo_diffuse.png",
                    "environment": "Textures/Cap/Environment.png"
                }
            }
        }
    ]
}

Параметр	Описание
`diffuse`	Путь до файла `diffuse` текстуры. Тип данных: `string`.
`normal`	Путь до файла `normal` текстуры. Тип данных: `string`.
`specular`	Путь до файла `specular` текстуры. Тип данных: `string`.
`environment`	Путь до файла `environment` текстуры. См. Создание файла environment текстуры. Тип данных: `string`.
`emissive`	Путь до файла `emissive` текстуры. Тип данных: `string`.

Примечания:

•

Все параметры должны указывать файловые пути относительно конфигурационного файла маски (mask.json).
•

Поддерживаемые форматы изображений для всех текстур: PNG и JPEG.

Создание файла environment текстуры

1.

Текстура вида environment создаётся на основе 360-панорамных HDRI изображений. Сделайте такую панорамную фотографию или скачайте готовое HDRI изображение с одного из сайтов, например, https://polyhaven.com/hdris.
2.

Сконвертируйте ваше изображение в cubemap-развёртку с помощью сервиса https://berrymoor.github.io/cubemap/. Сохраните сконвертированное изображение как PNG или JPEG файл.
3.

Разместите файл в папке с файлами маски (мы рекомендуем сохранять текстуры в подпапке Textures). Укажите путь до файла в параметре environment:

JSON

{
  ...
      "material": {
        "technique": "Techniques/DiffUnlit.xml",
        "textures": {
           "environment": "Textures/Cap/Environment.png"          
        }
      }
  ...
}

Теперь модель будет использовать вашу environment текстуру.

parameters

Это поле служит для задания цветовых настроек текстур материала.

Параметр	Описание
`MatDiffColor`	Коэффициенты RGBA для `diffuse` текстуры. Тип данных: `array<float>[4]`.
`MatSpecColor`	Последовательность из 4 чисел в плавающей точкой. Три первые значения задают коэффициенты RGB для `specular` текстуры, а четвёртый – значение силы затухания блика. Тип данных: `array<float>[4]`.
`MatEnvMapColor`	Коэффициенты RGB для отражённого от окружения света или `environment` текстуры. Тип данных: `array<float>[3]`.
`MatEmissiveColor`	Коэффициенты RGB яркости самосвечения или `emissive` текстуры. Тип данных: `array<float>[3]`.

Особые случаи

•

Для техник Diff, Normal, Spec, EnvCube, Emissive обязательно наличие соответствующей текстуры.
•

Параметрами MatDiffColor, MatEmissiveColor, MatSpecColor допустимо управление без объявления соответствующей техники.

textures/animation

Эффект model3d поддерживает анимацию текстур, которые накладываются на модель. Такая анимация позволяет оживить поверхность 3D-модели.

Примечание: следует отличать этот вид анимации от анимации самой модели. Последняя описывается параметрами animation.

Анимированные текстуры состоят из нескольких кадров, которые зачитываются из отдельных .png файлов и воспроизводятся последовательно.

Анимировать можно текстуры различных типов: diffuse,normal, specular, environment, emissive.

Чтобы объявить текстуру анимированной, нужно включить в нее следующие параметры:

•
texture — путь к файлу текстуры;
•
animation — группа параметров с настройками анимации.

Пример конфигурации текстуры без свойств анимации (обратите внимание на параметры effects > material > textures):

JSON

{
    "preview": "Icon.png",
    "effects": [
        {
            "name": "model3d",
            "anchor": "forehead",
            "model": "Models/Cap.mdl",
            "material": {
                "technique": "Techniques/DiffUnlit.xml",
                "textures": {
                    "diffuse": "Textures/Cap_diffuse.png"
                }
            },
            "position": [0, 45, 10],
            "rotation": [10, 0, 0],
            "scale": [28, 28, 28]
        }
    ]
}

Пример конфигурации текстуры после добавления свойств анимации (обратите внимание на параметры effects > material > textures):

JSON

{
    "preview": "Icon.png",
    "effects": [
        {
            "name": "model3d",
            "anchor": "forehead",
            "model": "Models/Cap.mdl",
            "material": {
                "technique": "Techniques/DiffUnlit.xml",
                "textures": {
                    "diffuse": {
                        "texture": "Textures/Cap_diffuse.png",
                        "animation": {
                            "fps": 15,
                            "type": "loop"
                        }
                    }
                }
            },
            "position": [0, 45, 10],
            "rotation": [10, 0, 0],
            "scale": [28, 28, 28]
        }
    ]
}

Параметр texture (в нашем примере, это строка "texture": "Textures/Cap_diffuse.png") определяет файл с первым кадром анимации. Остальные файлы с кадрами должны иметь подобное имя и числовые индексы: 1, 2, 3 и т. д. Например, если мы хотим использовать 4 кадра, то имена файлов должны быть такими:

•
Cap_diffuse.png — 1-ый кадр, имя в параметре texture;
•
Cap_diffuse1.png — 2-ой кадр;
•
Cap_diffuse2.png — 3-ий кадр;
•
Cap_diffuse3.png — 4-ый кадр.

Параметры анимации текстур

Параметр	Описание
`fps`	Число кадров в секунду при отображении анимации, другими словами — скорость воспроизведения. Тип данных: `int`.
`type`	Тип воспроизведения: • `"once"` — одно проигрывание и остановка на 1 кадре, или • `"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`.

Параметры animation

Параметры animation служат для настройки анимации 3D-модели в маске.

Примечание: кроме этой анимации, вы можете еще анимировать текстуры, накладываемые на маску. Подробнее об этом рассказывается в разделе texture/animation.

Прежде чем использовать анимацию в маске, её нужно подготовить и экспортировать. См. Экспорт 3D-моделей.

Пример объявления анимации модели:

JSON

{
    "preview": "Icon.png",
    "effects": [
        {
            "name": "model3d",
            "anchor": "forehead",
            "model": "Models/Cat.mdl",
            "material": {
                "technique": "Techniques/DiffUnlit.xml",
                "textures": {
                    "diffuse": "Textures/Cat_diffuse.png"
                }
            },
            "animation": {
                "file": "Models/Cat.ani"
            },
            "position": [0, 80, 10],
            "scale": [12, 12, 12]
        }
    ]
}

Параметр	Описание
`file`	Путь к файлу анимации 3D-модели относительно конфигурационного файла маски `mask.json`. Тип данных: `string`.
`speed`	Скорость воспроизведения анимации. По умолчанию равна `1.0`. Тип данных: `float`.
`type`	Тип воспроизведения: • `"once"` — одно проигрывание и остановка на 1 кадре, или • `"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`.

Invisible Occluder

Invisible Occluder — это название объекта, который скрывает геометрию позади себя, но сам при этом является прозрачным. На изображении ниже этим объектом является голова, которая скрывает внутреннюю часть шапки:

Эффект model3d можно использовать как Invisible Occluder. Для этого в нем необходимо объявить в нем материал InvisibleOccluder.xml из внутренних ресурсов (в этом случае материал задаётся как путь к файлу, т.е. как строка). Пример:

JSON

{
    "preview": "Icon.png",
    "effects": [
        {
            "name": "model3d",
            "anchor": "forehead",
            "model": "Models/head.mdl",
            "material": "Materials/InvisibleOccluder.xml",
            "position": [0, -12, 115],
            "rotation": [0, 90, -90 ],
            "scale": [2.29, 2.29, 2.29]
        }
    ]
}

Ссылки по теме

Эффекты