A YOLOv8-based project for real-time traffic density estimation.

https://github.com/fanqingsong/YOLOv8_Traffic_Density_Estimation

https://docs.ultralytics.com/models/yolov8 

A YOLOv8-based project for real-time traffic density estimation. It employs fine-tuned vehicle detection models to analyze and count vehicles per frame, aiding urban traffic management and planning. The repository includes model training, traffic intensity analysis, and deployment strategies.

这是一个基于 YOLOv8 的实时交通密度估算项目，旨在通过视频帧中的车辆检测与计数，辅助城市交通管理与规划。

🚗 项目概述

该项目利用 YOLOv8 的实时检测能力，专注于交通密度估算。核心目标是准确统计视频帧中指定区域的车辆数量，以评估交通流量。这些数据有助于识别交通高峰期、瓶颈路段，并为城市规划提供支持。

项目不仅包含模型训练，还提供了完整的 Docker Compose 工作流，用于自动化下载数据集、准备数据、模型微调以及无头（headless）推理。

🎯 核心目标

项目实现了以下关键里程碑：

• 模型选择与评估： 选用预训练的 YOLOv8 模型，并评估其在 COCO 数据集上的车辆检测基线性能。
• 数据集构建： 整理并标注了一个专门的车辆数据集，以提升模型对各类车辆的检测精度。
• 模型微调： 应用迁移学习技术对 YOLOv8 模型进行微调，特别优化了从俯视角度检测车辆的能力，显著提升了精确率和召回率。
• 性能评估： 通过分析学习曲线、混淆矩阵和性能指标，确保模型的可靠性与泛化能力。
• 实时交通分析： 开发了算法，通过在测试视频上进行实时车辆计数和交通强度分析来量化交通密度。
• 跨平台部署： 将优化后的模型导出为 ONNX 格式，确保跨平台兼容性。

📚 数据集

项目使用了一个名为“Top-View Vehicle Detection Image Dataset for YOLOv8”的数据集，该数据集从俯视角度提供车辆行为和交通模式信息。

• 类别： 'Vehicle'（包含轿车、卡车和公交车）。
• 图片总数： 626 张。
• 图片尺寸： 640x640 像素。
• 数据划分： 训练集 536 张，验证集 90 张。
• 数据来源： 数据集从 Pexels 收集视频，并使用 Roboflow 以每秒 1 帧的速率提取图像。

🛠️ 技术栈与文件结构

项目采用模块化设计，主要技术栈和文件包括：

• 核心模型： YOLOv8
• 脚本 (scripts/)： 包含用于 Kaggle 数据下载、数据集准备、模型训练、模型量化（OpenVINO INT8）和交通分析的独立 Python 模块。
• Docker 化：
  • Dockerfile: 用于 CPU 推理。
  • Dockerfile.train: 用于 GPU 训练。
  • Dockerfile.quantize: 用于 CPU 上的 OpenVINO/NNCF 量化。
  • compose.yaml: 定义了下载、准备、训练、量化和推理等独立服务。
• 其他： 包含用于架构决策记录（ADR）的 docs/adr/ 目录和标准库单元测试 tests/。

🐳 运行方式

项目推荐使用 Docker Compose 运行，每个阶段都是一个独立的一次性服务。

训练流程 (需 Kaggle API 凭证)

1. 配置环境： 复制 .env.example 为 .env 并设置 KAGGLE_USERNAME 和 KAGGLE_KEY。
2. 下载数据： docker compose run --rm download-data
3. 准备数据： docker compose run --rm prepare-data
4. 开始训练 (GPU)： docker compose -f compose.yaml -f compose.gpu.yaml run --rm train
   • 训练完成后，权重文件将保存在 models/best.pt 和 models/best.onnx。

OpenVINO INT8 量化

在训练和数据准备完成后，运行以下命令进行量化和性能对比： docker compose run --rm --build quantize-model 该命令会导出 FP32 和 INT8 两种精度的 OpenVINO 模型，并生成包含 mAP、推理延迟、模型大小等指标的对比报告。

推理 (交通分析)

1. 准备文件： 将 models/best.pt 和 sample_video.mp4 放置在项目根目录。
2. 运行分析： docker compose run --rm --build traffic-analysis
3. 输出结果： 处理后的视频将保存在 output/processed_sample_video.avi。

🚀 本地运行

你也可以在本地环境中运行推理部分：

1. 安装依赖：pip install -r requirements.txt
2. 运行分析脚本：python -m scripts.traffic_analysis
   • 默认会显示视频窗口（按 q 键退出）。
   • 无头模式运行：DISPLAY_VIDEO=false python -m scripts.traffic_analysis

https://github.com/fanqingsong/PPE-Detection-YOLOv8

Overall (val split): mAP50 = 0.566 | mAP50-95 = 0.283 | Precision = 0.621 | Recall = 0.509

The pattern is consistent across every metric I looked at: classes with more training instances perform well (0.79–0.90 mAP50), classes with few instances perform poorly (no_boots had only 4 validation instances and 0.018 mAP50). This isn't a bug — it's the expected effect of class imbalance in the source dataset, and it's the single biggest lever for improving this model further (see Limitations).

A few things worth calling out:

• The well-represented classes (Person 0.88, no_helmet 0.76, boots 0.70, no_gloves 0.71) sit cleanly on the diagonal
• none (no PPE at all) is frequently confused with vest (0.21) and goggles (0.28) — plausible, since it's essentially a catch-all/ambiguous class
• A meaningful share of no_goggle (0.17) and no_gloves (0.21) predictions land in background — meaning the model often misses these rare violation classes entirely, rather than confusing them with something else. That's a recall problem tied directly to how few training examples those classes have.

