irsim.env.env_plot

This file is the implementation of the environment plot to visualize the environment objects.

Author: Ruihua Han

Classes

EnvPlot

EnvPlot class for visualizing the environment.

Functions

linewidth_from_data_units(→ float)	Convert a linewidth in data units to linewidth in points.
draw_patch(→ Any)	Draw a geometric element (patch or line) on the given axes.
set_patch_property(→ None)	Apply transform and style properties to a patch/artist, matching ObjectBase semantics.

Module Contents

class irsim.env.env_plot.EnvPlot(world: Any, objects: list[Any] | None = None, **kwargs: Any)

EnvPlot class for visualizing the environment.

Parameters:

• world – The world object with ranges and a plot_parse dictionary that configures plotting (e.g., saved_figure, figure_pixels, show_title, no_axis, tight).

• objects (list, optional) – Initial objects to draw. Default is [].

• kwargs – Plot overrides that update world.plot_parse at runtime (e.g., saved_figure, figure_pixels, show_title, no_axis, tight).

Initialize the EnvPlot instance.

Sets up the matplotlib figure, configures plotting parameters, and initializes the plot with world data and objects. Any provided kwargs override values in world.plot_parse.

saved_figure_kwargs: dict[str, Any]

viewpoint

dyna_line_list: list[Any] = []

dyna_point_list: list[Any] = []

dyna_quiver_list: list[Any] = []

step(mode: str = 'dynamic', objects: list[Any] | None = None, **kwargs: Any) → None

Advance the plot by one step for the given objects.

Parameters:

• mode (str) – Which objects to update: “dynamic”, “static”, or “all”.

• objects (list | None) – The objects to update/draw. Defaults to empty list.

• **kwargs – Extra drawing options passed through to objects’ plot methods.

init_objects_plot(objects: list[Any], **kwargs: Any) → None

Initialize plot state for provided objects, then render once.

Parameters:

• objects (list) – Objects to be initialized on the axes.

• **kwargs – Extra drawing options passed to initialization/plot.

step_objects_plot(mode: str = 'dynamic', objects: list[Any] | None = None, **kwargs: Any) → None

Update the plot for the objects by transform based on the object’s original geometry.

draw_components(mode: str = 'all', objects: list[Any] | None = None, **kwargs: Any) → None

Draw the components in the environment with global axis.

Parameters:

• mode (str) – ‘static’, ‘dynamic’, or ‘all’ to specify which objects to draw.

• objects (list) – List of objects to draw.

• kwargs – Additional plotting options.

clear_components(mode: str = 'all', objects: list[Any] | None = None) → None

Clear the components in the environment.

Parameters:

• mode (str) – ‘static’, ‘dynamic’, or ‘all’ to specify which objects to clear.

• objects (list) – List of objects to clear.

draw_grid_map(grid_map: Any | None = None, **kwargs: Any) → None

Draw the grid map on the plot.

Parameters:

grid_map (optional) – The grid map to draw.

draw_trajectory(traj: list[Any] | numpy.ndarray, traj_type: str = 'g-', label: str = 'trajectory', show_direction: bool = False, refresh: bool = False, **kwargs: Any) → None

Draw a trajectory on the plot.

Parameters:

• traj (list or np.ndarray) – List of points or array of points [x, y, theta].

• traj_type (str) – Type of trajectory line (e.g., ‘g-‘). See https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.plot.html for details.

• label (str) – Label for the trajectory.

• show_direction (bool) – Whether to show the direction of the trajectory.

• refresh (bool) – Whether to refresh the plot.

• kwargs – Additional plotting options for ax.plot()

draw_points(points: list[Any] | numpy.ndarray | None, s: int = 10, c: str = 'm', refresh: bool = True, **kwargs: Any) → None

Draw points on the plot.

Parameters:

• points (list) – List of points, each point as [x, y] or (2, 1) array or (np.array): points array: (2, N), NL number of points

• s (int) – Size of the points.

• c (str) – Color of the points.

• refresh (bool) – Whether to refresh the plot.

• kwargs – Additional plotting options.

draw_quiver(point: numpy.ndarray | None, refresh: bool = False, color: str = 'black', **kwargs: Any) → None

