Plotters#

A plotter visualizes sampled data live as the scene steps, and can save the animation. Pass one as the rec_options argument of scene.add_recorder. See Recording and playback for the recording workflow and the shared options (hz, buffer_size) that every plotter inherits.

A data function that returns a dict becomes one labeled subplot per key.

gs.recorders.PyQtLinePlot#

Draws a live line plot with PyQtGraph. The fastest option for high-rate time-series data, at the cost of a PyQt dependency.

class genesis.options.recorders.PyQtLinePlot(*, labels: tuple[str, ...] | dict[str, tuple[str, ...]] | None = None, x_label: str = '', y_label: str = '', history_length: int = 100, hz: float | None = None, buffer_size: int = 0, buffer_full_wait_time: float = 0.1, title: str = '', window_size: tuple[int, int] = (800, 600), save_to_filename: str | None = None, show_window: bool | None = None) → None[source]#

Live line plot visualization of data using PyQtGraph.

The recorded data_func should return scalar data (single scalar, a tuple of scalars, or a dict with string keys and scalar or tuple of scalars as values).

Parameters:

  • title (str) – The title of the plot.

  • window_size (tuple[int, int]) – The size of the window in pixels.

  • save_to_filename (str | None) – If provided, the animation will be saved to a file with the given filename.

  • show_window (bool | None) – Whether to show the window. If not provided, it will be set to True if a display is connected, False otherwise.

  • labels (tuple[str] | dict[str, tuple[str]] | None) – The labels for the plot. The length of the labels should match the length of the data. If a dict is provided, the data should also be a dict of tuples of strings that match the length of the data. The keys will be used as subplot titles and the values will be used as labels within each subplot.

  • x_label (str, optional) – Label for the horizontal axis.

  • y_label (str, optional) – Label for the vertical axis.

  • history_length (int) – The maximum number of previous data to store.

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

Bases: BasePyQtPlotter

build()[source]#

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

process(data, cur_time)[source]#

Process each incoming data sample.

Parameters:

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

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

cleanup()[source]#

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

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

gs.recorders.MPLLinePlot#

Draws a live line plot with Matplotlib. Use it for time-series data when you want a Matplotlib figure.

class genesis.options.recorders.MPLLinePlot(*, labels: tuple[str, ...] | dict[str, tuple[str, ...]] | None = None, x_label: str = '', y_label: str = '', history_length: int = 100, hz: float | None = None, buffer_size: int = 0, buffer_full_wait_time: float = 0.1, title: str = '', window_size: tuple[int, int] = (800, 600), save_to_filename: str | None = None, show_window: bool | None = None) → None[source]#

Live line plot visualization of data using matplotlib.

The recorded data_func should return scalar data (single scalar, a tuple of scalars, or a dict with string keys and scalar or tuple of scalars as values).

Parameters:

  • title (str) – The title of the plot.

  • window_size (tuple[int, int]) – The size of the window in pixels.

  • save_to_filename (str | None) – If provided, the animation will be saved to a file with the given filename.

  • show_window (bool | None) – Whether to show the window. If not provided, it will be set to True if a display is connected, False otherwise.

  • labels (tuple[str] | dict[str, tuple[str]] | None) – The labels for the plot. The length of the labels should match the length of the data. If a dict is provided, the data should also be a dict of tuples of strings that match the length of the data. The keys will be used as subplot titles and the values will be used as labels within each subplot.

  • x_label (str, optional) – Label for the horizontal axis.

  • y_label (str, optional) – Label for the vertical axis.

  • history_length (int) – The maximum number of previous data to store.

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

Bases: BaseMPLPlotter

build()[source]#

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

process(data, cur_time)[source]#

Process each incoming data sample.

Parameters:

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

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

cleanup()[source]#

Clean up matplotlib resources.

gs.recorders.MPLImagePlot#

Displays a 2D array as a live image or heatmap, for example a camera frame or a sensor grid.

class genesis.options.recorders.MPLImagePlot(*, hz: float | None = None, buffer_size: int = 0, buffer_full_wait_time: float = 0.1, title: str = '', window_size: tuple[int, int] = (800, 600), save_to_filename: str | None = None, show_window: bool | None = None) → None[source]#

