Traffic Violation Detector (YOLOv8)

REST API на YOLOv8m для детекции участников дорожного движения и состояния светофора (9 классов) на видео — для автоматизации контроля нарушений (проезд на красный) в системах видеонаблюдения.

---

Business Problem

Ручной просмотр записей с камер для фиксации проезда на красный свет занимает часы человеко-времени на каждый перекрёсток. Автоматическая детекция транспорта и состояния светофора на видео позволяет находить кадры-кандидаты на нарушение без непрерывного наблюдения оператора — модель выделяет только кадры, где есть машина/мотоцикл рядом с красным сигналом, а не весь поток видео.

---

Demo

curl -X POST "http://127.0.0.1:8000/detect/video" \
  -H "accept: application/json" \
  -F "file=@intersection.mp4"

Response (сокращённо):

{
  "status": "success",
  "filename": "intersection.mp4",
  "total_frames_processed": 145,
  "frames_with_detections": 62,
  "detections": [
    {
      "frame": 20,
      "detections": [
        {
          "class": "red_light",
          "confidence": 0.91,
          "bbox": {"x1": 340, "y1": 120, "x2": 380, "y2": 210}
        },
        {
          "class": "car",
          "confidence": 0.87,
          "bbox": {"x1": 100, "y1": 300, "x2": 260, "y2": 420}
        }
      ]
    }
  ],
  "preview_frame_base64": "..."
}

Классы (9): bus · car · green_light · motorcycle · red_light · truck · van · vehicle · yellow_light

---

Results

Метрика (валидация, imgsz=832)	Значение
mAP50 (Box)	63.2%
mAP50-95 (Box)	52.0%
Precision	68.0%
Recall	75.2%

По классам (mAP50):

Класс	mAP50	Комментарий
yellow_light	98.5%	отлично
green_light	97.7%	отлично
red_light	95.1%	отлично — ключевой класс для нарушений
motorcycle	89.0%	хорошо
bus	56.7%	средне
truck	55.3%	средне
vehicle	34.6%	слабо — размытый класс-корзина
van	22.4%	слабо — мало примеров, путается с car
car	19.7%	слабо — всего 12 инстансов в валидации

Светофоры распознаются почти идеально (>95%), что критично для детекции самого нарушения. Транспортные средства — хуже, особенно car и van: в датасете всего 9 и 41 изображение соответственно (дисбаланс классов), плюс vehicle — общий класс, который пересекается по смыслу с car/truck/van.

---

Dataset

• Источник: Roboflow, workspace yolov8-crime-detection, проект traffic-red-light-violation (2101 train / 595 valid изображений)
• Классы: bus, car, green_light, motorcycle, red_light, truck, van, vehicle, yellow_light
• Формат: YOLOv8 (bbox в relative x,y,w,h)

---

Approach

1. Базовое обучение — YOLOv8m (предобученный на COCO), 100 эпох, imgsz=640, batch=16, ранняя остановка (patience=20, остановлено на эпохе 87, лучший результат — эпоха 67)
2. Аугментации — HSV jitter, повороты (±5°), сдвиг, зум, mosaic (1.0), mixup (0.1), copy-paste (0.1), горизонтальный флип (0.5), почти без вертикального (0.01 — машины не летают)
3. Оптимизатор — AdamW (lr0=0.001, cosine LR schedule), weight_decay=0.0005, mixed precision (amp=True)
4. Fine-tune — дообучение лучшей модели: 30 эпох, увеличенное разрешение imgsz=832 (для мелких объектов вроде светофоров), заморожены первые 10 слоёв backbone, сниженный LR (0.0001), меньше аугментаций (mosaic=0.5, mixup=0.05)
5. Финальная валидация — на imgsz=832, conf=0.25, iou=0.5
6. Inference API — FastAPI-эндпоинт /detect/video обрабатывает видео покадрово (каждый 10-й кадр, conf=0.25, iou=0.45), рисует bbox через OpenCV, возвращает JSON с детекциями + превью первого кадра с обнаружением (base64)

---

Key Challenges & Solutions

Сильный дисбаланс классов транспорта car (12 инстансов в валидации) и van (44) на порядок реже, чем green_light/red_light/yellow_light (по 100) → mAP50 для car всего 19.7% против >95% у светофоров — модель просто не видела достаточно примеров этих классов для уверенной генерализации; дальнейшее улучшение требует расширения датасета именно по редким классам, а не общей дообучения.

Обработка длинного видео целиком — избыточная нагрузка Прогон YOLO на каждом кадре видео (25-30 fps) создаёт огромную вычислительную нагрузку и объём данных на выходе → в main.py обработка идёт с шагом frame_idx % 10 == 0 (каждый 10-й кадр) — компромисс между полнотой детекции и скоростью обработки.

Двухэтапное обучение (640px → 832px) для мелких объектов Светофоры занимают маленькую площадь кадра при стандартном разрешении 640px → базовое обучение на 640px для общей сходимости, затем fine-tune на 832px с заморозкой backbone (freeze=10) и низким LR — дообучение головы под более высокое разрешение без разрушения уже выученных признаков.

---

Tech Stack

Category	Tools
Язык	Python 3.12
ML	Ultralytics YOLOv8m
Видео	OpenCV
API	FastAPI, Uvicorn
Данные	Roboflow
Обучение	Google Colab (T4 GPU)

---

How to Run

# 1. Клонировать и установить зависимости
git clone https://github.com/your-username/traffic-violation-detector
cd TrafficViolationDetector
pip install ultralytics fastapi uvicorn opencv-python torch

# 2. Обучение — Google Colab (TrafficViolationDetector_YOLOv8.ipynb)
# сохраняет TrafficViolationDetector.pt

# 3. Запуск API
python main.py
# или: uvicorn main:app --host 0.0.0.0 --port 8000
# Docs: http://127.0.0.1:8000/docs

---

Business Impact

• Автоматическая предфильтрация видео с камер — оператор смотрит только кадры с детекциями, а не весь поток
• REST API принимает видео напрямую (mp4, avi, mov, mkv) — готов к интеграции с системами видеонаблюдения на перекрёстках
• Высокая точность распознавания сигналов светофора (>95% mAP50) делает модель пригодной как первый фильтр для дальнейшего ручного подтверждения нарушения

---

Структура проекта:

cv_TrafficViolationDetector/
├── .gitignore
├── readme.md
└── TrafficViolationDetector/
    ├── TrafficViolationDetector.pt
    ├── TrafficViolationDetector_YOLOv8.ipynb
    └── main.py

---