Viewer

class pyrender.viewer.Viewer(scene, viewport_size=None, render_flags=None, viewer_flags=None, registered_keys=None, run_in_thread=False, **kwargs)[source]

Bases: pyglet.window.Window

An interactive viewer for 3D scenes.

The viewer’s camera is separate from the scene’s, but will take on the parameters of the scene’s main view camera and start in the same pose. If the scene does not have a camera, a suitable default will be provided.

Parameters:
  • scene (Scene) – The scene to visualize.
  • viewport_size ((2,) int) – The width and height of the initial viewing window.
  • render_flags (dict) – A set of flags for rendering the scene. Described in the note below.
  • viewer_flags (dict) – A set of flags for controlling the viewer’s behavior. Described in the note below.
  • registered_keys (dict) –

    A map from ASCII key characters to tuples containing:

    • A function to be called whenever the key is pressed, whose first argument will be the viewer itself.
    • (Optionally) A list of additional positional arguments to be passed to the function.
    • (Optionally) A dict of keyword arguments to be passed to the function.
  • kwargs (dict) – Any keyword arguments left over will be interpreted as belonging to either the Viewer.render_flags or Viewer.viewer_flags dictionaries. Those flag sets will be updated appropriately.

Note

The basic commands for moving about the scene are given as follows:

  • Rotating about the scene: Hold the left mouse button and drag the cursor.
  • Rotating about the view axis: Hold CTRL and the left mouse button and drag the cursor.
  • Panning:
    • Hold SHIFT, then hold the left mouse button and drag the cursor, or
    • Hold the middle mouse button and drag the cursor.
  • Zooming:
    • Scroll the mouse wheel, or
    • Hold the right mouse button and drag the cursor.

Other keyboard commands are as follows:

  • a: Toggles rotational animation mode.
  • c: Toggles backface culling.
  • f: Toggles fullscreen mode.
  • h: Toggles shadow rendering.
  • i: Toggles axis display mode (no axes, world axis, mesh axes, all axes).
  • l: Toggles lighting mode (scene lighting, Raymond lighting, or direct lighting).
  • m: Toggles face normal visualization.
  • n: Toggles vertex normal visualization.
  • o: Toggles orthographic mode.
  • q: Quits the viewer.
  • r: Starts recording a GIF, and pressing again stops recording and opens a file dialog.
  • s: Opens a file dialog to save the current view as an image.
  • w: Toggles wireframe mode (scene default, flip wireframes, all wireframe, or all solid).
  • z: Resets the camera to the initial view.

Note

The valid keys for render_flags are as follows:

  • flip_wireframe: bool, If True, all objects will have their wireframe modes flipped from what their material indicates. Defaults to False.
  • all_wireframe: bool, If True, all objects will be rendered in wireframe mode. Defaults to False.
  • all_solid: bool, If True, all objects will be rendered in solid mode. Defaults to False.
  • shadows: bool, If True, shadows will be rendered. Defaults to False.
  • vertex_normals: bool, If True, vertex normals will be rendered as blue lines. Defaults to False.
  • face_normals: bool, If True, face normals will be rendered as blue lines. Defaults to False.
  • cull_faces: bool, If True, backfaces will be culled. Defaults to True.
  • point_size : float, The point size in pixels. Defaults to 1px.

Note

The valid keys for viewer_flags are as follows:

  • rotate: bool, If True, the scene’s camera will rotate about an axis. Defaults to False.
  • rotate_rate: float, The rate of rotation in radians per second. Defaults to PI / 3.0.
  • rotate_axis: (3,) float, The axis in world coordinates to rotate about. Defaults to [0,0,1].
  • view_center: (3,) float, The position to rotate the scene about. Defaults to the scene’s centroid.
  • use_raymond_lighting: bool, If True, an additional set of three directional lights that move with the camera will be added to the scene. Defaults to False.
  • use_direct_lighting: bool, If True, an additional directional light that moves with the camera and points out of it will be added to the scene. Defaults to False.
  • lighting_intensity: float, The overall intensity of the viewer’s additional lights (when they’re in use). Defaults to 3.0.
  • use_perspective_cam: bool, If True, a perspective camera will be used. Otherwise, an orthographic camera is used. Defaults to True.
  • save_directory: str, A directory to open the file dialogs in. Defaults to None.
  • window_title: str, A title for the viewer’s application window. Defaults to “Scene Viewer”.
  • refresh_rate: float, A refresh rate for rendering, in Hertz. Defaults to 30.0.
  • fullscreen: bool, Whether to make viewer fullscreen. Defaults to False.
  • show_world_axis: bool, Whether to show the world axis. Defaults to False.
  • show_mesh_axes: bool, Whether to show the individual mesh axes. Defaults to False.
  • caption: list of dict, Text caption(s) to display on the viewer. Defaults to None.

Note

Animation can be accomplished by running the viewer with run_in_thread enabled. Then, just run a loop in your main thread, updating the scene as needed. Before updating the scene, be sure to acquire the Viewer.render_lock, and release it when your update is done.

Attributes Summary

is_active True if the viewer is active, or False if it has been closed.
registered_keys Map from ASCII key character to a handler function.
render_flags Flags for controlling the renderer’s behavior.
render_lock If acquired, prevents the viewer from rendering until released.
run_in_thread Whether the viewer was run in a separate thread.
scene The scene being visualized.
viewer_flags Flags for controlling the viewer’s behavior.
viewport_size The width and height of the viewing window.

