Robot Tracking - 机器人跟踪

完整的camera跟随机器人功能指南。

概述

Camera可以attach到机器人上，在机器人的local frame下运动，实现自动跟随拍摄。

核心特性

• ✅ 6种预设模式 - chase/follow/side/top/first_person/static

• ✅ 自动跟随 - Camera跟随entity运动和旋转

• ✅ 灵活配置 - 使用预设或完全自定义

• ✅ Headless支持 - 无需viewer即可跟踪录制

快速开始

Chase模式（推荐）

最常用的跟踪模式，电影感十足：

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

编程方式：

from genesislab.engine.scene import CameraCfg

cfg.scene.camera = CameraCfg(
    track_mode="chase",
    entity_name="robot",
)

Track Modes详解

1. Chase - 追逐镜头 ⭐

电影追逐镜头，后方上方视角

• 位置：机器人后方3.5m，上方2.5m

• 视角：向前看

• FOV: 50°

• 效果：电影感强烈的追逐镜头

使用场景：

• ✅ 展示视频

• ✅ 宣传片

• ✅ Demo演示

命令行：

--camera-track chase

编程：

CameraCfg(track_mode="chase", entity_name="robot")

坐标：

• pos=(-3.5, 0.0, 2.5) - robot local frame

• lookat=(1.0, 0.0, 0.5) - 向前看

2. Follow - 跟随镜头

第三人称游戏视角，肩后视角

• 位置：机器人后方2m，略微侧面，高1.8m

• 视角：肩后向前

• FOV: 45°

• 效果：类似第三人称游戏

使用场景：

• ✅ 更近距离观察

• ✅ 第三人称游戏风格

• ✅ 精细动作展示

命令行：

--camera-track follow

坐标：

• pos=(-2.0, 0.5, 1.8)

• lookat=(1.0, 0.0, 0.8)

3. Side - 侧面视角

侧面跟随，步态分析

• 位置：机器人侧面3m，高1.5m

• 视角：从侧面观察

• FOV: 45°

• 效果：清晰观察侧向动作

使用场景：

• ✅ 步态分析

• ✅ 侧向动作观察

• ✅ 技术分析

命令行：

--camera-track side

坐标：

• pos=(0.0, -3.0, 1.5) - 右侧3m

• lookat=(0.0, 0.5, 0.8) - 向内看

4. Top - 俯视视角

正上方俯视，鸟瞰视角

• 位置：机器人正上方5m

• 视角：向下俯视

• FOV: 60°（广角）

• 效果：鸟瞰全局

使用场景：

• ✅ 路径规划展示

• ✅ 地形导航

• ✅ 全局位置观察

命令行：

--camera-track top

坐标：

• pos=(0.0, 0.0, 5.0)

• lookat=(0.5, 0.0, -1.0) - 向下看

5. First Person - 第一人称

机器人的”眼睛”视角

• 位置：pelvis link位置，略微上方

• 视角：向前看

• FOV: 75°（广角）

• 效果：沉浸式第一人称

使用场景：

• ✅ 导航任务展示

• ✅ 感知任务

• ✅ 机器人视角体验

命令行：

--camera-track first_person

坐标：

• pos=(0.0, 0.0, 0.2) - pelvis上方

• lookat=(1.0, 0.0, 0.0) - 向前

• link_name="pelvis" - 附加到pelvis

6. Static - 静态镜头

世界坐标系固定位置

• 位置：世界坐标系 (5.0, 0.0, 3.0)

• 视角：固定方向

• 效果：不跟随，观察全局

使用场景：

• ✅ 全局场景观察

• ✅ 多机器人交互

• ✅ 固定视角需求

命令行：

--camera-track static

编程：

CameraCfg(
    track_mode="static",
    entity_name=None,  # 不attach
)

自定义配置

微调预设

在预设基础上微调参数：

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

命令行：

--camera-track chase \
--camera-pos -4.0 0.5 3.0 \
--camera-fov 55

完全自定义

