Implementation:Facebookresearch Habitat lab Manipulator

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

Overview

Generic manipulator interface that defines a standard API for controlling a robot arm with a gripper, managing joint positions, motor settings, end-effector transforms, and camera sensors in the Habitat simulator.

Description

The Manipulator class implements the ArticulatedAgentInterface and provides a comprehensive API for controlling robots with articulated arms. Key features include:

Initialization and Configuration:

• Loads a robot from a URDF file into the Habitat simulator.
• Configures joint motors with appropriate position and velocity gains for arm and gripper joints.
• Sets up camera sensors attached to specific robot links.
• Supports fixed-base and free-base configurations.

Joint Control:

• arm_joint_pos (property): Get/set the current arm joint positions, kinematically and via motor targets.
• gripper_joint_pos (property): Get/set the current gripper joint positions.
• arm_motor_pos (property): Get/set the desired arm joint motor targets directly.
• arm_motor_forces (property): Get/set arm joint torques.
• arm_velocity (property): Read the current arm joint velocities.
• set_fixed_arm_joint_pos: Fix the arm to a desired position at every internal timestep (kinematic control).
• arm_joint_limits (property): Get upper and lower joint position limits.

Gripper Control:

• set_gripper_target_state: Set the gripper to an interpolated state between open and closed.
• open_gripper / close_gripper: Convenience methods for full open or close.
• is_gripper_open / is_gripper_closed (properties): Check gripper state within epsilon.

End-Effector:

• ee_transform: Get the transformation of the end-effector, offset from the link.
• ee_link_id: Get the Habitat Sim link ID of the end-effector.
• ee_local_offset: Get the local offset of the end-effector from its link.
• clip_ee_to_workspace: Clip a position to the reachable workspace.
• calculate_ee_forward_kinematics: Compute end-effector position from joint state.
• calculate_ee_inverse_kinematics: Placeholder for IK (not yet implemented).

Lifecycle:

• reconfigure: Load the URDF, set up joints and motors.
• update: Called each step to update camera transforms and enforce fixed joint values.
• reset: Reset joints to initial parameters.

Usage

Use the Manipulator class as the base for specific robot implementations (e.g., Fetch, Spot). It is instantiated by the agent manager and provides the control interface used by rearrangement task actions to move the arm and gripper.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-lab/habitat/articulated_agents/manipulator.py
• Lines: 1-477

Signature

class Manipulator(ArticulatedAgentInterface):
    def __init__(
        self,
        params,
        urdf_path: str,
        sim: Simulator,
        limit_robo_joints: bool = True,
        fixed_based: bool = True,
        sim_obj=None,
        maintain_link_order=False,
        auto_update_sensor_transform=True,
        **kwargs,
    ): ...

    def reconfigure(self) -> None: ...
    def update(self) -> None: ...
    def reset(self) -> None: ...

    @property
    def arm_joint_pos(self) -> np.ndarray: ...
    @arm_joint_pos.setter
    def arm_joint_pos(self, ctrl: List[float]): ...

    @property
    def gripper_joint_pos(self) -> np.ndarray: ...
    @gripper_joint_pos.setter
    def gripper_joint_pos(self, ctrl: List[float]): ...

    @property
    def arm_joint_limits(self) -> Tuple[np.ndarray, np.ndarray]: ...

    def ee_transform(self, ee_index: int = 0) -> mn.Matrix4: ...
    def ee_link_id(self, ee_index: int = 0) -> int: ...
    def ee_local_offset(self, ee_index: int = 0) -> mn.Vector3: ...
    def clip_ee_to_workspace(self, pos: np.ndarray, ee_index: int = 0) -> np.ndarray: ...

    def set_gripper_target_state(self, gripper_state: float) -> None: ...
    def open_gripper(self) -> None: ...
    def close_gripper(self) -> None: ...

    @property
    def is_gripper_open(self) -> bool: ...
    @property
    def is_gripper_closed(self) -> bool: ...

    def set_fixed_arm_joint_pos(self, fix_arm_joint_pos): ...
    def calculate_ee_forward_kinematics(self, joint_state: np.ndarray, ee_index: int = 0) -> np.ndarray: ...
    def calculate_ee_inverse_kinematics(self, ee_target_position: np.ndarray, ee_index: int = 0) -> np.ndarray: ...

Import

from habitat.articulated_agents.manipulator import Manipulator

I/O Contract

Inputs

Name	Type	Required	Description
params	object	Yes	Robot parameters object containing arm_joints, gripper_joints, ee_links, ee_offset, motor gains, init params, camera configs, etc.
urdf_path	str	Yes	File path to the robot URDF model
sim	Simulator	Yes	Habitat simulator instance
limit_robo_joints	bool	No	Whether to auto-clamp joint limits after physics steps (default True)
fixed_based	bool	No	Whether the robot base is fixed in place (default True)
sim_obj	object	No	Pre-existing articulated object; if None, loaded from URDF
maintain_link_order	bool	No	Whether to preserve link order from the URDF (default False)
auto_update_sensor_transform	bool	No	Whether to automatically update sensor transforms (default True)

Outputs

Name	Type	Description
arm_joint_pos	np.ndarray	Current arm joint position values
gripper_joint_pos	np.ndarray	Current gripper joint position values
ee_transform()	mn.Matrix4	End-effector 4x4 transformation matrix in world space
arm_joint_limits	Tuple[np.ndarray, np.ndarray]	Lower and upper joint position limits for the arm

Usage Examples

Basic Arm Control

import numpy as np
from habitat.articulated_agents.manipulator import Manipulator

# Assuming robot_params and sim are already configured
manipulator = Manipulator(
    params=robot_params,
    urdf_path="data/robots/fetch/fetch.urdf",
    sim=sim,
)
manipulator.reconfigure()

# Set arm to a desired configuration
target_joint_pos = np.array([0.0, -0.5, 0.0, 1.0, 0.0, 0.5, 0.0])
manipulator.arm_joint_pos = target_joint_pos

# Get the current end-effector position
ee_transform = manipulator.ee_transform(ee_index=0)
ee_position = ee_transform.translation

Gripper Control

# Open the gripper fully
manipulator.open_gripper()

# Check if the gripper is open
if manipulator.is_gripper_open:
    print("Gripper is open")

# Close the gripper
manipulator.close_gripper()

# Set gripper to 50% closed
manipulator.set_gripper_target_state(0.5)