Draw a quiver plot on the plot.

Parameters:

• points (4*1 np.ndarray) – List of points, each point as [x, y, u, v]. u, v are the components of the vector.

• kwargs – Additional plotting options.

draw_quivers(points: collections.abc.Iterable[numpy.ndarray], refresh: bool = False, color: str = 'black', **kwargs: Any) → None

Draw a series of quiver plot on the plot.

Parameters:

points (list or np.ndarray) – List of points, each point as [x, y, u, v]. u, v are the components of the vector.

draw_box(vertices: numpy.ndarray, refresh: bool = False, color: str = 'b-') → None

Draw a box by the vertices.

Parameters:

• vertices (np.ndarray) – 2xN array of vertices.

• refresh (bool) – Whether to refresh the plot.

• color (str) – Color and line type of the box.

update_title() → None

Update the figure title with current time/status or a custom title.

save_figure(file_name: str = '', file_format: str = 'png', include_index: bool = False, save_gif: bool = False, **kwargs: Any) → None

Save the current figure.

Parameters:

• file_name (str) – Name of the figure. Default is ‘’.

• file_format (str) – Format of the figure. Default is ‘png’.

• kwargs – Additional arguments for saving the figure. See https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html for details.

save_animate(ani_name: str = 'animation', suffix: str = '.gif', last_frame_duration: int = 1, rm_fig_path: bool = True, **kwargs: Any) → None

Save the animation by streaming frames to avoid loading all images into memory.

Parameters:

• ani_name (str) – Name of the animation. Default is ‘animation’.

• last_frame_duration (int) – Duration of the last frame for the gif. Default is 1 second.

• suffix (str) – Suffix of the animation file. Default is ‘.gif’.

• rm_fig_path (bool) – Whether to remove the figure path after saving. Default is True.

• kwargs – Additional arguments for saving the animation. For GIF: See pillow plugin documentation. For video: See ffmpeg/pyav plugin documentation.

set_ax_viewpoint(objects: list[Any] | None = None) → None

Set the viewpoint of the plot windows by the viewpoint parameter.

Parameters:

objects (list) – List of objects to search for the viewpoint.

show() → None

Display the plot.

close() → None

Close the plot.

property logger

property x_range

property y_range

irsim.env.env_plot.linewidth_from_data_units(linewidth: float, axis: Any, reference: str = 'y') → float

Convert a linewidth in data units to linewidth in points.

Parameters:

• linewidth (float) – Linewidth in data units of the respective reference-axis

• axis (matplotlib axis) – The axis which is used to extract the relevant transformation data (data limits and size must not change afterwards)

• reference (string) – The axis that is taken as a reference for the data width. Possible values: ‘x’ and ‘y’. Defaults to ‘y’.

Returns:

linewidth – Linewidth in points

Return type:

float

irsim.env.env_plot.draw_patch(ax: Any, shape: str, state: numpy.ndarray | None = None, radius: float | None = None, vertices: numpy.ndarray | None = None, color: str | None = None, zorder: int | None = None, linestyle: str | None = None, **kwargs: Any) → Any

Draw a geometric element (patch or line) on the given axes.

Supported shapes and expected inputs (refer to irsim.world.object_base plotting patterns): - circle: use state (x,y,theta) and radius; created at origin and transformed - rectangle: prefer vertices (2xN) else use width/height with state transform - polygon: use vertices (2xN) - ellipse: use width/height with state transform - wedge: use radius and either theta1/theta2 (deg) or fov (rad); transformed by state - arrow: use state for position/orientation or provide theta; supports arrow_length and arrow_width - line|linestring: use vertices (2xN) to draw a line element

Styling: - color/edgecolor/facecolor, alpha, zorder, linestyle are respected when applicable.

Returns the created matplotlib artist (patch, line, or list from ax.plot).

irsim.env.env_plot.set_patch_property(element: Any, ax: Any, state: numpy.ndarray | None = None, **kwargs: Any) → None

Apply transform and style properties to a patch/artist, matching ObjectBase semantics.

• If state provided with at least 3 rows, apply rotation by theta and translation by (x, y).

• Apply color/facecolor/edgecolor, alpha, zorder, linestyle when supported.