warp.render.OpenGLRenderer#

class warp.render.OpenGLRenderer( title='Warp', scaling=1.0, fps=60, up_axis='Y', screen_width=1024, screen_height=768, near_plane=1.0, far_plane=100.0, camera_fov=45.0, camera_pos=(0.0, 2.0, 10.0), camera_front=(0.0, 0.0, -1.0), camera_up=(0.0, 1.0, 0.0), background_color=(0.53, 0.8, 0.92), draw_grid=True, draw_sky=True, draw_axis=True, show_info=True, render_wireframe=False, render_depth=False, axis_scale=1.0, vsync=False, headless=None, enable_backface_culling=True, enable_mouse_interaction=True, enable_keyboard_interaction=True, device=None, use_legacy_opengl=None, )[source]#

Interactive OpenGL-based renderer for real-time 3D visualization.

This renderer provides hardware-accelerated visualization of Warp simulations with support for geometric primitives (spheres, boxes, capsules, cylinders, cones), meshes, and point clouds. It features an interactive camera system, customizable scene setup, and can render to screen or offscreen buffers.

The renderer supports both windowed and headless modes, making it suitable for interactive development and automated visualization pipelines. It can also render tiled viewports for multi-view visualization.

Note

Requires pyglet (version >= 2.0) to be installed.

Headless rendering (without a display) is supported on Linux systems. To enable headless rendering, set the Pyglet options before importing warp.render:

import pyglet

pyglet.options["headless"] = True

import warp.render

# OpenGLRenderer will run headless when pyglet.options["headless"] is True.
# Alternatively, pass headless=True to control window visibility explicitly.
renderer = warp.render.OpenGLRenderer()

Parameters:

title (str)
scaling (float)
fps (int)
up_axis (str)
screen_width (int)
screen_height (int)
near_plane (float)
far_plane (float)
camera_fov (float)
camera_pos (tuple[float, float, float])
camera_front (tuple[float, float, float])
camera_up (tuple[float, float, float])
background_color (tuple[float, float, float])
draw_grid (bool)
draw_sky (bool)
draw_axis (bool)
show_info (bool)
render_wireframe (bool)
render_depth (bool)
axis_scale (float)
vsync (bool)
headless (bool | None)
enable_backface_culling (bool)
enable_mouse_interaction (bool)
enable_keyboard_interaction (bool)
device (wp.DeviceLike)
use_legacy_opengl (bool | None)

__init__( title='Warp', scaling=1.0, fps=60, up_axis='Y', screen_width=1024, screen_height=768, near_plane=1.0, far_plane=100.0, camera_fov=45.0, camera_pos=(0.0, 2.0, 10.0), camera_front=(0.0, 0.0, -1.0), camera_up=(0.0, 1.0, 0.0), background_color=(0.53, 0.8, 0.92), draw_grid=True, draw_sky=True, draw_axis=True, show_info=True, render_wireframe=False, render_depth=False, axis_scale=1.0, vsync=False, headless=None, enable_backface_culling=True, enable_mouse_interaction=True, enable_keyboard_interaction=True, device=None, use_legacy_opengl=None, )[source]#

Initialize the OpenGL renderer.

Parameters:

title (str) – The window title.
scaling (float) – The scaling factor for the scene.
fps (int) – The target frames per second.
up_axis (str) – The up axis of the scene. Can be "X", "Y", or "Z".
screen_width (int) – The width of the window.
screen_height (int) – The height of the window.
near_plane (float) – The near clipping plane.
far_plane (float) – The far clipping plane.
camera_fov (float) – The camera field of view in degrees.
camera_pos (tuple[float, float, float]) – The initial camera position as (x, y, z).
camera_front (tuple[float, float, float]) – The initial camera front direction as (x, y, z).
camera_up (tuple[float, float, float]) – The initial camera up direction as (x, y, z).
background_color (tuple[float, float, float]) – The background color as RGB values (r, g, b).
draw_grid (bool) – Whether to draw a grid indicating the ground plane.
draw_sky (bool) – Whether to draw a sky sphere.
draw_axis (bool) – Whether to draw the coordinate system axes.
show_info (bool) – Whether to overlay rendering information.
render_wireframe (bool) – Whether to render scene shapes as wireframes.
render_depth (bool) – Whether to show the depth buffer instead of the RGB image.
axis_scale (float) – The scale of the coordinate system axes (only if draw_axis is True).
vsync (bool) – Whether to enable vertical synchronization.
headless (bool | None) – Whether to run in headless mode (no window). If None, determined by pyglet.options["headless"].
enable_backface_culling (bool) – Whether to enable backface culling.
enable_mouse_interaction (bool) – Whether to enable mouse interaction.
enable_keyboard_interaction (bool) – Whether to enable keyboard interaction.
device (Device | str | None) – Warp device where internal data is stored.
use_legacy_opengl (bool | None) – Whether to use legacy OpenGL (more compatible with macOS). If None, auto-detected.

