# Camera & Tracking Quick Reference

## 🚀 快速开始

### 最简单的用法（推荐）

```bash
# Chase模式跟踪机器人 + 录制视频
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --camera-track chase \
    --max-steps 500
```

## 📷 Track Modes一览

| 模式 | 命令 | 效果 |
|------|------|------|
| 🎬 Chase | `--camera-track chase` | 电影追逐镜头（后方上方） |
| 🎮 Follow | `--camera-track follow` | 第三人称游戏视角 |
| 👁️ Side | `--camera-track side` | 侧面跟随 |
| 🦅 Top | `--camera-track top` | 俯视跟随 |
| 👤 First Person | `--camera-track first_person` | 第一人称视角 |
| 📍 Static | `--camera-track static` | 静态镜头（不跟随） |

## 💻 常用命令

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

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

### 高分辨率录制
```bash
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --camera-track chase \
    --camera-res 1920 1080 \
    --video-fps 60 \
    --max-steps 1000
```

### 只渲染不录制（调试）
```bash
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --camera-track chase \
    --max-steps 100
```

### 自定义视角
```bash
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --camera-track custom \
    --camera-pos -4.0 1.0 3.0 \
    --camera-lookat 0.0 0.0 0.5 \
    --max-steps 1000
```

## 🔧 关键参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--camera-track` | chase | 跟踪模式 |
| `--camera-res` | 1920 1080 | 分辨率 |
| `--video-fps` | 60 | 视频帧率 |
| `--video-path` | output/amo_mesh_terrain.mp4 | 输出路径 |
| `--camera-entity` | robot | 跟踪的entity |
| `--camera-fov` | (自动) | 视野角度 |

## 📝 编程用法

### 基础配置
```python
from genesislab.engine.scene import CameraCfg, RecordingCfg

# Chase模式跟踪
cfg.scene.camera = CameraCfg(
    track_mode="chase",
    entity_name="robot",
    res=(1920, 1080),
)

cfg.scene.recording = RecordingCfg(
    enabled=True,
    save_path="output/video.mp4",
    fps=60,
)
```

### 完全自定义
```python
cfg.scene.camera = CameraCfg(
    entity_name="robot",
    link_name="pelvis",
    pos=(-3.0, 0.0, 2.5),   # robot local frame
    lookat=(1.0, 0.0, 0.5),
    fov=50.0,
)
```

### 禁用camera
```python
cfg.scene.camera = None
cfg.scene.recording = None
```

## 🎯 推荐配置

### 展示视频（高质量）
```bash
--camera-track chase \
--camera-res 1920 1080 \
--video-fps 60
```

### 调试（快速）
```bash
--camera-track chase \
--camera-res 640 480
# 不加 --record-video
```

### 步态分析
```bash
--camera-track side \
--camera-res 1280 720 \
--video-fps 60
```

### 导航演示
```bash
--camera-track first_person \
--camera-res 1280 720 \
--video-fps 30
```

## 📚 完整文档

- **[CAMERA_TRACKING_GUIDE.md](CAMERA_TRACKING_GUIDE.md)** - 完整使用指南
- **[CAMERA_TRACKING_IMPLEMENTATION.md](CAMERA_TRACKING_IMPLEMENTATION.md)** - 实现细节
- **[CAMERA_RECORDING_EXAMPLE.md](CAMERA_RECORDING_EXAMPLE.md)** - Camera和Recording基础

## 🧪 测试

```bash
# 配置测试
python test_camera_tracking.py

# 实际运行测试
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless --record-video --camera-track chase --max-steps 300
```

## ❓ 常见问题

**Q: Camera不跟随机器人？**
- 检查 `--camera-track` 不是 `static` 或 `custom`
- 确认 `--camera-entity robot` 正确

**Q: 视频文件在哪？**
- 默认：`output/amo_mesh_terrain.mp4`
- 自定义：`--video-path` 参数

**Q: 如何更改分辨率？**
```bash
--camera-res 1920 1080  # Full HD
--camera-res 1280 720   # HD
--camera-res 640 480    # SD (最快)
```

**Q: 想要更远的视角？**
```bash
--camera-track chase \
--camera-pos -5.0 0.0 4.0  # 更远更高
```

## 🎨 视角对比

```
chase:        后方3.5m, 上方2.5m  (电影感)
follow:       后方2.0m, 上方1.8m  (游戏感)
side:         侧面3.0m, 上方1.5m  (分析)
top:          正上方5.0m          (俯瞰)
first_person: 机器人视角          (沉浸感)
static:       固定位置            (全局)
```

## ⚡ 性能提示

- **分辨率** ↑ → 质量 ↑，速度 ↓
- **FPS** ↑ → 流畅度 ↑，速度 ↓
- **Codec preset**:
  - `veryfast` - 快速编码（默认）
  - `medium` - 平衡
  - `slow` - 高质量，慢

调试时用低分辨率，最终渲染用高分辨率！