Implementation:ARISE Initiative Robosuite HumanoidModel
| Knowledge Sources | |
|---|---|
| Domains | Robotics, Robot Modeling, Humanoid Robots |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
The HumanoidModel class is the abstract base class for all full-body humanoid robot models in robosuite, providing gripper management, end-effector name resolution, and the interface contract for humanoid-specific properties.
Description
HumanoidModel extends RobotModel to define the shared behavior and interface for full-body humanoid robots. It manages bimanual gripper attachment through the add_gripper method, which merges a gripper model into the robot's MJCF tree at the appropriate end-effector body. The class tracks grippers in an OrderedDict keyed by arm name and prevents duplicate gripper attachments.
During initialization, the class extracts hand rotation offsets for both the right and left arms from the XML model, converting the quaternion from wxyz to xyzw format. It also collects all camera names defined in the robot's worldbody. The eef_name property returns naming-prefix-adjusted end-effector names, while models returns the complete list of sub-models including all attached grippers.
The class defines several abstract properties that all humanoid subclasses must implement: default_gripper, arm_type, base_xpos_offset, top_offset, _horizontal_radius, default_controller_config, and init_qpos. It provides a default mount type of "HumanoidFreeMount" and defaults the _eef_name to "right_hand".
Usage
Do not instantiate this class directly. Instead, create subclasses for specific humanoid robots that implement all required abstract properties. Use it as the base class when defining new humanoid robot models for robosuite.
Code Reference
Source Location
Signature
class HumanoidModel(RobotModel):
def __init__(self, fname, idn=0)
def add_gripper(self, gripper, arm_name=None)
Import
from robosuite.models.robots.manipulators.humanoid_model import HumanoidModel
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| fname | str | Yes | Path to the MJCF XML file for this robot |
| idn | int or str | No | Unique identification number or string (default: 0) |
| gripper | GripperModel | Yes (add_gripper) | Gripper MJCF model to mount on the arm |
| arm_name | str | No (add_gripper) | Name of arm mount body; defaults to eef_name |
Outputs
| Name | Type | Description |
|---|---|---|
| eef_name | str or dict | Prefix-adjusted end-effector name(s); dict for bimanual robots |
| models | list | List of all sub-models including the robot and attached grippers |
| grippers | OrderedDict | Dictionary of attached gripper models keyed by arm name |
| hand_rotation_offset | dict | Quaternion offsets (xyzw) for right and left hand frames |
| cameras | list | Camera names defined in the robot's worldbody |
| default_mount | str | "HumanoidFreeMount" |
Usage Examples
from robosuite.models.robots.manipulators.humanoid_model import HumanoidModel
# HumanoidModel is abstract - use a concrete subclass instead
# Example: defining a custom humanoid
class MyHumanoid(HumanoidModel):
arms = ["right", "left"]
def __init__(self, idn=0):
super().__init__("path/to/my_humanoid.xml", idn=idn)
@property
def default_gripper(self):
return {"right": "PandaGripper", "left": "PandaGripper"}
@property
def arm_type(self):
return "bimanual"
@property
def base_xpos_offset(self):
return {"bins": (0, 0, 0), "empty": (0, 0, 0),
"table": lambda l: (0, 0, 0)}
# ... implement other required abstract properties