YAML配置语法#

配置文件是用于初始化环境的 YAML 文件。它包含用于模拟和可视化世界、障碍物和机器人的配置参数。你只需通过这些参数即可自定义场景并定义对象的行为。

World 配置#

本节介绍 world 区块可用的配置参数。

World 参数表#

参数	类型	默认值	说明
`name`	`str`	`"world"`	世界名称
`height`	`float`	`10`	长（米）
`width`	`float`	`10`	世界的宽
`step_time`	`float`	`0.1`	决定仿真每一步之间的时间间隔（秒）。
`sample_time`	`float`	`step_time`	渲染和数据提取的采样时间间隔（秒）。如未指定则默认为 `step_time`。
`offset`	`float` 列表	`[0, 0]`	世界位置在 `[x, y]` 坐标上的偏移量
`control_mode`	`str`	`"auto"`	仿真控制模式，支持 `auto` 或 `keyboard`
`collision_mode`	`str`	`"stop"`	碰撞处理模式（支持：`"stop"`、`"unobstructed"`、`"unobstructed_obstacles"`）
`status`	`str`	`"None"`	仿真环境状态初始化（支持 `"Running"`、`"Arrived"`、`"Collision"`、`"Pause"`）
`obstacle_map`	`str`、`ndarray`、`dict` 或 `null`	`None`	生成器配置 dict（例如 `{ name: image, path: '…' }` 或 `{ name: perlin, resolution: 0.1, … }`）。字符串路径是 image 生成器的简写形式。参见配置栅格地图。
`mdownsample`	`int`	`1`	障碍地图的降采样系数，用于降低分辨率并减少计算量。
`plot`	`dict`	`{}`	初始化世界图形的绘制选项。

参数详解#

完整世界配置示例#

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

警告

obstacle_map：将 "path/to/map.png" 替换为你的障碍物地图图像的实际文件路径。请确保图像为兼容格式（如 PNG、JPEG）并正确表示障碍物位置。

Object 配置#

仿真中的 robot 与 obstacle 都作为对象进行配置，参数结构类似但默认值可能不同。本节介绍这些对象可用的配置项。

Object Parameters Table#

Parameter	类型	默认值	描述
`name`	`str` 或者 `list` of `str`	`None`	对象的唯一标识符；若省略，则会自动分配为`"<role>_<id>"`。当`number > 1`时支持参数列表。
`number`	`int`	`1`	要创建的对象数量。
`distribution`	`dict`	`{name: manual}`	定义多个对象的分布方式。支持的分布方式有：`manual`, `random`, `circle`
`kinematics`	`dict`	`None`	对象的运动学模型。支持的模型有`diff`、`acker`、`omni`、`omni_angular`。
`shape`	`dict`	`{name: circle}`	对象的几何形状。支持的形状有`circle`, `rectangle`, `polygon` , `linestring`
`state`	`float` 列表	`[0, 0, 0]`	对象的初始状态向量。
`velocity`	`float` 列表	`[0] * action_dim`	初始速度向量。长度与运动学动作维度匹配（`diff`/`omni`/`acker` 为 2，`omni_angular` 为 3）。
`goal`	`float`列表或`float`列表的列表	`None`	目标状态向量。
`behavior`	`dict`	`None`	决定对象运动的行为配置，支持 `dash`、`rvo`（可用性取决于 `kinematics`，详见配置行为）。
`group_behavior`	`dict`	`None`	同组对象的群体行为配置，支持 `orca`。
`role`	`str`	`"obstacle"`	对象在仿真中的角色。
`color`	`str`	`'k'`（黑色）	对象在仿真中的显示颜色。
`static`	`bool`	`False`	指示对象是否是静态的。
`vel_min`	`float` 列表	`[-1] * action_dim`	各控制维度的最小速度限制。长度与运动学动作维度匹配。
`vel_max`	`float` 列表	`[1] * action_dim`	各控制维度的最大速度限制。长度与运动学动作维度匹配。
`acce`	`float` 列表	`[inf] * action_dim`	加速度限制。长度与运动学动作维度匹配。
`angle_range`	`float` 列表	`[-pi, pi]`	朝向角的弧度范围。
`goal_threshold`	`float`	`0.1`	判定到达目标的距离阈值。
`sensors`	`dict` 列表	`None`	List of sensor configurations attached to the object. Support name: `lidar2d`, `fmcw_lidar2d`
`arrive_mode`	`str`	`'position'`	到达检测模式。
`description`	`str`	`None`	对象的图像描述或标签。
`group`	`int`	`0`	用于组织的分组 ID，使对象可以按组管理。
`group_name`	`str`	`None`	用于组织的分组名称，使对象能够按组名进行管理。
`unobstructed`	`bool`	`False`	指示对象是否忽略碰撞。
`plot`	`dict`	`{}`	对象可视化的绘图选项。
`state_dim`	`int`	`None`	状态向量维度。
`vel_dim`	`int`	`None`	速度向量维度。
`fov`	`float`	`None`	对象传感器的视场角（弧度）。
`fov_radius`	`float`	`None`	对象传感器的视场半径。

