irsim.world#

Submodules#

Classes#

`ObstacleMap`	Static obstacle object backed by map line segments and optional grid data.
`ObjectBase`	Base class representing a generic object in the robot simulator.
`ObjectFactory`	Factory class for creating various objects in the simulation.
`ObstacleAcker`	Ackermann-steered obstacle.
`ObstacleDiff`	Differential-drive obstacle.
`ObstacleOmni`	Omnidirectional obstacle.
`ObjectStatic`	Static object implementation used for static robots and obstacles.
`RobotAcker`	Ackermann-steered robot.
`RobotDiff`	Differential-drive robot.
`RobotOmni`	Omnidirectional robot.
`SensorFactory`	Factory for sensors declared in YAML object configurations.
`World`	Represents the main simulation environment, managing objects and maps.

Package Contents#

Bases: irsim.world.object_base.ObjectBase

Static obstacle object backed by map line segments and optional grid data.

Create an obstacle map object from a set of line segments.

参数:

shape (dict | None) -- Map shape configuration with keys like {"name": "map", "reso": float, "points": array}.
color (str) -- Display color. Default: the palette obstacle color.
static (bool) -- Whether the object is static. Default True.
grid_map (np.ndarray | None) -- Grid map array for fast collision detection.
grid_reso (np.ndarray | None) -- Resolution [x_reso, y_reso] of the grid.
world_offset (list | None) -- World offset [x, y].
**kwargs -- Forwarded to ObjectBase constructor.

linestrings#

geometry_tree#

grid_map = None#

grid_reso#

world_offset#

check_grid_collision(geometry) → bool[源代码]#

Check collision using grid array lookup.

参数:: geometry -- Shapely geometry object to check collision for.
返回:: True if collision detected, False otherwise.
返回类型:: bool

is_collision(geometry) → bool[源代码]#: Check collision against grid (if present) and map geometry.

Base class representing a generic object in the robot simulator.

This class encapsulates common attributes and behaviors for all objects, including robots and obstacles, managing their state, velocity, goals, and kinematics.

参数:

shape (dict) -- Parameters defining the shape of the object for geometry creation. The dictionary should contain keys and values required by the GeometryFactory to create the object's geometry, including name (for example, circle or rectangle) and associated parameters. If omitted, a circle with radius 1 is created; an explicit {"name": "circle"} uses radius 0.2.
kinematics (dict) -- Parameters defining the kinematics of the object. Includes kinematic model and any necessary parameters. If None, the object is a passive body that never drives itself and only moves when a contact pushes it. tau sets the drive lag used in collision_mode: contact: the velocity follows the command as a first-order response with that time constant (the world's drive_tau unless set, 0 by default, which tracks commands instantly; 0.2 s models a small base with a soft velocity loop). Defaults to None.
state (list of float) -- Initial state vector [x, y, theta, ...]. The state can have more dimensions depending on state_dim. Excess dimensions are truncated, and missing dimensions are filled with zeros. Defaults to [0, 0, 0].
velocity (list of float) -- Initial velocity vector [vx, vy] or according to the kinematics model. Defaults to [0, 0].
goal (list of float or list of list of float) -- Goal state vector [x, y, theta, ...] or [[x, y, theta], [x, y, theta], ...] for multiple goals Used by behaviors to determine the desired movement. Defaults to None.
role (str) -- Role of the object in the simulation, e.g., "robot" or "obstacle". Defaults to "obstacle".
color (str) -- Color of the object when plotted. Defaults to the palette's obstacle color (black), or to its pushable color (orange) for a pushable object without kinematics, so bodies that only move when pushed stand out; see irsim.config.palette_param.
static (bool) -- Whether the object never moves. Defaults to False for an object with kinematics; an object without kinematics is static unless it has a finite mass. True freezes any object, which contacts then never move either.
mass (float) -- Mass in kilograms, used by the contact collision mode. With friction it sets the ground friction force that decides what a robot can push, and two passive bodies that collide share the overlap by inverse mass. inf makes the object immovable. Defaults to 1.0 for an object with kinematics and inf for one without. A finite mass on an object without kinematics turns it into a pushable body that does not move on its own. A robot can push a body only while its own friction * mass is at least the body's, as a wheeled robot's traction must beat the load's ground friction; otherwise it stalls against it. Static objects are immovable regardless of their mass.
friction (float) -- Coulomb friction coefficient with the ground; the world's friction (0.5, the physics engines' default material) unless set. For a robot it is the wheels' grip: it caps the push force at friction * mass * gravity and the change of speed at friction * gravity per second. It slows a released body by friction * gravity (the world's gravity) until it stops (0 lets it slide freely), decides whether a robot can push a body (see mass), and whether a body pressed against a wall slides along it or sticks (the push must leave the friction cone of the two surfaces' mean coefficient).
inertia (float) -- Moment of inertia about the object's center of mass (the centroid of its shape, which a free body turns about), in kg m^2, computed from the shape and mass unless set. A contact that misses a body's center turns it through this value. A robot that pushes successfully keeps its heading; one that is stopped by a wall or a load it cannot move is deflected by an off-center contact, as its slipping wheels would let it be. inf mass gives inf.
restitution (float) -- Bounciness of the object's material from 0 (a perfectly inelastic contact) to 1 (elastic); the world's restitution (0, the physics engines' default) unless set. Two bodies that collide separate at the mean of their values times their approach speed; only passive bodies bounce, a robot's drive re-asserts its velocity.
vel_min (list of float) -- Minimum velocity limits for each control dimension. Used to constrain the object's velocity. Defaults to [-1, -1].
vel_max (list of float) -- Maximum velocity limits for each control dimension. Used to constrain the object's velocity. Defaults to [1, 1].
acce (list of float) -- Acceleration limits, specifying the maximum change in velocity per time step. Defaults to [inf, inf].
angle_range (list of float) -- Allowed range of orientation angles [min, max] in radians. The object's orientation will be wrapped within this range. Defaults to [-pi, pi].
behavior (dict or str) -- Behavioral mode or configuration of the object. Can be a behavior name (str) or a dictionary with behavior parameters. If None and no group behavior is configured, the object remains static unless an external velocity is supplied.
group_behavior (dict) -- Shared behavior defaults for objects in the same group. When an object's own behavior configuration is empty or missing, the group behavior will be used as a fallback and exposed via beh_config.
goal_threshold (float) -- Threshold distance to determine if the object has reached its goal. When the object is within this distance to the goal, it's considered to have arrived. Defaults to 0.1.
sensors (list of dict) -- List of sensor configurations attached to the object. Each sensor configuration is a dictionary specifying sensor type (lidar2d, fmcw_lidar2d or contact2d) and parameters. Defaults to None.
arrive_mode (str) -- Mode for arrival detection, either "position" or "state". Determines how arrival at the goal is evaluated. Defaults to "position".
description (str) -- Description or label for the object. Can be used for identification or attaching images in plotting. Defaults to None.
group (int) -- Group identifier for organizational purposes, allowing objects to be grouped. Defaults to 0.
state_dim (int) -- Dimension of the state vector. If None, it is inferred from the class attribute state_shape. Defaults to None.
vel_dim (int) -- Dimension of the velocity vector. If None, it is inferred from the class attribute vel_shape. Defaults to None.
unobstructed (bool) -- Indicates if the object should be considered to have an unobstructed path, ignoring obstacles in certain scenarios. Defaults to False.
fov (float) -- Field of view angles in radians for the object's sensors. Defaults to None. If set lidar, the default value is angle range of lidar.
fov_radius (float) -- Field of view radius for the object's sensors. Defaults to None. If set lidar, the default value is range_max of lidar.
**kwargs --
Additional keyword arguments for extended functionality.
- plot (dict): Plotting options for the object. May include 'show_goal', 'show_text', 'show_arrow', 'show_uncertainty', 'show_trajectory', 'trail_freq', etc.

抛出:

ValueError -- If dimension parameters do not match the provided shapes or if input parameters are invalid.

变量:

state_dim (int) -- Dimension of the state vector.
state_shape (tuple) -- Shape of the state array.
vel_dim (int) -- Dimension of the velocity vector.
vel_shape (tuple) -- Shape of the velocity array.
state (np.ndarray) -- Current state of the object.
_init_state (np.ndarray) -- Initial state of the object.
_velocity (np.ndarray) -- Current velocity of the object.
_init_velocity (np.ndarray) -- Initial velocity of the object.
_goal (np.ndarray) -- Goal state of the object.
_init_goal (np.ndarray) -- Initial goal state of the object.
_geometry (any) -- Geometry representation of the object.
group (int) -- Group identifier for the object.
stop_flag (bool) -- Flag indicating if the object should stop.
arrive_flag (bool) -- Flag indicating if the object has arrived at the goal.
collision_flag (bool) -- Flag indicating a collision has occurred.
unobstructed (bool) -- Indicates if the object has an unobstructed path.
static (bool) -- Indicates if the object is static.
vel_min (np.ndarray) -- Minimum velocity limits.
vel_max (np.ndarray) -- Maximum velocity limits.
color (str) -- Color of the object.
role (str) -- Role of the object (e.g., "robot", "obstacle").
info (ObjectInfo) -- Information container for the object.
wheelbase (float) -- Distance between the front and rear wheels. Specified for ackermann robots.
fov (float) -- Field of view angles in radians.
fov_radius (float) -- Field of view radius.

Initialize an ObjectBase instance.

This method sets up a new ObjectBase object with the specified parameters, initializing its geometry, kinematics, behaviors, sensors, and other properties relevant to simulation.

The initialization process includes: - Setting up geometry handlers and collision detection - Configuring kinematics models for movement - Initializing state vectors and goal management - Setting up behaviors and sensor systems - Configuring visualization and plotting options

备注

All parameters are documented in the class docstring above. Refer to the ObjectBase class documentation for detailed parameter descriptions.

抛出:: ValueError -- If dimension parameters do not match the provided shapes or if input parameters are invalid.

vel_shape = (2, 1)#

state_shape = (3, 1)#

role = 'obstacle'#

group = 0#

description = None#

mass#

friction#

inertia#

restitution#

color#

classmethod reset_id_iter(start: int = 0, step: int = 1)[源代码]#: Restart the object id counter of the currently bound environment.

step(velocity: numpy.ndarray | None = None, sensor_step: bool = True, **kwargs: Any)[源代码]#

Perform a single simulation step, updating the object's state and sensors.

This method advances the object by one time step, integrating the given velocity or behavior-generated velocity to update the object's position, orientation, and other state variables. It also updates sensors and checks for collisions.

参数:

velocity (np.ndarray, optional) --
Desired velocity for this step. If None, the object will use its behavior system to generate velocity. The shape and meaning depend on the kinematics model:
- Differential: [linear_velocity, angular_velocity]
- Omnidirectional: [velocity_x, velocity_y]
- Ackermann: [linear_velocity, steering_angle]
**kwargs -- Additional parameters passed to behavior generation and processing.

返回:

The updated state vector of the object after the step. Returns the current state unchanged if the object is static or stopped.

返回类型:

np.ndarray

备注

Static objects (static=True) will not move and return their current state
Objects with stop_flag=True will halt and return their current state
The method automatically handles sensor updates and trajectory recording

sensor_step()[源代码]#: Update all sensors for the current state.

check_status(colliding=None)[源代码]#

Check the current status of the object, including arrival and collision detection.

This method evaluates collision detection and sets stop flags based on the collision mode. It also handles different collision modes like 'stop', 'reactive', 'unobstructed', 'unobstructed_obstacles', and 'contact'.

check_arrive_status()[源代码]#

Check if the object has arrived at its goal position.

The arrival detection depends on the arrive_mode setting: - "state": Compares full state (x, y, theta) - "position": Compares only position (x, y)

Updates the arrive_flag and handles multiple goals by removing completed ones.

check_arrive(goal, threshold=None)[源代码]#

Check if the object has arrived at a given goal.

参数:

goal (np.ndarray) -- Goal state to check arrival against.
threshold (float, optional) -- Distance threshold for arrival. Defaults to self.goal_threshold if not provided.

返回:

True if the object is within the threshold, False otherwise.

返回类型:

bool

check_collision_status(colliding=None)[源代码]#

Update the collision flag and the list of colliding objects.

参数:: colliding (list, optional) -- Objects already known to intersect this one, e.g. from the environment's batched geometry query. When None the geometry tree is queried for this object alone.

check_collision(obj)[源代码]#

Check collision with another object.

参数:: obj (ObjectBase) -- Another object to check collision with.
返回:: True if collision occurs, False otherwise.
返回类型:: bool

gen_behavior_vel(velocity: numpy.ndarray | None = None) → numpy.ndarray[源代码]#

Generate behavior-influenced velocity for the object.

This method adjusts the desired velocity based on the object's behavior configurations. If no desired velocity is provided (velocity is None), the method may generate a default velocity or issue warnings based on the object's role and behavior settings.

备注

Wander goal renewal (sampling a new random goal upon arrival) is handled in pre_process().

参数:: velocity (Optional[np.ndarray]) -- Desired velocity vector. If None, the method determines the velocity based on behavior configurations. Defaults to None.
返回:: Velocity vector adjusted based on behavior configurations and constraints.
返回类型:: np.ndarray

Logging:: Emits a warning if velocity is None and no behavior configuration is set for a robot.

pre_process()[源代码]#

Perform pre-processing before stepping the object.

This method is called before velocity generation and state updates. Can be overridden by subclasses to implement custom pre-processing logic.

Default behavior:

If wander is enabled and the object has just arrived (arrive_flag), sample a new random goal within [rl, rh] and clear arrive_flag.
If loop is enabled and the object has just arrived (arrive_flag), reset goals to initial waypoints and clear arrive_flag.

post_process()[源代码]#

Perform post-processing after stepping the object.

This method is called after state updates and sensor updates. Can be overridden by subclasses to implement custom post-processing logic.

mid_process(state: numpy.ndarray)[源代码]#

Process state in the middle of a step. Make sure the state is within the desired dimension.

参数:: state (np.ndarray) -- State vector.
返回:: Processed state.
返回类型:: np.ndarray

get_lidar_scan()[源代码]#

Get the lidar scan of the object.

返回:: Lidar scan data containing range and angle information.
返回类型:: dict

get_lidar_points()[源代码]#

Get the lidar scan points of the object.

返回:: Array of lidar scan points.
返回类型:: np.ndarray

get_lidar_offset()[源代码]#

Get the lidar offset relative to the object.

返回:: Lidar offset [x, y, theta] relative to the object center.
返回类型:: list

get_fov_detected_objects()[源代码]#

Detect the env objects that in the field of view.

返回:: The objects that in the field of view of the object.
返回类型:: list

fov_detect_object(detected_object: ObjectBase)[源代码]#

Detect whether the input object is in the field of view.

参数:: object -- The object that to be detected.
返回:: Whether the object is in the field of view.
返回类型:: bool

set_state(state: list | numpy.ndarray | None = None, init: bool = False)[源代码]#

Set the current state of the object.

This method updates the object's position, orientation, and other state variables. It also updates the object's geometry representation to match the new state.

参数:

state (Union[list, np.ndarray]) --
The new state vector for the object. The format depends on the object's state dimension:
- 2D objects: [x, y, theta] where theta is orientation in radians
- 3D objects: [x, y, z, roll, pitch, yaw] or similar based on configuration
Must match the object's state_dim dimension.
init (bool) -- Whether to also set this as the initial state for reset purposes. If True, the object will return to this state when reset() is called. Default is False.

抛出:

AssertionError -- If the state dimension doesn't match the expected state_dim.

示例

>>> # Set robot position and orientation
>>> robot.set_state([5.0, 3.0, 1.57])  # x=5, y=3, facing pi/2 radians
>>>
>>> # Set as initial state for resets
>>> robot.set_state([0, 0, 0], init=True)

set_velocity(velocity: list | numpy.ndarray | None = None, init: bool = False) → None[源代码]#

Set the velocity of the object.

参数:

velocity -- The velocity of the object. Depending on the kinematics model.
init (bool) -- Whether to set the initial velocity (default False).

apply_contact_displacement(delta_xy: list | numpy.ndarray, delta_theta: float = 0.0) → None[源代码]#

Move the object by a contact correction and fold it into its velocity.

Called by the contact collision mode after the kinematic step. The position, heading, geometry, and this step's trajectory sample move by delta_xy and delta_theta, and the motion divided by the step time is added to the velocity in the object's own command frame, so sensors, reactive behaviors, and messages all see the resolved motion. The rotation is about the center of mass, so an object whose origin lies elsewhere has that origin swing around the centroid.

参数:

delta_xy (list | np.ndarray) -- World-frame translation [dx, dy] in meters.
delta_theta (float) -- Rotation about the object's center of mass in radians.

apply_contact_velocity(delta_xy: list | numpy.ndarray) → None[源代码]#

Add a world-frame velocity change from a contact, such as a bounce.

The companion of apply_contact_displacement() for a change that moves nothing this step: the contact collision mode uses it for restitution. The change is expressed in the object's own command frame by its kinematics before it is added.

参数:: delta_xy (list | np.ndarray) -- World-frame velocity change [dvx, dvy] in meters per second.

set_original_geometry(geometry: shapely.geometry.base.BaseGeometry)[源代码]#

Set the original geometry of the object.

参数:: geometry (BaseGeometry) -- Shapely geometry to use as the new original geometry. Subsequent geometry updates will be transformed from this base.

set_random_goal(obstacle_list, init: bool = False, free: bool = True, goal_check_radius: float = 0.2, range_limits: list | None = None, max_attempts: int = 100)[源代码]#

Set random goal(s) in the environment. If free set to True, the goal will be placed only in the free from obstacles part of the environment.

参数:

obstacle_list -- List of objects in the environment
init (bool) -- Whether to set the initial goal (default False).
free (bool) -- Whether to check that goal is placed in a position free of obstacles.
goal_check_radius (float) -- Radius in which to check if the goal is free of obstacles.
range_limits (list) -- List of lower and upper bound range limits in which to set the random goal position.
max_attempts (int) -- Max number of attempts to place the goal in a position free of obstacles.

set_goal(goal: list | numpy.ndarray | None = None, init: bool = False)[源代码]#

Set the goal(s) for the object to navigate towards.

This method configures the target location(s) that the object's behavior system will attempt to reach. Multiple goals can be provided for sequential navigation.

参数:

goal (Union[list, np.ndarray]) --
The goal specification. Can be:
- Single goal: [x, y, theta] for one target location
- Multiple goals: [[x1, y1, theta1], [x2, y2, theta2], ...] for sequential targets
- None: Clear all goals
The theta component specifies the desired final orientation in radians.
init (bool) -- Whether to also set this as the initial goal for reset purposes. If True, these goals will be restored when reset() is called. Default is False.

示例

>>> # Set single goal
>>> robot.set_goal([10.0, 5.0, 0.0])  # Move to (10,5) facing East
>>>
>>> # Set multiple sequential goals
>>> waypoints = [[5, 0, 0], [10, 5, 1.57], [0, 10, 3.14]]
>>> robot.set_goal(waypoints)
>>>
>>> # Clear goals
>>> robot.set_goal(None)

append_goal(goal: list | numpy.ndarray)[源代码]#: Append a goal to the goal list.

set_laser_color(laser_indices, laser_color: str | None = None, alpha: float = 0.3)[源代码]#

Set the color of the lasers.

参数:

laser_indices (list) -- The indices of the lasers to set the color.
laser_color (str) -- The color to set the lasers. Default is palette_param.laser_highlight.
alpha (float) -- The transparency of the lasers. Default is 0.3.

input_state_check(state: list, dim: int = 3)[源代码]#

Check and adjust the state to match the desired dimension.

参数:

state (list) -- State of the object.
dim (int) -- Desired dimension. Defaults to 3.

返回:

Adjusted state.

返回类型:

list

plot(ax: Any, state: numpy.ndarray | None = None, vertices: numpy.ndarray | None = None, **kwargs: Any) → None[源代码]#: Plot this object through its dedicated renderer.

plot_object(ax: Any, state: numpy.ndarray | None = None, vertices: numpy.ndarray | None = None, **kwargs: Any) → None[源代码]#: Draw this object's geometry or description image.

plot_object_image(ax: Any, state: numpy.ndarray | None = None, vertices: numpy.ndarray | None = None, description: str | None = None, **kwargs: Any) → None[源代码]#: Draw this object's configured description image.

plot_trajectory(ax: Any, trajectory: list | None = None, keep_traj_length: int = 0, **kwargs: Any) → None[源代码]#: Draw this object's trajectory.

plot_goal(ax: Any, goal_state: numpy.ndarray | None = None, vertices: numpy.ndarray | None = None, goal_color: str | None = None, goal_zorder: int | None = 1, goal_alpha: float | None = 0.5, **kwargs: Any) → None[源代码]#: Draw this object's goal.

plot_text(ax: Any, state: numpy.ndarray | None = None, **kwargs: Any) → None[源代码]#: Draw this object's text labels.

plot_arrow(ax: Any, state: numpy.ndarray | None = None, velocity: numpy.ndarray | None = None, arrow_theta: float | None = 0.0, arrow_length: float = 0.4, arrow_width: float = 0.6, arrow_color: str | None = None, arrow_zorder: int = 3, **kwargs: Any) → None[源代码]#: Draw this object's velocity arrow.

plot_trail(ax: Any, state: numpy.ndarray | None = None, vertices: numpy.ndarray | None = None, keep_trail_length: int = 0, **kwargs: Any) → None[源代码]#: Draw one historical outline for this object.

plot_fov(ax: Any, **kwargs: Any) → None[源代码]#: Draw this object's field of view.

plot_uncertainty(ax: Any, **kwargs: Any) → None[源代码]#: Draw this object's uncertainty visualization.

plot_clear(all: bool = False) → None[源代码]#: Clear this object's artists.

done()[源代码]#

Check if the object has completed its task.

返回:: True if the task is done, False otherwise.
返回类型:: bool

reset()[源代码]#: Reset the object to its initial state.

refresh(sensor_step: bool = True)[源代码]#

Refresh state-derived attributes (geometry and sensors) without advancing the simulation. Used after reset so geometry/sensor readings reflect the current state without running a kinematic step (which would clobber _velocity and add noise drift).

参数:: sensor_step -- Whether to update attached sensors immediately. Environments pass False while refreshing all object geometries, rebuild the spatial index, then update all sensors from the same state snapshot.

remove()[源代码]#: Remove the object from the environment.

get_vel_range() → tuple[numpy.ndarray, numpy.ndarray][源代码]#

Get the velocity range considering acceleration limits.

返回:: Minimum and maximum velocities.
返回类型:: tuple

get_info() → ObjectInfo[源代码]#

Get object information.

返回:: Information about the object.
返回类型:: ObjectInfo

get_obstacle_info() → ObstacleInfo[源代码]#

Get information about the object as an obstacle.

返回:: Obstacle-related information, including state, vertices, velocity, and radius.
返回类型:: ObstacleInfo

get_init_Gh() → tuple[numpy.ndarray, numpy.ndarray][源代码]#

Get the initial generalized inequality matrices G and h for the convex object.

返回:: Tuple containing initial G matrix and h vector.
返回类型:: tuple[np.ndarray, np.ndarray]

get_Gh() → tuple[numpy.ndarray, numpy.ndarray][源代码]#

Get the generalized inequality matrices G and h for the convex object.

返回:: Tuple containing G matrix and h vector.
返回类型:: tuple[np.ndarray, np.ndarray]

get_desired_omni_vel(goal_threshold=0.1, normalized=False) → numpy.ndarray[源代码]#

Get the desired omnidirectional velocity of the object.

参数:

goal_threshold (float) -- Threshold for goal proximity.
normalized (bool) -- Whether to normalize the velocity.

property name: str#

Get the name of the object.

返回:: The name of the object.
返回类型:: str

property group_name: str#

Get the group name of the object.

返回:: The group name of the object.
返回类型:: str

property abbr: str#

Get the abbreviation of the object.

返回:: The abbreviation of the object.
返回类型:: str

property goal_abbr: str#

Get the goal abbreviation of the object.

返回:: The goal abbreviation of the object.
返回类型:: str

set_text(text: str | None) → None[源代码]#

Set custom display text for this object.

The text will be shown on the next render when show_text is enabled. Pass None to reset back to the default abbreviation.

参数:: text -- The text string to display, or None to reset.

set_goal_text(text: str | None) → None[源代码]#

Set custom display text for this object's goal.

The text will be shown on the next render when show_goal_text is enabled. Pass None to reset back to the default goal abbreviation.

参数:: text -- The text string to display, or None to reset.

property shape: str#

Get the shape name of the object.

返回:: The shape name of the object.
返回类型:: str

property z: float#

Get the z coordinate of the object. For 3D object, the z coordinate is the height of the object, for 2D object, the z coordinate is 0.

返回:: The z coordinate of the object.
返回类型:: float

property kinematics: str | None#

Get the kinematics name of the object.

返回:: The kinematics name of the object.
返回类型:: str

property geometry: shapely.geometry.base.BaseGeometry#

Get the geometry Instance of the object.

返回:: The geometry of the object.
返回类型:: shapely.geometry.base.BaseGeometry

property centroid: numpy.ndarray#

Get the centroid of the object.

返回:: The centroid of the object.
返回类型:: np.ndarray

property id: int#

Get the id of the object.

返回:: The id of the object.
返回类型:: int

property state: numpy.ndarray#

Get the state of the object.

返回:: The state of the object.
返回类型:: np.ndarray

property init_state: numpy.ndarray#

Get the initial state of the object.

返回:: The initial state of the object.
返回类型:: np.ndarray

property velocity: numpy.ndarray#

Get the velocity of the object.

返回:: The velocity of the object.
返回类型:: np.ndarray

property goal: numpy.ndarray | None#

Get the goal of the object.

返回:: The goal of the object.
返回类型:: np.ndarray

property goal_vertices: numpy.ndarray | None#

Get the goal vertices of the object.

返回:: The goal vertices of the object.
返回类型:: np.ndarray

property position: numpy.ndarray#

Get the position of the object.

返回:: The position of the object .
返回类型:: np.ndarray

property radius: float#

Get the radius of the object.

返回:: The radius of the object.
返回类型:: float

property length: float#

Get the length of the object.

返回:: The length of the object.
返回类型:: float

property width: float#

Get the width of the object.

返回:: The width of the object.
返回类型:: float

property wheelbase: float#

Get the wheelbase of the object.

返回:: The wheelbase of the object.
返回类型:: float

property radius_extend: float#

Get the radius of the object with a buffer.

返回:: The radius of the object with a buffer.
返回类型:: float

property arrive: bool#

Get the arrive flag of the object.

返回:: The arrive flag of the object.
返回类型:: bool

property collision: bool#

Get the collision flag of the object.

返回:: The collision flag of the object.
返回类型:: bool

property pushable: bool#

it is not static and has a finite mass. A pushable object without kinematics only moves when pushed.

返回:: True when a contact correction can move the object.
返回类型:: bool
Type:: Whether contacts can move this object

property passive: bool#

it moves only when a contact pushes it and then coasts under ground friction.

返回:: True for a passive body.
返回类型:: bool
Type:: Whether the object has no drive of its own (no kinematics)

property drive_tau: float#

Time constant of the drive's velocity response in contact mode, in seconds: the kinematics' tau if set, else the world's drive_tau.

返回:: The time constant; 0 tracks commands instantly.
返回类型:: float

property drive_velocity_xy: numpy.ndarray#

World-frame velocity the drive is trying to move the body at, which differs from velocity_xy while a contact holds the body back.

返回:: (2, 1) velocity [vx, vy].
返回类型:: np.ndarray

property friction_force: float#

Ground friction force on the object, friction * mass * gravity in newtons, with the world's gravity.

For a passive body it is what a push must overcome to slide it; for a driven object it is its traction, the most it can push with. A robot pushes a body only while its own value is at least the body's.

返回:: The force, inf for an infinitely massive object.
返回类型:: float

property inv_inertia: float#

Inverse moment of inertia used to turn the object in a contact.

Any pushable object turns; an immovable one never moves. The solver lets a driven object turn only when a contact makes it yield, i.e. when it is stopped by a wall or by a load it cannot push, since its drive holds the heading while it pushes.

返回:: 1 / inertia, or 0 when contacts never turn it.
返回类型:: float

property gyration: float#

Radius of gyration sqrt(inertia / mass), the lever at which a spinning body's rim slides on the ground.

返回:: The radius in meters; 0 for an immovable object.
返回类型:: float

property inv_mass: float#

Inverse mass used to share contact corrections.

返回:: 1 / mass for a pushable object, otherwise 0 (static or infinitely massive, which contacts never move).
返回类型:: float

property vertices: numpy.ndarray | None#

Get the vertices of the object.

返回:: The single-boundary vertices, or None for compound geometry.
返回类型:: np.ndarray | None

property original_vertices: numpy.ndarray | None#

Get the original vertices of the object.

返回:: Original single-boundary vertices, or None for compound geometry.
返回类型:: np.ndarray | None

property part_vertices: list[numpy.ndarray] | None#

Return current vertices for each compound part.

返回:: One (2, N) array per compound part, or None for non-compound shapes.
返回类型:: list[np.ndarray] | None

property original_part_vertices: list[numpy.ndarray] | None#: Return body-frame vertices for each compound part.

property original_geometry: shapely.geometry.base.BaseGeometry#

Get the original geometry of the object.

返回:: The original geometry of the object.
返回类型:: shapely.geometry.base.BaseGeometry

property original_centroid: numpy.ndarray#

Get the center of the object.

返回:: The center of the object.
返回类型:: np.ndarray

property original_state: numpy.ndarray#

Get the original state of the object from the original centroid.

返回:: The original state of the object.
返回类型:: np.ndarray (3,1)

property external_objects#

Get the environment objects that are not the self object.

返回:: The environment objects that are not the self object.
返回类型:: list

property ego_object#

Get the ego object (this object itself).

返回:: The ego object (this object).
返回类型:: ObjectBase

property possible_collision_objects#

Get the possible collision objects of the object from the geometry tree.

返回:: The possible collision objects that could collide with this object.
返回类型:: list

property desired_omni_vel#

Calculate the desired omnidirectional velocity.

参数:: goal_threshold (float) -- Threshold for goal proximity.
返回:: Desired velocity [vx, vy].
返回类型:: np.ndarray

property rvo_neighbors#: Get the list of RVO neighbors. :returns: List of RVO neighbor states [x, y, vx, vy, radius]. :rtype: list

property rvo_neighbor_state#

Get the RVO state for this object.

返回:: State [x, y, vx, vy, radius], with (x, y) at the geometry centroid so the disc covers the collision geometry.
返回类型:: list

property rvo_line_segments: list[list[float]]#

Get line segments for RVO line obstacle avoidance.

返回:

List of line segments [[x1, y1, x2, y2], ...] for linestring objects,: empty list for other shapes.

返回类型:

list

property rvo_state#

Get the full RVO state including desired velocity.

返回:: State [x, y, vx, vy, radius, vx_des, vy_des, theta].
返回类型:: list

property velocity_xy#

Get the velocity in x and y directions.

返回:: Velocity [vx, vy].
返回类型:: (2*1) np.ndarray

vel_world2body(velocity_xy: numpy.ndarray) → numpy.ndarray[源代码]#

Convert a world-frame velocity into this object's own command frame.

Velocity commands are given in the object's own frame, while holonomic planners such as RVO, SFM and ORCA produce a world-frame velocity. This converts one into the other using the object's current state, so the caller does not have to.

omni rotates the velocity into its own frame; diff turns it into [linear, angular] through vel_world2diff(), using this object's angular limit and step time.

参数:: velocity_xy -- World-frame velocity [vx, vy] (2x1).
返回:: Velocity in the object's command frame, shaped for its kinematics.
返回类型:: np.ndarray
抛出:: NotImplementedError -- For a model whose command a world-frame velocity does not determine.

示例

>>> action = env.robot.vel_world2body(world_vel)
>>> env.step(action)

property max_speed#

Get the maximum speed of the object.

返回:: The maximum speed of the object.
返回类型:: float

property beh_config: dict[str, Any]#

Get the behavior configuration for this object with group fallback.

返回:

The per-object behavior configuration if defined and non-empty;: otherwise, the group's shared behavior configuration.

返回类型:

dict

property world_param#

Get the world parameters.

返回:

World parameters including time, control_mode,: collision_mode, step_time, and count.

返回类型:

WorldParam

property env_param#

Get the environment parameters.

返回:: Environment parameters including logger and objects.
返回类型:: EnvParam

property logger#

Get the logger of the env_param.

返回:: The logger associated in the env_param.
返回类型:: Logger

property heading#

Get the heading of the object.

返回:: The heading of the object.
返回类型:: float

property orientation#

Get the orientation of the object.

返回:: The orientation angle of the object in radians.
返回类型:: float

class irsim.world.ObjectFactory(world: Any = None)[源代码]#

Factory class for creating various objects in the simulation.

world = None#

create_from_parse(parse: list[dict[str, Any]] | dict[str, Any], obj_type: str = 'robot', group_start_index: int = 0) → list[Any][源代码]#

Create objects from a parsed configuration.

参数:

parse (list or dict) -- Parsed configuration data.
obj_type (str) -- Type of object to create, 'robot' or 'obstacle'.
group_start_index (int) -- Starting index for the group.

返回:

List of created objects.

返回类型:

list

create_from_map(points: numpy.ndarray, reso: numpy.ndarray | None = None, grid_map: numpy.ndarray | None = None, world_offset: list[float] | None = None) → list[Any][源代码]#

Create map objects from points.

参数:

points (np.ndarray) -- (2, N) array of obstacle cell positions.
reso (np.ndarray) -- (2, 1) array of [x_reso, y_reso] cell sizes.
grid_map (np.ndarray, optional) -- Grid map array for fast collision detection. If None, no precomputed grid is used.
world_offset (list[float], optional) -- World offset [x, y]. If None, no additional world offset is applied.

返回:

List of ObstacleMap objects.

返回类型:

list

create_object(obj_type: str = 'robot', number: int = 1, distribution: dict[str, Any] | None = None, state: list[float] | None = None, goal: list[float] | None = None, **kwargs: Any) → list[Any][源代码]#

Create multiple objects based on the parameters.

参数:

obj_type (str) -- Type of object, 'robot' or 'obstacle'.
number (int) -- Number of objects to create.
distribution (dict) -- Distribution type for generating states.
state (list) -- Initial state for objects.
goal (list) -- Goal state for objects.
**kwargs -- Additional parameters for object creation. color: 'cycle' gives the objects the colors of palette_param.cycle in turn.

返回:

List of created objects.

返回类型:

list

create_robot(kinematics: dict[str, Any] | None = None, **kwargs: Any) → Any[源代码]#

Create a robot based on kinematics.

Uses the kinematics registry to look up handler-class metadata (default color, state_dim, description) and creates an ObjectBase directly. A static kinematics name produces an ObjectStatic. No kinematics produces an ObjectBase without a handler, which decides for itself whether it is static or pushable (a finite mass) by the contact collision mode.

参数:

kinematics (dict) -- Kinematics configuration.
**kwargs -- Additional parameters for robot creation.

返回:

An instance of a robot.

返回类型:

ObjectBase

create_obstacle(kinematics: dict[str, Any] | None = None, **kwargs: Any) → Any[源代码]#

Create an obstacle based on kinematics.

Uses the kinematics registry to look up handler-class metadata (default color, state_dim) and creates an ObjectBase directly. A static kinematics name produces an ObjectStatic. No kinematics produces an ObjectBase without a handler, which decides for itself whether it is static or pushable (a finite mass) by the contact collision mode, and picks its own default color accordingly.

参数:

kinematics (dict) -- Kinematics configuration.
**kwargs -- Additional parameters for obstacle creation.

返回:

An instance of an obstacle.

返回类型:

ObjectBase

generate_state_list(number: int = 1, distribution: dict[str, Any] | None = None, state: list[float] | None = None, goal: list[float] | None = None) → tuple[list[list[float]], list[list[float]]][源代码]#

Generate a list of state vectors for multiple objects based on the specified distribution method.

This function creates initial states for multiple objects in the simulation environment. It supports various distribution methods such as 'manual', 'circle', and 'random' to position the objects according to specific patterns or randomness.

Defaults for the circle and random distributions are derived from the world attached to the factory (self.world). If no world is attached (e.g. in unit tests that instantiate ObjectFactory() directly), defaults fall back to a 10x10 world at offset [0, 0].

参数:

number (int) -- Number of state vectors to generate. Default is 1.
distribution (Dict[str, Any]) --
Configuration dictionary specifying the distribution method and its parameters. Default is {"name": "manual"}.
- 'name' (str): Name of the distribution method. Supported values are:
  - 'manual': States are specified manually.
  - 'circle': States are arranged in a circular pattern.
  - 'random': States are placed at random positions.
- Additional parameters depend on the distribution method:
  - For 'manual': Manually specified states and goal.
  - For 'circle':
    - 'center' (List[float]): Center coordinates [x, y] of the circle. Default is the world center [offset_x + width / 2, offset_y + height / 2].
    - 'radius' (float): Radius of the circle. Default is min(width, height) / 2 - 0.5 so the circle sits inside the world with a small margin.
  - For 'random':
    - 'range_low' (List[float]): Lower bounds [x, y, theta] for random state values. Default is [offset_x + 0.5, offset_y + 0.5, -pi] (the world bounds inset by 0.5).
    - 'range_high' (List[float]): Upper bounds [x, y, theta] for random state values. Default is [offset_x + width - 0.5, offset_y + height - 0.5, pi].
    - 'min_distance' (float): Minimum pairwise xy distance between sampled points. Default is 1.0.
state (List[float]) -- Base state vector [x, y, theta] used as a template when distribution['name'] == 'manual'. Default is [1, 1, 0].
goal (List[float]) -- Goal state vector [x, y, theta] used when distribution['name'] == 'manual'. Default is [1, 9, 0].

返回:

A pair (state_list, goal_list) where each element is a list of 3-element state vectors [x, y, theta] for every generated object.

返回类型:

tuple[list[list[float]], list[list[float]]]

抛出:

ValueError -- If the distribution method specified in 'name' is not supported or if required parameters for a distribution method are missing.

class irsim.world.ObstacleAcker(color='k', state_dim=4, **kwargs)[源代码]#

Bases: irsim.world.object_base.ObjectBase

Ackermann-steered obstacle.

自 Use 版本弃用: ObjectBase with kinematics={'name': 'acker'}, role='obstacle' directly. This subclass will be removed in a future version.

Initialize an ObjectBase instance.

This method sets up a new ObjectBase object with the specified parameters, initializing its geometry, kinematics, behaviors, sensors, and other properties relevant to simulation.

The initialization process includes: - Setting up geometry handlers and collision detection - Configuring kinematics models for movement - Initializing state vectors and goal management - Setting up behaviors and sensor systems - Configuring visualization and plotting options

备注

All parameters are documented in the class docstring above. Refer to the ObjectBase class documentation for detailed parameter descriptions.

抛出:: ValueError -- If dimension parameters do not match the provided shapes or if input parameters are invalid.

class irsim.world.ObstacleDiff(color='k', state_dim=3, **kwargs)[源代码]#

Bases: irsim.world.object_base.ObjectBase

Differential-drive obstacle.

自 Use 版本弃用: ObjectBase with kinematics={name: 'diff'}, role='obstacle' directly. This subclass will be removed in a future version.

Initialize an ObjectBase instance.

This method sets up a new ObjectBase object with the specified parameters, initializing its geometry, kinematics, behaviors, sensors, and other properties relevant to simulation.

The initialization process includes: - Setting up geometry handlers and collision detection - Configuring kinematics models for movement - Initializing state vectors and goal management - Setting up behaviors and sensor systems - Configuring visualization and plotting options

备注

All parameters are documented in the class docstring above. Refer to the ObjectBase class documentation for detailed parameter descriptions.

抛出:: ValueError -- If dimension parameters do not match the provided shapes or if input parameters are invalid.

class irsim.world.ObstacleOmni(color='k', state_dim=3, **kwargs)[源代码]#

Bases: irsim.world.object_base.ObjectBase

Omnidirectional obstacle.

自 Use 版本弃用: ObjectBase with kinematics={'name': 'omni'}, role='obstacle' directly. This subclass will be removed in a future version.

Initialize an ObjectBase instance.

This method sets up a new ObjectBase object with the specified parameters, initializing its geometry, kinematics, behaviors, sensors, and other properties relevant to simulation.

The initialization process includes: - Setting up geometry handlers and collision detection - Configuring kinematics models for movement - Initializing state vectors and goal management - Setting up behaviors and sensor systems - Configuring visualization and plotting options

备注

All parameters are documented in the class docstring above. Refer to the ObjectBase class documentation for detailed parameter descriptions.

抛出:: ValueError -- If dimension parameters do not match the provided shapes or if input parameters are invalid.

class irsim.world.ObjectStatic(color=None, role='obstacle', state_dim=3, **kwargs)[源代码]#

Bases: irsim.world.object_base.ObjectBase

Static object implementation used for static robots and obstacles.

Create a static object (robot or obstacle).

参数:

color (str) -- Display color. Default: the palette obstacle color.
role (str) -- Role of the object ("robot" or "obstacle").
state_dim (int) -- State vector dimension (>=3).
**kwargs -- Forwarded to ObjectBase.

class irsim.world.RobotAcker(color: str = 'y', state_dim: int = 4, description: str = 'car_green.png', **kwargs: Any)[源代码]#

Bases: irsim.world.object_base.ObjectBase

Ackermann-steered robot.

自 Use 版本弃用: ObjectBase with kinematics={'name': 'acker'} directly. This subclass will be removed in a future version.

Initialize an ObjectBase instance.

This method sets up a new ObjectBase object with the specified parameters, initializing its geometry, kinematics, behaviors, sensors, and other properties relevant to simulation.

The initialization process includes: - Setting up geometry handlers and collision detection - Configuring kinematics models for movement - Initializing state vectors and goal management - Setting up behaviors and sensor systems - Configuring visualization and plotting options

备注

All parameters are documented in the class docstring above. Refer to the ObjectBase class documentation for detailed parameter descriptions.

抛出:: ValueError -- If dimension parameters do not match the provided shapes or if input parameters are invalid.

class irsim.world.RobotDiff(color: str = 'g', state_dim: int = 3, **kwargs: Any)[源代码]#

Bases: irsim.world.object_base.ObjectBase

Differential-drive robot.

自 Use 版本弃用: ObjectBase with kinematics={'name': 'diff'} directly. This subclass will be removed in a future version.

Initialize an ObjectBase instance.

This method sets up a new ObjectBase object with the specified parameters, initializing its geometry, kinematics, behaviors, sensors, and other properties relevant to simulation.

The initialization process includes: - Setting up geometry handlers and collision detection - Configuring kinematics models for movement - Initializing state vectors and goal management - Setting up behaviors and sensor systems - Configuring visualization and plotting options

备注

All parameters are documented in the class docstring above. Refer to the ObjectBase class documentation for detailed parameter descriptions.

抛出:: ValueError -- If dimension parameters do not match the provided shapes or if input parameters are invalid.

class irsim.world.RobotOmni(color: str = 'g', state_dim: int = 3, **kwargs: Any)[源代码]#

Bases: irsim.world.object_base.ObjectBase

Omnidirectional robot.

自 Use 版本弃用: ObjectBase with kinematics={'name': 'omni'} directly. This subclass will be removed in a future version.

Initialize an ObjectBase instance.

This method sets up a new ObjectBase object with the specified parameters, initializing its geometry, kinematics, behaviors, sensors, and other properties relevant to simulation.

The initialization process includes: - Setting up geometry handlers and collision detection - Configuring kinematics models for movement - Initializing state vectors and goal management - Setting up behaviors and sensor systems - Configuring visualization and plotting options

备注

All parameters are documented in the class docstring above. Refer to the ObjectBase class documentation for detailed parameter descriptions.

抛出:: ValueError -- If dimension parameters do not match the provided shapes or if input parameters are invalid.

class irsim.world.SensorFactory[源代码]#

Factory for sensors declared in YAML object configurations.

The factory reads the name or type key from a sensor dictionary and creates the matching concrete sensor class. Currently supported names are "lidar2d", "fmcw_lidar2d" and "contact2d".

create_sensor(state: numpy.ndarray, obj_id: int, **kwargs: Any) → Any[源代码]#

Create a sensor instance from configuration kwargs.

参数:

state (np.ndarray) -- Initial sensor state.
obj_id (int) -- Associated object id.
**kwargs -- Sensor configuration; expects 'name' or 'type'.

返回:

A concrete sensor instance (e.g., Lidar2D).

返回类型:

Any

抛出:

NotImplementedError -- If the requested sensor type is not supported.

class irsim.world.World(name: str | None = 'world', height: float = 10, width: float = 10, step_time: float = 0.1, sample_time: float | None = None, offset: list[float] | None = None, step_mode: str = 'internal', control_mode: str = 'auto', collision_mode: str = 'stop', gravity: float = 9.81, friction: float = 0.5, restitution: float = 0.0, drive_tau: float = 0.0, obstacle_map: Any | None = None, mdownsample: int = 1, fog_map: bool = False, fog_map_resolution: float | None = None, plot: dict[str, Any] | None = None, status: str = 'None', world_param_instance: irsim.config.world_param.WorldParam | None = None, **kwargs: Any)[源代码]#

Represents the main simulation environment, managing objects and maps.

变量:

name (str) -- Name of the world.
height (float) -- Height of the world.
width (float) -- Width of the world.
step_time (float) -- Time interval between steps.
sample_time (float) -- Time interval between samples.
offset (list) -- Offset for the world's position.
step_mode (str) -- State advancement mode ('internal' or 'external').
control_mode (str) -- Control mode ('auto' or 'keyboard').
collision_mode (str) -- Collision mode ('stop', 'unobstructed', 'unobstructed_obstacles', or 'contact').
obstacle_map -- None, image path (str), grid ndarray, or generator spec dict.
mdownsample (int) -- Downsampling factor for the obstacle map.
status -- Status of the world and objects.
plot -- Plot configuration for the world.

Initialize the world object.

参数:

name (str) -- Name of the world.
height (float) -- Height of the world.
width (float) -- Width of the world.
step_time (float) -- Time interval between steps.
sample_time (float) -- Time interval between samples.
offset (list) -- Offset for the world's position.
step_mode (str) -- internal lets IR-SIM advance object states; external expects callers to update states before each environment step.
control_mode (str) -- Control mode ('auto' or 'keyboard').
collision_mode (str) -- stop halts colliding objects, unobstructed ignores collisions, unobstructed_obstacles lets only obstacles overlap, and contact resolves overlaps as rigid-body contacts with mass, friction, inertia and restitution.
gravity (float) -- Gravitational acceleration in m/s^2; with a body's friction and mass it gives the ground friction force the contact mode works with.
friction (float) -- Ground friction coefficient objects get unless they set their own (PhysX's material default 0.5).
restitution (float) -- Bounciness objects get unless they set their own (0, Isaac Lab's material default: no bounce).
drive_tau (float) -- Drive lag in seconds of driven objects in contact mode unless their kinematics set tau; 0 (the default) tracks commands instantly.
obstacle_map -- None, image path (str), grid ndarray, or generator spec dict.
mdownsample (int) -- Downsampling factor for the obstacle map.
plot (dict) -- Plot configuration.
status (str) -- Initial simulation status.
world_param_instance -- Optional WorldParam instance. If provided, uses this instance for param storage; otherwise falls back to global.

name#

height = 10#

width = 10#

step_time = 0.1#

sample_time#

sample_steps#

offset = None#

count = 0#

sampling = True#

x_range#

y_range#

plot_parse = None#

status = 'None'#

step_mode = ''#

step(objects: list[Any] | None = None) → None[源代码]#

Advance the simulation by one step.

参数:: objects -- Current scene objects. When fog_map is enabled, their lidars reveal the fog-of-map overlay along their line of sight. Pass None or an empty list to skip the fog update.

gen_grid_map(obstacle_map: Any | None = None, mdownsample: int = 1) → tuple[源代码]#

Generate a grid map for obstacles.

The obstacle_map value is resolved to a float64 ndarray by irsim.world.map.resolve_obstacle_map(). Accepted types: None, path string (image), ndarray, or generator spec dict.

参数:

obstacle_map -- None, path string, ndarray, or generator spec dict.
mdownsample (int) -- Downsampling factor.

返回:

(grid_map, obstacle_index, obstacle_positions).

返回类型:

tuple

get_map(resolution: float = 0.1, obstacle_list: list[Any] | None = None) → irsim.world.map.Map[源代码]#

Get the map of the world with the given resolution.

When resolution is coarser than the obstacle grid, the grid is downsampled (conservative: any obstacle in a block marks the block) so that planning and collision use the same grid. When resolution is finer than the grid, no upsampling is done; planning uses the grid resolution and a warning is emitted.

reset() → None[源代码]#: Reset the world simulation.

property time: float#

Get the current simulation time.

返回:: Current time based on steps and step_time.
返回类型:: float

property logger#

Get the logger of the env_param.

返回:: The logger associated in the env_param.
返回类型:: Logger