# Robot Tracking - 机器人跟踪

完整的camera跟随机器人功能指南。

## 概述

Camera可以**attach到机器人**上，在机器人的local frame下运动，实现自动跟随拍摄。

### 核心特性

- ✅ **6种预设模式** - chase/follow/side/top/first_person/static
- ✅ **自动跟随** - Camera跟随entity运动和旋转
- ✅ **灵活配置** - 使用预设或完全自定义
- ✅ **Headless支持** - 无需viewer即可跟踪录制

## 快速开始

### Chase模式（推荐）

最常用的跟踪模式，电影感十足：

```bash
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --camera-track chase \
    --max-steps 500
```

编程方式：

```python
from genesislab.engine.scene import CameraCfg

cfg.scene.camera = CameraCfg(
    track_mode="chase",
    entity_name="robot",
)
```

## Track Modes详解

### 1. Chase - 追逐镜头 ⭐

**电影追逐镜头，后方上方视角**

- **位置**：机器人后方3.5m，上方2.5m
- **视角**：向前看
- **FOV**: 50°
- **效果**：电影感强烈的追逐镜头

**使用场景**：
- ✅ 展示视频
- ✅ 宣传片
- ✅ Demo演示

**命令行**：
```bash
--camera-track chase
```

**编程**：
```python
CameraCfg(track_mode="chase", entity_name="robot")
```

**坐标**：
- `pos=(-3.5, 0.0, 2.5)` - robot local frame
- `lookat=(1.0, 0.0, 0.5)` - 向前看

### 2. Follow - 跟随镜头

**第三人称游戏视角，肩后视角**

- **位置**：机器人后方2m，略微侧面，高1.8m
- **视角**：肩后向前
- **FOV**: 45°
- **效果**：类似第三人称游戏

**使用场景**：
- ✅ 更近距离观察
- ✅ 第三人称游戏风格
- ✅ 精细动作展示

**命令行**：
```bash
--camera-track follow
```

**坐标**：
- `pos=(-2.0, 0.5, 1.8)`
- `lookat=(1.0, 0.0, 0.8)`

### 3. Side - 侧面视角

**侧面跟随，步态分析**

- **位置**：机器人侧面3m，高1.5m
- **视角**：从侧面观察
- **FOV**: 45°
- **效果**：清晰观察侧向动作

**使用场景**：
- ✅ 步态分析
- ✅ 侧向动作观察
- ✅ 技术分析

**命令行**：
```bash
--camera-track side
```

**坐标**：
- `pos=(0.0, -3.0, 1.5)` - 右侧3m
- `lookat=(0.0, 0.5, 0.8)` - 向内看

### 4. Top - 俯视视角

**正上方俯视，鸟瞰视角**

- **位置**：机器人正上方5m
- **视角**：向下俯视
- **FOV**: 60°（广角）
- **效果**：鸟瞰全局

**使用场景**：
- ✅ 路径规划展示
- ✅ 地形导航
- ✅ 全局位置观察

**命令行**：
```bash
--camera-track top
```

**坐标**：
- `pos=(0.0, 0.0, 5.0)`
- `lookat=(0.5, 0.0, -1.0)` - 向下看

### 5. First Person - 第一人称

**机器人的"眼睛"视角**

- **位置**：pelvis link位置，略微上方
- **视角**：向前看
- **FOV**: 75°（广角）
- **效果**：沉浸式第一人称

**使用场景**：
- ✅ 导航任务展示
- ✅ 感知任务
- ✅ 机器人视角体验

**命令行**：
```bash
--camera-track first_person
```

**坐标**：
- `pos=(0.0, 0.0, 0.2)` - pelvis上方
- `lookat=(1.0, 0.0, 0.0)` - 向前
- `link_name="pelvis"` - 附加到pelvis

### 6. Static - 静态镜头

**世界坐标系固定位置**

- **位置**：世界坐标系 (5.0, 0.0, 3.0)
- **视角**：固定方向
- **效果**：不跟随，观察全局

**使用场景**：
- ✅ 全局场景观察
- ✅ 多机器人交互
- ✅ 固定视角需求

**命令行**：
```bash
--camera-track static
```

**编程**：
```python
CameraCfg(
    track_mode="static",
    entity_name=None,  # 不attach
)
```

## 自定义配置

### 微调预设

在预设基础上微调参数：

```python
CameraCfg(
    track_mode="chase",       # 使用chase预设
    entity_name="robot",
    pos=(-4.0, 0.5, 3.0),    # 覆盖位置（更远、更高、略微偏右）
    fov=55.0,                 # 覆盖FOV
)
```

命令行：
```bash
--camera-track chase \
--camera-pos -4.0 0.5 3.0 \
--camera-fov 55
```

### 完全自定义

不使用预设，手动指定所有参数：