参数详解#

object 运动学

运动学模型

diff — 差速驱动，由线速度和角速度控制（[v, omega]）
omni — 全向移动，由机体坐标系下的前进和横向速度控制（[forward, lateral]）
omni_angular — 带角速度控制的全向移动，由机体坐标系下的速度和偏航角速度控制（[forward, lateral, yaw_rate]）
acker — 阿克曼转向，由线速度和转向角控制（[v, phi]）

kinematics（dict，默认 None）

设置控制对象运动的运动学模型。

选项:

'diff'：差速驱动机器人，适用于原地旋转的机器人（如两轮机器人）。通过线速度和角速度控制。可选参数：
- noise（bool）：是否给速度命令添加噪声。默认为 False。
- alpha（列表）：速度命令的噪声参数。默认值为 [0.03, 0, 0, 0.03]。
```
# Example usage
kinematics: {name: 'diff', noise: True, alpha: [0.03, 0, 0, 0.03]}
```
'omni'：全向运动，允许在任意方向移动而不改变朝向。此类机器人通过机体坐标系速度 [forward, lateral] 控制。朝向角（theta）保持不变。可选参数：
- noise（bool）：是否给速度命令添加噪声。默认为 False。
- alpha（列表）：速度命令的噪声参数 [alpha_forward, alpha_lateral]。默认值为 [0.03, 0.03]。
```
# Example usage
kinematics: {name: 'omni', noise: True, alpha: [0.03, 0.03]}
```
'omni_angular'：带角速度控制的全向运动。在 omni 基础上增加偏航角速度通道以积分朝向角（theta）。此类机器人通过机体坐标系速度 [forward, lateral, yaw_rate] 控制。可选参数：
- noise（bool）：是否给速度命令添加噪声。默认为 False。
- alpha（列表）：速度命令的噪声参数 [alpha_forward, alpha_lateral, alpha_yaw]。默认值为 [0.03, 0.03, 0.03]。
```
# Example usage
kinematics: {name: 'omni_angular', noise: True, alpha: [0.03, 0.03, 0.03]}
```
'acker'：阿克曼转向，典型用于类车辆，需要转向半径。
- noise（bool）：是否给速度命令添加噪声。默认为 False。
- alpha（列表）：速度命令的噪声参数。默认值为 [0.03, 0, 0, 0.03]。
- mode（str）：转向模式，为 steer 或 angular。默认为 steer。
  - steer：对象通过线速度和转向角控制。
  - angular：对象通过线速度和角速度控制。
```
# Example usage
kinematics: {name: 'acker', noise: True, alpha: [0.03, 0, 0, 0.03], mode: 'steer'}
```

vel_min（float 列表，默认值：[-1, -1]）和 vel_max（float 列表，默认值：[1, 1]）: 设置每个控制维度的最小和最大速度限制（例如线速度和角速度）。这些约束确保对象的运动保持在可行且安全的范围内。

acce（float 列表，默认值：[inf, inf]）: 定义加速度限制，即每个控制维度在每个时间步内的最大速度变化。此参数模拟对象运动能力的物理限制。

angle_range（float 列表，默认：[-pi, pi]）: 指定允许的朝向角范围 [min, max]（弧度）。对象的朝向角 theta 会被归整到此范围内以保持一致性。

goal_threshold（float，默认：0.1）

确定对象被认为已到达目标的距离阈值。一旦在此距离范围内，可能会触发到达行为或状态变化。

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

警告

