lib

irsim.lib.behavior

class irsim.lib.behavior.behavior.Behavior(object_info=None, behavior_dict=None)

Bases: object

Represents the behavior of an agent in the simulation.

Parameters:

• object_info (object) – Object information from the object_base class ObjectInfo.

• behavior_dict (dict) –

  Dictionary containing behavior parameters for different behaviors. Name Options include: ‘dash’, ‘rvo’. target_roles:

  ’all’: all objects in the environment will be considered within this behavior. ‘obstacle’: only obstacles will be considered within this behavior. ‘robot’: only robots will be considered within this behavior.

gen_vel(ego_object, external_objects=[])

Generate velocity for the agent based on the behavior dictionary.

Parameters:

• ego_object – the object itself

• external_objects – all the other objects in the environment

Returns:

Generated velocity for the agent.

Return type:

np.array (2, 1)

load_behavior(behaviors: str = '.behavior_methods')

Load behavior parameters from the script.

Parameters:

behaviors (str) – name of the bevavior script.

invoke_behavior(kinematics: str, action: str, **kwargs: Any) → Any

Invoke a behavior method.

Parameters:

• kinematics (str) – Name of the behavior method. only support: ‘diff’, ‘omni’, ‘acker’.

• action – Name of the action method. example: ‘dash’, ‘rvo’.

• **kwargs – Arbitrary keyword arguments.

Returns:

Velocity (2x1).

Return type:

np.array

property logger

irsim.lib.behavior_methods

irsim.lib.behavior.behavior_methods.beh_diff_rvo(ego_object, external_objects, **kwargs)

Behavior function for differential drive robot using RVO (Reciprocal Velocity Obstacles).

Parameters:

• ego_object – The ego robot object.

• external_objects (list) – List of external objects in the environment.

• **kwargs – Additional keyword arguments: - vxmax (float): Maximum x velocity, default 1.5. - vymax (float): Maximum y velocity, default 1.5. - acce (float): Acceleration factor, default 1.0. - factor (float): Additional scaling factor, default 1.0. - mode (str): RVO calculation mode, default “rvo”. - neighbor_threshold (float): Neighbor threshold distance, default 10.0.

Returns:

Velocity [linear, angular] (2x1) for differential drive.

Return type:

np.array

irsim.lib.behavior.behavior_methods.beh_diff_dash(ego_object, external_objects, **kwargs)

Behavior function for differential drive robot using dash-to-goal behavior.

Parameters:

• ego_object – The ego robot object.

• external_objects (list) – List of external objects in the environment.

• **kwargs – Additional keyword arguments: - angle_tolerance (float): Allowable angular deviation, default 0.1.

Returns:

Velocity [linear, angular] (2x1) for differential drive.

Return type:

np.array

irsim.lib.behavior.behavior_methods.beh_omni_dash(ego_object, external_objects, **kwargs)

Behavior function for omnidirectional robot using dash-to-goal behavior.

Parameters:

• ego_object – The ego robot object.

• external_objects (list) – List of external objects in the environment.

• **kwargs – Additional keyword arguments (currently unused).

Returns:

Velocity [vx, vy] (2x1) for omnidirectional drive.

Return type:

np.array

irsim.lib.behavior.behavior_methods.beh_omni_rvo(ego_object, external_objects, **kwargs)

Behavior function for omnidirectional robot using RVO (Reciprocal Velocity Obstacles).

Parameters:

• ego_object – The ego robot object.

• external_objects (list) – List of external objects in the environment.

• **kwargs – Additional keyword arguments: - vxmax (float): Maximum x velocity, default 1.5. - vymax (float): Maximum y velocity, default 1.5. - acce (float): Acceleration factor, default 1.0. - factor (float): Additional scaling factor, default 1.0. - mode (str): RVO calculation mode, default “rvo”. - neighbor_threshold (float): Neighbor threshold distance, default 3.0.

Returns:

Velocity [vx, vy] (2x1) for omnidirectional drive.

Return type:

np.array

irsim.lib.behavior.behavior_methods.beh_acker_dash(ego_object, external_objects, **kwargs)

Behavior function for Ackermann steering robot using dash-to-goal behavior.

Parameters:

• ego_object – The ego robot object.

• external_objects (list) – List of external objects in the environment.

• **kwargs – Additional keyword arguments: - angle_tolerance (float): Allowable angular deviation, default 0.1.

