Свойства модели¶

Вводится в Модель (ModelReactor)

параметр Ресурс модели; model¶

Параметр позволяет выбрать ресурс модели для данного объекта.

Note

Можно присваивать как ресурс, так и id ресурса. Подробнее см. Ресурсы.

действие Модель - изменить ресурс; setModel(modelResource)¶

Установить новый ресурс модели (параметр Ресурс модели (model)).

Данный вызов равносилен присваиванию параметра Ресурс модели (model)

Parameters:	Ресурс модели / modelResource – Новый ресурс модели, который будет выставлен объекту

Работа с анимациями¶

Вводится в Модель (ModelReactor)

Каждая 3D модель может иметь одну или несколько анимаций. Ниже приведены события и действия по работе с анимациями.

Warning

Если была запущена анимация у скрытой модели, то событие onAnimationPlay будет запущено только после того, как модель будет показана.

Такая же ситуация может происходить, если сначала была запущена анимация, и сразу после этого - её сокрытие:

local model = reactorController:getReactorByName("MyModel")

-- Неправильно:

model:playAnimation("Deactivate")
model:hide()


-- Правильно:

-- Инициализация
model:subscribeEvent("onAnimationFinish", function(animationName)
    if animationName == "Deactivate" then
        model:hide()
    end
end)

model:playAnimation("Deactivate")

Неправильно	Правильно

действие Анимация - запуск; playAnimation(animationOrName, playMode = "once", stopOthers = false, fromBeginning = false)¶

Запустить анимацию. Если задан параметр “С начала”, то анимация будет проиграна с самого начала.

После запуска будет вызвано событие Анимация - началась (onAnimationPlay). Данное событие может быть вызвано не моментально, в зависимости от видимости объекта. Подробнее см. выше

Если Режим выставлен в Один раз, то после окончания анимации будет вызвано событие Анимация - закончилась (onAnimationFinish). Если режим проигрывания выставлен в Повтор, то анимация никогда не закончится сама, и, соответственно, событие вызвано не будет. Однако режим проигрывания анимации может быть изменён явно при помощи действия Анимация - смена режима (setAnimationPlayMode).

Parameters:

Название / animationOrName – Анимация, которую нужно запустить (в версии Advanced можно использовать как имя анимации типа string, так и саму анимацию типа osg.Animation) Режим проигрывания / playMode – Режим проигрывания: *Один раз*(osgAnimation.Animation.ONCE) - проиграть один раз, *Повтор*(osgAnimation.Animation.LOOP) - проигрывать в цикле, *Повтор с возвратом*(osgAnimation.Animation.PPONG) - проигрывать в цикле с возвратом обратно Остановить остальные / stopOthers – Надо ли останавливать остальные проигрываемые в данный момент анимации С начала / fromBeginning – Запустить ли анимацию с самого начала

действие Анимация - стоп; stopAnimation(animationOrName = nil)¶

Остановить запущенную анимацию. Анимация при этом вернётся в начальное состояние.

В случае, если анимация проигрывалась, будет запущено событие Анимация - приостановилась (onAnimationPause). Если такая анимация не проигрывалась, то событие вызвано не будет.

Имя анимации может быть не определено, тогда будут остановлены все анимации (вызов будет равносилен Анимация - остановить все (stopAllAnimations)). Соответственно, событие Анимация - приостановилась (onAnimationPause) будет вызвано для всех анимаций, которые в данный момент проигрывались.

Parameters:	Название / animationOrName – Анимация, которую необходимо остановить (в версии Advanced можно использовать как имя анимации типа string, так и саму анимацию типа osg.Animation). Если значение отсутствует, то будут остановлены все анимации

действие Анимация - остановить все; stopAllAnimations()¶

Остановить все запущенные анимации. Все анимации вернутся в начальное состояние.

Для каждой проигрываемой анимации будет вызвано событие Анимация - приостановилась (onAnimationPause)

действие Анимация - пауза; pauseAnimation(animationOrName = nil)¶

Приостановить анимацию по её имени. Данная анимация останется в том положении, которое было до остановки. Остальные проигрываемые анимации при этом продолжат проигрывание.

Для каждой анимации будет вызвано событие Анимация - приостановилась (onAnimationPause)

Вызов с animationOrName равным nil или “” равносильно вызову Анимация - приостановить все (pauseAllAnimations).

Parameters:	Название / animationOrName – Анимация, которая должна быть приостановлена (в версии Advanced можно использовать как имя анимации типа string, так и саму анимацию типа osg.Animation). Отсутствующее значение означает приостановку всех анимаций.

