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 bind-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 bind-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 bind-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).
You can save bones retargeting settings to a *.bones_retargeting file that can be uploaded to a created BonesRetargeting object, which may further be registered for an ObjectMeshSkinned and used via the SetRetargeting() method.
BonesRetargeting Class
Enums
MODE#
Retargeting mode.Properties
UGUID SrcMeshFileGUID#
The GUID of the source *.mesh file.
UGUID DstMeshFileGUID#
The GUID of the target *.mesh file.
int NumDstBones#
The total number of bones in the target object that reuses the animation.
int NumSrcBones#
The total number of bones in the source object containing animation.
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 information on the bones of 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 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. If the custom proportion has been set for the bone, its value will be returned.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.
Return value
The custom proportion value for the bone.bool IsBoneCustomProportion ( string src_name ) #
Checks if the custom proportion is set for the specified bone.Arguments
- string src_name - Name of the source bone.
Return value
true if the bone proportion is custom, otherwise false.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. Such files can be uploaded to a created BonesRetargeting object, which may further be registered for an ObjectMeshSkinned and used via the SetRetargeting() 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 uploaded to a created BonesRetargeting object, which may further be registered for an ObjectMeshSkinned and used via the SetRetargeting() method.Arguments
- string path - Path to a file containing bones retargeting settings to be loaded (.bones_retargeting extension).
bool LoadBones ( string src_mesh_path, string dst_mesh_path ) #
Loads the bone information from the source and the target meshes.Arguments
- string src_mesh_path - Path to the mesh file with the source bone settings.
- string dst_mesh_path - Path to the mesh file with the target bone settings.
Return value
true if the bone settings are loaded successfully, otherwise false.bool LoadBonesFromMeshes ( Mesh src_mesh, Mesh dst_mesh ) #
Loads the bone information from the source and the target meshes. Unlike the loadBones() method, this method uses loaded meshes, therefore it would be impossible to obtain mesh GUIDs via the getSrcMeshFileGUID() and getDstMeshFileGUID() methods.Arguments
- Mesh src_mesh - The mesh with the source bone settings.
- Mesh dst_mesh - The mesh with the target bone settings.
Return value
true if the bone settings are loaded successfully, otherwise false.bool LoadBonesFromObjects ( ObjectMeshSkinned src_obj, ObjectMeshSkinned dst_obj ) #
Loads the bone information from the source and the target MeshSkinned objects. MeshSkinned objects GUIDs will be possible to obtain unless the Procedural flag is enabled.Arguments
- ObjectMeshSkinned src_obj - The MeshSkinned object with the source bone settings.
- ObjectMeshSkinned dst_obj - The MeshSkinned object with the target bone settings.
Return value
true if the bone settings are loaded successfully, otherwise false.Last update:
2024-06-07
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)