背景 / Background
目前系统相机只支持静态视角:
SystemCameraCfg(motrix_env_core/src/motrix_env_core/config/scene/base.py)只有 lookat / distance / elevation / azimuth,视角在 MotrixSimRenderer.__init__(motrix_env_motrixsim/src/motrix_env_motrixsim/renderer.py)构造时设置一次,之后不随场景对象更新。
- MotrixSim
SystemCamera API(set_view / set_pose)也没有 follow/attach 能力。
用户希望 camera 能跟随 env 中的某个对象(例如 locomotion 里的机器人),目前只能在自己持有 renderer 的脚本里每帧手动 set_view,标准训练/可视化流程拿不到入口(core 的 SimRenderer 刻意不暴露渲染类型)。
方案 / Proposal
不暴露抽象 camera 对象(避免在 core 边界镜像 backend 渲染 API),改为两层:
1. 声明式 follow 配置(覆盖常见需求)
@configclass
class SystemCameraCfg:
lookat: Vec3 | None = None
distance: float = 2.0
elevation: float = -20.0
azimuth: float = 90.0
follow: str | None = None # SceneCfg 中 asset/obj 名字
- follow 目标引用
SceneCfg 里已声明的名字,backend 构造时解析为内部 body 索引;解析失败在 scene validation 阶段报错(与 query 命名解析同模式)。
- 更新逻辑完全留在 renderer 内部:
render() / capture() 每帧从 renderer 自己的 DataSource 读对象位置刷新 lookat,distance / elevation / azimuth 保持配置值。
- 不渲染不更新:headless 无渲染时零开销;frontend 与 core 不感知。
- follow 属于场景/视角语义,放在
SystemCameraCfg,而不是 RenderConfig(后者是单次渲染运行参数)。
2. SimRenderer 增加纯值方法(脚本级 escape hatch)
class SimRenderer(abc.ABC):
def set_camera_view(
self, lookat: Sequence[float], distance: float, elevation: float, azimuth: float
) -> None:
"""Update the system camera view (windowed and headless)."""
- 参数全是值类型,无对象句柄;
view.py、replay.py 及自定义 follow 逻辑(平滑插值、多目标切换等)可使用,无需触碰 renderer 私有属性。
- 与现有语义自洽:
RenderConfig.camera_* 定初始视角,方法改运行时视角。
明确不做 / Non-goals
- 不暴露返回 backend 原生对象的
camera property(渲染类型跨边界,MuJoCo backend 无对应物)。
- 不引入抽象
Camera 接口(会逐步镜像 backend 渲染 API,双边同步负担)。
验收要点 / Acceptance
SystemCameraCfg(follow="robot") 在交互窗口与 headless 录制下均能跟随对象。
- follow 名字未在 scene 中声明时有明确报错。
SimRenderer.set_camera_view 各 backend 可用;view.py / replay.py 迁移到该方法。
- 测试覆盖配置契约与 follow 名字解析,不测具体数值视角。
背景 / Background
目前系统相机只支持静态视角:
SystemCameraCfg(motrix_env_core/src/motrix_env_core/config/scene/base.py)只有lookat / distance / elevation / azimuth,视角在MotrixSimRenderer.__init__(motrix_env_motrixsim/src/motrix_env_motrixsim/renderer.py)构造时设置一次,之后不随场景对象更新。SystemCameraAPI(set_view/set_pose)也没有 follow/attach 能力。用户希望 camera 能跟随 env 中的某个对象(例如 locomotion 里的机器人),目前只能在自己持有 renderer 的脚本里每帧手动
set_view,标准训练/可视化流程拿不到入口(core 的SimRenderer刻意不暴露渲染类型)。方案 / Proposal
不暴露抽象 camera 对象(避免在 core 边界镜像 backend 渲染 API),改为两层:
1. 声明式 follow 配置(覆盖常见需求)
SceneCfg里已声明的名字,backend 构造时解析为内部 body 索引;解析失败在 scene validation 阶段报错(与 query 命名解析同模式)。render()/capture()每帧从 renderer 自己的DataSource读对象位置刷新 lookat,distance / elevation / azimuth保持配置值。SystemCameraCfg,而不是RenderConfig(后者是单次渲染运行参数)。2.
SimRenderer增加纯值方法(脚本级 escape hatch)view.py、replay.py及自定义 follow 逻辑(平滑插值、多目标切换等)可使用,无需触碰 renderer 私有属性。RenderConfig.camera_*定初始视角,方法改运行时视角。明确不做 / Non-goals
cameraproperty(渲染类型跨边界,MuJoCo backend 无对应物)。Camera接口(会逐步镜像 backend 渲染 API,双边同步负担)。验收要点 / Acceptance
SystemCameraCfg(follow="robot")在交互窗口与 headless 录制下均能跟随对象。SimRenderer.set_camera_view各 backend 可用;view.py/replay.py迁移到该方法。