MAGAIL4AutoDrive/README.md

# 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! 🚗💨**