Methods Summary

close_external() Close the viewer from another thread.
on_close() Exit the event loop when the window is closed.
on_draw() Redraw the scene into the viewing window.
on_key_press(symbol, modifiers) Record a key press.
on_mouse_drag(x, y, dx, dy, buttons, modifiers) Record a mouse drag.
on_mouse_press(x, y, buttons, modifiers) Record an initial mouse press.
on_mouse_release(x, y, button, modifiers) Record a mouse release.
on_mouse_scroll(x, y, dx, dy) Record a mouse scroll.
on_resize(width, height) Resize the camera and trackball when the window is resized.
save_gif([filename]) Save the stored GIF frames to a file.

Attributes Documentation

is_active

True if the viewer is active, or False if it has been closed.

Type:bool
registered_keys

Map from ASCII key character to a handler function.

This is a map from ASCII key characters to tuples containing:

  • A function to be called whenever the key is pressed, whose first argument will be the viewer itself.
  • (Optionally) A list of additional positional arguments to be passed to the function.
  • (Optionally) A dict of keyword arguments to be passed to the function.
Type:dict
render_flags

Flags for controlling the renderer’s behavior.

  • flip_wireframe: bool, If True, all objects will have their wireframe modes flipped from what their material indicates. Defaults to False.
  • all_wireframe: bool, If True, all objects will be rendered in wireframe mode. Defaults to False.
  • all_solid: bool, If True, all objects will be rendered in solid mode. Defaults to False.
  • shadows: bool, If True, shadows will be rendered. Defaults to False.
  • vertex_normals: bool, If True, vertex normals will be rendered as blue lines. Defaults to False.
  • face_normals: bool, If True, face normals will be rendered as blue lines. Defaults to False.
  • cull_faces: bool, If True, backfaces will be culled. Defaults to True.
  • point_size : float, The point size in pixels. Defaults to 1px.
Type:dict
render_lock

If acquired, prevents the viewer from rendering until released.

Run Viewer.render_lock.acquire() before making updates to the scene in a different thread, and run Viewer.render_lock.release() once you’re done to let the viewer continue.

Type:threading.RLock
run_in_thread

Whether the viewer was run in a separate thread.

Type:bool
scene

The scene being visualized.

Type:Scene
viewer_flags

Flags for controlling the viewer’s behavior.

The valid keys for viewer_flags are as follows:

  • rotate: bool, If True, the scene’s camera will rotate about an axis. Defaults to False.
  • rotate_rate: float, The rate of rotation in radians per second. Defaults to PI / 3.0.
  • rotate_axis: (3,) float, The axis in world coordinates to rotate about. Defaults to [0,0,1].
  • view_center: (3,) float, The position to rotate the scene about. Defaults to the scene’s centroid.
  • use_raymond_lighting: bool, If True, an additional set of three directional lights that move with the camera will be added to the scene. Defaults to False.
  • use_direct_lighting: bool, If True, an additional directional light that moves with the camera and points out of it will be added to the scene. Defaults to False.
  • lighting_intensity: float, The overall intensity of the viewer’s additional lights (when they’re in use). Defaults to 3.0.
  • use_perspective_cam: bool, If True, a perspective camera will be used. Otherwise, an orthographic camera is used. Defaults to True.
  • save_directory: str, A directory to open the file dialogs in. Defaults to None.
  • window_title: str, A title for the viewer’s application window. Defaults to “Scene Viewer”.
  • refresh_rate: float, A refresh rate for rendering, in Hertz. Defaults to 30.0.
  • fullscreen: bool, Whether to make viewer fullscreen. Defaults to False.
  • show_world_axis: bool, Whether to show the world axis. Defaults to False.
  • show_mesh_axes: bool, Whether to show the individual mesh axes. Defaults to False.
  • caption: list of dict, Text caption(s) to display on the viewer. Defaults to None.
Type:dict
viewport_size

The width and height of the viewing window.

Type:(2,) int

Methods Documentation

close_external()[source]

Close the viewer from another thread.

This function will wait for the actual close, so you immediately manipulate the scene afterwards.

on_close()[source]

Exit the event loop when the window is closed.

on_draw()[source]

Redraw the scene into the viewing window.

on_key_press(symbol, modifiers)[source]

Record a key press.

on_mouse_drag(x, y, dx, dy, buttons, modifiers)[source]

Record a mouse drag.

on_mouse_press(x, y, buttons, modifiers)[source]

Record an initial mouse press.

on_mouse_release(x, y, button, modifiers)[source]

Record a mouse release.

on_mouse_scroll(x, y, dx, dy)[source]

Record a mouse scroll.

on_resize(width, height)[source]

Resize the camera and trackball when the window is resized.

save_gif(filename=None)[source]

Save the stored GIF frames to a file.

To use this asynchronously, run the viewer with the record flag and the run_in_thread flags set. Kill the viewer after your desired time with Viewer.close_external(), and then call Viewer.save_gif().

Parameters:filename (str) – The file to save the GIF to. If not specified, a file dialog will be opened to ask the user where to save the GIF file.