env

irsim.env.env_base

Class EnvBase is the base class of the environment. This class will read the yaml file and create the world, robot, obstacle, and map objects.

Author: Ruihua Han

class irsim.env.env_base.EnvBase(world_name: str | None = None, display: bool = True, disable_all_plot: bool = False, save_ani: bool = False, full: bool = False, log_file: str | None = None, log_level: str = 'INFO')

Bases: object

The base class of environment. This class will read the yaml file and create the world, robot, obstacle, and map objects.

Parameters:

• world_name (str) – Path to the world yaml file.

• display (bool) – Flag to display the environment.

• disable_all_plot (bool) – Flag to disable all plots and figures.

• save_ani (bool) – Flag to save the animation.

• full (bool) – Flag to full screen the figure.

• log_file (str) – Name of the log file.

• log_level (str) – Level of the log output.

step(action: ndarray | list | None = None, action_id: int | list | None = 0)

Perform a simulation step in the environment.

Parameters:

• action (list or numpy array 2*1) –

  Action to be performed in the environment.

  • differential robot action: linear velocity, angular velocity

  • omnidirectional robot action: v_x – velocity in x; v_y – velocity in y

  • Ackermann robot action: linear velocity, Steering angle

• action_id (int or list of int) – Apply the action(s) to the robot(s) with the given id(s).

render(interval: float = 0.02, figure_kwargs={}, mode: str = 'dynamic', **kwargs)

Render the environment.

Parameters:

• interval (float) – Time interval between frames in seconds.

• figure_kwargs (dict) – Additional keyword arguments for saving figures, see savefig for detail.

• mode (str) – “dynamic”, “static”, “all” to specify which type of objects to draw and clear.

• kwargs – Additional keyword arguments for drawing components. see ObjectBase.plot() function for detail.

show()

Show the environment figure.

draw_trajectory(traj: list, traj_type: str = 'g-', **kwargs)

Draw the trajectory on the environment figure.

Parameters:

• traj (list) – List of trajectory points (2 * 1 vector).

• traj_type – Type of the trajectory line, see matplotlib plot function for detail.

• **kwargs – Additional keyword arguments for drawing the trajectory, see EnvPlot.draw_trajectory() for detail.

draw_points(points: list, s: int = 30, c: str = 'b', refresh: bool = True, **kwargs)

Draw points on the environment figure.

Parameters:

• points (list) – List of points (2*1) to be drawn. or (np.array): (2, Num) to be drawn.

• s (int) – Size of the points.

• c (str) – Color of the points.

• refresh (bool) – Flag to refresh the points in the figure.

• **kwargs – Additional keyword arguments for drawing the points, see ax.scatter function for detail.

draw_box(vertex: ndarray, refresh: bool = False, color: str = '-b')

Draw a box by the vertices.

Parameters:

• vertex (np.ndarray) – matrix of vertices, point_dim*vertex_num

• refresh (bool) – whether to refresh the plot, default True

• color (str) – color of the box, default ‘-b’

draw_quiver(point, refresh=False, **kwargs)

Draw a single quiver (arrow) on the environment figure.

Parameters:

• point – Point data for the quiver

• refresh (bool) – Flag to refresh the quiver in the figure, default False

• **kwargs – Additional keyword arguments for drawing the quiver

draw_quivers(points, refresh=False, **kwargs)

Draw multiple quivers (arrows) on the environment figure.

Parameters:

• points – Points data for the quivers

• refresh (bool) – Flag to refresh the quivers in the figure, default False

• **kwargs – Additional keyword arguments for drawing the quivers

end(ending_time: float = 3.0, **kwargs)

End the simulation, save the animation, and close the environment.

Parameters:

• ending_time (float) – Time in seconds to wait before closing the figure, default is 3 seconds.

• **kwargs – Additional keyword arguments for saving the animation, see EnvPlot.save_animate() for detail.

done(mode: str = 'all')

Check if the simulation is done.

Parameters:

mode (str) –

Mode to check if all or any of the objects are done.

• all (str): Check if all objects are done.

• any (str): Check if any of the objects are done.

Returns:

True if the simulation is done based on the specified mode, False otherwise.

Return type:

bool

step_status()

Get the status of the environment.

pause()

Pause the environment.

resume()

Resume the environment.

reset()

Reset the environment.

reset_plot()

Reset the environment figure.

random_obstacle_position(range_low: list = [0, 0, -3.14], range_high: list = [10, 10, 3.14], ids: list | None = None, non_overlapping: bool = False)

Random obstacle positions in the environment.

Parameters:

