# 无人机检测 ONNX 模型推理工具

## 项目概述
基于ONNX Runtime的无人机目标检测解决方案，支持：
- GPU加速推理（需CUDA环境）
- 自适应图像预处理流水线（CPU/GPU双模式）
- 误报过滤机制（ORB特征匹配）
- 多格式检测报告生成（CSV/Excel）

## 项目结构
```
Model/
├── src/                    # 源代码目录
│   ├── core/              # 核心功能模块
│   │   ├── inference.py   # 推理主程序
│   │   ├── feature_extractor.py
│   │   └── image_validation.py
│   ├── utils/             # 工具函数
│   │   ├── visualizer.py  # 可视化工具
│   │   └── dataset.py     # 数据集工具
│   └── analysis/          # 分析工具
│       ├── hotspot_analyzer.py
│       └── report_generator.py
├── data/                  # 数据目录
│   ├── false_positive/   # 误报样本
│   └── models/           # 模型文件
├── tests/                # 测试目录
├── outputs/              # 输出目录
└── docs/                 # 文档目录
```

## 环境要求
- Python 3.8+ 
- CUDA环境（如需GPU加速）
- 依赖库：
```bash
pip install -r requirements.txt
```

## 快速开始

### 1. 安装依赖
```bash
pip install -r requirements.txt
```

### 2. 运行推理
在项目根目录下运行：

#### 使用图形界面（推荐）
```bash
python -m src.core.inference --gui
```

#### 单张图片检测
```bash
python -m src.core.inference --input 图片路径 --threshold 0.5 --output results --report excel
```

#### 批量检测目录
```bash
python -m src.core.inference --input 图片目录 --max-bbox-ratio 0.1 --output batch_results --report all
```

## 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|-------|-----|
| --input | path | 必填 | 输入图像路径/目录 |
| --threshold | float | 0.45 | 检测置信度阈值 |
| --max-bbox-ratio | float | 0.05 | 最大检测框面积比例 |
| --output | path | 自动生成 | 输出目录（自动创建） |
| --report | [csv/excel/all] | excel | 报告格式 |
| --save-empty | flag | False | 保存无检测结果的图像 |
| --gui | flag | False | 启用图形界面选择输入目录 |

## 结果输出
输出目录包含：
- `目标截图/`：检测到的无人机目标截图
- `检测报告.xlsx`：包含检测时间、置信度、坐标等详细信息
- 带检测框的标注图像

## 模型管理
- 模型文件位置：`data/models/UAV-250321.onnx`
- 模型版本通过文件名自动识别（如：UAV-250321.onnx 版本号为250321）

## 常见问题
Q: 如何启用GPU加速？
A: 确保安装onnxruntime-gpu并配置CUDA环境，程序会自动优先使用GPU

Q: 误报特征库如何更新？
A: 将误报样本放入data/false_positive目录，程序启动时会自动加载

## 开发指南
1. 代码规范
   - 遵循PEP 8编码规范
   - 使用类型注解
   - 编写单元测试

2. 测试
```bash
# 运行测试
pytest tests/

# 生成测试覆盖率报告
pytest --cov=src tests/
```

3. 文档
   - 使用Google风格文档字符串
   - 保持README.md更新
   - 重要功能添加使用示例

## 性能指标说明

### 1. 基础统计指标

- **总样本数**：CSV文件中所有唯一的图像文件数量
- **检测到的目标总数**：模型检测到的所有目标数量
- **真实目标总数（TP）**：确认的真实无人机目标数量
- **误报目标数（FP）**：错误检测为非无人机目标的数量
- **真阴性数量（TN）**：正确识别为非无人机目标的数量

### 2. 性能评估指标

- **准确率（Accuracy）**
  - 计算公式：`(TP + TN) / (TP + FP + TN)`
  - 说明：反映模型整体正确分类的能力，即正确预测的样本占总样本的比例
  - 取值范围：0-1，越接近1表示模型整体性能越好

- **精确率（Precision）**
  - 计算公式：`TP / (TP + FP)`
  - 说明：反映模型在预测为正样本（无人机）时的准确程度
  - 取值范围：0-1，越接近1表示模型在预测无人机时越准确

- **召回率（Recall）**
  - 计算公式：`TP / (TP + FN)`
  - 说明：反映模型发现所有真实无人机目标的能力
  - 取值范围：0-1，越接近1表示模型发现真实无人机的能力越强

- **F1分数（F1 Score）**
  - 计算公式：`2 * (Precision * Recall) / (Precision + Recall)`
  - 说明：精确率和召回率的调和平均数，用于平衡精确率和召回率
  - 取值范围：0-1，越接近1表示模型在精确率和召回率之间取得更好的平衡

- **误报率/虚警率（False Alarm Rate）**
  - 计算公式：`FP / (TN + FP)`
  - 说明：反映模型将非无人机目标错误识别为无人机的比例
  - 取值范围：0-1，越接近0表示模型在避免误报方面表现越好

## 使用方法

1. 运行推理：
```bash
python src/core/inference.py
```

2. 分析性能：
```bash
python src/analysis/performance_analyzer.py
```

## 输出说明

运行性能分析后，将在结果目录下生成`performance_stats.txt`文件，包含：
1. 详细统计信息（总样本数、检测目标数等）
2. 性能指标（准确率、精确率、召回率等）

## 注意事项

1. 确保模型文件路径正确
2. 确保输入图像格式正确
3. 性能分析前需要将确认的真实目标放入`targets_all_True`目录