MAGAIL4AutoDrive - 多智能体自动驾驶环境
基于 MetaDrive 的多智能体自动驾驶仿真与回放环境，支持 Waymo Open Dataset 的专家轨迹回放和自定义策略仿真。
📋 目录
项目简介
MAGAIL4AutoDrive 是一个基于 MetaDrive 0.4.3 的多智能体自动驾驶环境，专为模仿学习（Imitation Learning）和强化学习（Reinforcement Learning）研究设计。项目支持从真实世界数据集（如 Waymo Open Dataset）中加载场景，并提供两种核心运行模式：
- 回放模式（Replay Mode）：严格按照专家轨迹回放，用于数据可视化和验证
- 仿真模式（Simulation Mode）：使用自定义策略控制车辆，用于算法训练和测试
功能特性
核心功能
- ✅ 多智能体支持：同时控制多辆车辆进行协同仿真
- ✅ 专家轨迹回放：精确回放 Waymo 数据集中的专家驾驶行为
- ✅ 自定义策略接口：灵活接入各种控制策略（IDM、RL 等）
- ✅ 智能车道过滤：自动过滤不在车道上的异常车辆
- ✅ 场景时长控制：支持使用数据集原始场景时长或自定义 horizon
- ✅ 丰富的传感器：LiDAR、侧向检测器、车道线检测器、相机、仪表盘
高级特性
- 🎯 指定场景 ID 运行
- 🔄 自动场景切换（修复版）
- 📊 详细的调试日志输出
- 🚗 车辆动态生成与管理
- 🎮 支持可视化渲染和无头运行
环境要求
系统要求
- 操作系统：Ubuntu 18.04+ / macOS 10.14+ / Windows 10+
- Python 版本：3.8 - 3.10
- GPU：可选，但推荐使用（用于加速渲染）
依赖库
metadrive-simulator==0.4.3
numpy>=1.19.0
pygame>=2.0.0
安装步骤
1. 创建 Conda 环境
conda create -n metadrive python=3.10
conda activate metadrive
2. 安装 MetaDrive
pip install metadrive-simulator==0.4.3
3. 克隆项目
git clone https://github.com/your-username/MAGAIL4AutoDrive.git
cd MAGAIL4AutoDrive/Env
4. 准备数据集
将 Waymo 数据集转换为 MetaDrive 格式并放置在项目目录下：
MAGAIL4AutoDrive/Env/
├── exp_converted/
│ ├── scenario_0/
│ ├── scenario_1/
│ └── ...
快速开始
回放模式（推荐先尝试）
# 使用场景原始时长回放第一个场景
python run_multiagent_env.py --mode replay --episodes 1 --use_scenario_duration
# 回放指定场景
python run_multiagent_env.py --mode replay --scenario_id 0 --use_scenario_duration
# 回放多个场景
python run_multiagent_env.py --mode replay --episodes 3 --use_scenario_duration
仿真模式
# 使用默认策略运行仿真
python run_multiagent_env.py --mode simulation --episodes 1
# 无渲染运行（加速训练）
python run_multiagent_env.py --mode simulation --episodes 5 --no_render
使用指南
命令行参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--mode |
str | simulation | 运行模式：replay 或 simulation |
--data_dir |
str | 当前目录 | Waymo 数据目录路径 |
--episodes |
int | 1 | 运行回合数 |
--horizon |
int | 300 | 每回合最大步数 |
--no_render |
flag | False | 禁用渲染（加速运行） |
--debug |
flag | False | 启用调试模式 |
--scenario_id |
int | None | 指定场景 ID |
--use_scenario_duration |
flag | False | 使用场景原始时长 |
--no_vehicles |
flag | False | 禁止生成车辆 |
--no_pedestrians |
flag | False | 禁止生成行人 |
--no_cyclists |
flag | False | 禁止生成自行车 |
回放模式详解
回放模式严格按照专家轨迹回放车辆状态，不涉及物理引擎控制。主要用途：
- 数据集可视化
- 验证数据质量
- 生成演示视频
# 完整参数示例
python run_multiagent_env.py \
--mode replay \
--episodes 1 \
--use_scenario_duration \
--debug
# 仅回放车辆，禁止行人和自行车
python run_multiagent_env.py \
--mode replay \
--use_scenario_duration \
--no_pedestrians \
--no_cyclists
重要提示：回放模式建议始终启用 --use_scenario_duration，否则会出现场景播放完后继续运行的问题。
仿真模式详解
仿真模式使用自定义策略控制车辆，适合算法开发和测试：
# 基础仿真
python run_multiagent_env.py --mode simulation
# 长时间训练（无渲染）
python run_multiagent_env.py \
--mode simulation \
--episodes 100 \
--horizon 500 \
--no_render
# 仅车辆仿真（用于专注车车交互场景）
python run_multiagent_env.py \
--mode simulation \
--no_pedestrians \
--no_cyclists
自定义策略
修改 simple_idm_policy.py 或创建新的策略类：
class CustomPolicy:
def __init__(self, **kwargs):
# 初始化策略参数
pass
def act(self, observation=None):
# 返回动作 [steering, acceleration]
# steering: [-1, 1]
# acceleration: [-1, 1]
return [0.0, 0.5]
在 run_multiagent_env.py 中使用：
from custom_policy import CustomPolicy
env = MultiAgentScenarioEnv(
config={...},
agent2policy=CustomPolicy()
)
项目结构
MAGAIL4AutoDrive/Env/
├── run_multiagent_env.py \# 主运行脚本
├── scenario_env.py \# 多智能体场景环境
├── replay_policy.py \# 专家轨迹回放策略
├── simple_idm_policy.py \# IDM 策略实现
├── utils.py \# 工具函数
├── ENHANCED_USAGE_GUIDE.md \# 详细使用指南
├── README.md \# 本文档
└── exp_converted/ \# Waymo 数据集（需自行准备）
├── scenario_0/
├── scenario_1/
└── ...
核心文件说明
run_multiagent_env.py
- 主入口脚本
- 处理命令行参数
- 管理回放和仿真两种模式的运行逻辑
scenario_env.py
- 自定义多智能体环境类
- 车辆生成与管理
- 车道过滤逻辑
- 观测空间定义
replay_policy.py
- 专家轨迹回放策略
- 逐帧状态查询
- 轨迹完成判断
simple_idm_policy.py
- 简单的恒速策略示例
- 可作为自定义策略的模板
配置说明
环境配置参数
在 scenario_env.py 的 default_config() 中可修改：
config.update(dict(
data_directory=None, # 数据目录
num_controlled_agents=3, # 可控车辆数量（仅仿真模式）
horizon=1000, # 最大步数
filter_offroad_vehicles=True, # 是否过滤车道外车辆
lane_tolerance=3.0, # 车道容差（米）
replay_mode=False, # 是否为回放模式
specific_scenario_id=None, # 指定场景 ID
use_scenario_duration=False, # 使用场景原始时长
# 对象类型过滤选项
spawn_vehicles=True, # 是否生成车辆
spawn_pedestrians=True, # 是否生成行人
spawn_cyclists=True, # 是否生成自行车
))
传感器配置
默认启用的传感器（可在环境初始化时修改）：
- LiDAR：80 条激光，探测距离 30 米
- 侧向检测器：10 条激光，探测距离 8 米
- 车道线检测器：10 条激光，探测距离 3 米
- 主相机：分辨率 1200x900
- 仪表盘：车辆状态信息
常见问题
Q1: 回放模式为什么超出数据集的最大帧数还在继续？
A: 需要添加 --use_scenario_duration 参数。修复版本已在 scenario_env.py 中添加了自动检测机制。
Q2: 如何切换不同的场景？
A:
- 方法一：使用
--scenario_id指定场景 - 方法二：使用
--episodes N自动遍历 N 个场景
Q3: 为什么有些车辆没有出现？
A: 启用了车道过滤功能（filter_offroad_vehicles=True），不在车道上的车辆会被过滤。可以通过设置 lane_tolerance 调整容差或关闭此功能。
Q4: 如何提高运行速度？
A:
- 使用
--no_render禁用可视化 - 减少
num_controlled_agents数量 - 使用 GPU 加速
Q5: 如何控制场景中的对象类型？
A: 使用对象过滤参数：
# 仅车辆，无行人和自行车
python run_multiagent_env.py --mode replay --no_pedestrians --no_cyclists
# 仅行人和自行车，无车辆（特殊场景）
python run_multiagent_env.py --mode replay --no_vehicles
# 调试模式查看过滤统计
python run_multiagent_env.py --mode replay --debug --no_pedestrians
Q6: 为什么有些车辆生成在空中？
A: 已在 v1.2.0 中修复。现在所有车辆位置都只使用 2D 坐标（x, y），z 坐标设为 0，让 MetaDrive 自动处理高度，确保车辆贴在地面上。
Q7: 如何导出观测数据？
A: 在 run_multiagent_env.py 中添加数据保存逻辑：
import pickle
obs_data = []
while True:
obs, rewards, dones, infos = env.step(actions)
obs_data.append(obs)
if dones["__all__"]:
break
with open('observations.pkl', 'wb') as f:
pickle.dump(obs_data, f)
更新日志
v1.2.0 (2025-10-26)
- ✅ 修复车辆生成高度问题（车辆悬空）
- ✅ 添加对象类型过滤功能（车辆/行人/自行车）
- ✅ 新增命令行参数：
--no_vehicles、--no_pedestrians、--no_cyclists - ✅ 改进调试信息输出，显示各类型对象统计
- ✅ 优化位置处理逻辑，只使用 2D 坐标避免高度问题
v1.1.0 (2025-10-26)
- ✅ 修复回放模式超出场景时长问题
- ✅ 添加场景自动切换功能
- ✅ 改进
replay_policy.py，新增is_finished()方法 - ✅ 优化
scenario_env.py的 done 判断逻辑 - ✅ 修复多回合运行时的对象清理问题
v1.0.0 (初始版本)
- 基础多智能体环境实现
- 回放和仿真两种模式
- 车道过滤功能
- Waymo 数据集支持
贡献指南
欢迎提交 Issue 和 Pull Request！
提交 Issue
- 请详细描述问题和复现步骤
- 附上运行日志和错误信息
- 说明运行环境（OS、Python 版本等）
提交 PR
- Fork 本项目
- 创建特性分支：
git checkout -b feature/your-feature - 提交更改：
git commit -m 'Add some feature' - 推送分支：
git push origin feature/your-feature - 提交 Pull Request
许可证
本项目基于 MIT 许可证开源。
致谢
- MetaDrive - 优秀的驾驶仿真平台
- Waymo Open Dataset - 高质量的自动驾驶数据集
联系方式
如有问题或建议，请通过以下方式联系：
- GitHub Issues: [项目 Issues 页面]
- Email: huangfukk@xxx.com
Happy Driving! 🚗💨