# 模型性能评估工具

这是一个用于评估UAV和鸟类检测模型性能的完整工具集，包括误报率、漏报率、分类准确率和推理速度等关键指标的评估。

## 文件说明

### 核心文件

- **`model_evaluator.py`** - 主要的模型评估类，包含所有评估逻辑
- **`run_evaluation.py`** - 简化的运行脚本，提供命令行接口
- **`evaluation_config.json`** - 配置文件，可自定义评估参数
- **`generate_test_data.py`** - 测试数据生成器（当没有真实数据时使用）
- **`example_balanced_evaluation.py`** - 平衡采样评估示例脚本

### 功能特性

✅ **多种评估指标**
- 混淆矩阵（TP, FP, FN, TN）
- 精确率、召回率、F1分数
- 准确率、误报率、漏报率
- 按类别的详细指标

✅ **推理速度评估**
- 平均推理时间
- FPS（每秒处理帧数）
- 总处理时间统计

✅ **灵活的数据加载**
- 支持文件夹结构（BIRDS/UAV/OTHERS）
- 支持标注文件格式
- 可配置采样大小

✅ **可视化和报告**
- 自动生成详细的评估报告
- 混淆矩阵热图
- 性能指标图表

✅ **多模型支持**
- uav_and_bird
- Anti_UAV
- UAV-250411

## 快速开始

### 1. 环境准备

确保已安装必要的依赖：

```bash
pip install opencv-python numpy matplotlib seaborn pandas tqdm
```

### 2. 数据准备

将测试数据按以下结构组织：
```
data/
├── BIRDS/          # 鸟类图像
├── UAV/            # 无人机图像
└── OTHERS/         # 其他类型图像（背景等）
```

### 3. 运行评估

**基本用法：**
```bash
python run_evaluation.py --data-dir ./data
```

**平衡采样评估（推荐）：**
```bash
# 使用2:2:6比例进行平衡采样
python run_evaluation.py \
    --data-dir ./data \
    --sample-size 1000 \
    --balanced-sampling \
    --bird-ratio 0.2 \
    --uav-ratio 0.2 \
    --others-ratio 0.6
```

**自定义参数：**
```bash
python run_evaluation.py \
    --model-type uav_and_bird \
    --threshold 0.6 \
    --data-dir ./test_data \
    --sample-size 1000 \
    --output-dir ./results
```

**完整参数列表：**
```bash
python run_evaluation.py \
    --model-type uav_and_bird \
    --threshold 0.5 \
    --data-dir ./data \
    --sample-size 1000 \
    --balanced-sampling \
    --bird-ratio 0.2 \
    --uav-ratio 0.2 \
    --others-ratio 0.6 \
    --output-dir ./results \
    --config ./evaluation_config.json \
    --generate-data
```

**参数说明：**
- `--model-type`: 模型类型 (uav_and_bird, Anti_UAV, UAV-250411)
- `--threshold`: 置信度阈值 (0.0-1.0)
- `--data-dir`: 测试数据目录
- `--sample-size`: 采样大小，None表示使用全部数据
- `--balanced-sampling`: 启用平衡采样
- `--bird-ratio`: 鸟类样本比例 (0.0-1.0)
- `--uav-ratio`: 无人机样本比例 (0.0-1.0)
- `--others-ratio`: 其他样本比例 (0.0-1.0)
- `--output-dir`: 输出目录
- `--config`: 配置文件路径
- `--generate-data`: 强制重新生成测试数据

**运行示例脚本：**
```bash
# 运行平衡采样示例
python example_balanced_evaluation.py
```

#### 完整参数列表

```bash
python run_evaluation.py --help
```

参数说明：
- `--config, -c`: 配置文件路径（默认：evaluation_config.json）
- `--data-dir, -d`: 测试数据目录（默认：Data）
- `--model-type, -m`: 模型类型（uav_and_bird/Anti_UAV/UAV-250411）
- `--threshold, -t`: 置信度阈值（默认：0.5）
- `--sample-size, -s`: 采样大小（None表示全部数据）
- `--generate-data, -g`: 强制重新生成测试数据
- `--output-dir, -o`: 输出目录（默认：evaluation_results）

