RadarHub Documentation

Version 1.0 · AI speed radar and traffic vision engine

Overview

RadarHub turns any camera into a traffic analytics and speed measurement system. For every frame of video it:

• Detects vehicles (car, truck, bus, motorcycle) with a pretrained YOLO model.
• Tracks each vehicle with a persistent ID across frames.
• Measures speed in real km/h using a calibrated perspective transform.
• Counts vehicles by type as they cross a virtual line.
• Flags violations above your speed limit, with a photo snapshot of each speeder.
• Knows who is moving: every vehicle is classified as moving (green/red), stopped (amber, was moving), or parked (dim gray, never moved). Only moving vehicles are counted, speed-labelled and fined, so streets full of parked cars stay clean.
• Streams everything to a live web dashboard in your browser.

Everything runs on your own hardware. No footage ever leaves your machine.

Requirements

Installation

# 1. Unzip RadarHub, then inside the folder:
python -m venv .venv

# 2. Activate the environment
#    Windows:
.venv\Scripts\activate
#    macOS / Linux:
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

The first detection run automatically downloads the YOLO model weights (about 6 MB for the nano model).

Quick start

# Live dashboard on your webcam, then open http://localhost:8080
python main.py dashboard --source 0

# Live dashboard on an IP camera
python main.py dashboard --source "rtsp://user:pass@192.168.1.10:554/stream"

# Process a video file into an annotated MP4 + violations CSV
python main.py process --source road.mp4 --out annotated.mp4

Or use the one-command launcher, which creates the environment automatically on first run:

./run.sh road.mp4

Video inputs

RadarHub accepts three source types, all through the same --source flag or the dashboard's source field:

You can also upload a video file directly in the dashboard; RadarHub switches to it immediately.

The dashboard

Start it with python main.py dashboard --source ... and open http://localhost:8080. It shows:

• Live annotated video: boxes are green under the limit and red over it, each with the vehicle's ID, type and current km/h.
• Total and per-type counters from the counting line.
• Live speeds of every tracked vehicle.
• Violations feed with the photo snapshot of each speeder.
• Controls: switch source, change the speed limit, upload a file, export CSV.
• Use this device camera: streams your phone's or laptop's camera to the server for processing, turning any phone into a radar camera. Browsers require a secure context for camera access, so this works on http://localhost or any https:// address.

Calibration

Calibration is what turns pixel movement into real km/h. You do it once per camera position. The camera must be fixed (mounted or on a tripod); a moving camera invalidates the pixel-to-road mapping.

Option A: in the dashboard (easiest)

Click Calibrate under the video, tap the 4 corners of a road rectangle you can measure (top-left, top-right, bottom-right, bottom-left), enter its real width and length in meters, and save. It activates immediately and persists to your config.

Option B: the desktop tool

1. Find a rectangle on the road whose real size you know. A single lane (typically 3.5 m wide) over a measured stretch (for example 20 m between two road markings) is perfect.
2. Run:

   python main.py calibrate --source road.mp4 --width 3.5 --length 20

3. Click the 4 corners in order: top-left, top-right, bottom-right, bottom-left.
4. Press s to save. The points and sizes are written to config.json.

Tips for accurate calibration

• Choose points on the road surface itself, never on objects with height.
• The bigger the rectangle, the smaller the error.
• Lane widths and lane markings have standardized sizes in most countries; check your local road standards for reliable reference measurements.

Violations and CSV export

Whenever a tracked vehicle's smoothed speed exceeds speed_limit_kmh, RadarHub records one violation for that vehicle:

• A cropped photo snapshot saved to data/violations/.
• The vehicle's ID, type, speed, the limit, and timestamp.

Export everything to CSV with the dashboard's Export button, or find it at data/violations.csv after a process run. Each vehicle is logged at most once, so one speeder does not flood your report.

Configuration reference (config.json)

{
  "source": "0",
  "model": "models/yolov8n.pt",
  "conf": 0.35,
  "imgsz": 640,
  "device": "cpu",
  "speed_limit_kmh": 50.0,
  "count_line_y": 0.5,
  "speed_window": 8,
  "smooth": 5,
  "data_dir": "data",
  "calibration": {
    "points": [[0,0],[1,0],[1,1],[0,1]],
    "width_m": 10.0,
    "length_m": 30.0
  }
}

CLI commands

HTTP API

The dashboard server exposes a small JSON API you can integrate with:

How speed is measured

A camera sees the road in perspective: a pixel near the camera covers centimeters, a pixel far away covers meters. Measuring speed in pixels is therefore meaningless. RadarHub does it properly:

1. Your 4 calibration points define a quadrilateral in the image that corresponds to a real rectangle on the road with known width and length.
2. From these, RadarHub computes a perspective transform (homography) that maps any image point on the road to metric coordinates.
3. Each vehicle's ground point (the bottom-center of its box, where it touches the road) is transformed into meters every frame.
4. Speed = distance travelled on the ground plane divided by elapsed time, converted to km/h.
5. A median filter over recent readings removes jitter from detection noise.

This is the same principle used by professional video-based traffic measurement systems.

Architecture

radar/            core engine (importable, testable without a GPU)
  config.py       configuration dataclasses + JSON persistence
  detector.py     YOLO wrapper, vehicle-class filter
  tracker.py      persistent IDs across frames
  speed.py        homography speed estimator
  counter.py      line-crossing counts per class
  violations.py   violation log + snapshots + CSV
  annotator.py    overlay renderer (boxes, labels, stats panel)
  pipeline.py     frame in, annotated frame + stats out
  source.py       file / RTSP / webcam input
app/
  server.py       FastAPI dashboard server
  static/         dashboard UI
main.py           CLI entry point
calibrate.py      calibration tool
tests/            pipeline test, YOLO smoke test, demo renderer

The detector is injected into the pipeline, so the whole engine can be tested with a fake detector, and the heavy ML dependency loads only when detection actually runs.

Performance tuning

Troubleshooting

"Could not open source"

The path, URL or device index is wrong, or the codec is unsupported. For RTSP, test the URL in VLC first. For webcams, try index 1 or 2 if 0 fails.

"operator torchvision::nms does not exist"

Your torch and torchvision versions do not match. Fix by installing both from the same index:

pip install --force-reinstall torchvision --index-url https://download.pytorch.org/whl/cpu

(Remove --index-url for GPU builds.)

Speeds look wrong

Re-check calibration. The 4 points must lie flat on the road, in the correct click order, and the width/length must be real measured values. A 10% measurement error produces a 10% speed error.

Dashboard shows "not calibrated"

Expected until you run the calibration tool. Counting and tracking still work.

Slow or laggy live stream

See Performance tuning. On CPU, prefer analyzing recorded files over live streams.

FAQ

Can I run multiple cameras?

Run one RadarHub instance per camera on different ports: --port 8080, --port 8081, and so on. Each instance keeps its own config and violation log.

Does it detect pedestrians or bikes?

The model can see them, but RadarHub filters to motor vehicles by default. The vehicle class list is one line in radar/config.py if you want to extend it.

Can I get license plates?

Plate recognition (OCR on violation snapshots) is on the roadmap as an add-on. The snapshot system was designed with this in mind.

Is my footage sent anywhere?

No. Everything, including model inference, runs locally on your machine.