Viewer#

The interactive window that renders a scene in real time, with mouse and keyboard camera controls. It is optional: pass show_viewer=True to gs.Scene(...) to open it, and omit it (or pass show_viewer=False) to run headless. The viewer always uses the rasterizer backend, independent of the scene’s renderer. For the walkthrough, mouse and keyboard controls, and the gs command-line tools, see Visualization.

The viewer is configured by two options objects: ViewerOptions sets its initial camera pose, resolution, and refresh rate; VisOptions sets viewer-independent visualization such as lighting, world-frame display, and segmentation level.

scene = gs.Scene(
    viewer_options=gs.options.ViewerOptions(
        camera_pos=(3.0, 0.0, 2.0),
        camera_lookat=(0.0, 0.0, 0.5),
        camera_fov=40,
        refresh_rate=60,  # frames per second cap
    ),
    show_viewer=True,
)
for _ in range(1000):
    scene.step()
    scene.visualizer.update()  # refresh the viewer

Viewer#

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.

remove_plugin(plugin: ViewerPlugin) → None[source]#

Remove a viewer plugin from the viewer, detaching it from the live render loop if already built.

Parameters:

plugin (ViewerPlugin) – The viewer plugin to remove.

toggle_recording() → bool[source]#

Start or stop recording the on-screen viewer to a video file, returning the resulting record state.

Stopping prompts for a destination file. This is the same on-screen capture toggled by the ‘R’ shortcut.

property recording: bool#

Whether the viewer is currently recording its on-screen output to a video file.

property plugins#

The registered viewer plugins, read-only; use add_plugin to register one.

property is_built#
property res#
property refresh_rate#
property realtime_factor#
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#

ViewerOptions#

class genesis.options.ViewerOptions(*, res: tuple[int, int] | None = None, run_in_thread: bool | None = None, refresh_rate: int = 60, realtime_factor: float | None = 1.0, camera_pos: tuple[float, float, float] = (3.5, 0.5, 2.5), camera_lookat: tuple[float, float, float] = (0.0, 0.0, 0.5), camera_up: tuple[float, float, float] = (0.0, 0.0, 1.0), camera_fov: float = 40, enable_help_text: bool = True, enable_default_keybinds: bool = True, enable_gui: bool = False, max_FPS: int | None = None) → None[source]#

Options configuring preperties of the interactive viewer.

Note

The viewer’s camera uses the Rasterizer backend regardless of gs.renderers.* when creating the scene.

Parameters:

  • res (tuple, shape (2,), optional) – The resolution of the viewer. If not set, will auto-compute using resolution of the connected display.

  • run_in_thread (bool) – Whether to run the viewer in a background thread. This option is not supported on MacOS. True by default if available.

  • refresh_rate (int) – The rate (in frames per second) at which the viewer repaints on screen, and the framerate the recorded video is encoded at. Independent of the physics timestep.

  • realtime_factor (float | None) – When the viewer is shown, the simulation is paced to this multiple of wall-clock real time (1.0 is real time, 2.0 is twice as fast), falling behind gracefully when it cannot keep up. Set to None to run as fast as possible. Has no effect without a viewer. Defaults to 1.0.

  • camera_pos (tuple of float, shape (3,)) – The position of the viewer’s camera.

  • camera_lookat (tuple of float, shape (3,)) – The lookat position that the camera.

  • camera_up (tuple of float, shape (3,)) – The up vector of the camera’s extrinsic pose.

  • camera_fov (float) – The field of view (in degrees) of the camera.

  • enable_help_text (bool) – Whether to enable the rendering of instructions text in the viewer.

  • enable_default_keybinds (bool) – Whether to enable the default keyboard controls in the viewer.

  • enable_gui (bool) – Whether to automatically attach the ImGui overlay panel when the viewer is constructed. Defaults to False. The overlay renders its own controls and captures keyboard input, so it requires enable_help_text and enable_default_keybinds to be False; they default to False when enable_gui is True, and explicitly setting either to True alongside enable_gui raises an error. Scene editing controls (Rebuild Scene, Add Entity, per-entity remove) are visible but disabled unless the scene is managed by a gs.InteractiveScene that supports them.

