title	Traffic Tracking Analytics
emoji	🚗
colorFrom	blue
colorTo	indigo
sdk	gradio
sdk_version	5.25.0
app_file	app.py
pinned	false
license	mit
short_description	YOLOv8 + ByteTrack vehicle detection, tracking & analytics

Multi-Object Traffic Tracking & Analytics

A production-grade traffic analysis system that detects vehicles and pedestrians using YOLOv8, tracks them across frames with ByteTrack, computes real-time analytics (vehicle count, speed estimation, traffic density heatmap), and serves everything through a FastAPI backend with an interactive Streamlit dashboard.

---

Demo

YOLOv8n + ByteTrack live on UK motorway footage — 6 s clip, 12 fps. Track IDs persist through partial occlusions; trajectory tails show last 30 frames.

---

Sample Output

Multi-lane vehicle detection and tracking — UK motorway, dusk, 2560×1440

Frame 1	Frame 2

Green boxes = cars · Orange = trucks · Blue = motorcycles · Labels show track ID and confidence

Traffic density heatmap (60 s clip, decay = 0.98):

Hot spots correspond to the main travel lanes; the hard shoulder stays cold.

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        INPUT                                    │
│          Video file (MP4/AVI/MOV) or RTSP stream                │
└───────────────────────────┬─────────────────────────────────────┘
                            │ BGR frames (2560×1440)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  DETECTION  —  src/detection/detector.py                        │
│                                                                 │
│  YOLOv8n (COCO pretrained)                                      │
│  • Letterbox-resize → 640×640                                   │
│  • Single-shot inference + NMS                                  │
│  • Class filter: person, bicycle, car, motorcycle, bus, truck   │
│  • Output: List[Detection(bbox, confidence, class)]             │
└───────────────────────────┬─────────────────────────────────────┘
                            │ N detections per frame
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  TRACKING  —  src/tracking/byte_tracker.py                      │
│                                                                 │
│  ByteTrack (two-stage IoU matching)                             │
│  • Kalman filter predicts position during occlusion             │
│  • Stage 1: high-conf dets → all tracks   (thresh = 0.4 IoU)   │
│  • Stage 2: low-conf dets  → unmatched tracks                   │
│  • States: TENTATIVE (< 3 hits) → CONFIRMED → LOST → deleted   │
│  • Output: List[Track(id, class, bbox, trajectory, state)]      │
└──────────────┬────────────────────────────────┬─────────────────┘
               │ confirmed tracks               │
       ┌───────▼──────────┐           ┌─────────▼────────────────┐
       │  COUNTING        │           │  SPEED ESTIMATION        │
       │  counter.py      │           │  speed.py                │
       │                  │           │                          │
       │  Virtual lines   │           │  Pixel displacement      │
       │  Cross-product   │           │  × px/m constant         │
       │  direction check │           │  ÷ Δt (fps)              │
       │  Counted-IDs set │           │  5-frame smoothing window │
       └───────┬──────────┘           └─────────┬────────────────┘
               │                               │
       ┌───────▼──────────────────────────────▼─────────────────┐
       │  HEATMAP GENERATOR  —  heatmap.py                      │
       │                                                        │
       │  64×48 accumulation grid, exponential decay (α = 0.98) │
       │  Mapped to hot colormap and overlaid on frame          │
       └───────────────────────────┬────────────────────────────┘
                                   │ annotated frames + metrics
                    ┌──────────────▼──────────────────────────────┐
                    │  SERVING                                     │
                    │                                              │
                    │  FastAPI  :8000  — REST API (upload → JSON)  │
                    │  Streamlit :8501 — Live dashboard            │
                    └──────────────────────────────────────────────┘

---

Results

Benchmarked on a 60-second UK motorway clip, 2560×1440 @ 30 fps.

Metric	Value
Processing FPS — GTX 1650 (GPU)	~45 fps
Processing FPS — CPU (no GPU)	17.4 fps
ms / frame — GPU	~22 ms
ms / frame — CPU	57.3 ms
Source video resolution	2560 × 1440
YOLO input size (letterboxed)	640 × 640
Tracks in 60 s clip	~80 unique IDs
Avg vehicles visible per frame	12–18