使用 acker 运动学模型时，请确保在 shape 配置中设置 wheelbase 参数。

object 形状

概述

circle — 圆形（radius、center）
rectangle — 矩形（length、width、wheelbase）
polygon — 自定义多边形（vertices、is_convex）
linestring — 线段（vertices）

shape（dict，默认 {name: circle}）

Determines the geometric shape used for collision detection and visualization in the original state. If shape is omitted entirely, the object falls back to a circle of radius: 1 centered at [0, 0]; the radius: 0.2 below is the default only when a circle shape is given without an explicit radius.

支持的形状：

'circle'：圆形。
- radius（float）：圆半径，默认 0.2。
- center（列表）：圆心 (x, y)，默认 [0, 0]。
- random_shape（bool）：是否随机半径，默认 False。
- radius_range（list）：当 random_shape 为 True 时用于随机半径生成的范围 [min_radius, max_radius]。默认值为 [0.1, 1.0]。
- wheelbase（float）：阿克曼转向车辆的轴距，使用 'acker' 时必填，默认 None。
```
# Example usage
shape: {name: 'circle', radius: 0.2, center: [0, 0]}
```
'rectangle'：矩形。
- length（float）：x 轴方向长度，默认 1.0。
- width（float）：y 轴方向宽度，默认 1.0。
- wheelbase（float）：阿克曼转向车辆的轴距，使用 'acker' 时必填，默认 None。
```
# Example usage
shape: {name: 'rectangle', length: 1.0, width: 0.5}
```
'polygon'：由顶点列表定义的多边形。
- vertices（列表）：定义多边形的顶点列表，格式 [[x1, y1], ...]。若未提供则生成随机多边形。
- random_shape（bool）：是否生成一系列随机多边形，默认 False。
- is_convex（bool）：是否生成一系列随机凸多边形，默认 False。
- 随机多边形生成的参数，更多细节参见 random_generate_polygon()。参数包括 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'：由顶点列表定义的折线，类似多边形但生成的是一串线。
- vertices（列表）：定义线串的顶点列表，格式 [[x1, y1], ...]。
- random_shape（bool）：是否生成随机线串（多边形），默认 False。
- is_convex（bool）：是否生成随机凸线串（多边形），默认 True。
- 随机折线（多边形）生成的参数，更多细节参见 random_generate_polygon()。参数包括 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：dash（直接朝目标移动）、rvo（碰撞避让算法）
group_behavior：orca（最优互惠碰撞避免）
static — 静止对象（True/False）

behavior（dict，默认 None）

配置对象的运动行为，可为简单或复杂策略，并可包含额外参数。

选项:

'dash'：以最大允许速度直接朝目标移动。
- wander（bool/False）：是否加入随机游走。若为 True，对象到达当前目标后会随机分配新目标。
- loop（bool/False）：是否循环导航路径点。若为 True，对象到达最后一个路径点后会从第一个路径点重新开始。
- target_roles（str/all）：仅对具有目标角色的对象应用该行为。当前可设为 robot 或 obstacle。
- range_low（列表）：随机游走下界，默认 [0, 0, -3.14]。
- range_high（列表）：随机游走上界，默认 [10, 10, 3.14]。
- angle_tolerance（float）：diff、acker、omni_angular 运动学的朝向校准容差，默认 0.1。
示例：
```
behavior: {name: 'dash', wander: True, range_low: [0, 0, -3.14], range_high: [10, 10, 3.14], angle_tolerance: 0.1}
```
'rvo'：实现多动态体避碰的 RVO 算法，支持 diff 与 omni 运动学。
- wander（bool/False）：是否加入随机游走。若为 True，对象到达当前目标后会随机分配新目标。
- loop（bool/False）：是否循环导航路径点。若为 True，对象到达最后一个路径点后会从第一个路径点重新开始。
- target_roles（str/all）：仅对具有目标角色的对象应用该行为。当前可设为 robot 或 obstacle。
- range_low（列表）：随机游走下界，默认 [0, 0, -3.14]。
- range_high（列表）：随机游走上界，默认 [10, 10, 3.14]。
- vxmax（float）：x 轴最大线速度，默认 1.5。
- vymax（float）：y 轴最大线速度，默认 1.5。
- acce（float）：最大加速度，默认 1.0。
- factor（float）：RVO 算法因子，默认 1.0。
- mode（str）：RVO 算法模式，可选 rvo、hrvo、vo，默认 rvo。
  - rvo：互惠速度障碍法，用于多智能体避碰。
  - hrvo：混合 RVO，将 RVO 与 VO 结合以减少死锁。
  - vo：速度障碍，用于避障。
