# Camera Tracking Guide - 机器人跟踪摄像机

## 概述

GenesisLab的camera系统现在支持**将camera attach到机器人上**，实现跟随拍摄功能。Camera会在机器人的frame下运动，跟随机器人一起移动。

## 快速开始

### 1. 追逐镜头（Chase Camera）- 推荐

最常用的跟踪模式，镜头在机器人后方上方，拍摄效果类似电影追逐镜头：

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

### 2. 其他跟踪模式

```bash
# 跟随镜头（更近，肩后视角）
--camera-track follow

# 侧面视角
--camera-track side

# 俯视视角
--camera-track top

# 第一人称视角
--camera-track first_person

# 静态镜头（不跟随）
--camera-track static
```

## 跟踪模式详解

### Chase（追逐镜头）⭐ 推荐
- **位置**：机器人后方 3.5m，上方 2.5m
- **视角**：向前看
- **FOV**: 50°
- **效果**：电影感十足的追逐镜头
- **适用**：展示、演示视频、宣传片

```python
camera=CameraCfg(
    track_mode="chase",
    entity_name="robot",
)
```

### Follow（跟随镜头）
- **位置**：机器人正后方 2.0m，略微侧面，高度 1.8m
- **视角**：肩后视角，向前看
- **FOV**: 45°
- **效果**：类似第三人称游戏视角
- **适用**：更近距离观察机器人动作

```python
camera=CameraCfg(
    track_mode="follow",
    entity_name="robot",
)
```

### Side（侧面视角）
- **位置**：机器人侧面 3.0m，高度 1.5m
- **视角**：从侧面观察
- **FOV**: 45°
- **效果**：观察机器人步态、侧向动作
- **适用**：步态分析、侧面展示

```python
camera=CameraCfg(
    track_mode="side",
    entity_name="robot",
)
```

### Top（俯视镜头）
- **位置**：机器人正上方 5.0m
- **视角**：向下俯视
- **FOV**: 60°
- **效果**：鸟瞰视角
- **适用**：路径规划、地形导航展示

```python
camera=CameraCfg(
    track_mode="top",
    entity_name="robot",
)
```

### First Person（第一人称）
- **位置**：机器人头部/躯干（pelvis link）
- **视角**：向前看
- **FOV**: 75°（广角）
- **效果**：机器人的"眼睛"视角
- **适用**：导航、感知任务展示

```python
camera=CameraCfg(
    track_mode="first_person",
    entity_name="robot",
)
```

### Static（静态镜头）
- **位置**：世界坐标系固定位置
- **视角**：固定方向
- **效果**：不跟随机器人，固定视角
- **适用**：观察全局场景

```python
camera=CameraCfg(
    track_mode="static",
    entity_name=None,  # 不attach到entity
)
```

## 高级用法

### 自定义跟踪参数

可以在使用track_mode的同时，微调camera位置：

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

### 完全自定义Entity-Attached Camera

不使用预设，完全手动配置：

```python
camera=CameraCfg(
    entity_name="robot",      # Attach到robot
    link_name="pelvis",       # Attach到pelvis link
    pos=(-2.5, 1.0, 2.0),    # 在link local frame中的偏移
    lookat=(1.0, 0.0, 0.5),  # 在link local frame中的目标方向
    fov=50.0,
    backend="rasterizer",
)
```

**坐标系说明**：
- 当 `entity_name` 设置时，`pos` 和 `lookat` 是在**entity的local frame**中
- 对于人形机器人（如G1）：
  - +X: 向前
  - +Y: 向左
  - +Z: 向上
  - 所以 `pos=(-3.0, 0.0, 2.0)` 表示：后方3m，上方2m

### Attach到特定Link

```python
# Attach到头部
camera=CameraCfg(
    entity_name="robot",
    link_name="head",         # 或你的机器人的头部link名称
    pos=(0.1, 0.0, 0.05),    # 头部前方
    lookat=(1.0, 0.0, 0.0),  # 向前看
    fov=75.0,
)

# Attach到手部
camera=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,                 # 广角
)
```

## 命令行使用示例

### 基础跟踪录制

```bash
# Chase模式（默认）
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --video-path output/chase.mp4 \
    --camera-track chase \
    --max-steps 1000

# First person视角
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --video-path output/first_person.mp4 \
    --camera-track first_person \
    --max-steps 1000

# 侧面跟踪
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --video-path output/side.mp4 \
    --camera-track side \
    --max-steps 1000
```

