ComfyUI Node: HY-Motion Retarget to FBX

HY-Motion Retarget to FBX:

The HYMotionRetargetFBX node is designed to facilitate the process of retargeting animations from one skeleton to another using the FBX format. This node is particularly useful for AI artists who need to transfer motion data between different character models, ensuring that animations created for one character can be seamlessly applied to another. The node leverages the FBX SDK to import and manipulate skeleton data, allowing for precise control over the retargeting process. By utilizing this node, you can maintain consistency in animations across different models, which is crucial for creating cohesive and professional-looking animations. The node's capabilities include loading skeletons from FBX files, mapping bones between source and target skeletons, and applying transformations to achieve the desired animation retargeting. This process is essential for projects that involve multiple character models or require animation reuse, as it saves time and effort while ensuring high-quality results.

HY-Motion Retarget to FBX Input Parameters:

target_fbx

The target_fbx parameter specifies the file path to the FBX file containing the target skeleton to which the animation will be retargeted. This parameter is crucial as it determines the structure and hierarchy of the target skeleton, which directly impacts the retargeting process. The file path should be a valid string pointing to an existing FBX file. There are no specific minimum or maximum values for this parameter, but it must be a valid path to an FBX file.

mapping_file

The mapping_file parameter is used to provide a file that contains the bone mapping between the source and target skeletons. This mapping is essential for correctly aligning the bones of the source animation with those of the target skeleton. The file should be formatted in a way that the node can interpret, typically as a dictionary or similar structure. The accuracy of this mapping directly affects the quality of the retargeted animation.

scale

The scale parameter allows you to adjust the scale of the animation during the retargeting process. This is useful when the source and target skeletons are of different sizes, and you need to ensure that the animation fits the target model appropriately. The parameter accepts numerical values, with the default typically set to 1.0, indicating no scaling. Adjusting this value can help achieve the desired visual effect.

yaw_offset

The yaw_offset parameter is used to apply an offset to the yaw rotation of the animation. This can be helpful when the orientation of the source and target skeletons differs, and you need to align them correctly. The parameter accepts numerical values, with the default usually set to 0.0, indicating no offset. Modifying this value can help correct orientation discrepancies.

neutral_fingers

The neutral_fingers parameter determines whether the fingers of the target skeleton should be set to a neutral position during retargeting. This is particularly useful for ensuring that hand animations are transferred accurately, especially when the source and target skeletons have different default finger positions. The parameter is typically a boolean, with options for true or false.

in_place

The in_place parameter controls whether the animation should be retargeted in place, meaning that the root motion is removed, and the character remains stationary. This is useful for looping animations or when you want to maintain the character's position in the scene. The parameter is usually a boolean, with options for true or false.

in_place_x

The in_place_x parameter specifies whether the animation should be retargeted in place along the X-axis. This allows for more granular control over the in-place retargeting process, enabling you to maintain the character's position along specific axes. The parameter is typically a boolean, with options for true or false.

in_place_y

The in_place_y parameter specifies whether the animation should be retargeted in place along the Y-axis. Similar to in_place_x, this parameter provides control over the in-place retargeting process along the Y-axis. The parameter is usually a boolean, with options for true or false.

in_place_z

The in_place_z parameter specifies whether the animation should be retargeted in place along the Z-axis. This parameter allows for control over the in-place retargeting process along the Z-axis, ensuring that the character's position is maintained as desired. The parameter is typically a boolean, with options for true or false.

preserve_position

The preserve_position parameter determines whether the original position of the animation should be preserved during retargeting. This is useful when you want to maintain the spatial relationship of the animation within the scene. The parameter is usually a boolean, with options for true or false.

auto_stride

The auto_stride parameter controls whether the stride of the animation should be automatically adjusted during retargeting. This can help ensure that the character's movement appears natural and consistent with the target skeleton's proportions. The parameter is typically a boolean, with options for true or false.

target_pose_type

The target_pose_type parameter specifies the pose type of the target skeleton, such as "A-Pose" or "T-Pose." This information is used to align the source and target skeletons correctly, ensuring that the retargeted animation fits the target model's default pose. The parameter accepts string values, with common options being "A-Pose" or "T-Pose."

HY-Motion Retarget to FBX Output Parameters:

ret_rots

The ret_rots output parameter provides the retargeted rotations for the target skeleton. These rotations are the result of the retargeting process and represent the transformed animation data that aligns with the target skeleton's structure. This output is crucial for applying the retargeted animation to the target model, ensuring that the motion appears natural and consistent.

ret_locs

The ret_locs output parameter provides the retargeted locations for the target skeleton. These locations represent the transformed positional data that aligns with the target skeleton's structure. This output is essential for ensuring that the spatial positioning of the animation is accurately transferred to the target model.

active

The active output parameter indicates whether the retargeting process was successful and if the retargeted animation is active. This parameter is typically a boolean, with true indicating a successful retargeting process and false indicating an issue or failure. This output is important for verifying the success of the retargeting operation.

HY-Motion Retarget to FBX Usage Tips:

• Ensure that the target_fbx and mapping_file parameters are correctly specified to avoid errors during the retargeting process.
• Use the scale parameter to adjust the size of the animation to fit the target skeleton, especially if the source and target models differ significantly in size.
• Experiment with the yaw_offset parameter to correct any orientation discrepancies between the source and target skeletons.
• Utilize the in_place parameters to control the root motion of the animation, which can be useful for looping animations or maintaining the character's position in the scene.

HY-Motion Retarget to FBX Common Errors and Solutions:

Failed to initialize FBX importer for: <filepath>. Error: <error_string>

• Explanation: This error occurs when the FBX importer fails to initialize, possibly due to an incorrect file path or a corrupted FBX file.
• Solution: Verify that the target_fbx parameter is set to a valid file path and that the FBX file is not corrupted. Ensure that the file exists and is accessible.

Bone mapping not found for source and target skeletons

• Explanation: This error indicates that the bone mapping file does not contain the necessary mappings between the source and target skeletons.
• Solution: Check the mapping_file parameter to ensure it points to a valid file with the correct bone mappings. Update the file to include the necessary mappings if they are missing.

Retargeting process failed due to incompatible skeleton structures

• Explanation: This error suggests that the source and target skeletons have incompatible structures, making retargeting impossible.
• Solution: Review the skeleton structures of both the source and target models to ensure they are compatible. Adjust the models or the bone mapping file as needed to resolve structural differences.