创建环境#

Python 脚本与 YAML 配置文件#

要开始仿真，需要先创建一个环境。环境是仿真中所有对象的容器，并负责在每个时间步更新仿真状态。

Python 脚本

可以使用简单的 Python 脚本创建环境：

import irsim

env = irsim.make('empty_world.yaml')

make 函数会根据配置文件创建环境，支持的参数包括：

world_name（str，可选）：世界 YAML 配置文件路径
projection（str，可选）：投影类型（“3d” 表示 3D 环境，None 表示 2D）
display（bool）：是否显示环境可视化（默认 True）
save_ani（bool）：是否将仿真保存为动图（默认 False）
log_level（str）：环境日志级别（默认 "INFO"）
seed（int，可选）：IR-SIM 随机数引擎的种子。提供后，IR-SIM 生成的随机内容即可复现；若省略或为 None，则使用未设种子的生成器（不可复现）。若自定义扩展仍使用 np.random 或 Python random，需改用 IR-SIM RNG 或另行设定种子。

更多信息见 EnvBase 类文档。

YAML 配置

在 YAML 文件（如 empty_world.yaml）中定义世界属性：

world:
  height: 10  # the height of the world (meters)
  width: 10   # the width of the world (meters)
  step_time: 0.1  # simulation time step (seconds) - 10Hz
  sample_time: 0.1  # rendering frequency (seconds) - 10Hz
  offset: [0, 0] # the offset of the world origin [x, y]
  control_mode: 'auto' # control mode: 'auto', 'keyboard'
  collision_mode: 'stop' # collision behavior: 'stop', 'unobstructed', 'unobstructed_obstacles'
  obstacle_map: null # path to obstacle map file (optional)

配置文件采用 YAML 格式，用于描述环境属性。empty_world.yaml 是一个简单示例，用于创建空环境。

重要参数说明#

世界配置#

world：定义仿真环境属性的主段
height 与 width：以米为单位指定世界尺寸
step_time：控制仿真精度与速度（越小越精确但更慢）
sample_time：控制渲染频率（越大仿真越快，可视化越不平滑）
offset：以米为单位偏移世界坐标系原点 [x, y]
control_mode：决定仿真控制方式
- 'auto'：自动执行仿真
- 'keyboard'：手动键盘控制
collision_mode：定义碰撞检测行为
- 'stop'：发生碰撞时停止仿真（默认）
- 'unobstructed'：忽略所有碰撞
- 'unobstructed_obstacles'：仅忽略障碍物碰撞
obstacle_map：可选，指向预设障碍地图文件的路径

性能考量#

更小的 step_time：物理更精确但仿真更慢
更大的 sample_time：仿真更快但可视化不够流畅
世界尺寸：更大的世界需要更多算力

小技巧

可以通过 sample_time 控制渲染频率、提升仿真速度。默认情况下 sample_time 与 step_time 相同。

更详细的参数说明参见 YAML 配置参考。

小技巧

自动配置检测：默认 YAML 配置文件与 Python 脚本同名。例如脚本为 test.py，IR-SIM 会在同目录自动寻找 test.yaml。

import irsim

# Automatically uses 'test.yaml' if this file is 'test.py'
env = irsim.make()

该特性避免手动指定配置文件，简化了开发流程。

基础仿真循环#

创建环境后，通常会运行如下仿真循环：

import irsim

env = irsim.make('config.yaml')

# Main simulation loop
for i in range(1000):
    env.step()        # Update simulation state
    env.render(0.05)  # Render with 0.05 second interval (20Hz)
    
    if env.done():    # Check if simulation should end
        break

env.end()  # Clean up resources

核心方法说明#

env.step()：让仿真前进一步
env.render(interval)：按设定的帧间隔刷新可视化
env.done()：当满足结束条件时返回 True
env.end()：正确关闭环境并释放资源

小技巧

更新顺序

环境会先推进所有对象，再更新全部传感器。这种两阶段更新保证传感器读取到的都是最新世界状态。若手动推进对象，请在 ObjectBase.step(...) 传入 sensor_step=True，或在更新对象状态后调用 obj.sensor_step()。

环境控制与状态#

状态管理#

import irsim

env = irsim.make('config.yaml')

# Check current status
print(f"Current status: {env.status}")
print(f"Current time: {env.time}")

# Control simulation state
env.pause()    # Pause the simulation
env.resume()   # Resume the simulation

# Simulation loop with status checking
for i in range(50):
    env.step()
    env.render(0.05)

    if i < 10:
        env.pause()
    elif i > 20 and i < 30:
        env.resume()
    
    if env.status == "Pause":
        print("Environment is paused")
    
    if env.done():
        print("Simulation completed successfully")

env.end()

可用状态值#

"Running"：环境在自动控制模式运行
"Running (keyboard)"：环境在键盘控制模式运行
"Pause"：仿真已暂停
"Done"：仿真已完成
"Arrived"：所有机器人都到达目标
"Collision"：检测到碰撞
"Pause (Debugging)"：调试模式（按下 F5 时）
"Reset"：环境已复位
"Reload"：环境已重新加载
"Save Figure"：已保存图像
"Quit"：环境已退出

配置环境标题#

默认情况下，环境标题会显示仿真时间与状态。可通过设置 show_title 并调用 env.set_title() 来自定义该行为。

自定义标题配置

import irsim

env = irsim.make('config.yaml')

# Set custom title
env.set_title("Multi-Robot Navigation Simulation")

# Update title dynamically
for i in range(100):
    env.step()
    
    # Update title every 10 steps
    if i % 10 == 0:
        env.set_title(f"Simulation Step: {i}")
    
    env.render(0.05)

env.end()

启用/禁用标题显示

world:
  height: 20
  width: 20
  control_mode: 'auto'
  plot:
    show_title: true    # Show title with time and status
    show_axis: true     # Optional: show axis labels