chore: release v0.1.0

(cherry picked from commit 82525f882f3924a332d9ce40bf64255d0d14f6a4)
This commit is contained in:
motphys-developers
2026-01-04 04:43:04 +00:00
parent 13cfbce9a7
commit 62011bb24f
390 changed files with 18897 additions and 626 deletions

View File

@@ -0,0 +1,130 @@
# 乒乓球颠球
使用单臂机器人控制挡板颠球,实现连续弹跳并保持球在目标位置。
```{video} /_static/videos/bounce_ball.mp4
:poster: _static/images/poster/bounce_ball.jpg
:nocontrols:
:autoplay:
:playsinline:
:muted:
:loop:
:width: 100%
```
## 任务描述
Bounce Ball 是一个单臂机器人操作任务,使用 6 自由度的配天 AIR4-560 工业机械臂控制末端挡板(球拍)的位置。智能体通过控制机械臂 6 个关节的位置变化作为动作,使乒乓球在挡板上持续弹跳,并尽可能将球保持在目标高度和目标水平位置。
---
## 动作空间Action Space
| 项目 | 详细信息 |
| -------- | ------------------------------- |
| **类型** | `Box(-1.0, 1.0, (6,), float32)` |
| **维度** | 6 |
关节对应如下:
| 序号 | 动作含义(关节位置变化) | 最小值 | 最大值 | 对应 XML 中名称 |
| ---: | -------------------------- | :----: | :----: | :-------------: |
| 0 | Joint1基座旋转位置变化 | -1 | 1 | `Joint1` |
| 1 | Joint2大臂位置变化 | -1 | 1 | `Joint2` |
| 2 | Joint3小臂位置变化 | -1 | 1 | `Joint3` |
| 3 | Joint4手腕旋转位置变化 | -1 | 1 | `Joint4` |
| 4 | Joint5手腕俯仰位置变化 | -1 | 1 | `Joint5` |
| 5 | Joint6手腕旋转位置变化 | -1 | 1 | `Joint6` |
---
## 观察空间
| 项目 | 详细信息 |
| -------- | -------------------------------- |
| **类型** | `Box(-inf, inf, (25,), float32)` |
| **维度** | 25 |
观察空间由以下部分组成(按顺序):
| 部分 | 内容说明 | 维度 | 备注 |
| ----------- | -------------------- | ---- | --------------------------------------------------------------- |
| **dof_pos** | 各关节自由度位置信息 | 13 | 前 6 个为机械臂关节,后 7 个为球的自由关节3 位置 + 4 四元数) |
| **dof_vel** | 各关节自由度速度信息 | 12 | 速度为位置导数 |
| 序号 | 观察量 | 最小值 | 最大值 | XML 名称 | 类型 (单位) |
| ----- | -------------- | ------ | ------ | ----------- | ---------------- |
| 0-5 | 机械臂关节角度 | -Inf | Inf | Joint1-6 | 角度 (rad) |
| 6 | 球 x 坐标 | -Inf | Inf | ball_x | 位置 (m) |
| 7 | 球 y 坐标 | -Inf | Inf | ball_y | 位置 (m) |
| 8 | 球 z 坐标 | -Inf | Inf | ball_z | 位置 (m) |
| 9-12 | 球姿态四元数 | -Inf | Inf | ball_qw/xyz | 四元数 (w,x,y,z) |
| 13-24 | 关节和球速度 | -Inf | Inf | - | 速度/角速度 |
---
## 奖励函数设计
奖励函数由以下几个部分组成:
```python
# 位置控制奖励:保持球在挡板中心上方
# 受控向上速度奖励:在球位置良好时奖励适中的向上速度
# 高度精度奖励:球接近目标高度
# 连续弹跳奖励:奖励连续成功的弹跳
# 总奖励 = 各项加权组合
```
---
## 初始状态
- **机械臂初始位置**[0, 40, 110, 0, -60, 0] 度,带有随机噪声
- **球的初始位置**:挡板中心上方,带有随机噪声
- **球的初始速度**[0.0, 0.0, 0.0] m/s
---
## Episode 终止条件
- **球掉落**:球的 z 坐标 < 0.05m(接近地面)
- **球过高**:球的 z 坐标 > 目标高度 + 1.0m(失去控制)
- **水平偏离过远**:球的 x 坐标绝对值 > 1.5m
---
## 使用指南
### 1. 环境预览
```bash
uv run scripts/view.py --env bounce_ball
```
### 2. 开始训练
```bash
uv run scripts/train.py --env bounce_ball
```
### 3. 查看训练进度
```bash
uv run tensorboard --logdir runs/bounce_ball
```
### 4. 测试训练结果
```bash
uv run scripts/play.py --env bounce_ball
```
---
## 预期训练结果
1. 连续弹跳:能够实现 3 次以上的连续弹跳
2. 位置控制球的水平位置x 坐标)稳定在目标位置 ± 0.05m 范围内
3. 高度控制:球的高度稳定在目标高度 0.8 ± 0.1m 范围内
4. 速度控制球的向上速度保持在合理范围0.1-1.5 m/s
5. 稳定控制:能够持续 20 秒的稳定弹跳而不掉落