YAML Configuration Syntax#

The configuration file is a YAML file to initialize the environment. It contains the configuration parameters to simulate and visualize the world, obstacle, and robot. You can customize the scenario and define the behavior of the objects simply by using the parameters.

Parameter Quick Reference#

Use this navigation to quickly jump to specific parameter sections:

Quick Start Example

The configuration file is divided into three main sections: world, robot, and obstacle. Here’s a simple example:

Basic Configuration

world:
  height: 10  # the height of the world
  width: 10   # the width of the world
  step_time: 0.1  # 10Hz calculate each step
  sample_time: 0.1  # 10 Hz for render and data extraction 
  offset: [0, 0] # the offset of the world on x and y 
  collision_mode: 'stop'  # 'stop', 'unobstructed', 'unobstructed_obstacles'
  plot:
    show_title: true
    figure_pixels: [1000, 800]

robot:
  - kinematics: {name: 'diff'}  # omni, diff, acker
    shape: {name: 'circle', radius: 0.2}  # radius
    # shape: {name: 'rectangle', length: 0.5, width: 0.2}  # radius
    state: [1, 1, 0]  
    goal: [9, 9, 0] 
    # acce: [3, .inf]   # acce of [linear, angular]  or [v_x, v_y] or [linear, steer]
    behavior: {name: 'dash'} # move toward to the goal directly 
  
obstacle:
  - number: 10
    distribution: {name: 'random'}
    shape: 
      - {name: 'circle', radius: 1.0}  # radius
      - {name: 'rectangle', length: 1.5, width: 1.2}  # radius
    state: 
      - [5, 5, 0]  
      - [4, 4, 0]
  
  - shape: {name: 'rectangle', length: 1.5, width: 1.2}  # radius
    state: [6, 5, 1] 

  - shape: {name: 'linestring', vertices: [[5, 5], [4, 0], [1, 6]] }  # vertices
    state: [0, 0, 0] 
    unobstructed: True

Important

Key Configuration Guidelines:

To include several robots or obstacles in the configuration file, add separate entries under the robot and obstacle sections using - for each additional item.
Parameters such as distribution, shape, behavior, group_behavior, and kinematics must be formatted as {key: value} pairs. Ensure that each dictionary includes the name key; omitting name will result in a None value for that parameter.
When dealing with multiple objects (i.e., when the number is greater than 1), utilize the distribution parameter to define how these objects are distributed.
By default, all objects within the same group share identical configurations. To customize individual objects within a group, add sub-parameters using -. Any additional objects not explicitly configured will inherit the settings of the last specified object in the group.
Object-level name is optional and identifies each object. If omitted, it defaults to "<role>_<id>" (e.g., robot_0, obstacle_3). Names must be unique across all objects; duplicates raise an error during environment initialization. Do not confuse object-level name with the name keys used inside dictionaries like shape, kinematics, or behavior (which indicate component types).

World Configuration#

This section outlines the configuration parameters available for the world section.

World Parameters Table#

Parameter	Type	Default	Description
`name`	`str`	`"world"`	Name of the world
`height`	`float`	`10`	Height of the world (meter)
`width`	`float`	`10`	Width of the world (meter)
`step_time`	`float`	`0.1`	Time interval between simulation steps (in seconds)
`sample_time`	`float`	`step_time`	Time interval between samples for rendering and data extraction (in seconds). Defaults to `step_time` if not specified.
`offset`	`list` of `float`	`[0, 0]`	Offset for the world’s position in `[x, y]` coordinates
`control_mode`	`str`	`"auto"`	Control mode of the simulation. Support mode: `auto` or `keyboard`
`collision_mode`	`str`	`"stop"`	Collision handling mode (Support: `"stop"`, `"unobstructed"`, `"unobstructed_obstacles"`)
`status`	`str`	`"None"`	Initial status of the simulation environment (Support: `"Running"`, `"Arrived"`, `"Collision"`, `"Pause"`)
`obstacle_map`	`str` (file path)	`None`	Path to the image file representing the obstacle map
`mdownsample`	`int`	`1`	Downsampling factor for the obstacle map to reduce resolution and decrease computational load.
`plot`	`dict`	`{}`	Plotting options for initializing the plot of the world.