混淆矩阵是评估分类模型（比如你提供的网页中提到的YOLOv8目标检测模型）性能的核心工具。简单来说，它通过一个表格，直观地展示了模型的预测结果与真实情况的对比，从而揭示出模型“对在哪里”以及“错在哪里”。

🎯 混淆矩阵的核心作用

混淆矩阵的主要作用是帮助你深入分析模型的预测表现，而不仅仅是看一个笼统的准确率。它能帮你回答以下关键问题：

• 模型擅长识别哪些类别？
• 模型容易把哪个类别错认成另一个类别？
• 模型是否经常漏掉某些特定的类别？

🔍 如何解读混淆矩阵

混淆矩阵是一个二维表格：

• 纵轴 (Y-axis) 代表样本的 真实类别 (True Label)。
• 横轴 (X-axis) 代表模型 预测的类别 (Predicted Label)。

矩阵中的每一个单元格 (i, j) 的数值，表示 真实类别为 i 的样本中，被模型预测为类别 j 的数量或比例。

• 对角线上的值：表示模型预测正确的样本。例如，真实是“头盔”也被预测为“头盔”。这个值越高越好。
• 非对角线上的值：表示模型预测错误的样本。例如，真实是“无头盔”但被预测成了“背景”。这些值揭示了模型的混淆模式。

📊 结合你提供的网页内容分析

在你提供的关于PPE（个人防护装备）检测的网页中，作者就使用了混淆矩阵来深入分析其YOLOv8模型的性能，并得出了非常具体的结论：

1. 识别模型的优势：

   • 网页中提到，像 Person (人)、no_helmet (无头盔)、boots (靴子) 这些类别的预测结果清晰地聚集在对角线上（例如 Person 的对角线值为0.88，no_helmet 为0.76）。
   • 这说明：模型对于这些训练数据充足的类别，识别得非常准确。

2. 发现模型的弱点：

   • 网页中指出，no_goggle (无护目镜) 和 no_gloves (无手套) 这两个类别的预测结果有相当一部分落在了 background (背景) 这一列（分别为0.17和0.21）。
   • 这说明：模型经常完全“漏检”这些违规类别，而不是将它们错认成其他装备。作者分析，这是因为训练数据中这些类别的样本太少（类别不平衡），导致模型学不好。

3. 分析类别间的混淆：

   • 网页中还提到，none (无任何PPE) 类别经常被混淆为 vest (反光背心) 和 goggles (护目镜)。
   • 这说明：模型在判断一个人是否穿了背心或戴了护目镜时，容易与什么都没穿的情况搞混，这可能是因为“什么都没穿”这个类别本身就比较模糊。

总而言之，混淆矩阵就像一个“诊断报告”，它不仅能告诉你模型的整体健康状况（准确率），还能精准定位到具体是哪个“器官”（类别）出了问题，以及问题的具体表现（是误诊还是漏诊），为后续的模型优化提供了明确的方向。

https://github.com/fanqingsong/Applied-AI-YOLO-Walkthrough

Step-by-step walkthrough for fine-tuning a YOLO11 object detector on a custom webcam dataset. Capture, label in Label Studio, visualize augmentations, train, and run live inference with object counts and on-screen time tracking.

这是一个关于如何微调 YOLO11 目标检测模型的 GitHub 项目指南。该项目提供了一个完整的端到端流程，用于训练一个能够识别自定义物体的模型，并通过网络摄像头进行实时推理。

以下是该指南的核心内容总结：

🎯 项目目标

该项目旨在指导用户完成从数据收集到模型部署的全过程，最终实现一个网络摄像头应用，该应用能够：

• 在画面中用边界框标出指定物体。
• 统计画面中物体的数量。
• 追踪每个类别的物体在屏幕上出现的总时长。

🛠️ 准备工作

• 硬件/软件：带摄像头的电脑、Python 3.9+、Git、Docker（用于运行标注工具 Label Studio）。
• 环境搭建：项目建议在 Python 虚拟环境中安装依赖，主要包括 ultralytics (YOLO库)、opencv-python 和 matplotlib。

📝 核心步骤

整个流程分为六个主要步骤：

1. 采集训练图像 (Capture)

   • 运行 scripts/capture.py 脚本，通过摄像头拍摄至少 30 张包含目标物体的照片。
   • 强调图像的多样性，需从不同角度、距离、光照和背景下进行采集。

2. 标注图像 (Label)

   • 使用开源工具 Label Studio 为采集的图像绘制边界框并指定类别。
   • 将标注结果以 "YOLO with Images" 格式导出。

3. 准备数据集 (Prepare)

   • 运行 scripts/prepare_dataset.py 脚本，将标注好的数据自动划分为训练集（80%）和验证集（20%），并生成 YOLO 所需的 dataset.yaml 配置文件。

4. 可视化数据增强 (Visualize Augmentations)

   • 运行 scripts/visualize_augmentations.py 脚本，生成一个 PDF 文件，直观展示 YOLO 在训练时会使用的各种数据增强技术（如旋转、翻转、色彩调整等）对图像的影响。

5. 训练模型 (Train)

   • 运行 scripts/train.py 脚本开始训练。默认使用 YOLO11n（nano）模型，训练 50 个周期（epochs）。
   • 训练完成后，最佳模型权重会保存在 runs/detect/run1/weights/best.pt。

6. 实时推理 (Live Inference)

   • 运行 scripts/live_inference.py 脚本，加载训练好的模型，开启摄像头进行实时物体检测，并在画面上显示计数和追踪时间。

📂 项目结构

项目结构清晰，主要脚本位于 scripts/ 目录下，数据、模型和运行结果会分别生成在 data/ 和 runs/ 目录中。