действие Анимация - приостановить все; pauseAllAnimations()¶

Приостановить все анимации. Модель при этом застынет в том положении, которое было до приостановки.

Для каждой проигрываемой анимации будет вызвано событие Анимация - приостановилась (onAnimationPause)

действие Анимация - смена режима; setAnimationPlayMode(animationOrName, playMode)¶

Изменяет текущий режим проигрывания анимации. Имеет смысл только для проигрываемых в данный момент анимаций.

При смене режима никакие события вызваны не будут.

Parameters:

Название / animationOrName – Анимация (в версии Advanced можно использовать как имя анимации типа string, так и саму анимацию типа osg.Animation) Режим проигрывания / playMode – Новый режим проигрывания: *Один раз*(osgAnimation.Animation.ONCE) - проиграть один раз, *Повтор*(osgAnimation.Animation.LOOP) - проигрывать в цикле, *Повтор с возвратом*(osgAnimation.Animation.PPONG) - проигрывать в цикле с возвратом обратно.

Пример использования действия:

-- Проигрывать анимацию "RotateClockwise" в цикле до тех пор, пока пользователь не нажмёт кнопку.
-- После нажатия кнопки доигрывается анимация "RotateClockwise",после чего
-- запускается анимация "RotateCounterClockwise". Затем процесс повторяется.
local model = ...
local button = ...

-- Подписка на нажатие на кнопку.
button:subscribeEvent("onClick", function()
    -- В данный момент времени проигрывается ровно одна из этих анимаций,
    -- однако для остановленной анимации данный вызов будет проигнорирован:
    model:setAnimationPlayMode("RotateClockwise", osgAnimation.Animation.ONCE)
    model:setAnimationPlayMode("RotateCounterClockwise", osgAnimation.Animation.ONCE)

    -- Теперь остаётся дождаться, пока проигрываемая анимация закончится.
end)

-- После нажатия на кнопку одна из анимаций проигрывается в режиме "Один раз", и скоро закончится.
-- Необходимо поймать это событие, и запустить следующую анимацию
model:subscribeEvent("onAnimationFinished", function(animationName)
    if animationName == "RotateClockwise" then
        model:playAnimation("RotateCounterClockwise", osgAnimation.Animation.LOOP)
    else
        model:playAnimation("RotateClockwise", osgAnimation.Animation.LOOP)
    end
end)

-- Запускаем весь процесс
model:playAnimation("RotateClockwise", osgAnimation.Animation.LOOP)

действие Анимация - перемотать; rewindAnimation(animationOrName, aTime)¶

Перематывает указанную анимацию на указанное время. Если время не указано, то перемотает в начало.

Parameters:	Название / animationOrName – Анимация, которую нужно перемотать (в версии Advanced можно использовать как имя анимации типа string, так и саму анимацию типа osg.Animation) Время / aTime – Время, на которое нужно перемотать анимацию(по умолчанию равно 0)

событие Анимация - закончилась; onAnimationFinish¶

Вызывается при завершении какой-либо анимации

Param Название / animationName – string:
	Имя анимации, которая закончилась

событие Анимация - началась; onAnimationPlay¶

Вызывается на старте какой-либо анимации (см. действие Анимация - запуск (playAnimation))

Param Название / animationName – string:
	Имя анимации, которая началась

событие Анимация - приостановилась; onAnimationPause¶

Вызывается на паузе какой-либо анимации (см. действия Анимация - стоп (stopAnimation), Анимация - пауза (pauseAnimation))

Param Название / animationName – string:
	Имя анимации, которая остановилась

событие Анимация - перемотана; onAnimationRewind¶

Вызывается при перемотке какой-либо анимации

Param Название / animationName – string:
	Имя анимации, которая перемоталась

Пример использования анимаций:

local model = ...

model:subscribeEvent("onAnimationFinish", function(animationName)
    if animationName == "TurnLeft" then
        model:playAnimation("TurnRight")
    elseif animationName == "TurnRight" then
        model:playAnimation("TurnLeft")
    else
        logwarn("Unknown animation is finished:", animationName)
    end
end)

model:playAnimation("TurnLeft")

Свойства для оптимизации¶

параметр K-d деревья; kdTrees¶

Оптимизация с использованием структуры данных Kd-дерево позволяет сократить время поиска ближайшего объекта, проекции точек, трассировки лучей и т.п.

Возможные значения:

Авто - Автоматическая настройка

Включить - Включить оптимизацию

Выключить - Выключить оптимизацию

