402 lines
11 KiB
Markdown
402 lines
11 KiB
Markdown
# 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 | 禁止生成自行车 |
|
||
|
||
### 回放模式详解
|
||
|
||
回放模式严格按照专家轨迹回放车辆状态，不涉及物理引擎控制。主要用途：
|
||
- 数据集可视化
|
||
- 验证数据质量
|
||
- 生成演示视频
|
||
|
||
```bash
|
||
# 完整参数示例
|
||
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`，否则会出现场景播放完后继续运行的问题。
|
||
|
||
### 仿真模式详解
|
||
|
||
仿真模式使用自定义策略控制车辆，适合算法开发和测试：
|
||
|
||
```bash
|
||
# 基础仿真
|
||
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` 或创建新的策略类：
|
||
|
||
```python
|
||
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()` 中可修改：
|
||
|
||
```python
|
||
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**: 使用对象过滤参数：
|
||
```bash
|
||
# 仅车辆，无行人和自行车
|
||
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` 中添加数据保存逻辑：
|
||
```python
|
||
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](https://github.com/metadriverse/metadrive) - 优秀的驾驶仿真平台
|
||
- [Waymo Open Dataset](https://waymo.com/open/) - 高质量的自动驾驶数据集
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
- GitHub Issues: [项目 Issues 页面]
|
||
- Email: huangfukk@xxx.com
|
||
|
||
---
|
||
|
||
**Happy Driving! 🚗💨**
|