Implementation:Facebookresearch Habitat lab HumanoidRearrangeController

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

Overview

High-level humanoid controller that converts actions such as walk, turn, reach, and translate into joint positions and root transforms using motion capture data and inverse kinematics interpolation.

Description

HumanoidRearrangeController extends HumanoidBaseController to provide motion-capture-driven humanoid animation for rearrangement tasks. It loads walking motion data from a pickle file and provides several motion calculation methods:

Walking and Turning:

• calculate_walk_pose: Computes the next frame of a walking motion toward a relative target position. Handles rotation clamping (turning step amount), distance-based step sizing to prevent overshoot, and cyclic motion frame advancement. When the target is very close, it falls back to a stop pose.
• calculate_walk_pose_directional: Extended version that allows the humanoid to walk toward one position while facing a different direction (useful for backwards walking or strafing).
• calculate_turn_pose: Rotates the character toward a target without translation (calls calculate_walk_pose with distance_multiplier=0).
• calculate_stop_pose: Sets the humanoid to a stationary standing pose.
• translate_and_rotate_with_gait: Directly translates and rotates the character with gait animation, using binary search over the motion displacement curve to find the appropriate mocap frame.

Reaching (IK):

• calculate_reach_pose: Computes joint states to reach a 3D position with a specified hand using trilinear interpolation of pre-computed reaching poses.
• build_ik_vectors: Processes hand motion data into matrices of joint quaternions, root rotations, and translations for efficient interpolation.

Speed Configuration:

• set_framerate_for_linspeed: Adjusts the motion playback framerate based on desired linear speed, angular speed, and simulator control frequency.

Key constants: MIN_ANGLE_TURN (5.0 degrees), TURNING_STEP_AMOUNT (20.0 degrees), THRESHOLD_ROTATE_NOT_MOVE (20.0 degrees), DIST_TO_STOP (1e-9 meters).

Usage

Use this controller in rearrangement tasks where a humanoid agent needs realistic walking and reaching animations. Instantiate with a path to the walking pose data file. Call calculate_walk_pose each step with the relative target position from the agent's current position, then apply the resulting joint_pose and obj_transform_base to the articulated agent.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-lab/habitat/articulated_agent_controllers/humanoid_rearrange_controller.py
• Lines: 1-776

Signature

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

    def set_framerate_for_linspeed(
        self, lin_speed: float, ang_speed: float, ctrl_freq: float
    ) -> None: ...

    def calculate_stop_pose(self) -> None: ...

    def calculate_turn_pose(self, target_position: mn.Vector3) -> None: ...

    def calculate_walk_pose(
        self,
        target_position: mn.Vector3,
        distance_multiplier: float = 1.0,
    ) -> None: ...

    def calculate_walk_pose_directional(
        self,
        target_position: mn.Vector3,
        distance_multiplier: float = 1.0,
        target_dir: mn.Vector3 = None,
    ) -> None: ...

    def translate_and_rotate_with_gait(
        self, forward_delta: float, rot_delta: float
    ): ...

    def calculate_reach_pose(
        self, obj_pos: mn.Vector3, index_hand: int = 0
    ) -> None: ...

    def build_ik_vectors(
        self, hand_motion: Motion
    ) -> Tuple[List[np.ndarray], List[np.ndarray], List[np.ndarray]]: ...

Import

from habitat.articulated_agent_controllers.humanoid_rearrange_controller import (
    HumanoidRearrangeController,
)

I/O Contract

Inputs

Name	Type	Required	Description
walk_pose_path	str	Yes	Path to the pickle file containing walking motion capture data, stop pose, and optional hand reaching poses
motion_fps	int	No	Frames per second for motion playback (default 30)
base_offset	mn.Vector3	No	Offset between the character root and their feet

Outputs (calculate_walk_pose)

Name	Type	Description
self.joint_pose	List[float]	Updated joint positions (quaternions) for the current motion frame
self.obj_transform_base	mn.Matrix4	Updated root transform (position and rotation) for the humanoid base
self.obj_transform_offset	mn.Matrix4	Motion-pose-specific offset transform to combine with the base transform

Usage Examples

Walking Toward a Target

import magnum as mn
from habitat.articulated_agent_controllers.humanoid_rearrange_controller import (
    HumanoidRearrangeController,
)

controller = HumanoidRearrangeController(
    walk_pose_path="data/humanoids/humanoid_data/walking_motion.pkl",
    motion_fps=30,
)

# Set speed based on simulator frequency
controller.set_framerate_for_linspeed(
    lin_speed=1.0,    # 1 m/s
    ang_speed=1.5,    # 1.5 rad/s
    ctrl_freq=120.0,  # 120 Hz simulator
)

# Each step, provide the relative target position
relative_target = mn.Vector3(0.0, 0.0, -2.0)  # 2 meters ahead
controller.calculate_walk_pose(relative_target, distance_multiplier=1.0)

# Apply joint_pose and obj_transform_base to the articulated agent
agent.joint_positions = controller.joint_pose
agent.transformation = controller.obj_transform_base @ controller.obj_transform_offset

Reaching for an Object

# Reach with the right hand toward an object position
obj_world_pos = mn.Vector3(0.5, 1.0, -0.3)
controller.calculate_reach_pose(obj_world_pos, index_hand=1)  # 1 = right hand