- neighbor_threshold（float）：筛选邻居的距离阈值，默认 3.0。
示例：
```
behavior: {name: 'rvo', vxmax: 1.5, vymax: 1.5, acce: 1.0, factor: 1.0, mode: 'rvo', wander: False}
```

group_behavior（dict，默认 None）

同组内所有对象的群体行为。对于协同行为（如群体或人群仿真）更高效，因为它在单步中为所有成员计算动作。必须包含 name 及行为特定参数。

选项:

'orca'：用于多智能体导航的最优互惠碰撞避免（ORCA）。需要 pyrvo 包（pip install pyrvo）。仅在使用该行为时仿真才会尝试导入它。
- wander（bool/False）：是否加入随机游走。若为 True，对象到达当前目标后会随机分配新目标。
- range_low（列表）：随机游走下界，默认 [0, 0, -3.14]。
- range_high（列表）：随机游走上界，默认 [10, 10, 3.14]。
- neighborDist（float/15.0）：搜索邻居的最大距离。
- maxNeighbors（int/10）：考虑的邻居数量上限。
- timeHorizon（float/20.0）：相对于其他智能体计算安全速度的时间范围。
- timeHorizonObst（float/10.0）：相对于静态障碍物计算安全速度的时间范围。
- safe_radius（float/0.1）：额外的安全半径填充。
- maxSpeed（float/None）：智能体最大速度。若为 None，使用对象的 vel_max。
示例：
```
group_behavior: 
  name: 'orca'
  neighborDist: 10.0
  maxNeighbors: 10
  timeHorizon: 10.0
  timeHorizonObst: 10.0
  safe_radius: 0.1
```

static：布尔值，表示对象是否静止。静止对象忽略运动学与行为，保持初始状态。

示例：

static: True

object 传感器

概述

lidar2d — 2D 激光雷达（range_min/max、angle_range、noise）
fmcw_lidar2d — 2D FMCW LiDAR (range/radial_velocity, motion_compensate, Doppler visualization)
fov — 视场角（弧度）
fov_radius — 最大探测距离

sensors：为对象挂载传感器以感知环境。每个传感器以字典形式描述其类型与参数，目前支持：

lidar2d：用于距离测量的 2D LiDAR，参数包括：
- range_min（float）：最小探测距离，默认 0.0。
- range_max（float）：最大探测距离，默认 10.0。
- angle_range（float）：传感器覆盖角度，默认 pi。
- number（int）：激光束数量，默认 100。
- scan_time（float）：完成一次扫描的时间，默认 0.1。
- noise（bool）：测量是否加入噪声，默认 False。
- std（float）：当 noise=True 时距离噪声的标准差，默认 0.2。
- angle_std（float）：noise=True 时的角度噪声标准差，默认 0.02。
- offset（列表）：传感器相对对象位置 (x, y, theta) 的偏移，默认 [0, 0, 0]。
- has_velocity（bool）：是否测量点速度，默认 False。
Visualization options go under the sensor's plot: sub-dict (flat top-level keys are still accepted for backward compatibility):
- alpha（float）：绘图透明度，默认 0.3。
- color（str）：传感器颜色，默认 r。
示例：
```
sensors:
  - name: 'lidar2d'
    range_min: 0
    range_max: 5
    angle_range: 3.14 
    number: 200
    noise: False
    std: 0.2
    angle_std: 0.2
    offset: [0, 0, 0]
    plot:
      alpha: 0.3
```
fmcw_lidar2d: Simplified 2D FMCW LiDAR for range and radial Doppler measurements. It reuses the beam geometry of lidar2d and adds two functional parameters:
- motion_compensate (bool/False): Whether to remove ego-motion from the measured radial velocity.
- velocity_noise_std (float/0.0): Standard deviation of Gaussian noise on radial velocity.
All visualization options go under the sensor's plot: sub-dict (same convention as lidar2d and object plot:). Flat top-level keys are still accepted for backward compatibility.
- velocity_color (bool/True): Whether to color valid beams by radial velocity.
- velocity_color_max (float/2.0): Velocity magnitude where the plotting color saturates.
- velocity_linewidth (float/2.5): Plot line width for valid returns.
- no_hit_linewidth (float/0.8): Plot line width for invalid beams.
- no_hit_alpha (float/0.03): Plot transparency for invalid beams.
- show_velocity_markers (bool/True): Whether to draw colored hit markers at valid endpoints.
- velocity_marker_size (float/36): Plot marker size for valid endpoints.
- velocity_marker_edge_color (str/black): Edge color of the endpoint markers.
- velocity_marker_edge_width (float/0.6): Edge width of the endpoint markers.
- zero_velocity_color (str/cyan): Plot color used for near-zero radial velocity.
- positive_velocity_color (str/crimson): Plot color used for positive radial velocity.
- negative_velocity_color (str/royalblue): Plot color used for negative radial velocity.
- no_hit_color (str/lightgray): Plot color used for invalid beams.
The scan output adds radial_velocity and valid arrays on top of the standard LiDAR angular metadata.

