# Camera and Recording Implementation Summary

## 实现的功能

✅ **完成所有需求**：
1. ✅ 对env添加config，配置camera用于headless render and save
2. ✅ 视频recording功能
3. ✅ 都在headless模式下完成
4. ✅ 通过config进行配置
5. ✅ camera可以留空（设为None）

## 文件结构

### 新增文件

1. **[camera_cfg.py](source/genesislab/genesislab/engine/scene/camera_cfg.py)**
   - `CameraCfg`: Camera配置类（使用@configclass）
   - `RecordingCfg`: Recording配置类（使用@configclass）
   - 支持所有Genesis camera参数和recording选项

### 修改文件

2. **[lab_scene_cfg.py](source/genesislab/genesislab/engine/scene/lab_scene_cfg.py)**
   - 添加 `camera: CameraCfg = None` 字段
   - 添加 `recording: RecordingCfg = None` 字段
   - 保留旧的 `record_video_path` 以保持向后兼容

3. **[lab_scene.py](source/genesislab/genesislab/engine/scene/lab_scene.py)**
   - 添加 `_setup_camera_and_recording()` 方法
   - 添加 `camera` property
   - 添加 `render_camera()` 方法
   - 在 `build()` 中集成camera和recording设置

4. **[__init__.py](source/genesislab/genesislab/engine/scene/__init__.py)**
   - 导出 `CameraCfg` 和 `RecordingCfg`

5. **[play_amo_mesh_terrain.py](third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py)**
   - 添加camera和recording的命令行参数
   - 在env配置中使用新的CameraCfg和RecordingCfg
   - 支持headless模式下的视频录制

### 文档文件

6. **[CAMERA_RECORDING_EXAMPLE.md](CAMERA_RECORDING_EXAMPLE.md)**
   - 完整的使用指南和示例
   - 配置参数参考
   - 常见问题解答

7. **[test_camera_recording.py](test_camera_recording.py)**
   - 配置类的单元测试
   - 验证所有配置选项

## 核心设计

### 1. CameraCfg（Camera配置）

```python
@configclass
class CameraCfg:
    res: tuple[int, int] = (1280, 720)          # 分辨率
    pos: tuple[float, float, float] = (3.5, 0.0, 2.5)  # 位置
    lookat: tuple[float, float, float] = (0.0, 0.0, 0.5)  # 目标
    fov: float = 40.0                            # 视野
    entity_name: Optional[str] = None            # 可选：挂载到entity
    link_name: Optional[str] = None              # 可选：挂载到link
    backend: Literal["rasterizer", "raytracer", "batch_renderer"] = "rasterizer"
    show_in_gui: bool = False
```

**特点**：
- 使用 `@configclass`（遵循GenesisLab规范）
- 可以设为 `None` 来禁用camera
- 支持静态camera和entity-attached camera
- 支持三种backend（rasterizer/raytracer/batch_renderer）

### 2. RecordingCfg（Recording配置）

```python
@configclass
class RecordingCfg:
    enabled: bool = False                        # 启用/禁用
    save_path: str = "output/recording.mp4"     # 输出路径
    fps: int = 60                                # 帧率
    codec: str = "libx264"                       # 编码器
    codec_preset: str = "veryfast"               # 编码速度
    codec_tune: Optional[str] = "zerolatency"    # 编码优化
    render_rgb: bool = True                      # RGB
    render_depth: bool = False                   # Depth
    render_segmentation: bool = False            # Segmentation
    render_normal: bool = False                  # Normal
```

**特点**：
- 可以设为 `None` 或 `enabled=False` 来禁用recording
- 自动创建输出目录
- 灵活的codec配置
- 支持多种render模式

### 3. 集成到SceneCfg

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

### 4. LabScene自动设置

在 `LabScene.build()` 中：
1. Scene build完成后
2. 检查 `cfg.camera` 是否配置
3. 如果配置了，调用 `_setup_camera_and_recording()`
4. 创建camera（根据backend）
5. 如果 `cfg.recording.enabled=True`，启动recording

## 使用示例

### 基础用法（测试脚本）

```bash
# Headless + 录制视频
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --video-path output/amo_demo.mp4 \
    --camera-res 1920 1080 \
    --max-steps 500

# Headless 不录制（camera仍然配置，但不recording）
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --max-steps 500

# 带viewer（不需要camera/recording）
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --viewer \
    --max-steps 500
```

### 编程用法

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