Detailed Parameter Descriptions#

Complete World Configuration Example#

world:
  name: "world"                       # Name of the world
  height: 10                          # Height of the world
  width: 10                           # Width of the world
  step_time: 0.1                      # Time interval between steps (10 Hz)
  sample_time: 0.1                    # Time interval for rendering and data extraction (10 Hz)
  offset: [0, 0]                      # Positional offset of the world on the x and y axes
  control_mode: 'keyboard'            # Control mode ('auto' or 'keyboard')
  collision_mode: 'stop'              # Collision handling mode ('stop', 'unobstructed', 'unobstructed_obstacles')
  obstacle_map: "path/to/map.png"     # Path to the obstacle map image file
  mdownsample: 2                      # Downsampling factor for the obstacle map
  status: "Running"                   # Initial simulation status
  plot:                               # Plotting configuration
    show_title: true                  # Show plot title
    title: "Custom Simulation Title"  # Custom title (optional)
    figure_pixels: [1200, 800]        # Figure size in pixels
    viewpoint: "robot_0"              # Camera center: fixed [x, y], object name, or null
    saved_figure:                     # Figure saving options
      dpi: 150                        # Resolution for saved figures
      format: "png"                   # File format

Warning

obstacle_map: Replace "path/to/map.png" with the actual file path to your obstacle map image. Ensure that the image is in a compatible format (e.g., PNG, JPEG) and properly represents obstacle locations.

Object Configuration#

All robot and obstacle entities in the simulation are configured as objects with similar parameters but may have different default values. This section outlines the configuration parameters available for these objects.

Object Parameters Table#

Parameter	Type	Default	Description
`name`	`str` or `list` of `str`	`None`	Unique identifier for the object. If omitted, auto-assigned as `"<role>_<id>"`. Supports a list when `number > 1`.
`number`	`int`	`1`	Number of objects to create.
`distribution`	`dict`	`{name: manual}`	Defines how multiple objects are distributed. Support name: `manual`, `random`, `circle`
`kinematics`	`dict`	`None`	Kinematic model of the object. Support name: `diff`, `acker`, `omni`
`shape`	`dict`	`{name: circle}`	Shape of the object. Support name: `circle`, `rectangle`, `polygon` , `linestring`
`state`	`list` of `float`	`[0, 0, 0]`	Initial state vector of the object.
`velocity`	`list` of `float`	`[0, 0]`	Initial velocity vector.
`goal`	`list` of `float` or `list` of `list` of `float`	`None`	Goal state(s) vector.
`behavior`	`dict`	`None`	Behavior configuration dictating object movement. Support name: `dash`, `rvo`
`group_behavior`	`dict`	`None`	Group-level behavior for objects in the same group. Support name: `orca`
`role`	`str`	`"obstacle"`	Role of the object in the simulation.
`color`	`str`	`'k'` (black)	Visualization color of the object in the simulation.
`static`	`bool`	`False`	Indicates if the object is static.
`vel_min`	`list` of `float`	`[-1, -1]`	Minimum velocity limits for each control dimension.
`vel_max`	`list` of `float`	`[1, 1]`	Maximum velocity limits for each control dimension.
`acce`	`list` of `float`	`[inf, inf]`	Acceleration limits.
`angle_range`	`list` of `float`	`[-pi, pi]`	Range of orientation angles in radians.
`goal_threshold`	`float`	`0.1`	Threshold distance to determine goal arrival.
`sensors`	`list` of `dict`	`None`	List of sensor configurations attached to the object. Support name: `lidar2d`
`arrive_mode`	`str`	`'position'`	Mode for arrival detection.
`description`	`str`	`None`	Image description or label for the object.
`group`	`int`	`0`	Group identifier for organizational purposes, allowing objects to be grouped.
`group_name`	`str`	`None`	Group name used for organization, allowing objects to be managed by group name.
`unobstructed`	`bool`	`False`	Indicates if the object ignores collisions.
`plot`	`dict`	`{}`	Plotting options for object visualization.
`state_dim`	`int`	`None`	Dimension of the state vector.
`vel_dim`	`int`	`None`	Dimension of the velocity vector.
`fov`	`float`	`None`	Field of view angles in radians for the object’s sensors.
`fov_radius`	`float`	`None`	Field of view radius for the object’s sensors.