• range_low (list [x, y, theta]) – Lower bound of the random range for the obstacle states. Default is [0, 0, -3.14].

• range_high (list [x, y, theta]) – Upper bound of the random range for the obstacle states. Default is [10, 10, 3.14].

• ids (list) – A list of IDs of objects for which to set random positions. Default is None.

• non_overlapping (bool) – If set, the obstacles that will be reset to random obstacles will not overlap with other obstacles. Default is False.

random_polygon_shape(center_range: list = [0, 0, 10, 10], avg_radius_range: list = [0.1, 1], irregularity_range: list = [0, 1], spikeyness_range: list = [0, 1], num_vertices_range: list = [4, 10])

Random polygon shapes for the obstacles in the environment.

Parameters:

• center_range (list) – Range of the center of the polygon. Default is [0, 0, 10, 10].

• avg_radius_range (list) – Range of the average radius of the polygon. Default is [0.1, 1].

• irregularity_range (list) – Range of the irregularity of the polygon. Default is [0, 1].

• spikeyness_range (list) – Range of the spikeyness of the polygon. Default is [0, 1].

• num_vertices_range (list) – Range of the number of vertices of the polygon. Default is [4, 10].

• center (Tuple[float, float]) – a pair representing the center of the circumference used to generate the polygon.

• avg_radius (float) – the average radius (distance of each generated vertex to the center of the circumference) used to generate points with a normal distribution.

• irregularity (float) – 0 - 1 variance of the spacing of the angles between consecutive vertices.

• spikeyness (float) – 0 - 1 variance of the distance of each vertex to the center of the circumference.

• num_vertices (int) – the number of vertices of the polygon.

create_obstacle(**kwargs)

Create an obstacle in the environment.

Parameters:

**kwargs – Additional parameters for obstacle creation. see ObjectFactory.create_obstacle for detail

Returns:

An instance of an obstacle.

Return type:

Obstacle

add_object(obj: ObjectBase)

Add the object to the environment.

Parameters:

obj (ObjectBase) – The object to be added to the environment.

add_objects(objs: list)

Add the objects to the environment.

Parameters:

objs (list) – List of objects to be added to the environment.

delete_object(target_id: int)

Delete the object with the given id.

Parameters:

target_id (int) – ID of the object to be deleted.

delete_objects(target_ids: list)

Delete the objects with the given ids.

Parameters:

target_ids (list) – List of IDs of objects to be deleted.

build_tree()

Build the geometry tree for the objects in the environment to detect the possible collision objects.

get_robot_state()

Get the current state of the robot.

Returns:

3*1 vector [x, y, theta]

Return type:

state

get_lidar_scan(id: int = 0)

Get the lidar scan of the robot with the given id.

Parameters:

id (int) – Id of the robot.

Returns:

Dict of lidar scan points, see world.sensors.lidar2d.Lidar2D.get_scan() for detail.

Return type:

Dict

get_lidar_offset(id: int = 0)

Get the lidar offset of the robot with the given id.

Parameters:

id (int) – Id of the robot.

Returns:

Lidar offset of the robot, [x, y, theta]

Return type:

list of float

get_obstacle_info_list()

Get the information of the obstacles in the environment.

Returns:

List of obstacle information, see ObjectBase.get_obstacle_info() for detail.

Return type:

list of dict

get_robot_info(id: int = 0)

Get the information of the robot with the given id.

Parameters:

id (int) – Id of the robot.

Returns:

see ObjectBase.get_info() for detail

get_robot_info_list()

Get the information of the robots in the environment.

Returns:

List of robot information, see ObjectBase.get_info() for detail.

Return type:

list of dict

get_map(resolution: float = 0.1)

Get the map of the environment with the given resolution.

Parameters:

resolution (float) – Resolution of the map. Default is 0.1.

Returns:

The map of the environment with the specified resolution.

set_title(title: str)

Set the title of the plot.

save_figure(save_name: str | None = None, include_index: bool = False, save_gif: bool = False, **kwargs)

Save the current figure.

Parameters:

• save_name (str) – Name of the file with format to save the figure. Default is None.

• include_index (bool) – Flag to include index in the saved file name. Default is False.

• save_gif (bool) – Flag to save as GIF format. Default is False.

• **kwargs –

  Additional keyword arguments for saving the figure, see savefig function for detail.

load_behavior(behaviors: str = 'behavior_methods')

Load behavior parameters from the script. Please refer to the behavior_methods.py file for more details. Please make sure the python file is placed in the same folder with the implemented script.

Parameters:

behaviors (str) – name of the bevavior script.

