Viewer

Viewer 类提供了一个交互式窗口，用于实时可视化仿真。用户可以通过鼠标控制来浏览场景、检查对象以及控制仿真播放。

概述

Viewer 是一个可选组件，提供以下功能：

• 仿真的实时 3D 渲染

• 基于鼠标的相机导航（轨道、平移、缩放）

• 用于控制仿真的键盘快捷键

• 实体选择和高亮显示

• 渲染状态可视化

快速开始

import genesis as gs

gs.init()

# 创建带有交互式 viewer 的场景
scene = gs.Scene(
    show_viewer=True,
    viewer_options=gs.options.ViewerOptions(
        camera_pos=(3, 0, 2),
        camera_lookat=(0, 0, 0.5),
        res=(1280, 720),
        max_FPS=60,
    ),
)

scene.add_entity(gs.morphs.Plane())
scene.add_entity(gs.morphs.Box(pos=(0, 0, 0.5)))
scene.build()

# 在 viewer 中运行
for i in range(1000):
    scene.step()
    scene.visualizer.update()

相机控制

控制方式	操作
左键 + 拖动	轨道旋转相机
右键 + 拖动	平移相机
滚轮	放大/缩小
中键 + 拖动	缩放

键盘快捷键

按键	操作
Space	暂停/恢复仿真
R	重置相机到初始位置
Esc	关闭 viewer

配置

通过 ViewerOptions 配置 viewer：

viewer_options = gs.options.ViewerOptions(
    res=(1920, 1080),          # 分辨率
    camera_pos=(5, 0, 3),       # 初始相机位置
    camera_lookat=(0, 0, 0),    # 相机目标点
    camera_fov=45,              # 视野角度
    max_FPS=60,                 # 最大帧率
    run_in_thread=True,         # 在单独线程中运行 viewer
    enable_interaction=True,    # 启用鼠标/键盘交互
)

无头模式（Headless Mode）

对于没有显示环境的情况（服务器、CI），禁用 viewer：

scene = gs.Scene(show_viewer=False)

API 参考

class genesis.vis.viewer.Viewer(options: ViewerOptions, context)

Bases: RBC

build(scene)

run()

stop()

is_alive()

setup_camera()

update(auto_refresh=None, force=False)

close_offscreen(render_target)

render_offscreen(camera_node, render_target, rgb=True, depth=False, seg=False, normal=False)

set_camera_pose(pose=None, pos=None, lookat=None)

Set viewer camera pose.

Parameters:

• pose ([4,4] float, optional) – Camera-to-world pose. If provided, pos and lookat will be ignored.

• pos ((3,) float, optional) – Camera position.

• lookat ((3,) float, optional) – Camera lookat point.

follow_entity(entity, fixed_axis=(None, None, None), smoothing=None, fix_orientation=False)

Set the viewer to follow a specified entity. :param entity: The entity to follow. :type entity: genesis.Entity :param fixed_axis: The fixed axis for the viewer’s movement. For each axis, if None, the viewer will move freely. If a float, the viewer will be fixed on at that value.

For example, [None, None, None] will allow the viewer to move freely while following, [None, None, 0.5] will fix the viewer’s z-axis at 0.5.

Parameters:

• smoothing (float, optional) – The smoothing factor in ]0,1[ for the viewer’s movement. If None, no smoothing will be applied.

• fix_orientation (bool, optional) – If True, the viewer will maintain its orientation relative to the world. If False, the viewer will look at the base link of the entity.

update_following()

Update the viewer position to follow the specified entity.

register_keybinds(*keybinds: Keybind) → None

Register a callback function to be called when a key is pressed.

Parameters:

keybinds (Keybind) – One or more Keybind objects to register. See Keybind documentation for usage.

remap_keybind(keybind_name: str, new_key: Key, new_key_mods: tuple[genesis.vis.keybindings.KeyMod] | None, new_key_action: KeyAction = KeyAction.PRESS) → None

Remap an existing keybind by name to a new key combination.

Parameters:

• keybind_name (str) – The name of the keybind to remap.

• new_key (int) – The new key code from pyglet.

• new_key_mods (tuple[KeyMod] | None) – The new modifier keys pressed.

• new_key_action (KeyAction, optional) – The new type of key action. If not provided, the key action of the old keybind is used.

remove_keybind(keybind_name: str) → None

Remove an existing keybind by name.

Parameters:

keybind_name (str) – The name of the keybind to remove.

add_plugin(plugin: ViewerPlugin) → ViewerPlugin

Add a viewer plugin to the viewer.

Parameters:

plugin (ViewerPlugin) – The viewer plugin to add.

property is_built

property res

property refresh_rate

property max_FPS

property camera_pos

Get the camera’s current position.

property camera_lookat

Get the camera’s current lookat point.

property camera_pose

Get the camera’s current pose represented by a 4x4 matrix.

property camera_up

property camera_fov

另请参阅

• Visualizer - 主可视化控制器

• gs.options.Options - ViewerOptions 配置