Detailed Parameter Descriptions#

object kinematics

Kinematics Models

diff — Differential drive, controlled by linear speed and angular velocity ([v, omega])
omni — Omnidirectional, controlled by linear speed along the x and y axes ([vx, vy])
acker — Ackermann steering, controlled by linear speed and steering angle ([v, phi])

kinematics (dict, default: None)

Sets the kinematic model governing the object’s movement.

Options:

'diff': Differential drive robot, suitable for robots that can rotate in place (e.g., two-wheel robots). This type of robot is controlled by linear and angular velocity. Optional parameters:
- noise (bool): whether to add noise to the velocity commands. Default is False.
- alpha (list): noise parameters for velocity commands. Default is [0.03, 0, 0, 0.03].
```
# Example usage
kinematics: {name: 'diff', noise: True, alpha: [0.03, 0, 0, 0.03]}
```
'omni': Omnidirectional movement, allowing movement in any direction without changing orientation. This type of robot is controlled by velocities along the x and y axes. Optional parameters:
- noise (bool): whether to add noise to the velocity commands. Default is False.
- alpha (list): noise parameters for velocity commands. Default is [0.03, 0, 0, 0.03].
```
# Example usage
kinematics: {name: 'omni', noise: True, alpha: [0.03, 0, 0, 0.03]}
```
'acker': Ackermann steering, typical for car-like vehicles requiring a turning radius.
- noise (bool): whether to add noise to the velocity commands. Default is False.
- alpha (list): noise parameters for velocity commands. Default is [0.03, 0, 0, 0.03].
- mode (str): steering mode, either steer or angular. Default is steer.
  - steer: the object is controlled by linear and steer angle.
  - angular: the object is controlled by linear and angular velocity.
```
# Example usage
kinematics: {name: 'acker', noise: True, alpha: [0.03, 0, 0, 0.03], mode: 'steer'}
```

vel_min (list of float, default: [-1, -1]) and vel_max (list of float, default: [1, 1])

Set the minimum and maximum velocity limits for each control dimension (e.g., linear and angular velocities). These constraints ensure the object’s motion stays within feasible and safe bounds.

acce (list of float, default: [inf, inf])

Defines acceleration limits as the maximum change in velocity per time step for each control dimension. This parameter simulates the physical limitations of the object’s motion capabilities.

angle_range (list of float, default: [-pi, pi])

Specifies the allowed range of orientation angles [min, max] in radians. The object’s orientation angle theta is wrapped within this range to maintain consistency.

goal_threshold (float, default: 0.1)

Determines the proximity threshold to the goal at which the object is considered to have arrived. Once within this distance, arrival behaviors or state changes may be triggered.

# Example usage
vel_min: [-1, -1]
vel_max: [1, 1]
acce: [0.5, 0.1]
angle_range: [-pi, pi]
goal_threshold: 0.1

Warning

When using the acker kinematics model, ensure that the wheelbase parameter is set in the shape configuration.

object shape

Overview

circle — Round shape (radius, center)
rectangle — Rectangular shape (length, width, wheelbase)
polygon — Custom shape (vertices, is_convex)
linestring — Line segments (vertices)

shape (dict, default: {name: circle})

Determines the geometric shape used for collision detection and visualization in the original state.

Supported Shapes:

'circle': Represents a circular shape.
- radius (float): Radius of the circle. Default is 0.2.
- center (list): Center (x, y) of the circle. Default is [0, 0].
- random_shape (bool): Whether to generate a random radius. Default is False.
- radius_range (list): Range [min_radius, max_radius] for random radius generation if random_shape is True. Default is [0.1, 1.0].
- wheelbase (float): Wheelbase of the Ackermann steering vehicle. Required when using 'acker' kinematics. Default is None.
```
# Example usage
shape: {name: 'circle', radius: 0.2, center: [0, 0]}
```
'rectangle': Represents a rectangular shape.
- length (float): Length of the rectangle along the x-axis. Default is 1.0.
- width (float): Width of the rectangle along the y-axis. Default is 1.0.
- wheelbase (float): Wheelbase of the Ackermann steering vehicle. Required when using 'acker' kinematics. Default is None.
```
# Example usage
shape: {name: 'rectangle', length: 1.0, width: 0.5}
```
'polygon': Represents a polygonal shape defined by a list of vertices.
- vertices (list): List of vertices defining the polygon in the format [[x1, y1], [x2, y2], ...], if not provided, a random polygon will be generated.
- random_shape (bool): Whether to generate a series of random polygons. Default is False.
- is_convex (bool): Whether to generate a series of random convex polygons. Default is False.
- parameters for random polygon generation, see random_generate_polygon for more details. Parameters include number , center_range , avg_radius_range , irregularity_range , spikeyness_range , num_vertices_range .
```
# Example usage
shape:
  name: 'polygon'
  vertices: 
    - [4.5, 4.5]
    - [5.5, 4.5]
    - [5.5, 5.5]
    - [4.5, 5.5]
```
```
# Example usage - random polygon
shape:
  - {name: 'polygon', random_shape: true, center_range: [5, 10, 40, 30], avg_radius_range: [0.5, 2], irregularity_range: [0, 1], spikeyness_range: [0, 1], num_vertices_range: [4, 5]} 
```
'linestring': Represents a line string shape defined by a list of vertices. Similar to a polygon but generates a line string.
- vertices (list): List of vertices defining the line string in the format [[x1, y1], [x2, y2], ...].
- random_shape (bool): Whether to generate a series of random line strings (polygon). Default is False.
- is_convex (bool): Whether to generate a series of random convex line strings (polygons). Default is False.
- parameters for random line string generation (polygon), see random_generate_polygon for more details. Parameters include number , center_range , avg_radius_range , irregularity_range , spikeyness_range , num_vertices_range .
```
# Example usage
shape:
  name: 'linestring'
  vertices: 
    - [4.5, 4.5]
    - [5.5, 4.5]
    - [5.5, 5.5]
    - [4.5, 5.5]
```
```
# Example usage - random linestring
shape:
  - {name: 'linestring', random_shape: true, center_range: [5, 10, 40, 30], avg_radius_range: [0.5, 2], irregularity_range: [0, 1], spikeyness_range: [0, 1], num_vertices_range: [4, 5]} 
```

object behavior

Behavior Systems

behavior: dash (move toward the goal directly), rvo (collision avoidance algorithm)
group_behavior: orca (optimal reciprocal collision avoidance)
static — Immobile objects (True/False)

behavior (dict, default: None)

Configures the movement behavior of the object. Behaviors can be simple or complex and may include additional parameters.

Options:

'dash': Moves directly toward the goal at maximum allowable speed.
- wander (bool/False): Whether to add random wandering to the movement. If True, the object will have a random goal when reach current goal.
- target_roles (str/all): Only the objects with the target role will be applied to the behavior. Currently, you can set the target role as robot or obstacle.
- range_low(list/[0, 0, -3.14]): Lower bounds for random wandering.
- range_high(list/[10, 10, 3.14]): Upper bounds for random wandering.
- angle_tolerance (float/0.1): Tolerance for orientation alignment with diff and acker kinematics.
Example:
```
behavior: {name: 'dash', wander: True, range_low: [0, 0, -3.14], range_high: [10, 10, 3.14], angle_tolerance: 0.1}
```
'rvo': Implements Reciprocal Velocity Obstacles for collision avoidance among multiple moving objects. Support kinematics are diff and omni.
- wander (bool/False): Whether to add random wandering to the movement. If True, the object will have a random goal when reach current goal.
- target_roles (str/all): Only the objects with the target role will be applied to the behavior. Currently, you can set the target role as robot or obstacle.
- range_low(list/[0, 0, -3.14]): Lower bounds for random wandering.
- range_high(list/[10, 10, 3.14]): Upper bounds for random wandering.
- vxmax (float/1.5): Maximum linear velocity in x axis.
- vymax (float/1.5): Maximum linear velocity in y axis.
- acce (float/1.0): Maximum acceleration.
- factor (float/1.0): Factor for the RVO algorithm.
- mode (str/rvo): Mode for RVO algorithm, either rvo, hrvo, or vo.
  - rvo: Reciprocal Velocity Obstacles. For multi-agent collision avoidance.
  - hrvo: Hybrid Reciprocal Velocity Obstacles. Combine RVO with VO to avoid deadlocks.
  - vo: Velocity Obstacles. For obstacle avoidance.
