Implementation:Isaac sim IsaacGymEnvs FBX Backend

Knowledge Sources	IsaacGymEnvs
Domains	Animation_Import, File_Parsing
Last Updated	2026-02-15 11:00 GMT

Overview

FBX_Backend provides functions for parsing FBX animation files into numpy arrays, extracting skeleton hierarchy, joint transforms, and animation data for use in the poselib framework.

Description

This module implements the FBX file import pipeline for the poselib skeleton animation system. The primary function fbx_to_npy reads an FBX file using the Autodesk FBX SDK Python bindings, extracts the skeleton hierarchy and joint-local transformation matrices across all animation frames, and returns them as numpy arrays along with joint names, parent indices, and the frame rate.

The FBX parsing process begins by initializing the FBX SDK manager and scene objects, then locating the root joint of the skeleton. If no root joint name is specified, the function searches for the first node with an animation curve attached. The function then traverses the node tree using a breadth-first search to find the root node with the maximum key count. The _get_skeleton function performs a depth-first search from the root joint to extract the complete joint hierarchy, producing lists of joint objects, joint names, and parent indices.

Animation data is extracted frame-by-frame using _get_frame_count to determine the animation range and frame rate, and _get_animation_curve to find the longest animation curve for each joint. Local transformation matrices are evaluated at each time step, with scaling factors divided out and the [3,3] element set to 1.0 to produce proper 4x4 affine transforms. The parse_fbx function is a convenience alias for fbx_to_npy. A helper function _recursive_to_list converts the FBX SDK's C++ array wrappers into nested Python lists.

Usage

Use this module when importing motion capture data or skeletal animations from FBX files for use with the poselib motion retargeting and visualization system. The FBX SDK Python bindings must be installed separately. Call fbx_to_npy or parse_fbx with an FBX file path, optional root joint name, and desired FPS to extract skeleton and animation data.

Code Reference

Source Location

• Repository: IsaacGymEnvs
• File: isaacgymenvs/tasks/amp/poselib/poselib/skeleton/backend/fbx/fbx_backend.py
• Lines: 1-274

Signature

def fbx_to_npy(file_name_in, root_joint_name, fps):
    """
    Reads an FBX file and returns joint names, parent indices, local transforms, and FPS.
    """
    ...

def _get_frame_count(fbx_scene):
    """Returns (anim_range, frame_count, fps) from the FBX scene."""
    ...

def _get_animation_curve(joint, fbx_scene):
    """Returns the longest animation curve for a given joint."""
    ...

def _get_skeleton(root_joint):
    """Depth-first traversal returning (joint_list, joint_names, parents)."""
    ...

def _recursive_to_list(array):
    """Converts FBX C++ array wrappers to nested Python lists."""
    ...

def parse_fbx(file_name_in, root_joint_name, fps):
    """Convenience alias for fbx_to_npy."""
    ...

Import

from isaacgymenvs.tasks.amp.poselib.poselib.skeleton.backend.fbx.fbx_backend import fbx_to_npy, parse_fbx

I/O Contract

Inputs

Name	Type	Required	Description
file_name_in	str	Yes	Path to the input FBX file
root_joint_name	str	No	Name of the root joint to start parsing from; if empty or None, auto-detects the root by finding the first joint with an animation curve
fps	int	Yes	Desired frames per second for sampling the animation; if set to 120, uses the FBX file's native frame rate

Outputs

Name	Type	Description
joint_names	list[str]	List of joint names in depth-first traversal order
parents	list[int]	List of parent indices for each joint (-1 for root)
local_transforms	numpy.ndarray	Array of shape (num_frames, num_joints, 4, 4) containing local transformation matrices per frame per joint
fbx_fps	float	The effective frames per second used for sampling

Usage Examples

from isaacgymenvs.tasks.amp.poselib.poselib.skeleton.backend.fbx.fbx_backend import fbx_to_npy, parse_fbx

# Parse an FBX animation file
joint_names, parents, local_transforms, fps = fbx_to_npy(
    file_name_in="/path/to/motion_capture.fbx",
    root_joint_name="Hips",
    fps=30,
)

print(f"Joints: {len(joint_names)}")
print(f"Frames: {local_transforms.shape[0]}")
print(f"FPS: {fps}")

# Access the root joint transform at frame 0
root_transform_frame0 = local_transforms[0, 0]  # 4x4 matrix

# Alternatively use the convenience alias
joint_names, parents, transforms, fps = parse_fbx(
    "/path/to/animation.fbx", root_joint_name="", fps=120
)