Methods

`__init__`([title, scaling, fps, up_axis, ...])	Initialize the OpenGL renderer.
`add_shape_instance`(name, shape, body, pos, rot)	Add an instance of a registered shape.
`allocate_shape_instances`()	Allocate GPU buffers and Warp arrays for instances.
`begin_frame`([t])	Mark the start of a frame and set time.
`clear`()	Release OpenGL resources and reset renderer state.
`close`()	Close the window and release renderer resources.
`compute_model_matrix`(camera_axis, scaling)	Compute the model matrix for the given up-axis and scaling.
`compute_projection_matrix`(fov, aspect_ratio, ...)	Compute a projection matrix given the field of view, aspect ratio, near plane, and far plane.
`compute_view_matrix`(cam_pos, cam_front, cam_up)	Compute the view matrix from camera vectors.
`deregister_shape`(shape)	Remove a registered shape and free its buffers.
`end_frame`()	Finalize the current frame and render it.
`get_pixels`(target_image[, split_up_tiles, ...])	Read the pixels from the frame buffer (RGB or depth are supported) into the given array.
`initialize_gl`()	Import and cache pyglet OpenGL bindings.
`is_running`()	Whether the renderer event loop is still running.
`register_body`(name)	Register a body name and return its integer ID.
`register_input_processor`(callback)	Register a callback to process input each frame.
`register_key_press_callback`(callback)	Register a callback for key press events.
`register_shape`(geo_hash, vertices, indices)	Register a shape geometry and upload buffers.
`remove_shape_instance`(name)	Remove a shape instance by name.
`render_arrow`(name, pos, rot, base_radius, ...)	Add a arrow for visualization
`render_box`(name, pos, rot, extents[, ...])	Add a box for visualization
`render_capsule`(name, pos, rot, radius, ...)	Add a capsule for visualization
`render_cone`(name, pos, rot, radius, half_height)	Add a cone for visualization
`render_cylinder`(name, pos, rot, radius, ...)	Add a cylinder for visualization
`render_ground`([size, plane])	Add a ground plane for visualization
`render_line_list`(name, vertices, indices[, ...])	Add a line list as a set of capsules
`render_line_strip`(name, vertices[, color, ...])	Add a line strip as a set of capsules
`render_mesh`(name, points, indices[, colors, ...])	Add a mesh for visualization
`render_plane`(name, pos, rot, width, length)	Add a plane for visualization
`render_points`(name, points, radius[, ...])	Add a set of points
`render_ref`(name, path, pos, rot, scale[, color])	Create a reference (instance) with the given name to the given path.
`render_sphere`(name, pos, rot, radius[, ...])	Add a sphere for visualization
`save`()	Block until the window is closed, keeping rendering active.
`setup_tiled_rendering`(instances[, ...])	Set up tiled rendering where the render buffer is split into multiple tiles that can visualize different shape instances of the scene with different view and projection matrices.
`update`()	Advance the event loop and render a frame if enabled.
`update_body_transforms`(body_tf)	Update instance transforms from body transforms.
`update_instance_colors`()	Upload per-instance colors to GPU buffers.
`update_model_matrix`([model_matrix])	Update the model matrix and upload it to shaders.
`update_projection_matrix`()	Update the projection matrix from current camera settings.
`update_shape_instance`(name[, pos, rot, ...])	Update the instance properties of the shape
`update_shape_instances`()	Rebuild instance buffers after instance updates.
`update_shape_vertices`(shape, points)	Update vertex positions for a registered shape.
`update_tile`(tile_id[, instances, ...])	Update the shape instances, projection matrix, view matrix, tile size, or tile position for a given tile given its index.
`update_view_matrix`([cam_pos, cam_front, ...])	Update camera vectors and recompute the view matrix.

