# 乒乓球颠球

使用单臂机器人控制挡板颠球，实现连续弹跳并保持球在目标位置。

```{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 秒的稳定弹跳而不掉落