Racecar Gym

Racecar Gym 

参考：https://github.com/axelbr/racecar_gym/blob/master/README.md

1. 项目介绍

Racecar Gym 是一个基于 PyBullet 物理引擎的 reinforcement learning (RL) 训练环境，模拟微型 F1Tenth 竞速赛车。它兼容 Gym API 和 PettingZoo API，支持 single-agent 和 multi-agent 任务。

2. 环境结构

• Observations（观测）

通过sensors（传感器）获取，包括：

pose（位置 & 方向）

lidar（激光雷达）

rgb_camera（相机图像）

• Actions（动作）

由 actuators（执行器）控制：

 motor（油门，范围 -1 到 1）控制赛车前进或后退，-1 代表倒车，1 代表加速到最大速度。

 steering（方向盘，范围 -1 到 1）控制转向，-1 代表最左，1 代表最右，0 代表直行。

action space 是一个 dict，包含键 motor 和 steering 

action_space = {
    "motor": [-1, 1],  # 范围 -1 (倒车) 到 1 (全速前进)
    "steering": [-1, 1]  # 范围 -1 (左转) 到 1 (右转)
} 

action = {"motor": 0.5, "steering": -0.8} 

“motor”: 0.5 → 以 50% 的油门向前加速。

 “steering”: -0.8 → 方向盘向左转 80%。

 

• State（环境状态）

wall_collision（是否碰撞墙壁）

opponent_collisions（是否与其他agent碰撞）

progress（当前赛道进度）

lap（圈数）

rank（比赛排名）

wrong_way（是否逆行）

3. 代码示例解析

代码 1：安装 Racecar Gym

git clone https://github.com/axelbr/racecar_gym.git  # 下载项目代码
cd racecar_gym                                       # 进入项目目录
pip install -e .                                     # 以可编辑模式安装

 pip install -e .：安装本地包，允许修改后立即生效

代码 2：Gym API 使用示例

import gymnasium  # 导入 Gymnasium（新版 Gym）
import racecar_gym.envs.gym_api  # 导入 racecar_gym

env = gymnasium.make(
    id='SingleAgentAustria-v0',  # 选择环境（奥地利赛道）
    render_mode='human'          # 设置渲染模式
)

gymnasium.make()：创建环境

 id='SingleAgentAustria-v0'：选择预定义的单代理（Single-Agent）环境

render_mode='human'：启用人类可视化渲染

代码 3：自定义 Scenario

env = gymnasium.make(
    id='SingleAgentRaceEnv-v0', 
    scenario='path/to/scenario.yml',  # 加载自定义赛道
    render_mode='rgb_array_follow',   # 以RGB图像模式渲染
    render_options=dict(width=320, height=240, agent='A')  # 设定渲染参数
)

scenario='path/to/scenario.yml'：指定 YAML 场景文件

render_mode='rgb_array_follow'：启用摄像机跟随模式

render_options：设定画面分辨率 & 监控哪个代理（Agent）

代码 4：环境交互（Gym API）

done = False
reset_options = dict(mode='grid')  # 设置重置模式
obs, info = env.reset(options=reset_options)  # 重置环境，获取初始观测值

while not done:
    action = env.action_space.sample()  # 采样随机动作
    obs, rewards, terminated, truncated, states = env.step(action)  # 执行动作
    done = terminated or truncated  # 判断是否终止

env.close()  # 关闭环境

env.reset()：重置环境

env.action_space.sample()：随机采样动作

env.step(action)：

• 输入：执行 action

• 返回值：

• obs（新的观测值）

• rewards（奖励值）

• terminated（是否到达终止状态）

• truncated（是否提前截断）

• states（环境状态）

代码 5：PettingZoo API 使用

from racecar_gym.envs import pettingzoo_api  # 导入 PettingZoo API
env = pettingzoo_api.env(scenario='path/to/scenario')  # 加载自定义场景

• pettingzoo_api.env(scenario='...')：使用 multi-agent 版本

4. 赛道 & 代理配置

示例 YAML 场景文件 (austria.yml)

world:
  name: austria  # 赛道名称