Returns:

Velocity [linear, steering angle] (2x1) for Ackermann drive.

Return type:

np.array

irsim.lib.behavior.behavior_methods.OmniRVO(state_tuple, neighbor_list=None, vxmax=1.5, vymax=1.5, acce=1, factor=1.0, mode='rvo', neighbor_threshold=3.0)

Calculate the omnidirectional velocity using RVO.

Parameters:

• state_tuple (tuple) – Current state and orientation.

• neighbor_list (list) – List of neighboring agents (default None).

• vxmax (float) – Maximum x velocity (default 1.5).

• vymax (float) – Maximum y velocity (default 1.5).

• acce (float) – Acceleration factor (default 1).

• factor (float) – Additional scaling factor (default 1.0).

• mode (str) – RVO calculation mode (default “rvo”).

• neighbor_threshold (float) – Neighbor threshold (default 3.0).

Returns:

Velocity [vx, vy] (2x1).

Return type:

np.array

irsim.lib.behavior.behavior_methods.DiffRVO(state_tuple, neighbor_list=None, vxmax=1.5, vymax=1.5, acce=1, factor=1.0, mode='rvo', neighbor_threshold=3.0)

Calculate the differential drive velocity using RVO.

Parameters:

• state_tuple (tuple) – Current state and orientation.

• neighbor_list (list) – List of neighboring agents (default None).

• vxmax (float) – Maximum x velocity (default 1.5).

• vymax (float) – Maximum y velocity (default 1.5).

• acce (float) – Acceleration factor (default 1).

• factor (float) – Additional scaling factor (default 1.0).

• mode (str) – RVO calculation mode (default “rvo”).

• neighbor_threshold (float) – Neighbor threshold (default 3.0).

Returns:

Velocity [linear, angular] (2x1).

Return type:

np.array

irsim.lib.behavior.behavior_methods.OmniDash(state, goal, max_vel, goal_threshold=0.1)

Calculate the omnidirectional velocity to reach a goal.

Parameters:

• state (np.array) – Current state [x, y] (2x1).

• goal (np.array) – Goal position [x, y] (2x1).

• max_vel (np.array) – Maximum velocity [vx, vy] (2x1).

• goal_threshold (float) – Distance threshold to consider goal reached (default 0.1).

Returns:

Velocity [vx, vy] (2x1).

Return type:

np.array

irsim.lib.behavior.behavior_methods.DiffDash(state, goal, max_vel, goal_threshold=0.1, angle_tolerance=0.2)

Calculate the differential drive velocity to reach a goal.

Parameters:

• state (np.array) – Current state [x, y, theta] (3x1).

• goal (np.array) – Goal position [x, y] (2x1).

• max_vel (np.array) – Maximum velocity [linear, angular] (2x1).

• goal_threshold (float) – Distance threshold to consider goal reached (default 0.1).

• angle_tolerance (float) – Allowable angular deviation (default 0.2).

Returns:

Velocity [linear, angular] (2x1).

Return type:

np.array

irsim.lib.behavior.behavior_methods.AckerDash(state, goal, max_vel, goal_threshold, angle_tolerance)

Calculate the Ackermann steering velocity to reach a goal.

Parameters:

• state (np.array) – Current state [x, y, theta] (3x1).

• goal (np.array) – Goal position [x, y] (2x1).

• max_vel (np.array) – Maximum velocity [linear, steering angle] (2x1).

• goal_threshold (float) – Distance threshold to consider goal reached.

• angle_tolerance (float) – Allowable angular deviation.

Returns:

Velocity [linear, steering angle] (2x1).

Return type:

np.array

irsim.lib.handler

class irsim.lib.handler.geometry_handler.geometry_handler(name: str, **kwargs)

Bases: ABC

This class is used to handle the geometry of the object. It reads the shape parameters from yaml file and constructs the geometry of the object.

abstractmethod construct_original_geometry(**kwargs)

Construct the original geometry of the object when the state is in the origin of coordinates.

Parameters:

**kwargs – shape parameters

Returns: Geometry of the object

step(state)

Transform geometry to the new state.

Parameters:

state (np.ndarray) – State vector [x, y, theta].

Returns:

Transformed geometry.

get_init_Gh()

Generate initial G and h for convex object.

Returns:

(N, 2) h vector: (N, 1) cone_type (str): “norm2” for circle or “Rpositive” for polygon convex_flag (bool): for convex or not

Return type:

G matrix

get_Gh(**kwargs)

get_polygon_Gh(vertices: ndarray | None = None)

Generate G and h for convex polygon.

Parameters:

vertices – (2, N), N: Edge number of the object

Returns:

(N, 2) h vector: (N, 1) cone_type (str): “norm2” for circle or “Rpositive” for polygon convex_flag (bool): for convex or not

Return type:

G matrix

get_circle_Gh(center: ndarray, radius: float)

Generate G and h for circle.

Parameters:

• center – (2, 1) array of center

• radius – float of radius

Returns:

(3, 2) h vector: (3, 1) cone_type (str): “norm2” convex_flag (bool): True

Return type:

G matrix

cal_length_width(geometry)

property vertices

property init_vertices

[[x1, y1], [x2, y2]…. [[x1, y1]]]; [x1, y1] will repeat twice

Type:

return original_vertices

property original_vertices: ndarray

Get the original vertices of the geometry.

property original_centroid: ndarray

Get the original centroid of the geometry.

Returns:

The original centroid of the geometry.

Return type:

np.ndarray

property radius

class irsim.lib.handler.geometry_handler.CircleGeometry(name: str = 'circle', **kwargs)

Bases: geometry_handler

construct_original_geometry(radius: float = 0.2, center: list = [0, 0], random_shape: bool = False, radius_range: list = [0.1, 1.0], wheelbase: float | None = None)

Construct the original geometry of the object when the state is in the origin of coordinates.

Parameters:

**kwargs – shape parameters

Returns: Geometry of the object

class irsim.lib.handler.geometry_handler.PolygonGeometry(name: str = 'polygon', **kwargs)

Bases: geometry_handler

construct_original_geometry(vertices=None, random_shape: bool = False, is_convex: bool = False, **kwargs)

Construct a polygon geometry.

Parameters:

• vertices – [[x1, y1], [x2, y2]..]

• random_shape – whether to generate random shape, default is False

• is_convex – whether to generate convex shape, default is False

• **kwargs – see random_generate_polygon()

Returns:

Polygon object

class irsim.lib.handler.geometry_handler.RectangleGeometry(name: str = 'rectangle', **kwargs)

Bases: geometry_handler

construct_original_geometry(length: float = 1.0, width: float = 1.0, wheelbase: float | None = None)

Args

length: in x axis width: in y axis wheelbase: for ackermann robot

class irsim.lib.handler.geometry_handler.LinestringGeometry(name: str = 'linestring', **kwargs)

Bases: geometry_handler

construct_original_geometry(vertices, random_shape: bool = False, is_convex: bool = True, **kwargs)

Construct a LineString object.

Parameters:

• vertices – [[x1, y1], [x2, y2]..]

• random_shape – whether to generate random shape, default is False

• is_convex – whether to generate convex shape, default is False

• **kwargs – see random_generate_polygon()

Returns:

LineString object

class irsim.lib.handler.geometry_handler.PointsGeometry(name: str = 'map', **kwargs)

Bases: geometry_handler

construct_original_geometry(points: ndarray, reso: float = 0.1)

Parameters:

• points – (2, N) array of points

• reso – resolution for the buffer

class irsim.lib.handler.geometry_handler.geometry_handler3d(name: str, **kwargs)

Bases: ABC

This class is used to handle the 3D geometry of the object. It reads the shape parameters from yaml file and constructs the geometry of the object.

abstractmethod construct_original_geometry(**kwargs)

step(state)

Transform geometry to the new state.

Parameters:

state (np.ndarray 6*1) – [x, y, z, roll, pitch, roll].

Returns:

Transformed geometry.

class irsim.lib.handler.geometry_handler.GeometryFactory

Bases: object

Factory class to create geometry handlers.

static create_geometry(name: str = 'circle', **kwargs) → geometry_handler

class irsim.lib.handler.kinematics_handler.KinematicsHandler(name, noise: bool = False, alpha: list = None)

Bases: ABC

Abstract base class for handling robot kinematics.

abstractmethod step(state: ndarray, velocity: ndarray, step_time: float) → ndarray

Calculate the next state using the kinematics model.

Parameters:

• state (np.ndarray) – Current state.

• velocity (np.ndarray) – Velocity vector.