- neighbor_threshold (float/3.0): Distance threshold to filter the neighbors to the self robot.
Example:
```
behavior: {name: 'rvo', vxmax: 1.5, vymax: 1.5, acce: 1.0, factor: 1.0, mode: 'rvo', wander: False}
```

group_behavior (dict, default: None)

Group-level behavior for all objects within the same group. This is more efficient for coordinated behaviors (like swarm or crowd simulation) as it computes actions for all members in a single step. Must include name plus behavior-specific parameters.

Options:

'orca': Optimal Reciprocal Collision Avoidance (ORCA) for multi-agent navigation. Requires pyrvo package (pip install pyrvo). The simulation will attempt to import it only when this behavior is used.
- wander (bool/False): Whether to add random wandering to the movement. If True, the object will have a random goal when reach current goal.
- range_low(list/[0, 0, -3.14]): Lower bounds for random wandering.
- range_high(list/[10, 10, 3.14]): Upper bounds for random wandering.
- neighborDist (float/15.0): Max distance to search for neighbors.
- maxNeighbors (int/10): Max number of neighbors to consider.
- timeHorizon (float/20.0): Time horizon for computing safe velocities with respect to other agents.
- timeHorizonObst (float/10.0): Time horizon for computing safe velocities with respect to static obstacles.
- safe_radius (float/0.1): Additional safety radius padding.
- maxSpeed (float/None): Max speed for the agents. If None, uses the object’s vel_max.
Example:
```
group_behavior: 
  name: 'orca'
  neighborDist: 10.0
  maxNeighbors: 10
  timeHorizon: 10.0
  timeHorizonObst: 10.0
  safe_radius: 0.1
```

static: A boolean indicating whether the object is static (does not move). Static objects ignore kinematics and behaviors, remaining at their initial state.

Example:

static: True

object visualization

Overview

color — Object color ('r', 'blue', 'k')
description — Image file ('car_blue.png', 'diff_robot0.png')
plot — Advanced display options
- Object — Appearance (obj_color, obj_alpha, obj_linestyle)
- Goal — Goal markers (show_goal, goal_color, show_goal_text)
- Trail — Object trails (show_trail, keep_trail_length)
- Trajectory — Path lines (show_trajectory, keep_traj_length)
- Sensors — Sensor display (show_sensor, show_fov)

color (str, default: 'k' (black))

Specifies the object’s color in visualizations for easy identification. Detailed color options can be found in matplotlib color.

Example:

color: 'r'

description (str, default: None)

Provides an image for representing the object graphically. Supports image files located in world/description. You can also set the absolute path of the image file by your need.

Available Images:

car_green.png: A default image for the ackermann steering vehicle.
car_blue.png
car_red.png
diff_robot0.png
diff_robot1.png

Example:

description: 'car_blue.png'

plot: Contains plotting options controlling the visual representation of the object. All plot elements are initially created at the origin and positioned using transforms and data updates during animation updates.

Object Visualization Properties:

obj_linestyle (str/'-'): Line style for object outline (e.g., ‘-’, ‘–’, ‘:’, ‘-.’).
obj_zorder (int/3): Z-order (drawing layer) for object elements. Default is 3 for robots, 1 for obstacles.
obj_color (str): Color of the object. Default is the object’s color property.
obj_alpha (float/1.0): Transparency of the object (0.0 to 1.0).
obj_linewidth (float/None): Width of the object outline. Default varies by object type.

Goal Visualization:

show_goal (bool/False): Whether to show the goal position.
- goal_color (str): Color of the goal marker. Default is the object’s color.
- goal_alpha (float/0.5): Transparency of the goal marker (0.0 to 1.0).
- goal_zorder (int/1): Z-order of the goal marker.
show_goal_text (bool/False): Whether to show the goal text.

Text Label Visualization:

show_text (bool/False): Whether to show text information.
- text_color (str): Color of the text. Default is ‘k’ (black).
- text_size (int/10): Font size of the text.
- text_alpha (float/1.0): Transparency of the text (0.0 to 1.0).
- text_zorder (int/2): Z-order of the text.
- text_position (list/[-radius-0.1, radius+0.1]): Position offset from object center [dx, dy].