示例：
```
sensors:
  - type: 'fmcw_lidar2d'
    range_min: 0.0
    range_max: 8.0
    angle_range: 2.0944
    number: 121
    motion_compensate: False
    plot:
      velocity_color: True
      velocity_linewidth: 2.0
      velocity_marker_size: 45
```

fov 和 fov_radius：定义对象传感器的视场（FOV）。FOV 是传感器可检测对象的角度范围。fov 参数以弧度指定角度范围，fov_radius 设置最大检测距离。

示例：

fov: 1.57
fov_radius: 5.0

object 可视化

概述

color — 对象颜色（'r'、'blue'、'k' 等）
description — 图像文件（如 'car_blue.png'、'diff_robot0.png'）
plot — 进阶显示选项
- Object — 外观（obj_color、obj_alpha、obj_linestyle）
- Goal — 目标标记（show_goal、goal_color、show_goal_text）
- Trail — 轨迹点（show_trail、keep_trail_length）
- Trajectory — 路径线（show_trajectory、keep_traj_length）
- Sensors — 传感器显示（show_sensor、show_fov）

color（str，默认 'k' 黑色）

指定对象在可视化中的颜色以便于识别。详细的颜色选项见 matplotlib 颜色。

示例：

color: 'r'

description（str，默认 None）

提供用于图形展示的图像，可使用 world/description 下的文件，或自定义绝对路径。

可用图像：

car_green.png：阿克曼车辆默认图。
car_blue.png
car_red.png
diff_robot0.png
diff_robot1.png

示例：

description: 'car_blue.png'

plot：包含控制对象显示的绘图选项。所有绘图元素初始创建在原点，并在动画更新时通过变换与数据更新定位。

对象可视化属性：

obj_linestyle（str）：对象轮廓线型（如 '-', '--', ':', '-.'），默认 '-'.
obj_zorder（int）：对象元素的绘制层级，机器人默认 3、障碍物默认 1。
obj_color（str）：对象颜色，默认沿用 color。
obj_alpha（float）：对象透明度（0.0-1.0），默认 1.0。
obj_linewidth（float）：轮廓线宽，默认随对象类型而定。

目标可视化：

show_goal（bool）：是否显示目标位置，默认 False。
- goal_color（str）：目标标记颜色，默认与对象一致。
- goal_alpha（float）：目标透明度，默认 0.5。
- goal_zorder（int）：目标层级，默认 1。
show_goal_text（bool）：是否显示目标位置的文本，默认 False。

文本标签可视化：

show_text（bool）：是否显示文本信息，默认 False。默认显示对象缩写（如 r0、o1）。可在运行时通过 object.set_text("自定义文本") 设置自定义文本。传入 None 可重置为默认缩写。
- text_color（str）：文本颜色，默认 'k'（黑）。
- text_size（int）：字体大小，默认 10。
- text_alpha（float）：文本透明度，默认 1.0。
- text_zorder（int）：文本层级，默认 2。
- text_position（列表）：相对对象中心的偏移 [dx, dy]，默认 [-radius-0.1, radius+0.1]。

同样，目标文本可通过 object.set_goal_text("自定义目标文本") 进行自定义。

速度箭头可视化：