• step_time (float) – Time step for simulation.

Returns:

Next state.

Return type:

np.ndarray

class irsim.lib.handler.kinematics_handler.OmniKinematics(name, noise, alpha)

Bases: KinematicsHandler

step(state: ndarray, velocity: ndarray, step_time: float) → ndarray

Calculate the next state using the kinematics model.

Parameters:

• state (np.ndarray) – Current state.

• velocity (np.ndarray) – Velocity vector.

• step_time (float) – Time step for simulation.

Returns:

Next state.

Return type:

np.ndarray

class irsim.lib.handler.kinematics_handler.DifferentialKinematics(name, noise, alpha)

Bases: KinematicsHandler

step(state: ndarray, velocity: ndarray, step_time: float) → ndarray

Calculate the next state using the kinematics model.

Parameters:

• state (np.ndarray) – Current state.

• velocity (np.ndarray) – Velocity vector.

• step_time (float) – Time step for simulation.

Returns:

Next state.

Return type:

np.ndarray

class irsim.lib.handler.kinematics_handler.AckermannKinematics(name, noise: bool = False, alpha: list = None, mode: str = 'steer', wheelbase: float = 1.0)

Bases: KinematicsHandler

step(state: ndarray, velocity: ndarray, step_time: float) → ndarray

Calculate the next state using the kinematics model.

Parameters:

• state (np.ndarray) – Current state.

• velocity (np.ndarray) – Velocity vector.

• step_time (float) – Time step for simulation.

Returns:

Next state.

Return type:

np.ndarray

class irsim.lib.handler.kinematics_handler.KinematicsFactory

Bases: object

Factory class to create kinematics handlers.

static create_kinematics(name: str = None, noise: bool = False, alpha: list = None, mode: str = 'steer', wheelbase: float = None, role: str = 'robot') → KinematicsHandler

irsim.lib.algorithm

This file is the implementation of the generation of random polygons.

Author: Ruihua Han

irsim.lib.algorithm.generation.random_generate_polygon(number=1, center_range=[0, 0, 0, 0], avg_radius_range=[0.1, 1], irregularity_range=[0, 1], spikeyness_range=[0, 1], num_vertices_range=[4, 10], **kwargs)

reference: https://stackoverflow.com/questions/8997099/algorithm-to-generate-random-2d-polygon

Generate random polygons with specified properties.

Parameters:

• number (int) – Number of polygons to generate (default 1).

• center_range (List[float]) – Range for the polygon center [min_x, min_y, max_x, max_y].

• avg_radius_range (List[float]) – Range for the average radius of the polygons.

• irregularity_range (List[float]) – Range for the irregularity of the polygons.

• spikeyness_range (List[float]) – Range for the spikeyness of the polygons.

• num_vertices_range (List[int]) – Range for the number of vertices of the polygons.

Returns:

List of vertices for each polygon or a single polygon’s vertices if number=1.

irsim.lib.algorithm.generation.generate_polygon(center, avg_radius, irregularity, spikeyness, num_vertices)

Generate a random polygon around a center point.

Parameters:

• center (Tuple[float, float]) – Center of the polygon.

• avg_radius (float) – Average radius from the center to vertices.

• irregularity (float) – Variance of angle spacing between vertices. Range [0, 1]

• spikeyness (float) – Variance of radius from the center. Range [0, 1]

• num_vertices (int) – Number of vertices for the polygon.

Returns:

Vertices of the polygon in CCW order.

Return type:

numpy.ndarray

irsim.lib.algorithm.generation.random_angle_steps(steps: int, irregularity: float) → List[float]

Generate random angle steps for polygon vertices.

Parameters:

• steps (int) – Number of angles to generate.

• irregularity (float) – Variance of angle spacing.

Returns:

Random angles in radians.

Return type:

List[float]

irsim.lib.algorithm.generation.clip(value, lower, upper)

Clip a value to a specified range.

Parameters:

• value (float) – Value to be clipped.

• lower (float) – Lower bound of the range.

• upper (float) – Upper bound of the range.

Returns:

Clipped value.

Return type:

float

This file is the implementation of the kinematics for different robots.

reference: Lynch, Kevin M., and Frank C. Park. Modern Robotics: Mechanics, Planning, and Control. 1st ed. Cambridge, MA: Cambridge University Press, 2017.

