README.md

metadata

title: Computer Vison | Traffic Tracker
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

TrafficSense — Road Traffic Object Counting & Tracking

AIMS Senegal · Computer Vision Project 2 · April 2026

A real-time computer vision system for detecting, tracking, and counting road-traffic objects across multiple video scenes. Built with YOLOv8 + ByteTrack, deployed via FastAPI, with a live web dashboard.

---

Features

Feature	Details
Detection	YOLOv8n/s/m/l via Ultralytics — supports nano to large
Tracking	ByteTrack (built into Ultralytics) — persistent unique IDs
Classes	person, bicycle, car, motorbike, bus, truck
Counting	Virtual counting line — counts unique crossings + direction
Logging	JSONL detections, JSON summary, CSV frame stats per scene
Web UI	Upload video, select classes, view live annotated stream
Dashboard	Compare scenes, bar charts, timeline, global stats
CLI	Run without server for batch processing
Fine-tuning	Script to train on custom labeled dataset

---

Project Structure

traffic-tracker/
├── backend/
│   ├── main.py           # FastAPI REST + SSE server
│   ├── tracker.py        # YOLOv8 + ByteTrack engine
│   ├── run_tracker.py    # CLI: process video without server
│   ├── finetune.py       # Fine-tune on custom dataset
│   ├── extract_frames.py # Extract frames for labeling
│   └── requirements.txt
├── frontend/
│   └── index.html        # Full web interface (single file)
├── logs/                 # Auto-created: JSONL + JSON + CSV logs
├── uploads/              # Auto-created: uploaded videos
├── output/               # Auto-created: annotated output videos
└── README.md

---

Quick Start

1. Install dependencies

cd backend
pip install -r requirements.txt

GPU users: pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

2. Start the API server

cd backend
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

3. Open the web interface

Open frontend/index.html in your browser, or visit http://localhost:8000 (the server serves it automatically).

4. Analyse a video

1. Drop a traffic video into the upload zone
2. Give the scene a name (e.g. intersection_A)
3. Select classes to track
4. Choose model (YOLOv8n is fastest; YOLOv8s balances speed/accuracy)
5. Click START ANALYSIS
6. Watch the annotated live stream and live counters

---

CLI Usage (no server needed)

# Basic run (display window)
python run_tracker.py --video traffic.mp4 --scene roundabout_1 --show

# Save output video + logs
python run_tracker.py --video traffic.mp4 --scene highway_cam --classes car truck bus --save

# Custom confidence + model
python run_tracker.py --video traffic.mp4 --model yolov8m.pt --conf 0.45 --show --save

---

API Endpoints

Method	Endpoint	Description
POST	/upload	Upload video, start processing
GET	/stream/{sid}	SSE stream of annotated frames
GET	/status/{sid}	Processing progress + live stats
GET	/summary/{sid}	Final summary JSON
GET	/dashboard	Aggregated multi-scene stats
GET	/logs	List all saved log files
GET	/classes	Available traffic classes

---

Log File Schema (shared data format)

All groups must follow this schema for dashboard merging.

*_detections.jsonl — one JSON per line

{
  "frame":       1234,
  "timestamp":   41.13,
  "scene":       "intersection_A",
  "track_id":    7,
  "class":       "car",
  "confidence":  0.872,
  "bbox":        [120, 340, 280, 450],
  "center":      [200, 395],
  "crossed_line": true,
  "direction":   "down"
}

*_summary.json

{
  "scene":                "intersection_A",
  "session_id":           "abc123",
  "processed_at":         "2026-04-25T14:30:00",
  "total_frames":         1800,
  "duration_sec":         60.0,
  "fps":                  30.0,
  "resolution":           [1920, 1080],
  "selected_classes":     ["car", "bus", "truck", "person"],
  "total_unique_objects": 142,
  "count_per_class":      {"car": 98, "bus": 12, "truck": 17, "person": 15},
  "direction_counts":     {"car": {"up": 43, "down": 55}},
  "temporal_distribution": [
    {"bucket_10s": 0, "detections": 34},
    {"bucket_10s": 1, "detections": 51}
  ]
}

---

Fine-tuning on Custom Data

# 1. Extract frames from your traffic videos
python extract_frames.py --video traffic1.mp4 --out frames/ --every 10

# 2. Label with Roboflow (free) → export as YOLO format
#    https://roboflow.com

# 3. Fine-tune
python finetune.py --data dataset.yaml --model yolov8s.pt --epochs 50 --device 0

# 4. Use your fine-tuned model
python run_tracker.py --video test.mp4 --model runs/traffic/finetune/weights/best.pt

---

Video Sources

• Pexels Traffic Videos (free, no attribution required)
• Record your own: 1 min minimum, distinct scenes (intersection, roundabout, highway, urban)

---

Deliverables Checklist

• Detection model (YOLOv8 pre-trained)
• Fine-tuning script + instructions
• ByteTrack tracking with persistent IDs
• Virtual counting line + direction detection
• Unique object counting (not per-frame)
• Detailed detection logs (JSONL + JSON + CSV)
• Shared data schema across groups
• Web interface (upload, class selection, live display)
• Bounding boxes, labels, IDs, live counters
• "No object detected" indicator
• Multi-scene dashboard with comparisons
• GitHub-ready structure

Bonus features implemented

• Direction tracking (up/down crossing)
• Visual trail per tracked object
• Temporal traffic intensity chart
• Scene comparison table
• CSV frame statistics export

---

License

MIT — see LICENSE

---

Authors

AIMS Senegal — Computer Vision 2026