bev-project/project/docs/INFERENCE_GUIDE.md

# BEVFusion推理和可视化指南

**生成时间**：2025-10-21  
**基于Checkpoint**：epoch_19.pth  
**数据集**：nuScenes Validation Set

---

## 📋 文件说明

### 1. inference_and_visualize.py
**功能**：完整的推理和可视化脚本

**特性**：
- ✅ 加载epoch_19.pth权重
- ✅ 在nuScenes验证集上推理
- ✅ 生成BEV分割可视化
- ✅ 生成3D检测可视化
- ✅ 生成综合可视化（分割+检测）
- ✅ 支持自定义样本数量
- ✅ 支持置信度阈值设置

### 2. run_inference.sh
**功能**：一键运行推理脚本

**默认配置**：
```bash
Checkpoint: epoch_19.pth
样本数: 10
置信度阈值: 0.3
输出目录: inference_results_epoch19
```

---

## 🚀 快速开始

### 方法1：使用Shell脚本（推荐）

```bash
# 直接运行
bash run_inference.sh
```

### 方法2：使用Python脚本

```bash
# 基本用法
python inference_and_visualize.py

# 自定义参数
python inference_and_visualize.py \
    --checkpoint runs/run-326653dc-74184412/epoch_19.pth \
    --samples 20 \
    --output-dir my_results \
    --show-score-thr 0.4 \
    --device cuda:0
```

---

## 🎨 可视化输出

### 输出文件结构

```
inference_results_epoch19/
├── sample_0000_segmentation.png    # BEV分割结果
├── sample_0000_detection.png       # 3D检测结果
├── sample_0000_combined.png        # 综合可视化
├── sample_0001_segmentation.png
├── sample_0001_detection.png
├── sample_0001_combined.png
...
```

### 可视化内容

#### 1. BEV分割（*_segmentation.png）
显示6个地图类别：
- **紫色** - drivable_area（可行驶区域）
- **粉色** - ped_crossing（人行横道）
- **灰色** - walkway（人行道）
- **红色** - stop_line（停止线）
- **绿色** - carpark_area（停车区）
- **黄色** - divider（分隔线）

#### 2. 3D检测（*_detection.png）
显示检测到的3D目标框（BEV视图）：
- 不同颜色表示不同类别
- 框内显示置信度分数
- 显示物体朝向

#### 3. 综合可视化（*_combined.png）
左侧：BEV分割  
右侧：3D检测

---

## ⚙️ 参数说明

### 命令行参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--config` | multitask.yaml | 模型配置文件路径 |
| `--checkpoint` | epoch_19.pth | Checkpoint文件路径 |
| `--samples` | 10 | 推理的样本数量 |
| `--output-dir` | inference_results | 输出目录 |
| `--show-score-thr` | 0.3 | 检测框显示的置信度阈值 |
| `--device` | cuda:0 | 推理设备 |

### 修改参数示例

#### 增加样本数
```bash
python inference_and_visualize.py --samples 50
```

#### 提高置信度阈值（只显示高置信度检测）
```bash
python inference_and_visualize.py --show-score-thr 0.5
```

#### 更换输出目录
```bash
python inference_and_visualize.py --output-dir results_highconf
```

#### 使用不同GPU
```bash
python inference_and_visualize.py --device cuda:1
```

---

## 📊 预期输出示例

### 运行日志

```
================================================================================
BEVFusion推理和可视化
================================================================================
配置文件: configs/.../multitask.yaml
Checkpoint: runs/.../epoch_19.pth
样本数量: 10
输出目录: inference_results_epoch19
置信度阈值: 0.3
================================================================================

================================================================================
加载模型配置和权重
================================================================================

1. 构建模型...

2. 加载checkpoint: runs/run-326653dc-74184412/epoch_19.pth

✅ 模型加载完成
   - Device: cuda:0
   - Checkpoint epoch: 19

================================================================================
构建数据加载器
================================================================================

✅ 数据加载器构建完成
   - 样本数量: 10
   - 数据集: nuScenes validation set

================================================================================
开始推理和可视化
================================================================================

推理中: 100%|████████████| 10/10 [00:45<00:00,  4.5s/it]
   ✅ 已保存: inference_results_epoch19/sample_0000_combined.png
   ✅ 已保存: inference_results_epoch19/sample_0001_combined.png
   ...

================================================================================
✅ 推理完成！
   - 结果保存在: inference_results_epoch19
   - 共处理样本: 10
================================================================================
```

