Viewer#

The Viewer class provides an interactive window for real-time visualization of simulations. It allows users to navigate the scene with mouse controls, inspect objects, and control simulation playback.

Overview#

The Viewer is an optional component that provides:

  • Real-time 3D rendering of the simulation

  • Mouse-based camera navigation (orbit, pan, zoom)

  • Keyboard shortcuts for controlling simulation

  • Entity selection and highlighting

  • Render state visualization

Quick Start#

import genesis as gs

gs.init()

# Create scene with interactive 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()

# Run with viewer
for i in range(1000):
    scene.step()
    scene.visualizer.update()

Camera Controls#

Control

Action

Left Mouse + Drag

Orbit camera

Right Mouse + Drag

Pan camera

Scroll Wheel

Zoom in/out

Middle Mouse + Drag

Zoom

Keyboard Shortcuts#

Key

Action

Space

Pause/Resume simulation

R

Reset camera to initial position

Esc

Close viewer

Configuration#

The viewer is configured through ViewerOptions:

viewer_options = gs.options.ViewerOptions(
    res=(1920, 1080),          # Resolution
    camera_pos=(5, 0, 3),       # Initial camera position
    camera_lookat=(0, 0, 0),    # Camera look-at point
    camera_fov=45,              # Field of view
    max_FPS=60,                 # Maximum frame rate
    run_in_thread=True,         # Run viewer in separate thread
    enable_interaction=True,    # Enable mouse/keyboard interaction
)

Headless Mode#

For environments without a display (servers, CI), disable the viewer:

scene = gs.Scene(show_viewer=False)

API Reference#

class genesis.vis.viewer.Viewer(options: ViewerOptions, context)[source]#

Bases: RBC

build(scene)[source]#
run()[source]#
stop()[source]#
is_alive()[source]#
setup_camera()[source]#
update(auto_refresh=None, force=False)[source]#
close_offscreen(render_target)[source]#
render_offscreen(camera_node, render_target, rgb=True, depth=False, seg=False, normal=False)[source]#
set_camera_pose(pose=None, pos=None, lookat=None)[source]#

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)[source]#

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()[source]#

Update the viewer position to follow the specified entity.

register_keybinds(*keybinds: Keybind) → None[source]#

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[source]#

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[source]#

Remove an existing keybind by name.

Parameters:

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

add_plugin(plugin: ViewerPlugin) → ViewerPlugin[source]#

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#

See Also#