This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine Tools
GUI
VR Development
Double Precision Coordinates
API
Animations-Related Classes
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

Unigine::BonesRetargeting Class

Header: #include <UnigineObjects.h>

This class enables you to define animation retargeting for two meshes (source and target). Animation Retargeting is a feature that enables you to share and reuse animations between characters that use the same skeleton but may have significantly different proportions. Retargeting prevents your animated skeletons from losing their proportions or becoming unnecessarily deformed when from differently shaped characters are used.

The current implementation retargeting is applied only to relative positions of the bones, while rotation and scale are kept unchanged.

The following three modes are available:

  • MODE_ANIMATION - bone position is taken from the source animation.
  • MODE_BIND - Bone position is taken from the T-pose of the target skeleton.
  • MODE_PROPORTION - Bone position is taken from the source animation and multiplied by the proportion between the source and the target bones.

Proportions between bones are calculated by dividing their lenghts based on T-poses of their skeletons. The calculation is performed only once, then proportions are simply applied to the animation. A proportion is actually the length of the radius-vector of position relative to the parent bone. Root bones are the only exception, they might require setting the proportion manually.

Suppose these two skeletons have an animation of the root bone (root motion), that moves the object from the origin. In case we decide to move this animation to another skeleton we'd like to be able to adjust this translation as well. We have to options here:

  1. The left skeleton has this translation in the pelvic bone. The proportion for this bone is calculated as the height above the floor surface, i.e. the movement will be automatically changed in the MODE_PROPORTION mode.
  2. As for the right skeleton, the bone responsible for this translation is projected onto the plane (i.e it doesn't have height in T-pose), so we cannot calculate the movement proportion. In this case we should set a custom proportion (see the setBoneCustomProportion() method) and copy the value from the pelvic bone. Only after performing these actions the MODE_PROPORTION mode will work as expected.

The general setup for the most of the cases is as follows:

Bones retargeting settings can be saved to a .bones_retargeting file, and then use this file for an ObjectMeshSkinned via the addRetargetedAnimation() method.

BonesRetargeting Class

Enums

MODE#

Retargeting mode.
NameDescription
MODE_ANIMATION = 0Bone position is taken from the source animation.
MODE_BIND = 1Bone position is taken from the T-pose of the target skeleton.
MODE_PROPORTION = 2Bone position is taken from the source animation and multiplied by the proportion between the source and the target bones.

Members

bool isMeshesLoaded() const#

Returns the current value indicating if both source and target meshes are loaded.

Return value

true if is enabled; otherwise false.

getNumBones() const#

Returns the current total number of bones.

Return value

Current number of bones

getSrcMeshFileGUID() const#

Returns the current GUID of the source *.mesh file.

Return value

Current source mesh *.mesh GUID.

getDstMeshFileGUID() const#

Returns the current GUID of the target *.mesh file.

Return value

Current target mesh *.mesh GUID.

BonesRetargeting ( ) #

Constructor. Creates an instance of the class with default parameters.

BonesRetargeting ( const char * src_mesh_path, const char * dst_mesh_path ) #

Constructor. Creates an instance of the class with default parameters and loads the specified source and target meshes.

Arguments

  • const char * src_mesh_path - Path to the source *.mesh file.
  • const char * dst_mesh_path - Path to the target *.mesh file.

bool loadMeshes ( const char * src_mesh_path, const char * dst_mesh_path ) #

Loads source and target meshes from the specified locations.

Arguments

  • const char * src_mesh_path - Path to the source *.mesh file.
  • const char * dst_mesh_path - Path to the target *.mesh file.

Return value

true if source and target meshes were successfully loaded from the specified files; otherwise, false.

bool setNameMapping ( const char * src_name, const char * dst_name ) #

Sets name mapping for the pair of source and target bones.

Arguments

  • const char * src_name - Name of the source bone.
  • const char * dst_name - Name of the corresponding target bone.

Return value

true if name mapping for the specified pair of source and target bones is set successfully; otherwise, false.

void findEqualNameMapping ( ) #

Performs a search and automatically maps source and target bones by matching names.

const char * getSrcBoneName ( int index ) const#

Returns the name of the source bone by its index.

Arguments

  • int index - Index of the source bone.

Return value

Name of the source bone with the specified index.

const char * getDstBoneName ( int index ) const#

Returns the name of the target bone by its index.

Arguments

  • int index - Index of the target bone.

Return value

Name of the target bone with the specified index.

void setBoneMode ( const char * src_name, BonesRetargeting::MODE mode ) #

Sets a new retargeting mode to be used for the source bone with the specified name.

Arguments

  • const char * src_name - Name of the source bone.
  • BonesRetargeting::MODE mode - Retargeting mode to be used for the bone.

BonesRetargeting::MODE getBoneMode ( const char * src_name ) const#

Returns the current retargeting mode used for the source bone with the specified name.

Arguments

  • const char * src_name - Name of the source bone.

Return value

Retargeting mode currently used for the bone.

float getBoneProportion ( const char * src_name ) const#

Returns the calculated proportion value for the source bone with the specified name.

Arguments

  • const char * src_name - Name of the source bone.

Return value

Proportion value for the bone.

void setBoneCustomProportion ( const char * src_name, float proportion ) #

Sets a new custom proportion value for the source bone with the specified name.

Arguments

  • const char * src_name - Name of the source bone.
  • float proportion - New proportion value to be set.

float getBoneCustomProportion ( const char * src_name ) const#

Returns the current custom proportion value for the source bone with the specified name.

Arguments

  • const char * src_name - Name of the source bone.

void removeBoneCustomProportion ( const char * src_name ) #

Removes the custom proportion for the source bone with the specified name.

Arguments

  • const char * src_name - Name of the source bone.

const char * getDstBoneBySrcBone ( const char * src_name ) const#

Returns the name of the target bone corresponding to the source bone with the specified name.

Arguments

  • const char * src_name - Name of the source bone.

Return value

Name of the corresponding target bone for the specified source one.

const char * getSrcBoneByDstBone ( const char * dst_name ) const#

Returns the name of the source bone corresponding to the target bone with the specified name.

Arguments

  • const char * dst_name - Name of the target bone.

Return value

Name of the corresponding source bone for the specified target one.

bool save ( const char * path ) const#

Saves the current bones retargeting settings to a .bones_retargeting file according to the specified path. This file can then be used for an ObjectMeshSkinned via the addRetargetedAnimation() method.

Arguments

  • const char * path - Path to a file to which bones retargeting settings are to be saved (.bones_retargeting extension).

bool load ( const char * path ) #

Loads bones retargeting settings from a .bones_retargeting file according to the specified path. Such files can be used for an ObjectMeshSkinned via the addRetargetedAnimation() method.

Arguments

  • const char * path - Path to a file containing bones retargeting settings to be loaded (.bones_retargeting extension).
Last update: 2023-11-29
Build: ()