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.