### 性能指标

- **推理速度**：约4-5秒/样本
- **显存占用**：约8-10GB
- **输出文件大小**：每个PNG约1-3MB

---

## 🔍 结果分析

### 查看结果

```bash
# 列出所有生成的文件
ls -lh inference_results_epoch19/

# 统计文件数量
ls inference_results_epoch19/*.png | wc -l

# 使用图像查看器
# Linux:
eog inference_results_epoch19/sample_0000_combined.png

# 或者复制到本地查看
```

### 预期性能（基于epoch_19）

**3D检测**：
- NDS: ~0.70
- mAP: ~0.62
- 主要类别（car, pedestrian等）检测准确

**BEV分割**：
- mIoU: ~40-45%
- drivable_area: 较高IoU (~70%)
- 小目标类别（stop_line等）: 较低IoU (~20-30%)

---

## 🛠️ 高级用法

### 1. 批量推理所有验证集

```bash
python inference_and_visualize.py --samples 6019
# nuScenes val set共6019个样本
```

### 2. 只推理特定类别

修改`inference_and_visualize.py`中的`score_thr`或后处理逻辑

### 3. 导出为视频

```bash
# 使用ffmpeg合成视频
cd inference_results_epoch19
ffmpeg -framerate 2 -pattern_type glob -i '*_combined.png' \
    -c:v libx264 -pix_fmt yuv420p output_video.mp4
```

### 4. 评估指标计算

```bash
# 使用mmdetection3d的评估工具
python tools/test.py \
    configs/.../multitask.yaml \
    runs/.../epoch_19.pth \
    --eval bbox segm
```

---

## 📈 可视化质量说明

### 分割可视化
- **分辨率**：200×200（BEV空间）
- **覆盖范围**：100m × 100m（±50m）
- **分辨率**：0.5m/pixel
- **颜色编码**：符合nuScenes标准

### 检测可视化
- **显示范围**：±50m（BEV）
- **框表示**：矩形框表示物体边界
- **朝向表示**：框的开口方向表示物体朝向
- **置信度**：显示在框内

---

## ⚠️ 注意事项

### 1. 内存要求
- **GPU显存**：建议至少10GB
- **系统内存**：建议至少32GB

### 2. 数据路径
确保nuScenes数据集路径正确：
```python
# 配置文件中应该有
data_root = 'data/nuscenes/'
ann_file = 'data/nuscenes/nuscenes_infos_val.pkl'
```

### 3. 依赖项
需要安装：
- torch
- mmcv
- mmdet3d
- matplotlib
- opencv-python
- tqdm

### 4. 已知限制
- 当前可视化为2D BEV视图
- 不包含相机图像叠加
- 不支持3D可视化（如点云）

---

## 🐛 故障排除

### 问题1：找不到checkpoint
```bash
# 检查文件是否存在
ls -lh runs/run-326653dc-74184412/epoch_19.pth

# 如果不存在，检查其他runs目录
ls -lh runs/*/epoch_*.pth
```

### 问题2：CUDA OOM
```bash
# 减少batch size或使用CPU
python inference_and_visualize.py --device cpu

# 或者减少样本数
python inference_and_visualize.py --samples 5
```

### 问题3：数据集路径错误
```bash
# 检查数据集
ls data/nuscenes/
ls data/nuscenes/nuscenes_infos_val.pkl
```

### 问题4：可视化不显示
```bash
# 确保安装了matplotlib的backend
pip install matplotlib pillow

# 或者检查生成的PNG文件
file inference_results_epoch19/sample_0000_combined.png
```

---

## 📝 自定义修改

### 修改颜色方案

编辑`inference_and_visualize.py`中的`colors`字典：

```python
colors = {
    'drivable_area': [128, 64, 128],    # 修改为你想要的RGB值
    'ped_crossing': [244, 35, 232],
    ...
}
```

### 修改可视化布局

调整`visualize_combined`函数中的`figsize`和subplot布局

### 添加额外信息

在可视化函数中添加：
- 时间戳
- 场景ID
- 性能指标
- 统计信息

---

## 📚 参考资料

- [nuScenes数据集](https://www.nuscenes.org/)
- [BEVFusion论文](https://arxiv.org/abs/2205.13542)
- [MMDetection3D文档](https://mmdetection3d.readthedocs.io/)

---

**创建时间**：2025-10-21  
**脚本版本**：1.0  
**适用Checkpoint**：epoch_19.pth  
**状态**：✅ 可用