Implementation:Facebookresearch Habitat lab HumanoidBaseController

Knowledge Sources	Facebookresearch_Habitat_lab
Domains	Embodied_AI, Humanoid_Animation
Last Updated	2026-02-15 00:00 GMT

Overview

HumanoidBaseController is a generic controller class for replaying SMPL-X humanoid motions, providing data structures for poses and sequential motions along with base transform management.

Description

This module defines three core classes for humanoid animation control in Habitat:

• Pose -- Represents a single humanoid pose consisting of a global root transform (as a 4x4 matrix) and joint rotations in quaternion format. It assumes a SMPL-X representation where all joints are represented as quaternions.

• Motion -- Represents a sequential motion as a sequence of Pose objects. It stores the number of poses, frames-per-second, and a displacement vector that measures the linear displacement per pose, which is used to determine how many poses to advance for a given translation distance.

• HumanoidBaseController -- The main controller class that manages the global transformation of the humanoid base and the transformation caused by walking gait. It maintains two transformation matrices (offset and base), a list of joint poses, and provides methods to reset the agent and retrieve a vectorized pose suitable for passing to HumanoidJointAction.

A module-level constant BASE_HUMANOID_OFFSET (default mn.Vector3(0, 0.9, 0)) defines the default offset from the root of the character to its feet.

Usage

Use HumanoidBaseController as a base class for specific humanoid controllers (such as HumanoidSeqPoseController) that need to replay pre-recorded SMPL-X motions. The controller is instantiated with a motion FPS and base offset, then reset with an initial transformation before calling get_pose() to obtain the joint state for simulation.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-lab/habitat/articulated_agent_controllers/humanoid_base_controller.py
• Lines: 1-118

Signature

class Pose:
    def __init__(
        self,
        joints_quat: Union[List[float], np.ndarray],
        root_transform: mn.Matrix4,
    ) -> None:

class Motion:
    def __init__(
        self,
        joints_quat_array: np.ndarray,
        transform_array: np.ndarray,
        displacement: mn.Vector3,
        fps: int,
    ) -> None:

class HumanoidBaseController:
    def __init__(
        self,
        motion_fps: int = 30,
        base_offset: mn.Vector3 = BASE_HUMANOID_OFFSET,
    ):

Import

from habitat.articulated_agent_controllers.humanoid_base_controller import (
    HumanoidBaseController,
    Pose,
    Motion,
    BASE_HUMANOID_OFFSET,
)

I/O Contract

Inputs (HumanoidBaseController.__init__)

Name	Type	Required	Description
motion_fps	int	No (default=30)	The frames per second at which the motion should be played back
base_offset	mn.Vector3	No (default=BASE_HUMANOID_OFFSET)	The offset between the root of the character and their feet

Inputs (Pose.__init__)

Name	Type	Required	Description
joints_quat	Union[List[float], np.ndarray]	Yes	List or array of num_joints * 4 elements with rotation quaternions
root_transform	mn.Matrix4	Yes	4x4 matrix with the root transform

Inputs (Motion.__init__)

Name	Type	Required	Description
joints_quat_array	np.ndarray	Yes	Array of shape (num_poses, num_joints, 4) containing joint orientations
transform_array	np.ndarray	Yes	Array of shape (num_poses, 4, 4) containing root transforms
displacement	mn.Vector3	Yes	Linear displacement per pose for measuring translation distance
fps	int	Yes	Frames per second at which the motion was recorded

Outputs

Name	Type	Description
get_pose()	List[float]	Vectorized form of joint poses, offset transform, and base transform suitable for HumanoidJointAction

Usage Examples

Basic Usage

import magnum as mn
import numpy as np
from habitat.articulated_agent_controllers.humanoid_base_controller import (
    HumanoidBaseController,
    Pose,
    Motion,
)

# Create a single pose with 4 joints (16 quaternion values)
joints = np.zeros(16)  # 4 joints x 4 quaternion components
root_transform = mn.Matrix4.identity_init()
pose = Pose(joints_quat=joints, root_transform=root_transform)

# Create a controller and reset it
controller = HumanoidBaseController(motion_fps=30)
base_transform = mn.Matrix4.identity_init()
controller.reset(base_transform)

# Get the vectorized pose for simulation
vectorized_pose = controller.get_pose()

Related Pages

• Facebookresearch_Habitat_lab_HumanoidSeqPoseController