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]` 坐标上的偏移量
`step_mode`	`str`	`"internal"`	状态推进模式，支持 `internal` 或 `external`
`control_mode`	`str`	`"auto"`	仿真控制模式，支持 `auto` 或 `keyboard`
`collision_mode`	`str`	`"stop"`	碰撞处理模式（支持：`"stop"`、`"unobstructed"`、`"unobstructed_obstacles"`）
`status`	`str`	`"None"`	初始显示标签；第一个完整仿真步后会被运行时状态替换
`obstacle_map`	`str`、`ndarray`、`dict` 或 `null`	`None`	生成器配置 dict（例如 `{ name: image, path: '…' }` 或 `{ name: perlin, resolution: 0.1, … }`）。字符串路径是 image 生成器的简写形式。参见配置栅格地图。
`mdownsample`	`int`	`1`	障碍地图的降采样系数，用于降低分辨率并减少计算量。
`fog_map`	`bool`	`false`	启用地图迷雾叠加层：世界初始为灰色（未探索），随着机器人探索，由每个激光雷达的视线逐步揭示。详见下方 `fog_map`。
`fog_map_resolution`	`float`	地图栅格尺寸	迷雾栅格的尺寸（米，仅在 `fog_map: true` 时生效）。默认与障碍地图的栅格尺寸一致，若无障碍地图则为 `0.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
  step_mode: 'internal'               # State advancement mode ('internal' or 'external')
  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: "Ready"                     # Initial display label (does not control execution)
  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`	`None`	对象的几何形状。省略时，IR-SIM 创建半径为 `1` 的圆；显式指定 `{name: circle}` 时使用半径 `0.2`。支持 `circle`、`rectangle`、`polygon`、`linestring`、`compound`。
`state`	`float` 列表	手动分布时为 `[1, 1, 0]`	对象的初始状态向量。
`velocity`	`float` 列表	`[0] * action_dim`	初始速度向量。长度与运动学动作维度匹配（`diff`/`omni`/`acker` 为 2，`omni_angular` 为 3）。
`goal`	`float`列表或`float`列表的列表	手动分布时为 `[1, 9, 0]`	目标状态向量。
`behavior`	`dict`	`None`	决定对象运动的行为配置，支持 `dash`、`rvo`、`sfm`（可用性取决于 `kinematics`，详见配置行为）。
`group_behavior`	`dict`	`None`	同组对象的群体行为配置，支持 `orca`。
`role`	`str`	从顶层键推断	对象在仿真中的角色（`robot` 下为 `"robot"`，`obstacle` 下为 `"obstacle"`）。
`color`	`str`	从角色和运动学推断	对象在仿真中的显示颜色。机器人使用运动学相关的默认颜色；障碍物默认使用黑色。
`static`	`bool`	派生值	存在运动学模型时为 `False`；否则对象始终为静态。将其设为 `true` 可冻结具有运动学模型的对象。
`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`	附加到该对象的传感器配置列表。支持的 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`	对象传感器的视场角（弧度），限制在 `[0, 2*pi]` 内。
`fov_radius`	`float`	`None`	对象传感器的视场半径。

参数详解#

object 运动学

运动学模型

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

速度指令在机器人自身坐标系下表示，而 [vx, vy] 描述的是世界坐标系下的刚体运动。RVO、SFM、ORCA 等全向规划器在世界坐标系下求解，因此其速度会在该边界处完成转换。在世界坐标系下规划的外部控制器同样按此转换：

env.step(env.robot.vel_world2body(world_vel))

omni 将 [vx, vy] 旋转为 [forward, lateral]；diff 则依据机器人的角速度上限与世界步长，将其映射为 [linear, angular]。acker 与 omni_angular 由指令直接控制，世界坐标系下的平移速度无法确定其指令，因此该转换会抛出异常。

