Plotters

Genesis provides real-time plotting recorders for visualizing simulation data during execution.

Available Plotters

Plotter	Description
MPLLinePlot	Matplotlib line plot (time series)
MPLImagePlot	Matplotlib image display

MPLLinePlot

Real-time line plots using Matplotlib:

import genesis as gs

gs.init()
scene = gs.Scene()
robot = scene.add_entity(gs.morphs.URDF(file="robot.urdf"))
scene.build()

# Plot joint positions over time
scene.start_recording(
    data_func=lambda: robot.get_qpos()[:3],  # First 3 joints
    rec_options=gs.recorders.MPLLinePlot(
        title="Joint Positions",
    ),
)

for i in range(1000):
    scene.step()
scene.stop_recording()

Configuration

gs.recorders.MPLLinePlot(
    title="Plot Title",           # Plot title
    hz=30,                        # Update rate
)

MPLImagePlot

Display images in real-time:

cam = scene.add_camera(res=(320, 240), pos=(3, 0, 2), lookat=(0, 0, 0.5))

scene.start_recording(
    data_func=lambda: cam.render(rgb=True),
    rec_options=gs.recorders.MPLImagePlot(
        title="Camera View",
    ),
)

for i in range(500):
    scene.step()
scene.stop_recording()

Multiple Recorders

You can start multiple recorders for different data streams by calling start_recording multiple times or using the RecorderManager directly.

Performance Tips

1. Reduce update rate: Use lower hz for complex plots

2. Limit data points: Use smaller window_size

3. Use async mode: Enable async_mode=True for background updates

API Reference

class genesis.recorders.plotters.BasePlotter(manager: RecorderManager, options: BasePlotterOptions, data_func: Callable[[], T])

Bases: Recorder

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

process(data, cur_time)

Process each incoming data sample.

Parameters:

• data (Any) – The data to be processed.

• cur_time (float) – The current time of the simulation.

cleanup()

Cleanup all resources, e.g. by closing widgets or files.

This method is called when recording is stopped by scene.stop_recording().

get_image_array()

Capture the plot image as a video frame.

Returns:

image_array – The RGB image as a numpy array.

Return type:

np.ndarray

class genesis.recorders.plotters.LinePlotHelper(options: LinePlotterMixinOptions, data: dict[str, collections.abc.Sequence] | Sequence)

Bases: object

Helper class that manages line plot data.

Use composition pattern.

clear_data()

process(data, cur_time)

Process new data point and update plot.

property history_length

property is_dict_data

property subplot_structure

class genesis.recorders.plotters.BasePyQtPlotter(manager: RecorderManager, options: BasePlotterOptions, data_func: Callable[[], T])

Bases: BasePlotter

Base class for PyQt based plotters.

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

cleanup()

Cleanup all resources, e.g. by closing widgets or files.

This method is called when recording is stopped by scene.stop_recording().

property run_in_thread: bool

Whether to run the recorder in a background thread.

Running in a background thread allows for processing data without blocking the main thread, so this is encouraged for most recorders (simply return True), but implementers should check that the recorder is thread-safe on all devices (threading on macOS tends to be less supported).

get_image_array()

Capture the plot image as a video frame.

Returns:

image_array – The image as a numpy array in (b,g,r,a) format.

Return type:

np.ndarray

class genesis.recorders.plotters.PyQtLinePlotter(manager: RecorderManager, options: BasePlotterOptions, data_func: Callable[[], T])

Bases: BasePyQtPlotter

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

process(data, cur_time)

Process each incoming data sample.

Parameters:

• data (Any) – The data to be processed.

• cur_time (float) – The current time of the simulation.

cleanup()

Cleanup all resources, e.g. by closing widgets or files.

This method is called when recording is stopped by scene.stop_recording().

class genesis.recorders.plotters.BaseMPLPlotter(manager: RecorderManager, options: BasePlotterOptions, data_func: Callable[[], T])

Bases: BasePlotter

Base class for matplotlib based plotters.

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

cleanup()

Clean up matplotlib resources.

get_image_array()

Capture the plot image as a video frame.

Returns:

image_array – The RGB image as a numpy array.

Return type:

np.ndarray

property run_in_thread: bool

Whether to run the recorder in a background thread.

Running in a background thread allows for processing data without blocking the main thread, so this is encouraged for most recorders (simply return True), but implementers should check that the recorder is thread-safe on all devices (threading on macOS tends to be less supported).

class genesis.recorders.plotters.MPLLinePlotter(manager: RecorderManager, options: BasePlotterOptions, data_func: Callable[[], T])

Bases: BaseMPLPlotter

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

process(data, cur_time)

Process each incoming data sample.

Parameters:

• data (Any) – The data to be processed.

• cur_time (float) – The current time of the simulation.

cleanup()

Clean up matplotlib resources.

class genesis.recorders.plotters.MPLImagePlotter(manager: RecorderManager, options: BasePlotterOptions, data_func: Callable[[], T])

Bases: BaseMPLPlotter

Live image viewer using matplotlib.

The image data should be an array-like object with shape (H, W), (H, W, 1), (H, W, 3), or (H, W, 4).

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

process(data, cur_time)

Process new image data and update display.

cleanup()

Clean up matplotlib resources.

class genesis.recorders.plotters.MPLVectorFieldPlotter(manager: RecorderManager, options: BasePlotterOptions, data_func: Callable[[], T])

Bases: BaseMPLPlotter

Live 3D vector field viewer: projects positions and vectors onto a 2D plane and plots arrows colored by magnitude.

The data_func should return an array of shape (N, 3) with the 3D vector at each position given in options.

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

on_resize(event)

process(data, cur_time)

Process new vector data and update the quiver plot.

cleanup()

Clean up matplotlib resources.

See Also

• Recording & Playback - Recording overview

• File Writers - File export