# Basic Concepts - 基本概念

理解GenesisLab camera和recording系统的核心概念。

## Camera系统

### Camera vs Sensor

Genesis有两种camera API：

#### Regular Camera
```python
camera = scene.add_camera(pos=..., lookat=...)
```
- 用于：静态camera
- API: `camera.render()` 返回 `(rgb, depth, seg, normal)`
- 位置：世界坐标系固定位置

#### Sensor Camera
```python
camera = scene.add_sensor(gs.sensors.RasterizerCameraOptions(...))
```
- 用于：Entity-attached camera（跟随机器人）
- API: `camera.read()` 返回 `data.rgb`, `data.depth` 等
- 位置：相对entity的local frame

**GenesisLab自动选择**：根据是否配置`entity_name`自动选择合适的API。

### Entity Attachment

**Entity-attached camera**会跟随entity（如机器人）运动：

```python
CameraCfg(
    entity_name="robot",    # Attach到名为"robot"的entity
    link_name="pelvis",     # Attach到pelvis link（可选）
    pos=(-3.0, 0.0, 2.5),  # 在entity local frame的偏移
)
```

#### Local Frame坐标系

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

所以`pos=(-3.0, 0.0, 2.5)`表示：
- 后方3米
- 上方2.5米

### Track Modes

预设的camera视角模式：

| Mode | 位置 | 用途 |
|------|------|------|
| `chase` | 后方3.5m, 上方2.5m | 电影追逐镜头 |
| `follow` | 后方2m, 侧面0.5m, 高1.8m | 第三人称游戏 |
| `side` | 侧面3m, 高1.5m | 步态分析 |
| `top` | 正上方5m | 俯视导航 |
| `first_person` | pelvis位置 | 第一人称视角 |
| `static` | 世界坐标系 | 固定camera |

## Recording系统

### VideoFileWriter

Genesis的video recorder：
- 期望数据格式：`[H, W, 3]`（RGB图像）
- 编码：默认H.264 (libx264)
- 自动在每个`scene.step()`时调用data_func

### Data Function

Recording时提供的函数，每步调用获取数据：

```python
def data_func():
    data = camera.read()
    # 返回RGB图像 [H, W, 3]
    return data.rgb[0]  # [0]取第一个环境
```

### Multi-Environment处理

对于多环境场景（`num_envs > 1`）：
- Camera返回：`[n_envs, H, W, 3]`
- VideoWriter期望：`[H, W, 3]`
- **解决**：取第一个环境 `rgb[0]`

## Camera Backends

Genesis提供3种renderer backend：

### Rasterizer（默认）
- **速度**：⚡ 快
- **质量**：中等
- **适用**：默认选择，实时渲染，调试
- **API**: `gs.sensors.RasterizerCameraOptions`

### Raytracer
- **速度**：🐌 慢
- **质量**：高（光线追踪）
- **适用**：高质量渲染，最终展示
- **限制**：单环境only
- **API**: `gs.sensors.RaytracerCameraOptions`

### BatchRenderer
- **速度**：⚡⚡ 超快（GPU并行）
- **质量**：中等
- **适用**：大规模RL训练（数千环境）
- **限制**：所有camera必须同分辨率
- **API**: `gs.sensors.BatchRendererCameraOptions`

## Configuration Classes

### CameraCfg

Camera配置类（使用`@configclass`）：

```python
@configclass
class CameraCfg:
    res: tuple[int, int]           # 分辨率
    pos: tuple[float, float, float]  # 位置
    lookat: tuple[float, float, float]  # 目标
    fov: float                      # 视野
    entity_name: Optional[str]      # Entity名称
    link_name: Optional[str]        # Link名称
    track_mode: Optional[str]       # 预设模式
    backend: str                    # Backend选择
```

### RecordingCfg

Recording配置类：

```python
@configclass
class RecordingCfg:
    enabled: bool                   # 启用/禁用
    save_path: str                  # 输出路径
    fps: int                        # 帧率
    codec: str                      # 编码器
    codec_preset: str               # 编码速度
```

### SceneCfg扩展

Scene配置增加了camera和recording字段：

```python
@configclass
class SceneCfg:
    # ... 其他字段 ...
    camera: CameraCfg = None        # Camera配置（可选）
    recording: RecordingCfg = None  # Recording配置（可选）
```

## Headless Mode

**Headless模式**：无viewer窗口运行：

```bash
--headless  # 不显示viewer
# 但camera仍然渲染和录制！
```

- Camera在后台渲染（offscreen）
- 不影响recording功能
- 适合服务器、批量任务

## 工作流程

### Scene Build时

1. Scene build完成
2. 检查`cfg.camera`是否配置
3. 如果配置了：
   - 创建camera（static或attached）
   - 如果`cfg.recording.enabled=True`：启动recording
   - 设置data_func

### Simulation运行时

每个`scene.step()`：
1. 物理仿真更新
2. Recorder manager调用data_func
3. Camera渲染当前帧
4. 写入video file

### 结束时

- Recording自动停止
- Video file自动保存

## 下一步

- 查看[Camera配置指南](../user_guide/camera/configuration.md)学习详细配置
- 查看[Robot Tracking指南](../user_guide/camera/tracking.md)学习跟踪功能
- 查看[API参考](../api_reference/)了解所有参数