show_arrow（bool）：是否显示速度箭头，默认 False。
- arrow_color（str）：箭头颜色，默认 "gold"。
- arrow_length（float）：箭头长度，默认 0.4。
- arrow_width（float）：箭头宽度，默认 0.6。
- arrow_alpha（float）：箭头透明度，默认 1.0。
- arrow_zorder（int）：箭头层级，默认 4。

轨迹线可视化：

show_trajectory（bool）：是否显示路径线，默认 False。
- traj_color（str）：路径颜色，默认继承对象颜色。
- traj_style（str）：路径线型（如 '-', '--', ':', '-.'），默认 "-"。
- traj_width（float）：路径线宽，默认为对象宽度。
- traj_alpha（float）：路径透明度，默认 0.5。
- traj_zorder（int）：路径层级，默认 0。
- keep_traj_length（int）：保留的尾段步数，默认 0（保留全部）。

对象轨迹点可视化：

show_trail（bool）：是否显示轨迹点，默认 False。
- trail_freq（int）：轨迹显示频率（每 N 步），默认 2。
- trail_type（str）：轨迹形状类型，默认与对象形状相同。
- trail_edgecolor（str）：轨迹边缘颜色，默认为对象颜色。
- trail_linewidth（float）：轨迹线宽，默认 0.8。
- trail_alpha（float）：轨迹透明度，默认 0.7。
- trail_fill（bool）：是否填充轨迹形状，默认 False。
- trail_color（str）：轨迹填充色，默认为对象颜色。
- trail_zorder（int）：轨迹层级，默认 0。
- keep_trail_length（int）：保留的轨迹尾段步数，默认 0（保留全部）。

传感器可视化：

show_sensor（bool）：是否显示传感器，默认 True。

视场可视化：

show_fov（bool）：是否显示视场，默认 False。
- fov_color（str）：视场填充色，默认 "lightblue"。
- fov_edge_color（str）：视场边缘色，默认 "blue"。
- fov_alpha（float）：视场透明度，默认 0.5。
- fov_zorder（int）：视场层级，默认 1。

注意： 所有可视化元素在初始化时创建于原点，并在动画期间通过 matplotlib 的变换（patch）与 set_data（线）定位。

示例：

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 配置#

GUI 参数表#

Parameter	类型	默认值	描述
`keyboard`	`dict`	`{}`	键盘控制选项（当 `world.control_mode: keyboard` 时生效）。
`mouse`	`dict`	`{}`	鼠标控制选项。

配置示例#

下面通过多个配置示例展示 IR-SIM 的灵活性与能力：

多机器人 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

多机器人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

混合障碍

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]

阿克曼车辆

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

全向角速度机器人

robot:
  - kinematics: {name: 'omni_angular'}
    shape: {name: 'circle', radius: 0.2}
    state: [2, 2, 0]
    goal: [8, 8, 0]
    velocity: [0, 0, 0]
    vel_min: [-1, -1, -1]
    vel_max: [1, 1, 1]
    behavior: {name: 'dash'}
    plot:
      show_trajectory: True

传感器集成

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

小技巧

配置最佳实践：

多个对象：配置多个对象时，使用 number 和 distribution 参数可高效地生成它们。例如，设置 number: 10 并使用 'random' 的 distribution，可快速在仿真中随机放置大量对象。
字典参数：所有字典类型的参数（如 distribution、shape、kinematics、behavior）都必须包含 'name' 键以指定其类型。省略 'name' 键会导致使用默认值或报错。
分组配置：同组对象默认共享配置。若需定制，请使用 - 添加子参数；未显式配置的对象会继承组内最后一个配置。
运动学与速度：确保 velocity 与 vel_max 的格式与运动学模型匹配，例如差速 ('diff') 使用 [v, omega]，全向 ('omni') 使用机体坐标系 [forward, lateral]，'omni_angular' 使用 [forward, lateral, yaw_rate]。
绘图选项：若 plot 位于对象配置内部，可为单个对象定制可视化；若位于对象配置的根级，则应用于所有对象。

YAML配置语法#

配置总览#

快速上手示例#

World 配置#

World 参数表#

参数详解#

完整世界配置示例#

Object 配置#

Object Parameters Table#

参数详解#

GUI 配置#

GUI 参数表#

配置示例#