Attributes

`camera_front`	Current camera forward vector.
`camera_pos`	Current camera position vector.
`camera_up`	Current camera up vector.
`default_num_segments`
`gl`
`has_exit`	Whether the event loop has requested exit.
`num_instances`	Number of active shape instances.
`num_shapes`	Number of registered shape geometries.
`num_tiles`	Number of tiles configured for tiled rendering.
`paused`	Whether rendering is paused.
`scaling`	Global scene scaling factor.
`tile_height`	Tile height in pixels, or `None` if unset.
`tile_width`	Tile width in pixels, or `None` if unset.
`tiled_rendering`	Whether tiled rendering is enabled.

default_num_segments = 32#

gl = None#

classmethod initialize_gl()[source]#: Import and cache pyglet OpenGL bindings.

property paused[source]#: Whether rendering is paused.

property has_exit[source]#: Whether the event loop has requested exit.

clear()[source]#: Release OpenGL resources and reset renderer state.

close()[source]#: Close the window and release renderer resources.

property tiled_rendering[source]#: Whether tiled rendering is enabled.

setup_tiled_rendering( instances, rescale_window=False, tile_width=None, tile_height=None, tile_ncols=None, tile_nrows=None, tile_positions=None, tile_sizes=None, projection_matrices=None, view_matrices=None, )[source]#

Set up tiled rendering where the render buffer is split into multiple tiles that can visualize different shape instances of the scene with different view and projection matrices. See get_pixels() which allows to retrieve the pixels of for each tile. See update_tile() which allows to update the shape instances, projection matrix, view matrix, tile size, or tile position for a given tile.

Parameters:

instances (list[list[int]]) – A list of lists of shape instance ids. Each list of shape instance ids will be rendered into a separate tile.
rescale_window (bool) – If True, the window will be resized to fit the tiles.
tile_width (int | None) – The width of each tile in pixels (optional).
tile_height (int | None) – The height of each tile in pixels (optional).
tile_ncols (int | None) – The number of tiles rendered horizontally (optional). Will be considered if tile_width is set to compute the tile positions, unless tile_positions is defined.
tile_nrows (int | None) – The number of tiles rendered vertically (optional). Will be considered if tile_height is set to compute the tile positions, unless tile_positions is defined.
tile_positions (list[tuple[int]] | None) – A list of (x, y) tuples specifying the position of each tile in pixels. If None, the tiles will be arranged in a square grid, or, if tile_ncols and tile_nrows are set, in a grid with the specified number of columns and rows.
tile_sizes (list[tuple[int]] | None) – A list of (width, height) tuples specifying the size of each tile in pixels. If None, the tiles will have the same size as specified by tile_width and tile_height.
projection_matrices (list[list[float] | list[list[float]] | ndarray] | None) – A list of projection matrices for each tile (each view matrix is either a flattened 16-dimensional array or a 4x4 matrix). If the entire array is None, or only a view instances, the projection matrices for all, or these instances, respectively, will be derived from the current render settings.
view_matrices (list[list[float] | list[list[float]] | ndarray] | None) – A list of view matrices for each tile (each view matrix is either a flattened 16-dimensional array or a 4x4 matrix). If the entire array is None, or only a view instances, the view matrices for all, or these instances, respectively, will be derived from the current camera settings and be updated when the camera is moved.

update_tile( tile_id, instances=None, projection_matrix=None, view_matrix=None, tile_size=None, tile_position=None, )[source]#

Update the shape instances, projection matrix, view matrix, tile size, or tile position for a given tile given its index.

Parameters:

tile_id – The index of the tile to update.
instances (list[int] | None) – A list of shape instance ids (optional).
projection_matrix (list[float] | list[list[float]] | ndarray | None) – A projection matrix (optional).
view_matrix (list[float] | list[list[float]] | ndarray | None) – A view matrix (optional).
tile_size (tuple[int] | None) – A (width, height) tuple specifying the size of the tile in pixels (optional).
tile_position (tuple[int] | None) – A (x, y) tuple specifying the position of the tile in pixels (optional).

static compute_projection_matrix( fov, aspect_ratio, near_plane, far_plane, )[source]#

Compute a projection matrix given the field of view, aspect ratio, near plane, and far plane.

Parameters:

fov (float) – The field of view in degrees.
aspect_ratio (float) – The aspect ratio (width / height).
near_plane (float) – The near plane.
far_plane (float) – The far plane.

Returns:

A projection matrix.

Return type:

list[float] | list[list[float]] | ndarray

update_projection_matrix()[source]#: Update the projection matrix from current camera settings.

property camera_pos[source]#: Current camera position vector.

property camera_front[source]#: Current camera forward vector.

property camera_up[source]#: Current camera up vector.

compute_view_matrix(cam_pos, cam_front, cam_up)[source]#

Compute the view matrix from camera vectors.

Parameters:

cam_pos – Camera position in world space.
cam_front – Camera forward direction.
cam_up – Camera up direction.

Returns:

The 4x4 view matrix as a NumPy array.

update_view_matrix( cam_pos=None, cam_front=None, cam_up=None, stiffness=1.0, )[source]#

Update camera vectors and recompute the view matrix.

Parameters:

cam_pos – New camera position (optional).
cam_front – New camera forward direction (optional).
cam_up – New camera up direction (optional).
stiffness – Smoothing factor for camera updates.

static compute_model_matrix(camera_axis, scaling)[source]#

Compute the model matrix for the given up-axis and scaling.

Parameters:

camera_axis (int)
scaling (float)

update_model_matrix(model_matrix=None)[source]#

Update the model matrix and upload it to shaders.

Parameters:: model_matrix (list[float] | list[list[float]] | ndarray | None) – Optional 4x4 matrix override. If None, uses the current up-axis and scaling.

property num_tiles[source]#: Number of tiles configured for tiled rendering.

property tile_width[source]#: Tile width in pixels, or None if unset.

property tile_height[source]#: Tile height in pixels, or None if unset.

property num_shapes[source]#: Number of registered shape geometries.

property num_instances[source]#: Number of active shape instances.

property scaling[source]#: Global scene scaling factor.

begin_frame(t=None)[source]#

Mark the start of a frame and set time.

Parameters:: t (float | None) – Optional time value to assign to self.time. If None, the current clock time is used.

end_frame()[source]#: Finalize the current frame and render it.

update()[source]#: Advance the event loop and render a frame if enabled.

register_input_processor(callback)[source]#

Parameters:: callback – Function called with the key handler. Return pyglet.event.EVENT_HANDLED to stop further processing.

register_key_press_callback(callback)[source]#

Parameters:: callback – Function called as callback(symbol, modifiers).

register_shape( geo_hash, vertices, indices, color1=None, color2=None, )[source]#

Parameters:

geo_hash – Hashable identifier used to deduplicate geometry.
vertices – Vertex array for the mesh.
indices – Index array defining triangles.
color1 – Primary color for the shape.
color2 – Secondary color for the shape.

Returns:

Integer shape ID.

deregister_shape(shape)[source]#

Remove a registered shape and free its buffers.

Parameters:: shape – Shape ID returned by register_shape().

add_shape_instance( name, shape, body, pos, rot, scale=(1.0, 1.0, 1.0), color1=None, color2=None, custom_index=-1, visible=True, )[source]#

Add an instance of a registered shape.

Parameters:

name (str) – Name for the instance.
shape (int) – Shape ID returned by register_shape().
body – Optional body name or ID to bind the instance to.
pos (tuple) – Position tuple (x, y, z).
rot (tuple) – Orientation quaternion (x, y, z, w).
scale (tuple) – Scale tuple.
color1 – Primary color override.
color2 – Secondary color override.
custom_index (int) – Optional custom instance ID.
visible (bool) – Whether the instance is visible.

Returns:

Integer instance ID.

remove_shape_instance(name)[source]#

