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(
    viewer_options=gs.options.ViewerOptions(
        camera_pos=(3, 0, 2),
        camera_lookat=(0, 0, 0.5),
        res=(1280, 720),
        max_FPS=60,
    ),
    show_viewer=True,
)

scene.add_entity(gs.morphs.Plane())
scene.add_entity(gs.morphs.Box(pos=(0, 0, 0.5), size=(1.0, 1.0, 1.0)))
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
)

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, skip_markers=False, env_separate_rigid=None)[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, overwrite: bool = False) → 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.

consume_rebuild_requests() → bool[source]#

Let any plugin perform a pending scene rebuild on the calling (main) thread. Returns True if one did, in which case this viewer has just been torn down and the caller must stop using it.

should_advance_simulation() → bool[source]#

Whether the simulation may advance this frame, i.e. no plugin (e.g. the GUI play/pause control) vetoes it. Every plugin is polled so stateful single-step controls always observe the frame.

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#