Basic Concepts - 基本概念#

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

Camera系统#

Camera vs Sensor#

Genesis有两种camera API：

Regular Camera#

camera = scene.add_camera(pos=..., lookat=...)

  • 用于：静态camera

  • API: camera.render() 返回 (rgb, depth, seg, normal)

  • 位置：世界坐标系固定位置

Sensor Camera#

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（如机器人）运动：

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时提供的函数，每步调用获取数据：

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）：

@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配置类：

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

SceneCfg扩展#

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

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

Headless Mode#

Headless模式：无viewer窗口运行：

--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自动保存

下一步#