Remove a shape instance by name.

Parameters:: name (str) – Instance name passed to add_shape_instance().

update_instance_colors()[source]#: Upload per-instance colors to GPU buffers.

allocate_shape_instances()[source]#: Allocate GPU buffers and Warp arrays for instances.

update_shape_instance( name, pos=None, rot=None, color1=None, color2=None, scale=None, visible=None, )[source]#

Update the instance properties of the shape

Parameters:

name – The name of the shape
pos – The position of the shape
rot – The rotation of the shape
color1 – The first color of the checker pattern
color2 – The second color of the checker pattern
visible – Whether the shape is visible

update_shape_instances()[source]#: Rebuild instance buffers after instance updates.

update_body_transforms(body_tf)[source]#

Update instance transforms from body transforms.

Parameters:: body_tf (array) – Optional array of body transforms. If None, only the instance transforms are applied.

register_body(name)[source]#

Parameters:: name – Body name to register.
Returns:: Integer body ID.

is_running()[source]#: Whether the renderer event loop is still running.

save()[source]#: Block until the window is closed, keeping rendering active.

get_pixels( target_image, split_up_tiles=True, mode='rgb', use_uint8=False, )[source]#

Read the pixels from the frame buffer (RGB or depth are supported) into the given array.

If split_up_tiles is False, array must be of shape (screen_height, screen_width, 3) for RGB mode or (screen_height, screen_width, 1) for depth mode. If split_up_tiles is True, the pixels will be split up into tiles (see tile_width and tile_height for dimensions): array must be of shape (num_tiles, tile_height, tile_width, 3) for RGB mode or (num_tiles, tile_height, tile_width, 1) for depth mode.

Parameters:

target_image (array) – The array to read the pixels into. Must have float32 as dtype and be on a CUDA device.
split_up_tiles (bool) – Whether to split up the viewport into tiles, see setup_tiled_rendering().
mode (str) – can be either “rgb” or “depth”
use_uint8 (bool) – Whether to use uint8 as dtype in RGB mode for the target_image array and return values in the range [0, 255]. Otherwise, float32 is assumed as dtype with values in the range [0, 1].

Returns:

Whether the pixels were successfully read.

Return type:

bool

render_plane( name, pos, rot, width, length, color=(1.0, 1.0, 1.0), color2=None, parent_body=None, is_template=False, u_scaling=1.0, v_scaling=1.0, visible=True, )[source]#

Add a plane for visualization

Parameters:

name (str) – The name of the plane
pos (tuple) – The position of the plane
rot (tuple) – The rotation of the plane
width (float) – The width of the plane
length (float) – The length of the plane
color (tuple) – The color of the plane
texture – The texture of the plane (optional)
parent_body (str | None)
is_template (bool)
visible (bool)

render_ground(size=1000.0, plane=None)[source]#

Add a ground plane for visualization

Parameters:: size (float) – The size of the ground plane

render_sphere( name, pos, rot, radius, parent_body=None, is_template=False, color=None, visible=True, )[source]#

Add a sphere for visualization

Parameters:

pos (tuple) – The position of the sphere
radius (float) – The radius of the sphere
name (str) – A name for the USD prim on the stage
color (tuple[float, float, float] | None) – The color of the sphere
rot (tuple)
parent_body (str | None)
is_template (bool)
visible (bool)

render_capsule( name, pos, rot, radius, half_height, parent_body=None, is_template=False, up_axis=1, color=None, visible=True, )[source]#

Add a capsule for visualization

Parameters:

pos (tuple) – The position of the capsule
radius (float) – The radius of the capsule
half_height (float) – The half height of the capsule
name (str) – A name for the USD prim on the stage
up_axis (int) – The axis of the capsule that points up (0: x, 1: y, 2: z)
color (tuple[float, float, float] | None) – The color of the capsule
rot (tuple)
parent_body (str | None)
is_template (bool)
visible (bool)

render_cylinder( name, pos, rot, radius, half_height, parent_body=None, is_template=False, up_axis=1, color=None, visible=True, )[source]#

Add a cylinder for visualization

Parameters:

