luna-description / README.md
LimX-Gwen's picture
Add Luna Viewer Space link
62c7736 verified
|
Raw History Blame Contribute Delete
8.88 kB
---
license: apache-2.0
pipeline_tag: robotics
library_name: limx-dynamics
tags:
- robotics
- humanoid
- urdf
- mjcf
- usd
- mujoco
- isaac-sim
- ros
- limx-dynamics
- luna
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/luna-viewer)
**Try it in your browser / 在浏览器里试试**: [Luna Viewer](https://huggingface.co/spaces/limxdynamics/luna-viewer) loads the `HU_L04_01` MuJoCo model from this repo, plays back a dance from the luna-beyondmimic reference motions, and lets you pose every joint, right in the browser, no install. 打开网页就能在 3D 里看 Luna 跳舞、自己调每个关节,用的就是本仓库的 MuJoCo 模型,无需安装。
> **中文说明**:LimX Luna(型号 HU_L04)人形机器人的机器人描述文件,27 个主动关节,包含 URDF / MuJoCo MJCF / USD 模型与网格,MJCF 和闭链 USD 中建模了踝部、腰部并联机构,可直接用于 MuJoCo、Isaac Sim、ROS。本仓库镜像自 GitHub [limxdynamics/luna-description](https://github.com/limxdynamics/luna-description)。问题与合作请联系 opensource@limxdynamics.com。
>
> Mirrored as-is from [limxdynamics/luna-description](https://github.com/limxdynamics/luna-description). Download: `hf download limxdynamics/luna-description`
<div align="center">
<img src="docs/banner.png" alt="LimX Luna humanoid robot description" width="100%">
**English** | [中文](README_cn.md)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![ROS](https://img.shields.io/badge/ROS-1%20%7C%202-22314E?logo=ros)](#ros-1--2)
[![MuJoCo](https://img.shields.io/badge/MuJoCo-MJCF-0A7BBB)](#mujoco)
[![Isaac Lab](https://img.shields.io/badge/Isaac%20Sim%20%7C%20Lab-USD-76B900?logo=nvidia)](#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>
</div>
# luna-description
> **Part of the Luna humanoid open-source ecosystem.** Where to start and the other Luna repositories: [Luna quick start](https://github.com/limxdynamics/limxdynamics/blob/main/doc/quickstart.md#luna).
URDF, MuJoCo MJCF & USD models for the LimX Dynamics Luna humanoid robot (HU_L04). Provides simulation-ready robot descriptions for ROS, MuJoCo, and NVIDIA Isaac Sim / Isaac Lab.
## Highlights
- **Full-body humanoid, 27 actuated joints.** Legs, a 3-DoF waist, a 2-DoF head and 5-DoF arms, with `rotor_mass` and `gear_ratio` per joint in the SRDF.
- **Parallel linkages modeled faithfully.** The ankles and waist are driven through parallel linkages; the MJCF expresses them with `equality` constraints and `usd_parallel/` as true closed loops.
- **One robot, every simulator.** URDF for ROS, MJCF for MuJoCo, USD for Isaac Sim / Isaac Lab, all from the same geometry.
- **Ready for learning pipelines.** The MJCF ships actuators plus joint position/velocity and IMU sensors, and a kinematics-only variant for motion retargeting.
## Try it in 30 seconds
No ROS needed:
```bash
git clone https://github.com/limxdynamics/luna-description.git
cd luna-description
pip install mujoco
python -m mujoco.viewer --mjcf=HU_L04_description/xml/HU_L04_01.xml
```
## Available models
<table>
<tr>
<td align="center" width="50%"><img src="docs/model_hu_l04.png" width="400" alt="HU_L04 full body"></td>
<td align="center" width="50%"><img src="docs/model_hu_l04_parallel.png" width="400" alt="HU_L04 ankle parallel linkages"></td>
</tr>
<tr>
<td align="center"><b>HU_L04</b></td>
<td align="center"><b>HU_L04 (parallel)</b><br><sub>Ankle linkages in blue, rendered from the MJCF with a translucent shank shell</sub></td>
</tr>
</table>
| Model | Description | URDF | MuJoCo MJCF | USD |
| ----- | ----------- | ---- | ----------- | --- |
| **HU_L04** | Luna humanoid, 27 actuated joints | `urdf/HU_L04_01.urdf` | `xml/HU_L04_01.xml` | `usd/HU_L04_01.usd` |
| **HU_L04 (parallel)** | Same robot with the ankle and waist parallel linkages modeled as closed loops | — | — | `usd_parallel/HU_L04_01.usd` |
> **Note:** Luna's ankles and waist are driven through parallel linkages. URDF cannot represent closed kinematic loops, so the URDF and the matching `usd/` model use a serial approximation in which the ankle and waist joints are driven directly. The MJCF models the linkages with `equality` constraints, and `usd_parallel/` models them as true closed loops for Isaac Lab.
### Joint layout
| Group | DoF | Joints |
| ----- | :-: | ------ |
| Legs | 6 × 2 | `hip_pitch`, `hip_roll`, `hip_yaw`, `knee`, `ankle_pitch`, `ankle_roll` |
| Waist | 3 | `waist_yaw`, `waist_roll`, `waist_pitch` |
| Head | 2 | `head_yaw`, `head_pitch` |
| Arms | 5 × 2 | `shoulder_pitch`, `shoulder_roll`, `shoulder_yaw`, `elbow`, `wrist_yaw` |
| **Total** | **27** | |
Leg and arm joints are prefixed `left_` / `right_`, e.g. `left_knee_joint`.
### MJCF contents
| File | Actuators | Sensors | Parallel linkages |
| ---- | :-------: | ------- | ----------------- |
| `HU_L04_01.xml` | 27 | Joint position and velocity for all 27 joints, base IMU (orientation, gyro, accelerometer) | 6 `<connect>` constraints in `<equality>`: two per ankle, two for the waist |
| `HU_L04_01_vis.xml` | — | — | — (kinematics only, for motion retargeting) |
## Directory structure
`HU_L04_description/` contains:
| Directory | Contents |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `urdf/` | URDF + SRDF (per-joint `rotor_mass` and `gear_ratio`) |
| `xml/` | MuJoCo MJCF: `HU_L04_01.xml` (full dynamics) and `HU_L04_01_vis.xml` (kinematics only) |
| `usd/` | NVIDIA USD files, serial approximation consistent with the URDF, + `configuration/` subdirectory |
| `usd_parallel/` | NVIDIA USD files with the parallel linkages modeled as closed loops, + `configuration/` subdirectory |
| `meshes/` | STL mesh files |
| `world/` | Gazebo world file (`empty_world.world`) |
| `CMakeLists.txt` | ROS package build file |
| `package.xml` | ROS package manifest |
## Usage
### ROS 1 / 2
The description builds as the ROS package **`HU_L04_description`** on both ROS 1 (catkin) and ROS 2 (ament).
```bash
cd <workspace>/src
git clone https://github.com/limxdynamics/luna-description.git
cd ..
catkin_make # or colcon build
```
The URDF references meshes as `package://HU_L04_description/meshes/...`. Outside ROS, point your loader's package path at the repository root, or use the MJCF / USD files directly.
### MuJoCo
```bash
python -m mujoco.viewer --mjcf=HU_L04_description/xml/HU_L04_01.xml
```
For motion retargeting, load `HU_L04_01_vis.xml` instead.
### Isaac Sim / Isaac Lab
Import the USD file from `HU_L04_description/usd/HU_L04_01.usd` via Isaac Sim's reference assembly. Use `HU_L04_description/usd_parallel/HU_L04_01.usd` instead if you need the closed-loop parallel linkages.
Both `.usd` files are thin wrappers that reference the assets in the `configuration/` folder next to them, so copy the whole directory rather than the `.usd` file alone.
## Related repositories
[`luna-beyondmimic`](https://github.com/limxdynamics/luna-beyondmimic) — BeyondMimic motion tracking training for Luna (Isaac Lab).
## Research using LimX Luna / 使用 LimX Luna 的研究
Papers that use LimX Luna, collected in [Awesome LimX](https://github.com/limxdynamics/awesome-limx). Each title links to the paper page on Hugging Face.
| Paper | Authors | Year |
| --- | --- | --- |
| [Any2Any](https://huggingface.co/papers/2605.23733) | LimX | 2026 |
| [Timo](https://huggingface.co/papers/2609.30761) | LimX | 2026 |
| [WAVE-Go](https://huggingface.co/papers/2609.18193) | BIT, HKU, LimX et al. | 2026 |
Built something with LimX Luna? Add it to [Awesome LimX](https://github.com/limxdynamics/awesome-limx/blob/main/CONTRIBUTING.md).
## License
Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).