Unigine.BonesRetargeting Class
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:
- 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.
- 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:
- Set MODE_PROPORTION for the root bone.
- For all other bones use MODE_BIND (this is a default mode)
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.Properties
bool IsMeshesLoaded#
int NumBones#
UGUID SrcMeshFileGUID#
UGUID DstMeshFileGUID#
Members
BonesRetargeting ( ) #
Constructor. Creates an instance of the class with default parameters.BonesRetargeting ( string src_mesh_path, string dst_mesh_path ) #
Constructor. Creates an instance of the class with default parameters and loads the specified source and target meshes.Arguments
- string src_mesh_path - Path to the source *.mesh file.
- string dst_mesh_path - Path to the target *.mesh file.
bool LoadMeshes ( string src_mesh_path, string dst_mesh_path ) #
Loads source and target meshes from the specified locations.Arguments
- string src_mesh_path - Path to the source *.mesh file.
- string 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 ( string src_name, string dst_name ) #
Sets name mapping for the pair of source and target bones.Arguments
- string src_name - Name of the source bone.
- string 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.string GetSrcBoneName ( int index ) #
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.string GetDstBoneName ( int index ) #
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 ( string src_name, BonesRetargeting.MODE mode ) #
Sets a new retargeting mode to be used for the source bone with the specified name.Arguments
- string src_name - Name of the source bone.
- BonesRetargeting.MODE mode - Retargeting mode to be used for the bone.
BonesRetargeting.MODE GetBoneMode ( string src_name ) #
Returns the current retargeting mode used for the source bone with the specified name.Arguments
- string src_name - Name of the source bone.
Return value
Retargeting mode currently used for the bone.float GetBoneProportion ( string src_name ) #
Returns the calculated proportion value for the source bone with the specified name.Arguments
- string src_name - Name of the source bone.
Return value
Proportion value for the bone.void SetBoneCustomProportion ( string src_name, float proportion ) #
Sets a new custom proportion value for the source bone with the specified name.Arguments
- string src_name - Name of the source bone.
- float proportion - New proportion value to be set.
float GetBoneCustomProportion ( string src_name ) #
Returns the current custom proportion value for the source bone with the specified name.Arguments
- string src_name - Name of the source bone.
void RemoveBoneCustomProportion ( string src_name ) #
Removes the custom proportion for the source bone with the specified name.Arguments
- string src_name - Name of the source bone.
string GetDstBoneBySrcBone ( string src_name ) #
Returns the name of the target bone corresponding to the source bone with the specified name.Arguments
- string src_name - Name of the source bone.
Return value
Name of the corresponding target bone for the specified source one.string GetSrcBoneByDstBone ( string dst_name ) #
Returns the name of the source bone corresponding to the target bone with the specified name.Arguments
- string dst_name - Name of the target bone.
Return value
Name of the corresponding source bone for the specified target one.bool Save ( string path ) #
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
- string path - Path to a file to which bones retargeting settings are to be saved (.bones_retargeting extension).
bool Load ( string 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
- string path - Path to a file containing bones retargeting settings to be loaded (.bones_retargeting extension).