### 微调跟踪参数

```bash
# Chase模式，但更高的视角
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --camera-track chase \
    --camera-fov 60 \
    --max-steps 1000
```

### 完全自定义

```bash
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --camera-track custom \
    --camera-pos -3.0 0.5 2.5 \
    --camera-lookat 0.0 0.0 0.5 \
    --camera-fov 50 \
    --max-steps 1000
```

## 编程使用

### 在Task Config中配置

```python
from genesislab.envs import ManagerBasedRlEnvCfg
from genesislab.engine.scene import SceneCfg, CameraCfg, RecordingCfg

@configclass
class MyTaskEnvCfg(ManagerBasedRlEnvCfg):
    scene: SceneCfg = SceneCfg(
        num_envs=1,
        viewer=False,
        # 使用chase跟踪模式
        camera=CameraCfg(
            res=(1920, 1080),
            track_mode="chase",
            entity_name="robot",
        ),
        recording=RecordingCfg(
            enabled=True,
            save_path="output/training_demo.mp4",
            fps=60,
        ),
    )
```

### 运行时修改（在create_env_cfg中）

```python
def create_amo_mesh_terrain_env_config(args, ...):
    cfg = AmoGenesisEnvCfg()

    # 配置chase camera跟踪机器人
    cfg.scene.camera = CameraCfg(
        res=(1920, 1080),
        track_mode="chase",
        entity_name="robot",  # 跟踪名为"robot"的entity
    )

    # 可选：录制视频
    if args.record_video:
        cfg.scene.recording = RecordingCfg(
            enabled=True,
            save_path=args.video_path,
            fps=60,
        )

    return cfg
```

## 技术细节

### Camera Attachment原理

1. **Entity Index**：找到要attach的entity的索引
2. **Link Index**：在entity内找到要attach的link索引
3. **Local Frame**：Camera的pos/lookat在link的local frame中
4. **自动跟随**：每个simulation step，camera自动跟随link运动

### 坐标变换

Camera的位置通过以下变换计算：
```
camera_world_pos = link_world_transform * camera_local_pos
```

所以camera会：
- 跟随link的平移
- 跟随link的旋转
- 保持相对link的固定offset

### 查找可用Links

如果不确定entity有哪些links：

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

常见的人形机器人links：
- `pelvis`, `base_link`, `torso` - 躯干
- `head` - 头部
- `left_hand`, `right_hand` - 手
- `left_foot`, `right_foot` - 脚

## 性能考虑

- **Rasterizer backend**（默认）：快速，适合实时跟踪
- **Entity attachment**：几乎无额外开销（Genesis原生支持）
- **分辨率影响**：
  - 1920x1080: 适合高质量视频，略微降低速度
  - 1280x720: 平衡质量和速度
  - 640x480: 最快，适合调试

## 常见问题

### Q: Camera不跟随机器人？

检查：
1. 是否设置了 `entity_name="robot"`
2. Entity名称是否正确（默认是"robot"）
3. 是否在scene build之后设置camera

### Q: Camera视角奇怪？

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

### Q: 如何让camera"看向"机器人？

如果想要camera在世界坐标系某个位置，但"看向"移动的机器人：
```python
# 这需要自定义实现，暂不支持
# 当前的lookat也是在entity local frame中
```

### Q: 支持多个camera吗？

当前实现每个scene支持一个camera。如果需要多个camera，需要手动使用Genesis API：
```python
cam1 = scene.gs_scene.add_sensor(gs.sensors.RasterizerCameraOptions(...))
cam2 = scene.gs_scene.add_sensor(gs.sensors.RasterizerCameraOptions(...))
```

## 示例视频效果对比

| Track Mode | 视角描述 | 适用场景 |
|------------|---------|---------|
| `chase` | 电影追逐镜头，远距离跟随 | 展示、宣传片 |
| `follow` | 肩后视角，中距离跟随 | 第三人称游戏风格 |
| `side` | 侧面跟随 | 步态分析 |
| `top` | 俯视跟随 | 路径规划 |
| `first_person` | 第一人称视角 | 导航、感知任务 |
| `static` | 固定不动 | 全局场景观察 |

## 下一步

1. 尝试不同的track_mode
2. 录制对比视频
3. 根据任务选择最佳视角
4. 微调camera参数以获得最佳效果