Velocity Arrow Visualization:

show_arrow (bool/False): Whether to show the velocity arrow.
- arrow_color (str/"gold"): Color of the arrow.
- arrow_length (float/0.4): Length of the arrow.
- arrow_width (float/0.6): Width of the arrow.
- arrow_alpha (float/1.0): Transparency of the arrow (0.0 to 1.0).
- arrow_zorder (int/4): Z-order of the arrow.

Trajectory Path Visualization:

show_trajectory (bool/False): Whether to show the trajectory line.
- traj_color (str): Color of the trajectory. Default is the object’s color.
- traj_style (str): Line style of the trajectory (e.g., ‘-’, ‘–’, ‘:’, ‘-.’). Default is “-“.
- traj_width (float/None): Width of the trajectory line. Default is the object’s width.
- traj_alpha (float/0.5): Transparency of the trajectory (0.0 to 1.0).
- traj_zorder (int/0): Z-order for trajectory elements.
- keep_traj_length (int/0): Number of steps to keep from the end of trajectory. Default is 0 (keep all steps).

Object Trail Visualization:

show_trail (bool/False): Whether to show object trails.
- trail_freq (int/2): Frequency of trail display (every N steps).
- trail_type (str): Type of trail shape. Default is the object’s shape.
- trail_edgecolor (str): Edge color of the trail. Default is the object’s color.
- trail_linewidth (float/0.8): Width of the trail outline.
- trail_alpha (float/0.7): Transparency of the trail (0.0 to 1.0).
- trail_fill (bool/False): Whether to fill the trail shape.
- trail_color (str): Fill color of the trail. Default is the object’s color.
- trail_zorder (int/0): Z-order for trail elements.
- keep_trail_length (int/0): Number of steps to keep from the end of trail. Default is 0 (keep all steps).

Sensor Visualization:

show_sensor (bool/True): Whether to show sensor visualizations.

Field of View Visualization:

show_fov (bool/False): Whether to show field of view visualization.
- fov_color (str/"lightblue"): Fill color of the field of view.
- fov_edge_color (str/"blue"): Edge color of the field of view.
- fov_alpha (float/0.5): Transparency of the field of view (0.0 to 1.0).
- fov_zorder (int/1): Z-order of the field of view.

Note: All visual elements are created at the origin during initialization and positioned using matplotlib transforms (for patches) and set_data methods (for lines) during animation updates.

Example:

plot:
  # Object appearance
  obj_linestyle: '--'
  obj_zorder: 3
  obj_color: 'blue'
  obj_alpha: 0.8
  obj_linewidth: 2.0
  
  # Goal visualization
  show_goal: True
  goal_color: 'red'
  goal_alpha: 0.7
  goal_zorder: 2
  
  # Text labels
  show_text: True
  text_color: 'black'
  text_size: 12
  text_alpha: 0.9
  text_zorder: 5
  
  # Velocity arrows
  show_arrow: True
  arrow_color: 'gold'
  arrow_length: 0.5
  arrow_width: 0.8
  arrow_alpha: 0.9
  arrow_zorder: 4
  
  # Trajectory path
  show_trajectory: True
  traj_color: 'green'
  traj_style: '-'
  traj_width: 0.6
  traj_alpha: 0.6
  traj_zorder: 1
  
  # Object trails
  show_trail: True
  trail_freq: 3
  trail_edgecolor: 'purple'
  trail_linewidth: 1.0
  trail_alpha: 0.5
  trail_fill: False
  trail_color: 'purple'
  trail_zorder: 0
  
  # Sensors and FOV
  show_sensor: True
  show_fov: True
  fov_color: 'lightblue'
  fov_edge_color: 'blue'
  fov_alpha: 0.3
  fov_zorder: 1

GUI Configuration#

GUI Parameters Table#

Parameter	Type	Default	Description
`keyboard`	`dict`	`{}`	Keyboard control options (effective when `world.control_mode: keyboard`).
`mouse`	`dict`	`{}`	Mouse control options.

Configuration Examples#

Let’s explore various configuration examples to demonstrate the flexibility and power of IR-SIM:

Multi-Robot RVO