VisOptions#

class genesis.options.VisOptions(*, show_world_frame: bool = False, world_frame_size: float = 1.0, show_link_frame: bool = False, link_frame_size: float = 0.2, show_cameras: bool = False, shadow: bool = True, plane_reflection: bool = False, env_separate_rigid: bool = False, background_color: tuple[float, float, float] = (0.04, 0.08, 0.12), ambient_light: tuple[float, float, float] = (0.1, 0.1, 0.1), visualize_mpm_boundary: bool = False, visualize_sph_boundary: bool = False, visualize_pbd_boundary: bool = False, segmentation_level: typing.Literal['entity', 'link', 'geom'] = 'link', render_particle_as: typing.Literal['sphere', 'tet'] = 'sphere', particle_size_scale: float = 1.0, contact_force_scale: float = 0.01, n_support_neighbors: int = 12, rendered_envs_idx: tuple[int, ...] | None = None, lights: genesis.datatypes.List[genesis.options.vis.DirectionalLight | genesis.options.vis.PointLight | genesis.options.vis.AmbientLight] = ─────── <gs.List> of <gs.options.vis.DirectionalLight> ──────── <gs.List>(len=1, [     <gs.options.vis.DirectionalLight>, ])) → None[source]#

This configures visualization-related properties that are independent of the viewer or camera.

Parameters:

  • show_world_frame (bool) – Whether to visualize the world frame. Default to False.

  • world_frame_size (float) – The length (in meters) of the world frame’s axes.

  • show_link_frame (bool) – Whether to visualize the frames of each RigidLink. Default to False.

  • link_frame_size (float) – The length (in meters) of the link frames’ axes.

  • show_cameras (bool) – Whether to render the cameras added to the scene, together with their frustums. Default to False.

  • shadow (bool) – Whether to render shadow. Defaults to True.

  • plane_reflection (bool) – Whether to render plane reflection. Defaults to False.

  • env_separate_rigid (bool) – Whether to render all the rigid objects in batched environments in isolation or as part of the same scene. This is only an option for Rasterizer. This behavior is enforced for BatchRender. Defaults to False.

  • background_color (tuple of float, shape (3,)) – The color of the scene background.

  • ambient_light (tuple of float, shape (3,)) – The color of the scene’s ambient light.

  • visualize_mpm_boundary (bool) – Whether to visualize the boundary of the MPM Solver.

  • visualize_sph_boundary (bool) – Whether to visualize the boundary of the SPH Solver.

  • visualize_pbd_boundary (bool) – Whether to visualize the boundary of the PBD Solver.

  • segmentation_level (str) – The segmentation level used for segmentation mask rendering. Should be one of [‘entity’, ‘link’, ‘geom’]. Defaults to ‘link’.

  • render_particle_as (str) – How particles in the scene should be rendered. Should be one of [‘sphere’, ‘tet’]. Defaults to ‘sphere’.

  • particle_size_scale (float) – Scale applied to actual particle size for rendering. Defaults to 1.0.

  • contact_force_scale (float = 0.02) – Scale in m.N^{-1} for contact arrow visualization, e.g. the force arrow representing 10N will be 0.2m long if scale is 0.02. Defaults to 0.01.

  • n_support_neighbors (int) – Number of supporting neighbor particles used to compute vertex position of the visual mesh. Used for rendering deformable bodies. Defaults to 12.

  • rendered_envs_idx (list, optional) – Indices of the environments that will be rendered. If not provided, all the environments will be considered. Defaults to None.

  • n_rendered_envs (int, optional) – This option is deprecated. Please use rendered_envs_idx instead.

  • lights (list of dict.) – Lights added to the scene.

See also#

  • Visualizer: the orchestrator that owns the viewer, cameras, and renderer

  • Lights: lighting the scene through VisOptions

  • Visualization: the interactive viewer and gs tools