File size: 12,319 Bytes
b1cfd82
 
 
 
 
 
 
 
 
 
 
 
 
22e686c
 
b1cfd82
 
 
 
 
 
 
729853d
 
 
 
b1cfd82
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
a68b945
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b1cfd82
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
---
license: apache-2.0
pipeline_tag: robotics
library_name: limx-dynamics
tags:
- robotics
- humanoid
- urdf
- mjcf
- usd
- mujoco
- isaac-sim
- ros
- legged-robots
- biped
- limx-dynamics
- oli
language:
- en
- zh
---

[![Open in Spaces](https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-md.svg)](https://huggingface.co/spaces/limxdynamics/oli-teleop)

**Try it in your browser / 在浏览器里试试**: [Oli Teleop](https://huggingface.co/spaces/limxdynamics/oli-teleop) loads the `HU_D04_01` MuJoCo model from this repo and drives it with the official walking and greeting policies, right in the browser, no install. 打开网页就能用键盘遥控 Oli、让它挥手打招呼,用的就是本仓库的 MuJoCo 模型,无需安装。

> **中文说明**:LimX Oli(型号 HU_D04)人形机器人的机器人描述文件,包含 URDF / MJCF / USD 模型与网格,可直接用于 MuJoCo、Isaac Sim、ROS 等仿真与开发。本仓库镜像自 GitHub [limxdynamics/humanoid-description](https://github.com/limxdynamics/humanoid-description)。快速查看:`python -m mujoco.viewer --mjcf=<path-to-xml>`。问题与合作请联系 opensource@limxdynamics.com。
>
> Mirrored as-is from [limxdynamics/humanoid-description](https://github.com/limxdynamics/humanoid-description). Download: `hf download limxdynamics/oli-description`

<p align="center">
  <img src="docs/images/banner.png" alt="humanoid-description: the LimX Oli humanoid HU_D04 in its base, gripper and dexterous-hand variants" width="100%">
</p>

<div align="center">

**English** | [中文](README_cn.md)

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![ROS](https://img.shields.io/badge/ROS-1%20%7C%202-22314E?logo=ros)](#ros-1--ros-2)
[![MuJoCo](https://img.shields.io/badge/MuJoCo-MJCF-0A7BBB)](#mujoco-30-seconds)
[![Isaac Sim](https://img.shields.io/badge/Isaac%20Sim-USD-76B900?logo=nvidia&logoColor=white)](#isaac-sim--isaac-lab)
[![Hugging Face](https://img.shields.io/badge/Hugging%20Face-limxdynamics-FFD21E?logo=huggingface&logoColor=black)](https://huggingface.co/limxdynamics)
[![WeChat Community](https://img.shields.io/badge/WeChat-Developer%20Community-07C160?logo=wechat&logoColor=white)](https://github.com/limxdynamics/limxdynamics/blob/main/doc/wechat_qr.png)

<p align="center"><sub>For partnership and procurement inquiries, contact <a href="mailto:opensource@limxdynamics.com">opensource@limxdynamics.com</a></sub></p>

# LimX Humanoid Description

> **Part of the Oli humanoid open-source ecosystem.** Where to start and the other Oli repositories: [Oli quick start](https://github.com/limxdynamics/limxdynamics/blob/main/doc/quickstart.md#oli).

**Simulation-ready models of a real, full-size humanoid robot — in URDF, MuJoCo MJCF and USD.**

Drop the LimX Oli humanoid (HU_D04) into ROS, MuJoCo or NVIDIA Isaac Sim in minutes, with real actuator parameters and the true parallel-linkage ankles.

[Models](#robot-models) · [Quick Start](#quick-start) · [Specs](#specifications) · [Ecosystem](#ecosystem) · [Citation](#citation)

</div>

---

## Highlights

- **One robot, three formats** — matching URDF, MJCF and USD for the same hardware, so you can train in Isaac Lab, validate in MuJoCo and deploy with ROS without rebuilding the model.
- **Up to 53 joints** — 31-DoF base humanoid (legs, 3-DoF waist, 7-DoF arms, 2-DoF head), plus gripper and 11-joint dexterous hand variants.
- **Real parallel ankles & waist** — the MJCF drives the ankles and waist through their actual A/B push-rod linkages, closed with equality constraints, instead of an idealized serial approximation.
- **Real actuator data** — the SRDF lists rotor inertia and gear ratio for every joint, which matters for accurate sim-to-real transfer.
- **Sim-ready out of the box** — MJCF ships with 31 torque actuators, an IMU (orientation, gyro, accelerometer) and 65 sensors; USD is layered into base / physics / sensor for Isaac Sim.
- **Commercial-friendly** — Apache 2.0.

## Robot models

| | Type | Model | Joints | Formats |
|:-:|---|---|:-:|---|
| <img src="docs/images/hu_d04.png" width="260"> | **HU_D04** full-size humanoid | `HU_D04_01` | 31 | URDF · MJCF · USD |
| <img src="docs/images/hu_d04_gripper.png" width="260"> | **HU_D04 + Gripper** | `HU_D04_01_with_gripper` | 39<br><sub>35 independent</sub> | URDF · USD |
| <img src="docs/images/hu_d04_hand.png" width="260"> | **HU_D04 + Dexterous Hand** | `HU_D04_01_with_hand` | 53<br><sub>43 independent</sub> | URDF · USD |
| <img src="docs/images/hu_d03.png" width="260"> | HU_D03 *(discontinued)* | `HU_D03_03` | 31 | URDF · MJCF · USD |

> **Note:** MuJoCo MJCF is currently provided for the base HU_D04 only. HU_D03 is no longer maintained — please use HU_D04 for new projects.

## Quick Start

```bash
git clone --depth 1 https://github.com/limxdynamics/humanoid-description.git
cd humanoid-description
```

> `--depth 1` is recommended — the meshes and USD files make the full history large.

### MuJoCo (30 seconds)

```bash
pip install mujoco
python -m mujoco.viewer --mjcf=HU_D04_description/xml/HU_D04_01.xml
```

Or load it from Python:

```python
import mujoco

model = mujoco.MjModel.from_xml_path("HU_D04_description/xml/HU_D04_01.xml")
data = mujoco.MjData(model)
print(f"{model.nu} actuators, {model.nsensor} sensors")   # 31 actuators, 65 sensors

for _ in range(1000):
    data.ctrl[:] = 0.0          # joint torques (N·m) — plug in your controller here
    mujoco.mj_step(model, data)
```

> `HU_D04_01.xml` is the full simulation model (actuators, sensors, closed-loop linkages). `HU_D04_01_vis.xml` is a lightweight visualization-only version.

### ROS 1 / ROS 2

Clone into your workspace and build — each `HU_D0x_description` folder is a ROS package that works with both catkin and colcon:

```bash
cd ~/ros_ws/src
git clone --depth 1 https://github.com/limxdynamics/humanoid-description.git
cd ..
catkin_make        # ROS 1
colcon build       # ROS 2
```

View in RViz (ROS 1, requires `urdf_tutorial`):

```bash
roslaunch urdf_tutorial display.launch model:=$(rospack find HU_D04_description)/urdf/HU_D04_01.urdf
```

View in RViz (ROS 2):

```bash
URDF=$(ros2 pkg prefix HU_D04_description)/share/HU_D04_description/urdf/HU_D04_01.urdf
ros2 run robot_state_publisher robot_state_publisher --ros-args -p robot_description:="$(cat $URDF)" &
ros2 run joint_state_publisher_gui joint_state_publisher_gui &
rviz2   # Add → RobotModel, set Fixed Frame to base_link
```

### Isaac Sim / Isaac Lab

Open `HU_D04_description/usd/HU_D04_01.usd` directly in Isaac Sim (**File → Open**), or add it to your stage as a reference. The top-level USD composes the layers in `usd/configuration/` automatically (`sensor → physics → base`), so keep that folder next to it.

For RL training, see [humanoid-rl-isaaclab](https://github.com/limxdynamics/humanoid-rl-isaaclab), which uses these models out of the box.

## Specifications

Values below are read from the HU_D04 model files.

| | HU_D04 |
| --- | --- |
| Height (model) | ≈ 1.65 m |
| Mass (URDF, base model) | ≈ 52.5 kg |
| Legs | 2 × 6 DoF (hip pitch / roll / yaw, knee, ankle pitch / roll) |
| Waist | 3 DoF (yaw / roll / pitch) |
| Arms | 2 × 7 DoF (shoulder pitch / roll / yaw, elbow, wrist yaw / pitch / roll) |
| Head | 2 DoF (yaw / pitch) |
| Dexterous hand | 11 joints / 6 independent per hand |
| Parallel linkages | Ankles (A/B push-rods) and waist roll / pitch |

<details>
<summary><b>Joint limits & actuator parameters (click to expand)</b></summary>

<br>

Left side shown; the right side mirrors it.

| Joint | Range (°) | Torque (N·m) | Velocity (rad/s) | Gear ratio |
| --- | --- | --- | --- | --- |
| hip_pitch | −150 ~ 150 | 140 | 5 | 25 |
| hip_roll | −50 ~ 120 | 140 | 5 | 25 |
| hip_yaw | −150 ~ 150 | 140 | 5 | 25 |
| knee | −5 ~ 148 | 140 | 5 | 25 |
| ankle_pitch | −58 ~ 35 | 42 | 13.6 | 36 |
| ankle_roll | −25 ~ 25 | 42 | 13.6 | 36 |
| waist_yaw | −150 ~ 150 | 42 | 13.6 | 36 |
| waist_roll | −30 ~ 30 | 42 | 13.6 | 36 |
| waist_pitch | −30 ~ 45 | 42 | 13.6 | 36 |
| shoulder_pitch | −160 ~ 160 | 42 | 19.6 | 25 |
| shoulder_roll | −5 ~ 185 | 42 | 19.6 | 25 |
| shoulder_yaw | −195 ~ 90 | 42 | 19.6 | 25 |
| elbow | −140 ~ 90 | 42 | 19.6 | 25 |
| wrist_yaw / pitch / roll | −135 ~ 45 / −90 ~ 90 / −90 ~ 90 | 19 | 13 | 28.17 |
| head_yaw / pitch | −45 ~ 45 / −30 ~ 45 | 19 | 13 | 28.17 |

Rotor inertia for each joint is in `urdf/HU_D04_01.srdf`.

</details>

## Repository Structure

```
humanoid-description/
├── HU_D04_description/          # ROS package (catkin + ament)
│   ├── urdf/                    # URDF variants + SRDF (rotor inertia, gear ratio)
│   ├── xml/                     # MuJoCo MJCF (full sim + visualization-only)
│   ├── usd/                     # Isaac Sim USD + configuration/ layers
│   ├── meshes/                  # STL meshes
│   ├── world/                   # Gazebo (SDF) empty world
│   ├── CMakeLists.txt
│   └── package.xml
└── HU_D03_description/          # Legacy model, same layout
```

## Ecosystem

These models are the foundation of LimX's open humanoid stack — train a policy, verify it in a second simulator, then deploy it:

| Repository | What it does |
| --- | --- |
| [humanoid-rl-isaaclab](https://github.com/limxdynamics/humanoid-rl-isaaclab) | Train locomotion policies in Isaac Lab |
| [humanoid-mujoco-sim](https://github.com/limxdynamics/humanoid-mujoco-sim) | MuJoCo simulator for the humanoid |
| [humanoid-rl-deploy-ros](https://github.com/limxdynamics/humanoid-rl-deploy-ros) | Deploy RL policies with ROS 1 |
| [humanoid-rl-deploy-ros2](https://github.com/limxdynamics/humanoid-rl-deploy-ros2) | Deploy RL policies with ROS 2 |

## Verification

Checked on 2026-11-02 with MuJoCo 3.x and Python:

- All four MJCF files load. `HU_D04_01.xml` has 31 actuators, 65 sensors and 6 equality constraints (the ankle and waist linkages); `HU_D04_01_vis.xml` has 31 joints and no actuators.
- Every mesh referenced by the three HU_D04 URDFs and the HU_D03 URDF exists under `meshes/`; four `../meshes/` paths in `HU_D04_01_with_hand.urdf` were changed to `package://` so they also resolve in ROS.
- Joint counts in the table above (31 / 39 with 4 mimic / 53 with 10 mimic), the joint limits, torques, velocities and gear ratios match the URDF and SRDF files. Height is measured from the MJCF model.
- `HU_D04_01_with_hand.urdf` does not load in MuJoCo's URDF importer as is: the ten `*_tip_link` frames carry a 1 g mass with an inertia of 1.6e-15 kg·m², below MuJoCo's minimum. ROS and Isaac Sim are not affected by this check.
- ROS builds and Isaac Sim loading were not run in this pass.

## Citation

If these models help your research, please cite:

```bibtex
@misc{limx_humanoid_description,
  title        = {LimX Humanoid Description: URDF, MJCF and USD Models for LimX Humanoid Robots},
  author       = {{LimX Dynamics}},
  year         = {2025},
  howpublished = {\url{https://github.com/limxdynamics/humanoid-description}}
}
```

## Research using LimX Oli / 使用 LimX Oli 的研究

Papers that use LimX Oli, collected in [Awesome LimX](https://github.com/limxdynamics/awesome-limx). Each title links to the paper page on Hugging Face.

| Paper | Authors | Year |
| --- | --- | --- |
| [FastStair](https://huggingface.co/papers/2601.10365) | HIT, LimX et al. | 2026 |
| [VAPS](https://huggingface.co/papers/2610.01397) | TU Darmstadt, LimX et al. | 2026 |
| [Any2Any](https://huggingface.co/papers/2605.23733) | LimX | 2026 |
| [Timo](https://huggingface.co/papers/2609.30761) | LimX | 2026 |
| [CWI](https://huggingface.co/papers/2606.27676) | LimX, HKU et al. | 2026 |
| [HWAM](https://huggingface.co/papers/2610.12026) | LimX | 2026 |
| [GA-PHL](https://huggingface.co/papers/2512.07464) | USTC, LimX et al. | 2025 |
| [PvP](https://huggingface.co/papers/2512.13093) | PolyU, USTC et al. | 2025 |
| [Multi-Embodiment Retargeting](https://huggingface.co/papers/2505.20857) | SUSTech, HKUST et al. | 2025 |

Built something with LimX Oli? Add it to [Awesome LimX](https://github.com/limxdynamics/awesome-limx/blob/main/CONTRIBUTING.md).

## License

Released under the [Apache License 2.0](LICENSE).