Live visualization of image data 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).

Parameters:

  • title (str) – The title of the plot.

  • window_size (tuple[int, int]) – The size of the window in pixels.

  • save_to_filename (str | None) – If provided, the animation will be saved to a file with the given filename.

  • show_window (bool | None) – Whether to show the window. If not provided, it will be set to True if a display is connected, False otherwise.

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

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()[source]#

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

process(data, cur_time)[source]#

Process new image data and update display.

cleanup()[source]#

Clean up matplotlib resources.

gs.recorders.MPLVectorFieldPlot#

Draws a live vector field (quiver plot) from an array of 2D or 3D vectors.

class genesis.options.recorders.MPLVectorFieldPlot(*, hz: float | None = None, buffer_size: int = 0, buffer_full_wait_time: float = 0.1, title: str = '', window_size: tuple[int, int] = (800, 600), save_to_filename: str | None = None, show_window: bool | None = None, positions: tuple[tuple[float, float, float], ...], normal: tuple[float, float, float] = (0.0, 0.0, 1.0), scale_factor: float = 1.0, max_magnitude: float = 1.0, subplot_titles: tuple[str, ...] | None = None, twist_scale_factor: float | None = None, twist_max_magnitude: float = 1.0) → None[source]#

Live visualization of 3D vectors projected onto a 2D plane, colored by magnitude.

At initialization, provide the normal direction (view axis) and the 3D positions of each vector. The data_func should return an array of shape (N, 3) with the 3D vector at each position (e.g. displacement or force).

Parameters:

  • title (str) – The title of the plot.

  • window_size (tuple[int, int]) – The size of the window in pixels.

  • positions (array-like of shape (N, 3)) – The 3D positions of each vector (e.g. probe positions in link-local frame).

  • normal (tuple[float, float, float]) – The normal direction for projection (view axis). Vectors and positions are projected onto the plane perpendicular to this axis. Default: (0, 0, 1).

  • scale_factor (float, optional) – The scale factor to apply to the vectors. Defaults to 0.1.

  • max_magnitude (float, optional) – Maximum magnitude for the colorbar (colors are fixed to [0, max_magnitude]). Defaults to 1.0.

  • subplot_titles (StrArrayType | None, optional) – If provided, the figure holds one subplot per title (K subplots in a near-square grid), all sharing positions; the data_func then returns shape (K, N, 3) – one vector field per subplot. None (default) is a single plot whose data_func returns (N, 3).

  • twist_scale_factor (float | None, optional) – When set, overlays a curved rotation arrow at each position showing the twist about the view normal (the twist_vectors . normal component), with arc radius scaled by this factor – useful for reading a rotational quantity (e.g. per-taxel torque) alongside the straight vectors. The data_func then returns a pair (vectors, twist_vectors) instead of a single array, each shaped as above. The cost is a busier plot and a second colorbar. None (default) draws only the straight vectors.

  • twist_max_magnitude (float, optional) – Range for the diverging twist colorbar (colors fixed to [-twist_max_magnitude, +twist_max_magnitude], centered at zero). Only used when twist_scale_factor is set. Defaults to 1.0.

  • save_to_filename (str | None) – If provided, the animation will be saved to a file with the given filename.

  • show_window (bool | None) – Whether to show the window. If not provided, it will be set to True if a display is connected, False otherwise.

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

Bases: BaseMPLPlotter

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

The data_func returns an array of shape (N, 3) with the 3D vector at each position. When subplot_titles is set (K titles), the figure holds K subplots sharing the same positions, and the data_func instead returns shape (K, N, 3) – one vector field per subplot (e.g. one per environment).

When twist_scale_factor is set, a curved rotation arrow is overlaid at each position for the twist about the view normal (the twist_vectors . normal component), and the data_func instead returns a pair (vectors, twist_vectors) with each entry shaped as above. Positive twist (right-hand rule about normal) sweeps counter-clockwise; the arc is colored by signed twist on a diverging colorbar centered at zero.

build()[source]#

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

process(data, cur_time)[source]#

Process new vector data and update each subplot’s quiver (and the twist overlay when enabled).

cleanup()[source]#

Clean up matplotlib resources.

See also#