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:
- 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.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 bonesgetSrcMeshFileGUID() 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-12-19
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)