---
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.

![License](https://img.shields.io/badge/license-MIT-blue)
![Python](https://img.shields.io/badge/python-3.10%2B-green)
![YOLO](https://img.shields.io/badge/model-YOLOv8-red)

---

## 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

```bash
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

```bash
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)

```bash
# 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

```json
{
  "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`

```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

```bash
# 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](https://www.pexels.com/search/videos/traffic/) (free, no attribution required)
- Record your own: 1 min minimum, distinct scenes (intersection, roundabout, highway, urban)

---

## Deliverables Checklist

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

### Bonus features implemented
- [x] Direction tracking (up/down crossing)
- [x] Visual trail per tracked object
- [x] Temporal traffic intensity chart
- [x] Scene comparison table
- [x] CSV frame statistics export

---

## License

MIT — see [LICENSE](LICENSE)

---

## Authors

*AIMS Senegal — Computer Vision 2026*