不使用预设，手动指定所有参数：

CameraCfg(
    entity_name="robot",
    link_name="pelvis",
    pos=(-2.5, 1.0, 2.0),    # 自定义偏移
    lookat=(1.0, 0.0, 0.5),  # 自定义目标
    fov=50.0,
    backend="rasterizer",
)

命令行：

--camera-track custom \
--camera-pos -2.5 1.0 2.0 \
--camera-lookat 1.0 0.0 0.5

Attach到特定Link

常见Links

人形机器人常见的links：

• pelvis / base_link / torso - 躯干

• head - 头部（如果有）

• left_hand / right_hand - 手部

• left_foot / right_foot - 脚部

查找可用Links

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

示例：Attach到头部

CameraCfg(
    entity_name="robot",
    link_name="head",         # 头部
    pos=(0.1, 0.0, 0.05),    # 头前方
    lookat=(1.0, 0.0, 0.0),  # 向前看
    fov=75.0,                 # 广角
)

示例：Attach到手部

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,                 # 更广角
)

坐标系理解

Robot Local Frame

对于人形机器人（如G1）：

• +X: 前方（前进方向）

• +Y: 左侧

• +Z: 上方

位置示例

位置	X	Y	Z	说明
正前方	+3.0	0	0	前方3m
正后方	-3.0	0	0	后方3m
左侧	0	+3.0	0	左侧3m
右侧	0	-3.0	0	右侧3m
正上方	0	0	+3.0	上方3m
后上方	-3.0	0	+2.5	后方3m、上方2.5m

Lookat方向

lookat也在local frame中，通常使用单位向量表示方向：

方向	X	Y	Z	说明
向前看	+1.0	0	0	向前
向后看	-1.0	0	0	向后
向左看	0	+1.0	0	向左
向右看	0	-1.0	0	向右
向下看	0	0	-1.0	向下

命令行完整示例

生成对比视频

#!/bin/bash
# 录制所有track mode的对比视频

for mode in chase follow side top first_person static; do
    echo "Recording $mode mode..."
    python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
        --headless \
        --record-video \
        --camera-track $mode \
        --video-path output/${mode}.mp4 \
        --camera-res 1280 720 \
        --max-steps 500
done

echo "All videos recorded in output/"
ls -lh output/*.mp4

高质量chase录制

python third_party/genPiHub/scripts/amo/genesislab/play_amo_mesh_terrain.py \
    --headless \
    --record-video \
    --camera-track chase \
    --video-path output/chase_hq.mp4 \
    --camera-res 1920 1080 \
    --video-fps 60 \
    --max-steps 2000

最佳实践

选择Track Mode

目标	推荐模式	原因
展示视频	chase	电影感强，视觉效果好
技术分析	side或top	清晰观察动作细节
导航演示	first_person	展示机器人视角
调试开发	chase或follow	全面观察状态
多机器人	static	观察全局交互

性能优化

• 调试时：低分辨率 --camera-res 640 480

• 展示时：高分辨率 --camera-res 1920 1080

• Backend: rasterizer（默认）最快

视频质量

• 帧率: 60fps流畅，30fps省空间

• 编码: veryfast快速，slow高质量

• 分辨率: 1080p展示，720p平衡，480p调试

故障排查

Camera不跟随机器人？

检查：

1. ✅ 设置了 entity_name="robot"

2. ✅ Entity名称正确（默认是”robot”）

3. ✅ Track mode不是”static”

4. ✅ 不是”custom”模式（custom需要手动设置entity_name）

Camera视角奇怪？

• 检查pos是否在entity local frame中

• 对于人形机器人，+X是前方，-X是后方

• 尝试使用预设的track_mode

想要camera在世界坐标系某位置但”看向”机器人？

当前不直接支持。Lookat也是在entity local frame中。

可以使用static mode设置camera在世界坐标系，但lookat也是固定的。

下一步

• 查看Configuration Guide了解所有配置选项

• 查看Examples查看实际示例

• 查看API Reference了解API详情