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
orViewer.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 theViewer.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
-
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 runViewer.render_lock.release()
once you’re done to let the viewer continue.Type: threading.RLock
-
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
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.
-
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 therun_in_thread
flags set. Kill the viewer after your desired time withViewer.close_external()
, and then callViewer.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.
- scene (