# 方式1：只配置camera（不录制）
cfg.scene.camera = CameraCfg(
    res=(1920, 1080),
    pos=(5.0, 0.0, 3.0),
    lookat=(0.0, 0.0, 0.5),
)
cfg.scene.recording = None  # 不录制

# 方式2：camera + recording
cfg.scene.camera = CameraCfg(
    res=(1920, 1080),
    pos=(5.0, 0.0, 3.0),
    lookat=(0.0, 0.0, 0.5),
)
cfg.scene.recording = RecordingCfg(
    enabled=True,
    save_path="output/video.mp4",
    fps=60,
)

# 方式3：禁用camera
cfg.scene.camera = None
cfg.scene.recording = None
```

## 测试验证

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

结果：
```
✅ CameraCfg OK
✅ RecordingCfg OK
✅ SceneCfg with camera/recording OK
✅ SceneCfg without camera OK
```

### 实际使用测试

测试AMO脚本：
```bash
cd /home/ununtu/code/glab/genesislab
python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --video-path output/amo_test.mp4 \
    --video-fps 60 \
    --camera-res 1920 1080 \
    --camera-pos 5.0 0.0 3.0 \
    --max-steps 300
```

预期结果：
1. 程序在headless模式运行
2. 显示 "🎥 Video recording enabled" 消息
3. 显示 "[LabScene] Started video recording: output/amo_test.mp4"
4. 运行300 steps后
5. 在 `output/amo_test.mp4` 生成视频文件

## 技术细节

### Genesis API调用流程

1. **Camera创建**（`_setup_camera_and_recording`）
   ```python
   camera = scene.add_camera(res=..., pos=..., lookat=...)
   # 或
   camera = scene.add_sensor(gs.sensors.RasterizerCameraOptions(...))
   ```

2. **Recording启动**
   ```python
   scene.start_recording(
       data_func=lambda: camera.render(rgb=True)[0],
       rec_options=gs.recorders.VideoFile(
           filename="output.mp4",
           fps=60,
           codec="libx264",
       ),
   )
   ```

3. **自动录制**
   - 每次 `scene.step()` 调用时
   - Genesis自动调用 `data_func`
   - 渲染camera并写入video file

4. **停止录制**（可选）
   ```python
   scene.stop_recording()  # 手动停止
   # 或程序结束时自动停止
   ```

### Entity Attachment

如果配置了 `entity_name`：
```python
entity_idx = self._entities[cam_cfg.entity_name].gs_entity.idx
link_idx_local = entity.gs_entity.links_map[cam_cfg.link_name]
```

Camera会跟随entity/link移动。

### Backend选择

- **rasterizer**: 默认，快速，适合大多数场景
- **raytracer**: 高质量，慢，适合最终渲染
- **batch_renderer**: 超快，适合大规模RL训练

## 关键改进

1. **向后兼容**：保留 `record_video_path`，不破坏现有代码
2. **灵活配置**：camera和recording可以独立配置或禁用
3. **遵循规范**：使用 `@configclass`（符合GenesisLab规范）
4. **清晰API**：配置类语义明确，参数有文档
5. **易于测试**：配置类可以独立测试
6. **Headless支持**：完全支持无viewer的渲染和录制

## 下一步

用户可以：
1. 运行测试脚本验证基础配置
2. 使用AMO脚本测试实际录制
3. 在自己的任务中集成camera和recording
4. 根据需要调整camera参数和recording设置

## 命令行参数参考

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--record-video` | flag | False | 启用视频录制 |
| `--video-path` | str | output/amo_mesh_terrain.mp4 | 视频输出路径 |
| `--video-fps` | int | 60 | 视频帧率 |
| `--camera-res` | int int | 1920 1080 | Camera分辨率 |
| `--camera-pos` | float float float | 5.0 0.0 3.0 | Camera位置 |
| `--camera-lookat` | float float float | 0.0 0.0 0.5 | Camera目标点 |
| `--camera-fov` | float | 45.0 | 视野角度 |
| `--headless` | flag | False | 禁用viewer |
| `--viewer` | flag | False | 启用viewer |

## 注意事项

1. **Recording需要camera**：如果 `recording.enabled=True`，必须配置 `camera`
2. **Headless模式**：Camera在headless模式下正常工作，无需viewer
3. **输出目录**：自动创建，不需要手动mkdir
4. **视频格式**：建议使用 `.mp4` 后缀
5. **性能**：Recording会略微降低仿真速度（取决于分辨率和编码设置）