pos (tuple) – The position of the cylinder
radius (float) – The radius of the cylinder
half_height (float) – The half height of the cylinder
name (str) – A name for the USD prim on the stage
up_axis (int) – The axis of the cylinder that points up (0: x, 1: y, 2: z)
color (tuple[float, float, float] | None) – The color of the capsule
rot (tuple)
parent_body (str | None)
is_template (bool)
visible (bool)

render_cone( name, pos, rot, radius, half_height, parent_body=None, is_template=False, up_axis=1, color=None, visible=True, )[source]#

Add a cone for visualization

Parameters:

pos (tuple) – The position of the cone
radius (float) – The radius of the cone
half_height (float) – The half height of the cone
name (str) – A name for the USD prim on the stage
up_axis (int) – The axis of the cone that points up (0: x, 1: y, 2: z)
color (tuple[float, float, float] | None) – The color of the cone
rot (tuple)
parent_body (str | None)
is_template (bool)
visible (bool)

render_box( name, pos, rot, extents, parent_body=None, is_template=False, color=None, visible=True, )[source]#

Add a box for visualization

Parameters:

pos (tuple) – The position of the box
extents (tuple) – The extents of the box
name (str) – A name for the USD prim on the stage
color (tuple[float, float, float] | None) – The color of the box
rot (tuple)
parent_body (str | None)
is_template (bool)
visible (bool)

render_mesh( name, points, indices, colors=None, pos=(0.0, 0.0, 0.0), rot=(0.0, 0.0, 0.0, 1.0), scale=(1.0, 1.0, 1.0), update_topology=False, parent_body=None, is_template=False, smooth_shading=True, visible=True, )[source]#

Add a mesh for visualization

Parameters:

points – The points of the mesh
indices – The indices of the mesh
colors – The colors of the mesh
pos – The position of the mesh
rot – The rotation of the mesh
scale – The scale of the mesh
name (str) – A name for the USD prim on the stage
smooth_shading (bool) – Whether to average face normals at each vertex or introduce additional vertices for each face
parent_body (str | None)
is_template (bool)
visible (bool)

render_arrow( name, pos, rot, base_radius, base_height, cap_radius=None, cap_height=None, parent_body=None, is_template=False, up_axis=1, color=None, visible=True, )[source]#

Add a arrow for visualization

Parameters:

pos (tuple) – The position of the arrow
base_radius (float) – The radius of the cylindrical base of the arrow
base_height (float) – The height of the cylindrical base of the arrow
cap_radius (float | None) – The radius of the conical cap of the arrow
cap_height (float | None) – The height of the conical cap of the arrow
name (str) – A name for the USD prim on the stage
up_axis (int) – The axis of the arrow that points up (0: x, 1: y, 2: z)
rot (tuple)
parent_body (str | None)
is_template (bool)
color (tuple[float, float, float] | None)
visible (bool)

render_ref(name, path, pos, rot, scale, color=None)[source]#

Create a reference (instance) with the given name to the given path.

Parameters:

name (str)
path (str)
pos (tuple)
rot (tuple)
scale (tuple)
color (tuple[float, float, float] | None)

render_points( name, points, radius, colors=None, as_spheres=True, visible=True, )[source]#

Add a set of points

Parameters:

points – The points to render
radius – The radius of the points (scalar or list)
colors – The colors of the points
name (str) – A name for the USD prim on the stage
as_spheres (bool)
visible (bool)

render_line_list( name, vertices, indices, color=None, radius=0.01, visible=True, )[source]#

Add a line list as a set of capsules

Parameters:

vertices – The vertices of the line-list
indices – The indices of the line-list
color (tuple[float, float, float] | None) – The color of the line
radius (float) – The radius of the line
name (str)
visible (bool)

render_line_strip( name, vertices, color=None, radius=0.01, visible=True, )[source]#

Add a line strip as a set of capsules

Parameters:

vertices – The vertices of the line-strip
color (tuple[float, float, float] | None) – The color of the line
radius (float) – The radius of the line
name (str)
visible (bool)

update_shape_vertices(shape, points)[source]#

Update vertex positions for a registered shape.

Parameters:

shape – Shape ID returned by register_shape().
points – Vertex positions as a warp.array or array-like.