## 配置文件

可以通过修改 `evaluation_config.json` 来自定义评估参数：

```json
{
    "evaluation_settings": {
        "model_type": "uav_and_bird",
        "confidence_threshold": 0.5,
        "iou_threshold": 0.5,
        "sample_size": null,
        "balanced_sampling": {
            "enabled": false,
            "bird_ratio": 0.2,
            "uav_ratio": 0.2,
            "others_ratio": 0.6,
            "description": "平衡采样配置：按指定比例抽取各类别样本"
        }
    },
    "data_settings": {
        "data_directory": "Data",
        "use_folder_structure": true,
        "annotation_file": null
    },
    "output_settings": {
        "output_directory": "evaluation_results",
        "generate_plots": true,
        "save_detailed_results": true
    }
}
```

### 平衡采样配置

平衡采样是一种重要的评估策略，可以确保各类别样本按指定比例分布，避免数据不平衡对评估结果的影响：

- **enabled**: 是否启用平衡采样
- **bird_ratio**: 鸟类样本比例（默认0.2，即20%）
- **uav_ratio**: 无人机样本比例（默认0.2，即20%）
- **others_ratio**: 其他样本比例（默认0.6，即60%）

**为什么使用平衡采样？**

1. **避免数据偏差**：如果某类样本过多，可能导致评估结果偏向该类别
2. **更真实的性能评估**：按实际应用场景的比例分布进行评估
3. **提高评估效率**：在有限的计算资源下获得更有代表性的结果
4. **便于对比分析**：不同模型在相同数据分布下的对比更公平

## 高级用法

### 编程接口

```python
from model_evaluator import ModelEvaluator

# 初始化评估器
evaluator = ModelEvaluator(
    model_type='uav_and_bird',
    threshold=0.5,
    iou_threshold=0.5
)

# 加载ground truth
ground_truth = evaluator.load_ground_truth_from_folder_structure('Data')

# 运行评估
metrics = evaluator.evaluate_dataset(ground_truth, sample_size=100)

# 生成报告
report_file = evaluator.generate_report(metrics, 'results')
plot_file = evaluator.plot_results(metrics, 'results')
```

### 自定义标注文件

如果有自定义的标注文件，格式应为：

```json
[
    {
        "image_path": "path/to/image1.jpg",
        "label": "uav",
        "bbox": [x, y, width, height]  // 可选
    },
    {
        "image_path": "path/to/image2.jpg",
        "label": "bird",
        "bbox": [x, y, width, height]  // 可选
    }
]
```

然后使用：

```python
ground_truth = evaluator.load_ground_truth_from_file('annotations.json')
```

## 评估指标详解

### 混淆矩阵（Confusion Matrix）

混淆矩阵是评估分类模型性能的基础，包含四个关键指标：

- **真正例（True Positive, TP）**：模型正确地将正样本（如UAV或鸟类）识别为正类的数量。
  - 例如：无人机被正确识别为无人机。

- **假正例（False Positive, FP）**：模型错误地将负样本识别为正类的数量，即**误报**。
  - 例如：其他物体被错误识别为无人机或鸟类。

- **假负例（False Negative, FN）**：模型错误地将正样本识别为负类的数量，即**漏报**。
  - 例如：无人机或鸟类未被识别出来。

- **真负例（True Negative, TN）**：模型正确地将负样本识别为负类的数量。
  - 例如：其他物体被正确识别为非无人机、非鸟类。

### 性能指标

#### 精确率（Precision）

精确率衡量模型预测为正类的样本中实际为正类的比例，反映了模型的**准确性**。

- **计算公式**：Precision = TP / (TP + FP)
- **含义**：在所有被模型识别为无人机/鸟类的检测结果中，真正是无人机/鸟类的比例。
- **重要性**：精确率高意味着误报少，适用于对误报敏感的场景。

#### 召回率（Recall）

召回率衡量模型能够正确识别出的实际正样本的比例，反映了模型的**完整性**。