параметр Rig на GPU; rig¶

Если внутри 3D-модели размещается риг(набор виртуальных суставов и костей с установленными трансформациями), то данная оптимизация позволит выполнить его расчет на процессоре вашей графической карты, что значительно ускорит время вычислений.

Возможные значения:

Авто - Автоматическая настройка

Включить - Включить оптимизацию

Выключить - Выключить оптимизацию

параметр Morph на GPU; morph¶

Если анимация 3D-модели использует технику Morph(бесшовный переход из одного положения в другое), то данная оптимизация позволит выполнить ее расчет на процессоре вашей графической карты, что значительно ускорит время вычислений.

Note

Не работает на iOS-устройствах.

Возможные значения:

Авто - Автоматическая настройка

Включить - Включить оптимизацию

Выключить - Выключить оптимизацию

параметр GPU Instancing; gpuInstancing¶

Если в проекте присутствует множество экземпляров одной модели, то данный параметр позволяет оптимизировать этап отрисовки, вызвав ее всего один раз для всех экземпляров.

Возможные значения:

Авто - Автоматическая настройка

Включить - Включить оптимизацию

Выключить - Выключить оптимизацию

Дополнительный параметр:

Минимальное число экземпляров - минимальное число экземпляров, при котором оптимизация будет применена(по умолчанию равно 50).

Advanced¶

Пример кода:

local model = reactorController:getReactorByName("Model")
local animations = model:getAnimationList()