robot:
  - number: 10
    distribution: {name: 'circle', radius: 4.0, center: [5, 5]}  
    kinematics: {name: 'diff'}
    shape: 
      - {name: 'circle', radius: 0.2}  
    behavior: {name: 'rvo', vxmax: 1.5, vymax: 1.5, acce: 1.0, factor: 1.0}
    vel_min: [-3, -3.0]
    vel_max: [3, 3.0]
    color: ['royalblue', 'red', 'green', 'orange', 'purple', 'yellow', 'cyan', 'magenta', 'lime', 'pink', 'brown'] 
    arrive_mode: position
    goal_threshold: 0.15
    plot:
      show_trail: true
      show_goal: true
      trail_fill: true
      trail_alpha: 0.2
      show_trajectory: false

Multi-Robot ORCA

robot:
  - number: 10
    distribution: {name: 'circle', radius: 4.0, center: [5, 5]}
    kinematics: {name: 'omni'}
    shape: {name: 'circle', radius: 0.2}
    group_behavior: 
      name: 'orca'
      neighborDist: 10.0
      maxNeighbors: 10
      timeHorizon: 10.0
      timeHorizonObst: 10.0
      safe_radius: 0.1
    vel_max: [2.0, 2.0]
    goal: [9, 9, 0]
    plot:
      show_trail: true
      trail_alpha: 0.5

Mixed Obstacles

obstacle:
  - shape: {name: 'circle', radius: 1.0}  # radius
    state: [5, 5, 0]  
  
  - shape: {name: 'rectangle', length: 1.5, width: 1.2}  # radius
    state: [6, 5, 1] 

  - shape: {name: 'linestring', vertices: [[5, 5], [4, 0], [1, 6]] }  # vertices
    state: [0, 0, 0] 
    unobstructed: True

  - shape:
      name: 'polygon'
      vertices: 
        - [4.5, 4.5]
        - [5.5, 4.5]
        - [5.5, 5.5]
        - [4.5, 5.5]

Ackermann Vehicle

robot:  
  - kinematics: {name: 'acker'}  
    shape: {name: 'rectangle', length: 4.6, width: 1.6, wheelbase: 3}
    state: [1, 1, 0, 0]
    goal: [40, 40, 0]
    vel_max: [4, 1]
    behavior: {name: 'dash'}
    plot:
      show_trajectory: True

Sensor Integration

robot:
  - kinematics: {name: 'diff'}
    shape: {name: 'circle', radius: 0.3}
    state: [2, 2, 0]
    goal: [8, 8, 0]
    behavior: {name: 'rvo'}
    sensors:
      - name: 'lidar2d'
        range_min: 0.1
        range_max: 8.0
        angle_range: 6.28  # Full 360 degrees
        number: 360
        noise: True
        std: 0.1
        offset: [0, 0, 0]
        color: 'red'
    plot:
      show_sensor: True
      show_fov: True
      fov_color: 'lightgreen'
      fov_alpha: 0.3

Tip

Configuration Best Practices:

Multiple Objects: When configuring multiple objects, use the number and distribution parameters to efficiently generate them. For instance, setting number: 10 with a distribution of 'random' can quickly populate the simulation with randomly placed objects.
Dictionary Parameters: All dictionary-type parameters (e.g., distribution, shape, kinematics, behavior) must include a 'name' key to specify their type. Omitting the 'name' key will result in default values or errors.
Group Configurations: By default, objects within the same group share configurations. To customize individual objects within a group, add sub-parameters using -. Unspecified objects will inherit the last defined configuration within the group.
Kinematics and Velocities: Ensure that the velocity and vel_max parameters match the kinematics model. For example, a differential drive robot ('diff') should have velocities in [v, omega], while an omnidirectional robot ('omni') uses [vx, vy].
Plotting Options: Customize the visualization of your simulation through the plot parameter for each object if the plot section is located in the object configuration. If it is located in the root of the object configuration, it will be applied to all objects.

YAML Configuration Syntax#

Parameter Quick Reference#

World Configuration#

World Parameters Table#

Detailed Parameter Descriptions#

Complete World Configuration Example#

Object Configuration#

Object Parameters Table#

Detailed Parameter Descriptions#

GUI Configuration#

GUI Parameters Table#

Configuration Examples#

This Page