Shallow-dusty/Argus-YOLOv12-Crack
GitHub: Shallow-dusty/Argus-YOLOv12-Crack
一个基于YOLOv12n和EMA注意力改进的墙壁裂缝检测模型，用于提升小数据集上的检测精度和泛化性。
Stars: 0 | Forks: 0
# Argus YOLOv12 裂缝检测
[English](./README.en.md) · 中文
基于 YOLOv12n 的墙壁裂缝检测改进研究。在 YOLOv12n baseline 上进行候选模块横向筛选、EMA 深度消融及推荐配置稳健性验证，并在三个跨域数据集（Road Damage / Crack500 / DeepCrack）上观察泛化边界。
## 核心结果
数据集：wall_crack_v2_split（2366/295/297，单类裂痕，CC BY 4.0）。
| 口径 | 配置 | mAP50 |
|---|---|:---:|
| **推荐配置 · Kaggle n=3 mean ± std** | `YOLOv12n + EMA(P3+P4, factor=16)` | **0.73070 ± 0.00672** |
| 推荐配置 · RTX 3070 n=3 mean ± std | 同上 | 0.73689 ± 0.00400 |
| 跨平台一致性 · 同配置 / 同种子 | seed=0 | Δ = +0.063 pp |
| 单种子峰值（非主要推荐） | `YOLOv12n + EMA(P3+P4, factor=32), seed=0` | 0.74517 |
| 对照基线 | `YOLOv12n baseline` | 0.70561 |
完整数据见 [`docs/COMPARISON_TABLE.md`](./docs/COMPARISON_TABLE.md)。
## 项目结构
```
.
├── configs/ # 训练配置 YAML（baseline / 各模块 / 跨数据集对照）
├── models/ # YOLOv12n 结构 YAML 与改进变体
├── src/ # 训练入口与自定义模块
├── scripts/ # 数据集 setup、数值校验、可视化等工具
├── kaggle_kernels/ # Kaggle 自包含训练脚本（脱敏后模板）
├── web/ # FastAPI + React 可视化平台
├── docs/ # 命名口径 / 对比表 / 结果索引 / 复现步骤
└── prep/ # 基础知识补课材料
```
详细布局见 [`docs/PROJECT_STRUCTURE.md`](./docs/PROJECT_STRUCTURE.md)。
## 快速开始
```
# 1. 创建环境
conda create -n yolo python=3.10 -y
conda activate yolo
pip install ultralytics==8.4.21 opencv-python==4.13.0.92
# 2. 准备数据集（主数据 + Road Damage）
bash scripts/setup_datasets.sh
# 3. 训练推荐配置
python src/train.py --config configs/ema-p34-factor16.yaml
# 4. 评估 test split
python scripts/evaluate_test_split.py --preset paper-core
# 5. 用 results.csv 自动验证所有数值声称
python scripts/verify_paper_claims.py
```
完整复现指南见 [`docs/REPRODUCE.md`](./docs/REPRODUCE.md)。
## 预训练权重
推荐配置的预训练 `best.pt` 已发布在 Hugging Face：
**https://huggingface.co/ShallowDusty/argus-yolov12-crack**
```
from huggingface_hub import hf_hub_download
from ultralytics import YOLO
weights = hf_hub_download(
repo_id="ShallowDusty/argus-yolov12-crack",
filename="kaggle/ema-p34-factor16-seed0.pt",
)
model = YOLO(weights)
```
仓库内含 Kaggle n=3 / RTX 3070 n=3 / 跨域 T6 / 基线对照共 10 份权重。
## Web 演示
项目附带 FastAPI + React 可视化平台 (`web/`)，可在浏览器中：
- 现场推理对比 baseline 与推荐配置
- 浏览 T1–T6 实验证据表
- 查看 EMA 消融矩阵、推荐配置 n=3 稳健性、test split 与跨域压力测试
```
# 后端
PYTHONPATH=web/backend conda run -n yolo \
uvicorn app.main:app --host 127.0.0.1 --port 8000
# 前端
cd web/frontend && npm install && npm run dev -- --host 0.0.0.0
```
打开 http://127.0.0.1:5173。部署模板见 [`web/README.md`](./web/README.md)。
## 数据集与许可
| 数据集 | 来源 | 许可 |
|---|---|---|
| `wall_crack_v2_split`（主要数据） | Roboflow Universe (`athena-cheung-sftri/wall-crack-3`) | CC BY 4.0 |
| Road Damage Dataset (RDD2022) | Maeda et al. / sekilab/RoadDamageDetector | CC BY 4.0 |
| Crack500（可选 T6） | Yang et al. 2019, FPHBN, Temple University | 学术公开 |
| DeepCrack（可选 T6） | Zou et al. 2019 | 学术公开 |
Crack500 与 DeepCrack 是分割数据集，本仓库不自动转换；如需复现 T6 的 mask→bbox 流程，请自行处理。
## 局限性
- 推荐配置在主要数据上的提升幅度为 +2~+3 pp（mAP50），这是单类小数据集（< 3000 张）下的结论。
- 跨域压力测试（T6）的模型排序不稳定，**不**构成 EMA 跨数据集优越性的证据。
- 复杂度评估（参数量 / 浮点运算量 / FPS）不在本仓库主结论范围内。
- 本仓库侧重 YOLOv12n 在墙壁裂缝单类小数据集上的模块改进与稳健性验证；不包含模型推理延迟/部署优化等工程评估。
- 完整论文 PDF 不在本仓库发布。
## 引用
```
@software{argus_yolov12_crack_2026,
author = {Shallow},
title = {{Argus YOLOv12 Crack: Wall Crack Detection with YOLOv12n + EMA Attention}},
year = {2026},
url = {https://github.com/Shallow-dusty/Argus-YOLOv12-Crack},
license = {MIT}
}
```
亦可使用 GitHub 的 "Cite this repository" 按钮（基于 [`CITATION.cff`](./CITATION.cff)）。
## 致谢
- [Ultralytics YOLO](https://github.com/ultralytics/ultralytics) 训练/推理框架
- EMA / ECA / CA / SimAM / CBAM 各原模块作者
- Roboflow Universe 数据集贡献者
- sekilab/RoadDamageDetector 团队
## 许可
[MIT License](./LICENSE) © 2026 Shallow
标签：AV绕过, EMA注意力机制, FastAPI, Kaggle, Python, React, SEO优化, Syscalls, Ultralytics, YOLOv12n, 墙壁裂缝检测, 工程输出, 建筑维护, 技术栈, 数据集处理, 无后门, 模型改进, 泛化验证, 注意力模块, 消融研究, 深度学习, 特征金字塔网络, 目标检测, 研究项目, 缺陷检测, 计算机视觉, 训练配置, 论文阶段, 评估指标, 跨域数据集, 逆向工具