R360-UAVmodelTool/README.md

无人机检测 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加速）

• 依赖库：

  pip install -r requirements.txt
  

  快速开始

  1. 安装依赖

  pip install -r requirements.txt
  

2. 运行推理

在项目根目录下运行：

使用图形界面（推荐）

python -m src.core.inference --gui

单张图片检测

python -m src.core.inference --input 图片路径 --threshold 0.5 --output results --report excel

批量检测目录

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

1. 分析性能： bash python src/analysis/performance_analyzer.py ## 输出说明 运行性能分析后，将在结果目录下生成performance_stats.txt文件，包含： 1. 详细统计信息（总样本数、检测目标数等） 2. 性能指标（准确率、精确率、召回率等） ## 注意事项 1. 确保模型文件路径正确 2. 确保输入图像格式正确 3. 性能分析前需要将确认的真实目标放入targets_all_True目录