- **计算公式**：Recall = TP / (TP + FN)
- **含义**：在所有实际的无人机/鸟类中，被模型正确识别出的比例。
- **重要性**：召回率高意味着漏报少，适用于对漏报敏感的场景。

#### F1分数（F1 Score）

F1分数是精确率和召回率的调和平均值，提供了模型性能的综合评价。

- **计算公式**：F1 = 2 * (Precision * Recall) / (Precision + Recall)
- **含义**：平衡考虑精确率和召回率的综合指标。
- **重要性**：当需要在精确率和召回率之间取得平衡时，F1分数是一个很好的指标。

#### 准确率（Accuracy）

准确率衡量模型正确预测的样本比例。

- **计算公式**：Accuracy = (TP + TN) / (TP + TN + FP + FN)
- **含义**：所有预测中正确预测的比例。
- **重要性**：提供整体性能的概览，但在类别不平衡时可能产生误导。

#### 误报率（False Positive Rate, FPR）

误报率衡量模型将负样本错误分类为正样本的比例。

- **计算公式**：FPR = FP / (FP + TN)
- **含义**：在所有实际的非目标物体中，被错误识别为目标的比例。
- **重要性**：在安防监控等场景中，低误报率至关重要，避免频繁的虚假警报。

#### 漏报率（False Negative Rate, FNR）

漏报率衡量模型将正样本错误分类为负样本的比例。

- **计算公式**：FNR = FN / (TP + FN)
- **含义**：在所有实际的目标物体中，未被识别出的比例。
- **重要性**：在安全关键应用中，低漏报率至关重要，确保不会遗漏重要目标。

### 按类别评估

对于多类别检测（如区分UAV和鸟类），系统会计算每个类别的单独指标：

- **类别精确率**：特定类别的精确率。
- **类别召回率**：特定类别的召回率。
- **类别F1分数**：特定类别的F1分数。

这些指标帮助分析模型对不同类别的识别能力，发现模型在特定类别上的优势和不足。

### 推理速度指标

#### 平均推理时间

- **计算方法**：所有图像的推理时间总和除以图像数量。
- **单位**：秒/图像。
- **含义**：处理单张图像平均需要的时间。

#### FPS（每秒帧数）

- **计算方法**：1除以平均推理时间。
- **单位**：帧/秒。
- **含义**：模型每秒能处理的图像数量，反映实时处理能力。

#### 总处理时间

- **计算方法**：所有图像的处理时间总和，包括预处理、推理和后处理。
- **单位**：秒。
- **含义**：评估整个数据集所需的总时间。

### IoU（交并比）

IoU是评估目标检测边界框准确性的关键指标。

- **计算公式**：IoU = (预测框与真实框的交集面积) / (预测框与真实框的并集面积)
- **取值范围**：0到1，值越大表示预测框与真实框重叠度越高。
- **阈值设置**：通常设置IoU阈值（如0.5）来判断检测是否正确。
- **重要性**：评估模型定位目标的精度，IoU高表示不仅检测出目标，而且定位准确。

### 实际应用场景中的指标意义

#### 在UAV检测中的应用

**高精确率的重要性**：
- 在机场安全监控中，误报会导致不必要的航班延误和资源浪费。
- 在军事应用中，误报可能引发错误的防御响应。
- 建议目标：精确率 > 90%

**高召回率的重要性**：
- 在边境监控中，漏报意味着潜在的安全威胁未被发现。
- 在禁飞区监控中，漏报可能导致安全事故。
- 建议目标：召回率 > 95%

#### 在鸟类检测中的应用

**生态保护场景**：
- 高召回率确保不遗漏珍稀鸟类的观测记录。
- 适度的精确率可以接受，因为误报的代价相对较低。

**机场鸟击防护**：
- 需要平衡精确率和召回率，既要避免误报导致的不必要干预，也要确保及时发现鸟类威胁。
- 建议目标：F1分数 > 85%

#### 推理速度的实际要求

**实时监控系统**：
- 视频监控：需要至少25-30 FPS以确保流畅的实时处理。
- 无人机巡逻：10-15 FPS通常足够，因为飞行速度相对较慢。