Note on GPU FPS: The Docker image ships with a CPU-only PyTorch wheel. To use the GTX 1650, run with docker-compose --profile gpu up and ensure the image is rebuilt with a CUDA 12.x-compatible torch wheel (pip install torch --index-url https://download.pytorch.org/whl/cu124). The ~45 fps GPU figure is derived from published YOLOv8n benchmarks for the GTX 1650 tier; run scripts/benchmark.py with CUDA enabled to measure it precisely on your setup.

---

Quick Start

Option 1: Docker (CPU)

docker-compose up --build
# API:       http://localhost:8000/docs
# Dashboard: http://localhost:8501

Option 2: Docker (GPU — GTX 1650 / any NVIDIA)

# Requires: NVIDIA Container Toolkit
docker-compose --profile gpu up --build

Option 3: Local

conda create -n traffic-track python=3.10 -y
conda activate traffic-track
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

# Run full pipeline on a video
python scripts/run_pipeline.py --video assets/sample_videos/traffic.mp4 --output results/

# API server
uvicorn src.api.main:app --reload --port 8000

# Dashboard (separate terminal)
streamlit run src/dashboard/app.py

---

Project Structure

traffic-tracking-analytics/
├── README.md
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .flake8
├── .github/
│   └── workflows/
│       └── ci.yml               # pytest + flake8 on every push; Docker smoke test on main
├── configs/
│   ├── detector.yaml            # YOLOv8 model, confidence / IoU thresholds, target classes
│   ├── tracker.yaml             # ByteTrack parameters
│   └── analytics.yaml           # Counting lines, speed calibration, heatmap settings
├── src/
│   ├── detection/
│   │   ├── detector.py          # YOLOv8 wrapper — class filtering, batch inference
│   │   └── model_utils.py       # Model loading, benchmarking helpers
│   ├── tracking/
│   │   ├── byte_tracker.py      # Two-stage ByteTrack with Kalman IoU matching
│   │   ├── track.py             # Track dataclass — state machine + Kalman filter
│   │   ├── kalman_filter.py     # Constant-velocity Kalman (8-D state, 4-D measurement)
│   │   └── trajectory.py        # Trajectory storage and smoothing
│   ├── analytics/
│   │   ├── counter.py           # Virtual-line crossing counter (cross-product method)
│   │   ├── speed.py             # Speed estimation from pixel displacement
│   │   ├── heatmap.py           # Exponential-decay traffic density heatmap
│   │   └── zone.py              # Zone-based occupancy tracking (optional)
│   ├── api/
│   │   ├── main.py              # FastAPI app — lifespan, endpoints, pipeline orchestration
│   │   └── schemas.py           # Pydantic request/response models
│   └── dashboard/
│       └── app.py               # Streamlit dashboard — tabs: overview, timeline, classes, heatmap
├── scripts/
│   ├── run_pipeline.py          # CLI entry point for offline video processing
│   ├── download_sample.py       # Download sample traffic videos
│   └── benchmark.py             # FPS and latency benchmarking
├── tests/
│   ├── test_detector.py         # 20 tests — class filtering, thresholds, batch, mock YOLO
│   ├── test_tracker.py          # 34 tests — lifecycle, Kalman, two-stage matching
│   ├── test_counter.py          # 37 tests — crossing, direction, double-count prevention
│   ├── test_speed.py            # 20 tests — pixel→km/h conversion, smoothing, cap
│   ├── test_heatmap.py          # 27 tests — grid shape, decay, render, overlay, reset
│   └── test_api.py              # 9 tests  — FastAPI endpoints, schema validation
├── assets/
│   ├── demo.gif                 # 6-second animated demo (720p, 12fps)
│   ├── test_detection_001.jpg   # Sample annotated frame (cars, trucks)
│   ├── test_detection_002.jpg
│   ├── test_detection_003.jpg
│   ├── test_detection_004.jpg
│   └── test_detection_005.jpg
└── results/
    ├── traffic_tracked.mp4      # Full annotated output video (60 s, 2560×1440)
    └── traffic_heatmap.png      # 60-second density heatmap

---

Tech Stack

Layer	Technology
Detection	YOLOv8n (Ultralytics), pretrained on COCO
Tracking	ByteTrack + constant-velocity Kalman filter
Analytics	NumPy, OpenCV
API	FastAPI, Pydantic, uvicorn
Dashboard	Streamlit, Plotly
Deployment	Docker, docker-compose (CPU + GPU profiles)
CI	GitHub Actions — pytest, flake8, Docker smoke test
Video I/O	OpenCV, ffmpeg

---

Limitations

Speed estimation requires a near-overhead camera

The estimator converts pixel displacement to km/h using a fixed pixels_per_meter constant (configs/analytics.yaml). This is only a valid approximation when the camera is mounted directly above the road. For side-angle footage like the sample clip, perspective distortion means distant vehicles travel fewer pixels per metre than nearby ones — the estimator will under-report speed for far objects and over-report for close ones. A 4-point homography calibration would reduce the error for moderate angles (~45°+), but shallow-angle cameras (< 30° elevation) violate the ground-plane assumption entirely. Treat speed figures from non-overhead footage as indicative only.

Camera calibration is a prerequisite for reliable metrics

Without a measured pixels_per_meter value from a real calibration target in the scene, all speed and distance figures are estimates. To calibrate:

1. Place two markers of known distance (e.g., lane markings are typically 3 m apart in the UK) in the camera's field of view.
2. Measure the pixel distance between them in a representative frame.
3. Set pixels_per_meter in configs/analytics.yaml to pixel_distance / real_distance.
4. For perspective correction, run scripts/calibrate_perspective.py with four ground-plane control points to compute a homography matrix.

Tracking failures in dense traffic

ByteTrack assigns each detection an ID across frames, but three scenarios cause consistent failures on dense motorway footage:

• Occlusion cascades. When three or more vehicles overlap simultaneously (e.g., a truck overtaking two cars in adjacent lanes), the Kalman-predicted bounding boxes of the inner vehicles shrink in apparent size and may no longer overlap with any detection. All three tracks go to LOST simultaneously, and when the vehicles separate the tracker spawns three new IDs — inflating the total count.

• ID switching on lane changes. A vehicle changing lanes crosses the predicted trajectory of an adjacent vehicle. If their bounding boxes overlap even briefly (IoU > 0.4), the Hungarian algorithm may swap their IDs at that frame. The swap is usually permanent because the Kalman filters have already adopted each other's velocity. The 5-frame speed smoothing window partially masks the resulting speed spike but does not eliminate it.

• Missed detections at frame edges. Vehicles partially outside the frame have smaller visible bounding boxes with lower YOLO confidence, often falling below the 0.35 confidence threshold. They are detected intermittently, causing rapid TENTATIVE → (miss) → new TENTATIVE → CONFIRMED cycles that generate spurious counts on edge-crossing virtual lines.

Upgrading from yolov8n to yolov8s or yolov8m in configs/detector.yaml improves recall for partially-visible and occluded vehicles at the cost of throughput (roughly −30 fps per model size step on the GTX 1650).

YOLOv8n accuracy trade-off

The pipeline uses the nano YOLO model for speed. On the sample motorway clip, the nano model misses roughly 1 in 8 vehicles in the far lane (small apparent size, low contrast at dusk). Switching to yolov8s.pt recovers most of these detections with approximately 2× the inference time.

---

What I Learned

Kalman filters are what make tracking feel "real". Without Kalman prediction, IoU matching fails the moment a vehicle is partially occluded — the bounding box shrinks and IoU with any detection drops below the threshold. Once I added prediction-based matching (using track.predicted_bbox instead of track.bbox for IoU), the tracker bridged 10–15 frame gaps through bridge pillars and lane changes without dropping IDs. The constant-velocity model is the simplest thing that works; it is also usually enough.

ByteTrack's two-stage design solves a real problem. The standard approach — throw away low-confidence detections — loses heavily-occluded vehicles exactly when you most need to keep their IDs. Stage 2 catches those low-confidence detections and routes them only to tracks that are already unmatched, so they cannot pollute freshly-created tracks. Implementing this from scratch made the design obvious in a way that just reading the paper did not.

Building a production API around a CV pipeline exposes edge cases you would never test otherwise. The lifespan pattern in FastAPI (loading the model once at startup, reusing it across requests) seems obvious in hindsight, but the first implementation reloaded YOLOv8 weights on every /analyze call — a 2-second penalty per request. The global state for the tracker also needed a reset() call between videos, which I only discovered when the second uploaded video showed vehicles from the first one still being tracked.

Speed estimation without calibration is decoration, not measurement. I built the full pixel-displacement → km/h pipeline before running it on real footage and realising the numbers were off by a factor of three. The camera angle I was using was approximately 25° from horizontal — far too shallow for the ground-plane assumption to hold. The lesson: validate numerical outputs against ground truth before wiring them into a dashboard.

CPU vs GPU throughput gap is larger than I expected at high resolution. At 640×640 (YOLO's default input), the CPU is bottlenecked by inference (~50 ms/frame). At 2560×1440 source resolution, the bottleneck partially shifts to pre-processing (letterbox resize and normalisation), which costs an extra 10–15 ms on CPU but is almost free on GPU. The result is that the GPU speedup factor is larger at higher resolutions than the inference-only benchmark implies.

Mocking at the right level makes tests fast and honest. Mocking YOLO.__call__ at the tensor level (making .cpu().numpy() return a known array) let me test all of the wrapper's filtering and formatting logic without loading model weights. Mocking any higher — e.g., mocking VehicleDetector.detect — would have left the class-filtering code untested.

---

Author

Krishna Singh — MSc Artificial Intelligence @ IU Berlin

• GitHub: @krishna8399
• LinkedIn: krishna839

---

License

MIT — see LICENSE for details.