This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Basics
Rendering
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
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 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:

  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 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:

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.
NameDescription
MODE_ANIMATION = 0Bone position is taken from the source animation.
MODE_BIND = 1Bone position is taken from the bind-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

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

Return value

true if the bone settings are loaded successfully, otherwise false.
Last update: 2024-06-07
Build: ()