**批量处理系统**：
- 历史数据分析：推理速度要求较低，更注重准确性。
- 大规模数据集处理：需要考虑总处理时间和资源消耗。

### 指标权衡和优化建议

#### 精确率与召回率的权衡

**提高精确率的方法**：
- 提高置信度阈值（但可能降低召回率）
- 改进模型训练数据质量
- 使用更严格的后处理算法

**提高召回率的方法**：
- 降低置信度阈值（但可能降低精确率）
- 增加训练数据的多样性
- 使用数据增强技术

#### 速度与准确性的权衡

**提高推理速度**：
- 使用模型量化技术
- 优化输入图像分辨率
- 使用GPU加速
- 考虑使用轻量级模型架构

**保持准确性**：
- 在速度优化时监控性能指标变化
- 使用知识蒸馏技术
- 采用渐进式优化策略

### 评估结果解读指南

#### 优秀模型的指标范围

**UAV检测模型**：
- 精确率：85-95%
- 召回率：90-98%
- F1分数：87-96%
- 推理速度：>20 FPS（实时应用）

**鸟类检测模型**：
- 精确率：80-90%
- 召回率：85-95%
- F1分数：82-92%
- 推理速度：>15 FPS（实时应用）

#### 问题诊断

**高精确率，低召回率**：
- 问题：模型过于保守，漏报较多
- 解决方案：降低置信度阈值，增加训练数据

**低精确率，高召回率**：
- 问题：模型过于激进，误报较多
- 解决方案：提高置信度阈值，改进模型训练

**精确率和召回率都低**：
- 问题：模型性能整体较差
- 解决方案：重新训练模型，检查数据质量，调整模型架构

**推理速度慢**：
- 问题：无法满足实时应用需求
- 解决方案：模型优化，硬件升级，算法改进

## 输出结果

评估完成后，会在输出目录中生成：

1. **`evaluation_report_YYYYMMDD_HHMMSS.txt`** - 详细的文本报告
2. **`evaluation_plots_YYYYMMDD_HHMMSS.png`** - 可视化图表
3. **`detailed_results_YYYYMMDD_HHMMSS.json`** - 详细的JSON结果（如果启用）

### 报告内容

- 评估配置和参数
- 数据集统计信息
- 混淆矩阵
- 整体性能指标
- 按类别的性能指标
- 推理速度统计
- 错误分析

### 图表内容

- 混淆矩阵热图
- 性能指标柱状图
- 按类别的精确率/召回率对比
- 推理时间分布

## 故障排除

### 常见问题

1. **模型加载失败**
   - 检查模型文件是否存在
   - 确认ONNX Runtime已正确安装
   - 验证模型类型参数是否正确

2. **找不到测试数据**
   - 确认数据目录路径正确
   - 检查文件夹结构是否符合要求
   - 尝试使用 `--generate-data` 生成测试数据

3. **内存不足**
   - 使用 `--sample-size` 限制处理的图像数量
   - 减小图像分辨率
   - 关闭可视化功能

4. **推理速度慢**
   - 检查是否启用了GPU加速
   - 考虑使用较小的图像尺寸
   - 优化模型参数

### 调试模式

在代码中设置详细日志：

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

## 扩展功能

### 添加新的评估指标

在 `ModelEvaluator` 类中添加新的方法：

```python
def calculate_custom_metric(self, results):
    # 实现自定义指标计算
    pass
```

### 支持新的模型类型

在 `inference.py` 中添加新的模型处理逻辑，然后在评估器中引用。

### 自定义可视化

修改 `plot_results` 方法来添加新的图表类型。

## 性能优化建议

1. **批处理**: 对于大量图像，考虑实现批处理推理
2. **并行处理**: 使用多进程处理图像预处理
3. **缓存**: 缓存预处理结果以避免重复计算
4. **GPU加速**: 确保ONNX Runtime使用GPU提供程序

## 贡献

欢迎提交问题报告和功能请求。如果要贡献代码，请：

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 创建 Pull Request

## 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。