agents:
  - id: A
    vehicle:
      name: racecar
      sensors: [lidar, pose, velocity, acceleration]  # 传感器
      actuators: [motor, steering]  # 执行器
      color: blue  # 车辆颜色
    task:
      task_name: maximize_progress  # 任务：最大化进度
      params: {laps: 1, time_limit: 120.0, terminate_on_collision: False}  # 任务参数

• world.name：定义赛道名称

• agents：定义代理（Agent）

• vehicle.name：赛车类型

• sensors：传感器，如激光雷达（lidar）等

• actuators：执行器，如电机（motor）和方向盘（steering）

• color：赛车颜色

• task：定义任务（Task）

• task_name：任务类型，如 maximize_progress（最大化进度）

params：

• laps：完成圈数

• time_limit：时间限制

• terminate_on_collision：是否在碰撞时终止

5. 主要总结

（1）Racecar Gym 是一个 Gym 兼容的微型赛车模拟环境，支持强化学习（RL）。

（2） Observation space 通过 sensors 获取，如 lidar, velocity, acceleration。

（3） Action space 通过 actuators 控制，如 motor, steering。

（4） State 提供额外信息，如 progress, rank, collisions 等。

（5） 代码使用方式

• Gym API：gymnasium.make() 创建环境

• PettingZoo API：pettingzoo_api.env() 适用于 multi-agent 任务

• Scenario（YAML 配置） 可自定义赛道、代理、传感器等

6. 代码结构

• env.reset() 初始化环境

• env.step(action) 执行动作并返回新的状态

• env.close() 关闭环境

示例

假设你有一辆赛车（Agent），它装备了激光雷达（LiDAR）和速度计（Velocity Sensor）。

你可以在**车辆配置文件（vehicle configuration）中定义 LiDAR 的范围、分辨率，以及它是否带噪声。

然后，在场景配置（scenario specification）中，你可以选择是否在本次实验中启用 LiDAR。

vehicle:
  name: racecar
  sensors:
    - lidar:
        range: 10.0  # 激光雷达最大测距 10 米
        resolution: 1080  # 1080 线
        noise: 0.02  # 2% 的噪声
    - velocity:
        noise: 0.05  # 5% 的速度测量误差

• 如果你选择不启用 LiDAR，则 Observations 中不会包含它。

• 如果你启用了 LiDAR，赛车在行驶时会获取 1080 线的距离测量数据，并且每个测量值可能有 2% 的误差。

假设赛车有 LiDAR 和 Velocity Sensor，它们的 Observation Space 可能如下：

observation = {
    "lidar": [2.3, 4.5, 3.1, 5.2, 3.8],  # LiDAR 检测的障碍物距离（单位：米）
    "velocity": [3.0, 0.0],  # 速度数据 [前进速度 3m/s，转向速度 0 rad/s]
    "pose": [4.1, 2.3, 0.0, 0.0, 0.0, 1.57]  # 位置（x, y, z）+ 方向角（roll, pitch, yaw）
}

“lidar” 传感器返回 5 个数值，表示前方的障碍物距离。

“velocity” 传感器返回 2 个值，表示线速度（m/s）和角速度（rad/s）。

“pose” 传感器返回 6 个数值，表示位置和旋转角度。

在 AI 训练过程中，每次执行动作后，环境都会返回一个新的 observation dict，代理用它来决策下一步行动。

Vehicle Configuration

定义了赛车的物理特性

• 作用：定义一辆赛车的物理特性，包括传感器（sensors）、执行器（actuators）、最大速度等。

• 文件位置：通常是 .yaml 文件，例如 differential_racecar.yaml。

• 适用范围：同一个赛车模型可以被多个 scenarios（场景） 复用。

 vehicle:
  name: differential_racecar
  sensors:
    - lidar:
        range: 10.0  # 激光雷达最大探测 10 米
        resolution: 1080  # 1080 条激光束
        noise: 0.02  # 2% 噪声
    - velocity:
        noise: 0.05  # 5% 的速度测量误差
  actuators:
    - motor:   # 车辆的加速度控制
        max_force: 20.0  # 最大驱动力
    - steering: # 车辆的转向控制
        max_angle: 0.4  # 最大方向盘转角（弧度）
  max_speed: 5.0  # 最高速度 5 m/s