(p-o-kinematics)=
**`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]`.    

    ```yaml
    # 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 body-frame velocities `[forward, lateral]`. Orientation (theta) is preserved but not updated. Optional parameters:
    - `noise` (bool): whether to add noise to the velocity commands. Default is `False`.
    - `alpha` (list): noise parameters for velocity commands `[alpha_forward, alpha_lateral]`. Default is `[0.03, 0.03]`.   

    ```yaml
    # Example usage
    kinematics: {name: 'omni', noise: True, alpha: [0.03, 0.03]}
    ```

  - `'omni_angular'`: Omnidirectional movement with angular velocity control. Extends `omni` by adding a yaw rate channel that integrates orientation (theta). This type of robot is controlled by body-frame velocities `[forward, lateral, yaw_rate]`. Optional parameters:
    - `noise` (bool): whether to add noise to the velocity commands. Default is `False`.
    - `alpha` (list): noise parameters for velocity commands `[alpha_forward, alpha_lateral, alpha_yaw]`. Default is `[0.03, 0.03, 0.03]`.

    ```yaml
    # Example usage
    kinematics: {name: 'omni_angular', noise: True, alpha: [0.03, 0.03, 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. 

    ```yaml
    # Example usage
    kinematics: {name: 'acker', noise: True, alpha: [0.03, 0, 0, 0.03], mode: 'steer'}
    ```
  

  Any other key under `kinematics` is passed to the handler's constructor. This is how a model registered with `@register_kinematics` receives its own parameters, e.g. `kinematics: {name: 'lag', tau: 0.5}`.

(p-o-vel-min)=
**`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.

(p-o-acce)=
**`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.

(p-o-angle-range)=
**`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.

(p-o-goal-threshold)=
**`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.

  ```yaml
  # 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 参数；kinematics 下的 wheelbase 会覆盖它。

object 形状

概述

circle — 圆形（radius、center）
rectangle — 矩形（length、width、wheelbase）
polygon — 自定义多边形（vertices、is_convex）
compound — 固定实体部件的组合（parts、pose）
linestring — 线段（vertices）

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

决定初始状态下用于碰撞检测和可视化的几何形状。如果完全省略 shape，对象将回退为以 [0, 0] 为中心、radius: 1 的圆；下面的 radius: 0.2 仅在给定 circle 形状但未显式指定 radius 时作为默认值。

支持的形状：

'circle'：圆形。
- radius（float）：圆半径，默认 0.2。
- center（list）：圆心在机体坐标系中的 [x, y] 偏移，会随对象朝向旋转。默认值为 [0, 0]。对于阿克曼圆形，实际圆心还会向前偏移 wheelbase / 2。
- 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。

# 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]} 

'compound'：表示由固定实体部件组合而成的一个刚性形状。
- parts（list）：由 circle、rectangle 或 polygon 形状字典组成的非空列表。
- pose（list）：部件相对于所属对象坐标系原点的可选 [x, y, theta] 位姿。默认值为 [0, 0, 0]，theta 使用弧度。
```
# Example usage - compound robot body
shape:
  name: compound
  parts:
    - {name: rectangle, length: 0.8, width: 0.3}
    - {name: rectangle, length: 0.3, width: 0.8, pose: [-0.25, 0, 0]}
```

'linestring'：由顶点列表定义的折线，类似多边形但生成的是一串线。

vertices（列表）：定义线串的顶点列表，格式 [[x1, y1], ...]。
random_shape（bool）：是否生成随机线串（多边形），默认 False。
is_convex（bool）：是否生成随机凸线串（多边形），默认 True。

# 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（互惠速度障碍）、sfm（社会力模型）
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}
```
'sfm'：实现社会力模型，用于反应式行人风格避障。支持 diff 和 omni 运动学。

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 激光雷达（range/radial_velocity、motion_compensate、多普勒可视化）
fov — 视场角（弧度）
fov_radius — 最大探测距离

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

lidar2d：用于距离测量的 2D LiDAR，参数包括：
- range_min（float）：最小探测距离，默认 0.0。
- range_max（float）：最大探测距离，默认 10.0。
- angle_range（float）：传感器覆盖角度，默认 pi，限制在 [0, 2*pi] 内（6.283185 为 360° 全向扫描）。
- 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。
可视化选项位于传感器的 plot: 子字典下（为向后兼容，仍接受扁平的顶层键）：
- 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：用于距离和径向多普勒测量的简化 2D FMCW 激光雷达。它复用 lidar2d 的波束几何，并新增两个功能参数：
- motion_compensate（bool/False）：是否从测得的径向速度中消除自身运动。
- velocity_noise_std（float/0.0）：径向速度上高斯噪声的标准差。
所有可视化选项位于传感器的 plot: 子字典下（与 lidar2d 和对象的 plot: 约定相同）。为向后兼容，仍接受扁平的顶层键。
- velocity_color（bool/True）：是否按径向速度为有效波束着色。
- velocity_color_max（float/2.0）：绘图颜色饱和时对应的速度大小。
- velocity_linewidth（float/2.5）：有效回波的绘图线宽。
- no_hit_linewidth（float/0.8）：无效波束的绘图线宽。
- no_hit_alpha（float/0.03）：无效波束的绘图透明度。
- show_velocity_markers（bool/True）：是否在有效端点处绘制彩色命中标记。
- velocity_marker_size（float/36）：有效端点的绘图标记大小。
- velocity_marker_edge_color（str/black）：端点标记的边缘颜色。
- velocity_marker_edge_width（float/0.6）：端点标记的边缘宽度。
- zero_velocity_color（str/cyan）：用于接近零径向速度的绘图颜色。
- positive_velocity_color（str/crimson）：用于正径向速度的绘图颜色。
- negative_velocity_color（str/royalblue）：用于负径向速度的绘图颜色。
- no_hit_color（str/lightgray）：用于无效波束的绘图颜色。
扫描输出在标准激光雷达角度元数据的基础上，增加了 radial_velocity 和 valid 数组。

示例：
```
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，默认从角色和运动学推断）

指定对象在可视化中的颜色，便于识别。带有已注册运动学的机器人使用运动学处理器定义的颜色；障碍物默认使用黑色。详细颜色选项见 matplotlib color。

示例：

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，描述图片默认 2。
obj_color（str）：对象颜色，默认沿用 color。
obj_alpha（float）：对象透明度（0.0-1.0），默认 1.0。
obj_linewidth（float/1.0）：对象轮廓线宽，单位为 Matplotlib 点。

目标可视化：

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/3）：箭头的绘制层级。

轨迹线可视化：

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`	`{}`	鼠标控制选项。

自定义配置#

自定义参数#

custom 会从 YAML 中读取并原样返回。IR-SIM 不会解析其内容，因此场景可以把自己代码所需的数值（容差、规划器权重等）与仿真器读取的参数放在同一个文件中，一并修改。

world:
  height: 20
  width: 20
  step_time: 0.1

robot:
  - kinematics: {name: 'diff'}
    shape: {name: 'circle', radius: 0.35}

custom:
  safe_margin: 0.15
  planner: {horizon: 20, weights: [1.0, 0.5]}

通过 config 读取，它返回全部已解析的配置段，因此与机器人半径写在一起的数值无需再次打开文件即可获得：

env = irsim.make("world.yaml")

margin = env.config["custom"]["safe_margin"] + env.robot.radius
horizon = env.config["custom"]["planner"]["horizon"]
step_time = env.config["world"]["step_time"]

custom 内部不做任何校验，可以自由嵌套；场景未提供该段时默认为 {}。env.reload() 会连同文件其余部分一起重新读取。

配置示例#

下面通过多个配置示例展示 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 参数表#

自定义配置#

自定义参数#

配置示例#