local function getRandomAnimation()
    return animations[math.random(1, #animations)] -- получаем случайную анимацию
end

local animationToPlay = getRandomAnimation()

model:subscribeEvent("onAnimationFinish", function(animationName)
    animationToPlay = getRandomAnimation()
    model:playAnimation(animationToPlay, osgAnimation.Animation.ONCE, false, false) -- по завершении текущей анимации проигрываем следующую случайную
end)

model:playAnimation(animationToPlay, osgAnimation.Animation.ONCE, false, false)

Положение объекта¶

Вводится в Система координат (TransformNodeReactor)

параметр Перемещение; trans¶

Вводится в Система координат (TransformNodeReactor)

Параметр позволяет задать точный сдвиг объекта по координатам (x, y, z) относительно родительского объекта.

Перемещение задаётся в виде объекта osg.Vec3. Пример использования:

-- Заставим мячик прыгать на месте
local ball = ...

local velocity = 0                   -- Текущая скорость объекта
ball.trans = osg.Vec3(0, 0, 0.2)     -- Задаём начальное положение - 20 см.

local delta_time = 0.01              -- Время между кадрами для обновления

-- Функция для обновления
function update_velocity_and_position()
    -- Обновляем положение объекта.
    -- Для простоты считаем, что скорость за этот период времени не менялась
    ball.trans = ball.trans + osg.Vec3(0, 0, 1) * velocity * delta_time

    -- Обновляем скорость: на мячик действует ускорение свободного падения
    -- 9.8 м/с^2, с предыдущей итерации прошло время delta_time
    velocity = velocity - 9.8 * delta_time

    -- Мячик достиг земли - отскок от земли
    if ball.trans:z() <= 0 then
        velocity = - velocity
    end
end

-- Вызывать функцию обновления позиции каждые delta_time секунд
timer:subscribe(update_velocity_and_position, delta_time)

Доступны следующие действия:

• сбросить в нулевое положение
• поместить на метку автоматически (совместить центр с родительской меткой)

параметр Вращение; rotate¶

Вводится в Система координат (TransformNodeReactor)

Параметр позволяет задать точный поворот объекта по осям (x, y, z) относительно родительского объекта.

В данном параметре используются углы Крылова (или углы Эйлера), где порядок поворота осей определяется в порядке: z, x, y. Все углы задаются в градусах.

Параметр имеет тип osg.Vec3, где каждая компонента вектора соответствует своей оси.

Для перевода в градусы и из градусов можно воспользоваться функциями deg2rad(x) и rad2deg(x). Данные функции могут быть использованы как для чисел, так и для векторов osg.Vec3, osg.Vec2.

Для перевода в/из osg.Quat можно воспользоваться функциями euler2quat(ypr) и quat2euler(quat). Важно отметить, что обе функции работают с векторами в радианах. Таким образом, для получения кватерниона из параметра Вращение (rotate), а также наоборот необходимо сделать по два вызова:

local model = ...

-- Получение кватерниона по параметру rotate
local rotation_quat = euler2quat(deg2rad(model.rotate))

-- Присвоение кватерниона параметру rotate
model.rotate = rad2deg(quat2euler(rotation_quat))

Пример вращения логотипа:

local logo = ...

local function update_logo_rotation()
    -- Забираем текущий поворот
    local rot = logo.rotate

    -- Добавляем небольшое вращение вдоль одной из осей
    rot:y((rot:y() + 1) % 360)

    -- Присваиваем новое значение объекту
    logo.rotate = rot
end

-- Подписываемся на таймер, чтобы обновление происходило каждые 0.01 секунд
timer:subscribe(update_logo_rotation, 0.01)

Пример поворота объекта в сторону метки:

local model = ...
local marker = ...

-- Функция построения кватерниона для поворота от from к to
local function _make_directed_rotation(from, to)
    -- Вращать будем относительно оси, ортогональной обоим векторам,
    --   для его получения воспользуемся векторным произведением
    local axis = osg.Vec3.cross(from, to)

    -- Для получения угла вращения воспользуемся скалярным произведением:
    --   v1 * v2 = |v1| |v2| cos(angle(v1, v2)) => angle = acos(v1 * v2 / (|v1| |v2|))
    local angle_cos = osg.Vec3.dot(from, to) / (from:length() * to:length())
    local angle = math.acos(angle_cos)

    -- Возвращаем кватернион вращения с найденной осью и углом
    return osg.Quat(angle, axis)
end

local function update_rotation()
    -- Направление от модели к метке
    local delta_trans = marker.trans - model.trans

    -- Получим вращение модели в виде кватерниона
    local rotation = _make_directed_rotation(osg.Vec3(1, 0, 0), delta_trans)

    -- Присваиваем вращение. Заметим, что необходимо перевести кватернион
    -- сначала в углы Крылова, а затем перевести их значения из радианов в градусы
    model.rotate = deg2rad(quat2euler(rotation))
end

-- Будем обновлять вращение каждые 10 миллисекунд
timer:subscribe(update_rotation, 0.01)

Доступны следующие действия:

• сбросить в начальное состояние

параметр Масштаб; scale¶

Вводится в Система координат (TransformNodeReactor)

Параметр позволяет задать точный масштаб по координатам (x, y, z) относительно родительского объекта.

Доступны следующие действия:

• сбросить в начальное состояние
• поместить на метку автоматически (совместить габариты объекта и родительской метки)
• зафиксировать оси (масштабировать отдельно по каждой оси, или по всем одновременно)

действие Объект - переместить; setTrans(trans)¶

Установить новое значение перемещения объекта (параметра Перемещение (trans))

Данное действие равносильно присваиванию параметра Перемещение (trans)

transform:setTrans(osg.Vec3(0.0, 0.0, 0.0))
transform.trans = osg.Vec3(0.0, 0.0, 0.0)

Parameters:	Перемещение / trans – Новое значение перемещения

действие Объект - повернуть; setRotate(rotate)¶

Установить новое значение вращения объекта (параметра Вращение (rotate)).

Данное действие равносильно присваиванию параметра Вращение (rotate)

transform:setRotate(osg.Vec3(0.0, 0.0, 0.0))
transform.rotate = osg.Vec3(0.0, 0.0, 0.0)

Parameters:	Вращение / rotate – Новое значение вращения

действие Объект - масштабировать; setScale(scale)¶

Установить новое значение масштабирования объекта (параметра Масштаб (scale)).

Данное действие равносильно присваиванию параметра Масштаб (scale)

transform:setScale(osg.Vec3(1.0, 1.0, 1.0))
transform.scale = osg.Vec3(1.0, 1.0, 1.0)

Parameters:	Масштаб / scale – Новое значение вращения

действие Объект - преобразовать; setTransform(trans, rotate, scale)¶

Установить новые значения перемещения, вращения и масштаба (параметров Перемещение (trans), Вращение (rotate), Масштаб (scale). Данный вызов равносилен последовательным вызовам Объект - переместить (setTrans), Объект - повернуть (setRotate), Объект - масштабировать (setScale):

Следующие две конструкции полностью равносильны:

model:setTransform(osg.Vec3(0.0, 0.0, 0.0), osg.Vec3(0.0, 0.0, 0.0), osg.Vec3(1.0, 1.0, 1.0))

model:setTrans(osg.Vec3(0.0, 0.0, 0.0))
model:setRotate(osg.Vec3(0.0, 0.0, 0.0))
model:setScale(osg.Vec3(1.0, 1.0, 1.0))

Равносильная конструкция

Advanced¶