irsim.lib.algorithm.kinematics.differential_kinematics(state, velocity, step_time, noise=False, alpha=[0.03, 0, 0, 0.03])

Calculate the next state for a differential wheel robot.

Parameters:

• state – A 3x1 vector [x, y, theta] representing the current position and orientation.

• velocity – A 2x1 vector [linear, angular] representing the current velocities.

• step_time – The time step for the simulation.

• noise – Boolean indicating whether to add noise to the velocity (default False).

• alpha – List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). alpha[0] and alpha[1] are for linear velocity, alpha[2] and alpha[3] are for angular velocity.

Returns:

A 3x1 vector [x, y, theta] representing the next state.

Return type:

next_state

irsim.lib.algorithm.kinematics.ackermann_kinematics(state, velocity, step_time, noise=False, alpha=[0.03, 0, 0, 0.03], mode='steer', wheelbase=1)

Calculate the next state for an Ackermann steering vehicle.

Parameters:

• state – A 4x1 vector [x, y, theta, steer_angle] representing the current state.

• velocity – A 2x1 vector representing the current velocities, format depends on mode. For “steer” mode, [linear, steer_angle] is expected. For “angular” mode, [linear, angular] is expected.

• step_time – The time step for the simulation.

• noise – Boolean indicating whether to add noise to the velocity (default False).

• alpha – List of noise parameters for the velocity model (default [0.03, 0, 0, 0.03]). alpha[0] and alpha[1] are for linear velocity, alpha[2] and alpha[3] are for angular velocity.

• mode – The kinematic mode, either “steer” or “angular” (default “steer”).

• wheelbase – The distance between the front and rear axles (default 1).

Returns:

A 4x1 vector representing the next state.

Return type:

new_state

irsim.lib.algorithm.kinematics.omni_kinematics(state, velocity, step_time, noise=False, alpha=[0.03, 0, 0, 0.03])

Calculate the next position for an omnidirectional robot.

Parameters:

• state – A 2x1 vector [x, y] representing the current position.

• velocity – A 2x1 vector [vx, vy] representing the current velocities.

• step_time – The time step for the simulation.

• noise – Boolean indicating whether to add noise to the velocity (default False).

• alpha – List of noise parameters for the velocity model (default [0.03, 0.03]). alpha[0] is for x velocity, alpha[1] is for y velocity.

Returns:

A 2x1 vector [x, y] representing the next position.

Return type:

new_position

This file is the implementation of the Reciprocal Velocity Obstacle (RVO) algorithm for multi-robot collision avoidance.

Author: Ruihua Han

reference: MengGuo/RVO_Py_MAS

class irsim.lib.algorithm.rvo.reciprocal_vel_obs(state: list, obs_state_list=[], vxmax=1.5, vymax=1.5, acce=0.5, factor=1.0)

Bases: object

A class to implement the Reciprocal Velocity Obstacle (RVO) algorithm for multi-robot collision avoidance.

Parameters:

• state (list) – The rvo state of the agent [x, y, vx, vy, radius, vx_des, vy_des].

• obs_state_list (list) – List of states of static obstacles [[x, y, vx, vy, radius]].

• vxmax (float) – Maximum velocity in the x direction.

• vymax (float) – Maximum velocity in the y direction.

• acce (float) – Acceleration limit.

update(state, obs_state_list)

cal_vel(mode='rvo')

Calculate the velocity of the agent based on the Reciprocal Velocity Obstacle (RVO) algorithm.

Parameters:

mode (str) – The vo configure to calculate the velocity. It can be “rvo”, “hrvo”, or “vo”. - rvo: Reciprocal Velocity Obstacle (RVO) algorithm, for multi-robot collision avoidance. - hrvo: Hybrid Reciprocal Velocity Obstacle (HRVO) algorithm, for multi-robot collision avoidance. - vo: Velocity Obstacle (VO) algorithm, for obstacle-robot collision avoidance.

config_rvo()

config_rvo_mode(obstacle)

config_hrvo()

config_hrvo_mode(obstacle)

config_vo()

config_vo_mode(obstacle)

vel_candidate(rvo_list)

vo_out(vx, vy, rvo_list)

vel_select(vo_outside, vo_inside)

penalty(vel, vel_des, factor)

static between_vector(line_left_vector, line_right_vector, line_vector)

static cross_product(vector1, vector2)