property robot_list

Get the list of robots in the environment.

Returns:

List of robot objects [].

Return type:

list

property obstacle_list

Get the list of obstacles in the environment.

Returns:

List of obstacle objects.

Return type:

list

property objects

Get all objects in the environment.

Returns:

List of all objects in the environment.

Return type:

list

property static_objects

Get all static objects in the environment.

Returns:

List of static objects in the environment.

Return type:

list

property dynamic_objects

Get all dynamic objects in the environment.

Returns:

List of dynamic objects in the environment.

Return type:

list

property step_time

Get the step time of the simulation.

Returns:

Step time of the simulation from the world.

Return type:

float

property time

Get the time of the simulation.

property status

Get the status of the environment.

property robot

Get the first robot in the environment.

Returns:

The first robot object in the robot list.

Return type:

Robot

property obstacle_number

Get the number of obstacles in the environment.

Returns:

Number of obstacles in the environment.

Return type:

int

property robot_number

Get the number of robots in the environment.

Returns:

Number of robots in the environment.

Return type:

int

property logger

Get the environment logger.

Returns:

The logger instance for the environment.

Return type:

EnvLogger

property key_vel

property key_id

property mouse_pos

property mouse_left_pos

property mouse_right_pos

class irsim.env.env_base3d.EnvBase3D(world_name, **kwargs)

Bases: EnvBase

This class is the 3D version of the environment class. It inherits from the EnvBase class to provide the 3D plot environment.

irsim.env.env_logger

class irsim.env.env_logger.EnvLogger(log_file: str | None = 'irsim_error.log', log_level='WARNING')

Bases: object

info(msg)

Log an info message.

Parameters:

msg (str) – The message to log.

error(msg)

Log an error message.

Parameters:

msg (str) – The message to log.

debug(msg)

Log a debug message.

Parameters:

msg (str) – The message to log.

warning(msg)

Log a warning message.

Parameters:

msg (str) – The message to log.

irsim.env.env_config

class irsim.env.env_config.EnvConfig(world_name)

Bases: object

The base class of environment parameters read from yaml file.

basic categories: world, plot, robot, obstacle See for detail

property parse

The parsed kwargs from the yaml file.

property logger

Get the logger of the env_param.

irsim.env.env_plot

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

Author: Ruihua Han

class irsim.env.env_plot.EnvPlot(world, objects=[], saved_figure={}, figure_pixels: list = [1000, 800], show_title: bool = True, **kwargs)

Bases: object

EnvPlot class for visualizing the environment.

Parameters:

• world – The world object containing environment information including grid_map, x_range, y_range.

• objects (list, optional) – List of objects in the environment. Default is [].

• saved_figure (dict, optional) – Keyword arguments for saving the figure. See https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html for details. Default is dict().

• figure_pixels (list, optional) – Width and height of the figure in pixels. Default is [1180, 1080].

• show_title (bool, optional) – Whether to show the title. Default is True.

• kwargs – Additional options such as color_map, no_axis, and tight.

init_plot(grid_map, objects, no_axis=False, tight=True, **kwargs)

Initialize the plot with the given grid map and objects.

Parameters:

• grid_map (optional) – The grid map of the environment.

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

• no_axis (bool, optional) – Whether to show the axis. Default is False.

• tight (bool, optional) – Whether to show the axis tightly. Default is True.

step(mode='dynamic', objects=[], **kwargs)

init_objects_plot(objects, **kwargs)

step_objects_plot(mode='dynamic', objects=[], **kwargs)

Update the plot for the objects.

draw_components(mode='all', objects=[], **kwargs)

Draw the components in the environment.

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='all', objects=[])

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=None, **kwargs)

Draw the grid map on the plot.

Parameters:

grid_map (optional) – The grid map to draw.

draw_trajectory(traj, traj_type='g-', label='trajectory', show_direction=False, refresh=False, **kwargs)

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, s=10, c='m', refresh=True, **kwargs)

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, refresh=False, color='black', **kwargs)

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, refresh=False, color='black', **kwargs)

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, refresh=False, color='b-')

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()

save_figure(file_name='', file_format='png', include_index=False, save_gif=False, **kwargs)

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='animation', suffix='.gif', keep_len=30, rm_fig_path=True, **kwargs)

Save the animation.

Parameters:

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

• keep_len (int) – Length of the last frame. Default is 30.

• 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. See format_gif for details.

show()

Display the plot.

close()

Close the plot.

property logger

irsim.env.env_plot.linewidth_from_data_units(linewidth, axis, reference='y')

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