```python
CameraCfg(
    entity_name="robot",
    link_name="pelvis",
    pos=(-2.5, 1.0, 2.0),    # 自定义偏移
    lookat=(1.0, 0.0, 0.5),  # 自定义目标
    fov=50.0,
    backend="rasterizer",
)
```

命令行：
```bash
--camera-track custom \
--camera-pos -2.5 1.0 2.0 \
--camera-lookat 1.0 0.0 0.5
```

## Attach到特定Link

### 常见Links

人形机器人常见的links：
- `pelvis` / `base_link` / `torso` - 躯干
- `head` - 头部（如果有）
- `left_hand` / `right_hand` - 手部
- `left_foot` / `right_foot` - 脚部

### 查找可用Links

```python
# 在env初始化后
entity = env.scene.entities["robot"]
links = entity.gs_entity.links_map
print("Available links:", list(links.keys()))
```

### 示例：Attach到头部

```python
CameraCfg(
    entity_name="robot",
    link_name="head",         # 头部
    pos=(0.1, 0.0, 0.05),    # 头前方
    lookat=(1.0, 0.0, 0.0),  # 向前看
    fov=75.0,                 # 广角
)
```

### 示例：Attach到手部

```python
CameraCfg(
    entity_name="robot",
    link_name="right_hand",   # 右手
    pos=(0.05, 0.0, 0.0),     # 手前方
    lookat=(0.2, 0.0, 0.0),   # 向前
    fov=90.0,                 # 更广角
)
```

## 坐标系理解

### Robot Local Frame

对于人形机器人（如G1）：
- **+X**: 前方（前进方向）
- **+Y**: 左侧
- **+Z**: 上方

### 位置示例

| 位置 | X | Y | Z | 说明 |
|------|---|---|---|------|
| 正前方 | +3.0 | 0 | 0 | 前方3m |
| 正后方 | -3.0 | 0 | 0 | 后方3m |
| 左侧 | 0 | +3.0 | 0 | 左侧3m |
| 右侧 | 0 | -3.0 | 0 | 右侧3m |
| 正上方 | 0 | 0 | +3.0 | 上方3m |
| 后上方 | -3.0 | 0 | +2.5 | 后方3m、上方2.5m |

### Lookat方向

`lookat`也在local frame中，通常使用单位向量表示方向：

| 方向 | X | Y | Z | 说明 |
|------|---|---|---|------|
| 向前看 | +1.0 | 0 | 0 | 向前 |
| 向后看 | -1.0 | 0 | 0 | 向后 |
| 向左看 | 0 | +1.0 | 0 | 向左 |
| 向右看 | 0 | -1.0 | 0 | 向右 |
| 向下看 | 0 | 0 | -1.0 | 向下 |

## 命令行完整示例

### 生成对比视频

```bash
#!/bin/bash
# 录制所有track mode的对比视频

for mode in chase follow side top first_person static; do
    echo "Recording $mode mode..."
    python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
        --headless \
        --record-video \
        --camera-track $mode \
        --video-path output/${mode}.mp4 \
        --camera-res 1280 720 \
        --max-steps 500
done

echo "All videos recorded in output/"
ls -lh output/*.mp4
```

### 高质量chase录制

```bash
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --camera-track chase \
    --video-path output/chase_hq.mp4 \
    --camera-res 1920 1080 \
    --video-fps 60 \
    --max-steps 2000
```

## 最佳实践

### 选择Track Mode

| 目标 | 推荐模式 | 原因 |
|------|---------|------|
| 展示视频 | chase | 电影感强，视觉效果好 |
| 技术分析 | side或top | 清晰观察动作细节 |
| 导航演示 | first_person | 展示机器人视角 |
| 调试开发 | chase或follow | 全面观察状态 |
| 多机器人 | static | 观察全局交互 |

### 性能优化

- **调试时**：低分辨率 `--camera-res 640 480`
- **展示时**：高分辨率 `--camera-res 1920 1080`
- **Backend**: rasterizer（默认）最快

### 视频质量

- **帧率**: 60fps流畅，30fps省空间
- **编码**: veryfast快速，slow高质量
- **分辨率**: 1080p展示，720p平衡，480p调试

## 故障排查

### Camera不跟随机器人？

检查：
1. ✅ 设置了 `entity_name="robot"`
2. ✅ Entity名称正确（默认是"robot"）
3. ✅ Track mode不是"static"
4. ✅ 不是"custom"模式（custom需要手动设置entity_name）

### Camera视角奇怪？

- 检查pos是否在entity local frame中
- 对于人形机器人，+X是前方，-X是后方
- 尝试使用预设的track_mode

### 想要camera在世界坐标系某位置但"看向"机器人？

当前不直接支持。Lookat也是在entity local frame中。

可以使用static mode设置camera在世界坐标系，但lookat也是固定的。

## 下一步

- 查看[Configuration Guide](configuration.md)了解所有配置选项
- 查看[Examples](../../examples/robot_tracking.md)查看实际示例
- 查看[API Reference](../../api_reference/camera_cfg.md)了解API详情