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 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.Members
UGUID getSrcMeshFileGUID() const#
Returns the current GUID of the source *.mesh file.
Return value
Current source mesh *.mesh GUID.UGUID getDstMeshFileGUID() const#
Returns the current GUID of the target *.mesh file.
Return value
Current target mesh *.mesh GUID.int getNumDstBones() const#
Returns the current total number of bones in the target object that reuses the animation.
Return value
Current total number of bones in the target object that reuses the animation.int getNumSrcBones() const#
Returns the current total number of bones in the source object containing animation.
Return value
Current total number of bones in the source object containing animation.static BonesRetargetingPtr create ( ) #
Constructor. Creates an instance of the class with default parameters.static BonesRetargetingPtr create ( const char * src_mesh_path, const char * 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
- const char * src_mesh_path - Path to the source *.mesh file.
- const char * dst_mesh_path - Path to the target *.mesh file.
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. If the custom proportion has been set for the bone, its value will be returned.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.
Return value
The custom proportion value for the bone.bool isBoneCustomProportion ( const char * src_name ) const#
Checks if the custom proportion is set for the specified bone.Arguments
- const char * src_name - Name of the source bone.
Return value
true if the bone proportion is custom, otherwise false.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. 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
- 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 uploaded to a created BonesRetargeting object, which may further be registered for an ObjectMeshSkinned and used via the setRetargeting() method.Arguments
- const char * path - Path to a file containing bones retargeting settings to be loaded (.bones_retargeting extension).
bool loadBones ( const char * src_mesh_path, const char * dst_mesh_path ) #
Loads the bone information from the source and the target meshes.Arguments
- const char * src_mesh_path - Path to the mesh file with the source bone settings.
- const char * 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 ( const Ptr<Mesh> & src_mesh, const Ptr<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
- const Ptr<Mesh> & src_mesh - The mesh with the source bone settings.
- const Ptr<Mesh> & dst_mesh - The mesh with the target bone settings.
Return value
true if the bone settings are loaded successfully, otherwise false.bool loadBonesFromObjects ( const Ptr<ObjectMeshSkinned> & src_obj, const Ptr<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
- const Ptr<ObjectMeshSkinned> & src_obj - The MeshSkinned object with the source bone settings.
- const Ptr<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)