(1) name: differential_racecar → 车辆的名称，支持多个不同类型的赛车。

(2) sensors（传感器）

• lidar（激光雷达）：最大探测 10 米，有 1080 线，测量有 2% 误差。

• velocity（速度传感器）：速度测量有 5% 误差。

(3) actuators（执行器）

• motor（电机）：最大驱动力 20 N。

• steering（方向盘）：最大转向角 0.4 弧度（约 23°）。

(4) max_speed: 5.0 → 车辆的最高速度为 5 m/s。

 

Scenario Specification

定义了赛车的训练环境

• 作用：定义整个训练环境，包括赛道（track）、代理（agents）、任务（tasks） 等。

• 文件位置：通常是 .yaml 文件，例如 austria.yml。

• 适用范围：可以加载不同的 vehicle configurations（车辆配置） 来创建不同的训练环境。

world:
  name: austria  # 赛道名称

agents:
  - id: A
    vehicle:
      name: differential_racecar  # 选择使用 differential_racecar.yaml 定义的赛车
      sensors: [lidar, pose, velocity, acceleration]  # 指定使用的传感器
      actuators: [motor, steering]  # 指定控制方式
      color: blue  # 赛车颜色（可选 red, green, blue, yellow, magenta, random）
    task:
      task_name: maximize_progress  # 目标是尽快完成赛道
      params: 
        laps: 1  # 目标完成 1 圈
        time_limit: 120.0  # 120 秒内完成
        terminate_on_collision: False  # 碰撞时是否终止任务

(1) world.name: austria → 选择的赛道是奥地利（Austria）。

(2) agents（代理）

• id: A → 定义代理 A。

• vehicle.name: differential_racecar → 使用 differential_racecar.yaml 作为赛车配置。

• sensors（传感器） → 该赛车将使用 LiDAR（激光雷达）、Pose（位置）、Velocity（速度）、Acceleration（加速度）。

• actuators（执行器） → 该赛车使用 motor（油门） 和 steering（方向盘）。

• color: blue → 车辆颜色是蓝色（可选 red, green, blue, yellow, magenta, random）。

(3) task（任务）

• task_name: maximize_progress → 代理的目标是尽可能快地完成赛道（最大化进度）。

• laps: 1 → 目标是完成 1 圈。

• time_limit: 120.0 → 120 秒内完成，否则失败。

• terminate_on_collision: False → 碰撞后是否终止任务（False 表示继续比赛）。

 

1. 直接加载预设 Scenario 

import gymnasium

import racecar_gym.envs.gym_api

env = gymnasium.make(

    id='SingleAgentAustria-v0',  # 选择预设的 "austria" 赛道

    render_mode='human'          # 启用渲染

)

SingleAgentAustria-v0 已经包含了 scenario specification（场景配置） 和 vehicle configuration（车辆配置），因此直接使用。

2. 加载自定义 Scenario

env = gymnasium.make(
    id='SingleAgentRaceEnv-v0', 
    scenario='path/to/custom_scenario.yml',  # 加载自定义 Scenario
    render_mode='rgb_array_follow',  # 选择渲染模式
    render_options=dict(width=320, height=240, agent='A')  # 设置渲染参数
)

scenario='path/to/custom_scenario.yml' → 这里指定的是 Scenario Specification 文件。

render_mode='rgb_array_follow' → 选择摄像机跟随赛车模式。

3. 训练时加载

 如果你在强化学习训练时使用 Racecar Gym，通常会加载自定义的 scenario：

from stable_baselines3 import PPO

# 加载环境
env = gymnasium.make(id="SingleAgentRaceEnv-v0", scenario="my_scenario.yml")

# 训练 AI 代理
model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=100000)

# 保存训练的模型
model.save("racecar_model")

scenario="my_scenario.yml" → 加载自己设定的赛道、赛车、任务。

PPO("MlpPolicy", env, verbose=1) → 使用 PPO 强化学习算法训练赛车。