Spaces:
Sleeping
Sleeping
| 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 | |
| ```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* | |