本项目来自无人机巡检实习中的太阳能板检测任务，目标不只是训练一个检测器，而是形成一条可以复核的工程流程：
- 将 Roboflow/YOLOv8 标注可靠地转换为 MMYOLO 使用的 COCO 格式；
- 基于 YOLOv8-s 完成单类别太阳能板检测、微调与验证；
- 在固定测试集和外部场景上分别评估，定位跨来源数据的泛化问题；
- 自动整理误检、漏检和重复框，辅助 badcase 复核；
- 为 DJI 平台量化准备类别、输入尺寸、NMS 参数和配置快照。
仓库只公开代码、配置模板和实验结论，不包含私有影像、模型权重、标注文件、量化图片或内部文档。
| 模型与评估场景 | mAP50-95 | mAP50 | mAP75 | 结论 |
|---|---|---|---|---|
| 主模型 / 固定测试集 | 约 0.977 | 1.000 | 约 0.989 | 当前最稳定的项目基线 |
| 小数据集微调模型 / 对应 test | 0.285 | 0.663 | 0.229 | 对该小数据集有适配收益 |
| 小数据集微调模型 / 新外部 test | 0.011 | 0.092 | 0.000 | 跨场景泛化明显不足 |
| 小数据集微调模型 / 新外部 valid | 0.039 | 0.065 | 0.051 | 数据风格与标注口径存在偏移 |
这些数值来自不同数据划分，不能作为严格的同测试集模型排名。主模型权重由项目协作方提供；本仓库没有将其训练过程描述为个人独立完成。公开结论重点是评估、适配、badcase 分析和工程交付。
flowchart LR
A["UAV RGB images<br/>YOLO annotations"] --> B["Dataset audit"]
B --> C["YOLO to COCO conversion"]
C --> D["COCO integrity validation"]
D --> E["YOLOv8-s / MMYOLO"]
E --> F["Fixed-split evaluation"]
E --> G["External-scene evaluation"]
F --> H["FP / FN / duplicate analysis"]
G --> H
H --> I["DJI quantization handoff"]
- 数据转换不是简单改扩展名：脚本会解析标准
data.yaml、检查类别编号、归一化坐标和异常标注，并输出每个 split 的统计。 - 新增 COCO 完整性校验：检查 ID 唯一性、图片与标注引用、类别引用、边界框面积及越界情况。
- 将固定测试集和外部测试集分开报告，避免用不同验证集的 mAP 制造虚假的直接提升。
- badcase 工具兼容字典和 MMEngine/MMDetection 数据对象，自动统计 FP、FN 和最高误检置信度。
- 轻量 CI 不安装完整 CUDA 训练栈，仍会执行语法检查、单元测试和 JSON 校验。
- DJI 量化配置明确区分 2K 与 4K 模型宽度约束，不公开权重和标定图片。
.
├── .github/workflows/quality.yml # 轻量自动质量检查
├── assets/metrics_overview.svg # 不含私有影像的成果图
├── configs/
│ ├── algorithm_params.json # 类别、输入尺寸与检测后处理参数
│ ├── dji_yolov8_s_*_finetune.py # MMYOLO 微调配置
│ └── dji_yolov8_s_*_test.py # MMYOLO 测试配置
├── docs/ # 工作流、模型卡和 DJI 交付说明
├── reports/ # 指标口径与 badcase 结论
├── scripts/
│ ├── yolo_to_coco.py # YOLO → COCO
│ ├── validate_coco.py # COCO 完整性检查
│ └── make_badcase_notes_from_pkl.py # FP/FN 复核表生成
├── tests/ # 合成数据单元测试
├── requirements.txt # 历史完整实验环境快照
└── requirements-dev.txt # 数据工具与测试的轻量依赖
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt将 Roboflow/YOLOv8 数据转换为 COCO：
python scripts\yolo_to_coco.py `
--root D:\path\to\solar_panel_dataset `
--splits train valid test `
--strict验证生成的标注：
python scripts\validate_coco.py `
D:\path\to\solar_panel_dataset\annotations\train_coco.json `
D:\path\to\solar_panel_dataset\annotations\valid_coco.json `
D:\path\to\solar_panel_dataset\annotations\test_coco.json完整训练依赖对 CUDA 和 OpenMMLab 版本较敏感。requirements.txt 记录历史环境，建议按照 MMYOLO v0.6.0 安装文档 使用 OpenMIM 安装匹配版本。
配置文件使用 MMYOLO 官方 YOLOv8-s 配置作为相对基类，因此先复制到 MMYOLO 的 configs/yolov8/：
Copy-Item .\configs\dji_yolov8_s_solar_panel_*.py D:\mmyolo_dji\configs\yolov8\在复制后的配置中设置 data_root 和 load_from，再运行：
Set-Location D:\mmyolo_dji
conda run --live-stream -n dji-mmyolo python tools\train.py `
configs\yolov8\dji_yolov8_s_solar_panel_finetune.py `
--work-dir work_dirs\dji_yolov8_s_solar_panel_finetune测试、可视化和 badcase 分析的完整命令见 复现工作流。
当前公开配置对应可见光、2K、widen_factor=0.5 的 YOLOv8-s 单类别模型。DJI 交付包通常包含权重、500–1000 张代表性标定图片、类别文件、检测参数和训练配置快照；这些私有材料不进入本仓库。详见 DJI 量化说明。
- 原始数据、标注、权重和逐图预测未公开，因此仓库不能独立复算历史 mAP。
- 三组主要结果来自不同评估集，只能用于说明稳定性与域偏移，不能直接当作同集消融实验。
- 主模型是协作方提供的项目基线，个人工作集中在评估、微调、数据转换、badcase 和量化交付。
- DJI 端量化后仍应进行 FP32 与量化模型的一致性验证。
This repository documents an internship project for detecting solar panels in UAV RGB imagery with YOLOv8-s and MMYOLO. It covers robust YOLO-to-COCO conversion, annotation validation, fixed-split and cross-domain evaluation, automated FP/FN review, and DJI quantization handoff preparation.
The strongest project baseline achieved approximately 0.977 mAP50-95 on its fixed test split. A later small-dataset fine-tune reached 0.285 mAP50-95 on its matching test split but only 0.011 on a new external test set, highlighting substantial domain shift. These values come from different splits and are intentionally not presented as a direct leaderboard.
See workflow, evaluation report, model card, and known limitations for reproducibility boundaries.