SmartTraffic is a local validation platform for traffic video analytics. It combines YOLOv8 detection, DeepSORT tracking, trajectory reasoning, zone/rule configuration, event detection, alert review, evaluation, report export, one-click launch, and a Chinese-first Light SaaS Dashboard UI.
It is not a simple YOLOv8 bounding-box demo. It is also not a production enforcement system, not a formal traffic law-enforcement product, and not an official COCO / TrackEval benchmark. Generated reports are for analysis and review only.
| Area | What SmartTraffic Provides |
|---|---|
| π₯ Video analytics | Upload local traffic videos and run detection/tracking pipelines |
| π§ AI pipeline | YOLOv8 detection, DeepSORT tracking, and trajectory semantics |
| πΊοΈ Rule reasoning | Configurable zones, direction lines, counting lines, and event rules |
| π Event workflow | Events, evidence, alerts, manual review, and Bad Case tracking |
| π Evaluation and reports | Local metrics, report exports, PDF/JSON/CSV, and final review evidence |
| Item | Status |
|---|---|
| π·οΈ Latest documentation tag | v1.0.5-final-readme-showcase |
| π¨ Final UI showcase tag | v1.0.3-ui-showcase-polish |
| π¦ Project type | Local smart traffic event detection validation platform |
| β‘ Backend | FastAPI, SQLAlchemy, Alembic |
| βοΈ Frontend | React, TypeScript, Vite |
| π€ CV stack | YOLOv8 detector wrapper, DeepSORT adapter |
| ποΈ Database | SQLite prototype |
| π³ Delivery | Docker Compose local delivery |
| π₯οΈ UI | Chinese-first Light SaaS Dashboard |
| Not production-ready or law-enforcement-grade |
Object detection answers "what is in the frame". SmartTraffic adds the next layer: track objects over time, derive trajectory semantics, apply configurable road-space rules, then make the result reviewable and measurable.
video
-> detection
-> tracking
-> trajectory semantics
-> zone/rule reasoning
-> events
-> evidence
-> alert/review
-> bad case/evaluation
Video Upload / Camera Source
-> YOLOv8 Detection
-> DeepSORT Tracking
-> Trajectory Engine
-> Zone and Rule Config
-> Event Engine
-> Alert Center
-> Traffic Analysis Center
-> Review / Bad Case / Evaluation
-> Report Export / Docker Local Delivery
- Local video upload, metadata extraction, validation, and processing task lifecycle.
- Run-scoped analysis records so the same video can have multiple local validation runs.
- Local artifacts remain in ignored output directories and are not committed.
- YOLOv8 detector wrapper with deterministic dry-run support for environments without local model weights.
- DeepSORT adapter with deterministic mock tracking for repeatable tests.
- Detection and tracking produce structured inputs; event judgment is handled by the trajectory and rule layers.
- Derives pixel speed, moving angle, dwell time, track length, last-seen state, and direction consistency.
- Exposes trajectory semantics including
zone_history,lane_relation, andline_crossings. - DB-backed
zonesandevent_rulesenter the default processing pipeline when configured. - Pixel speed is a local image-space signal, not calibrated real-world speed.
- DB-backed zone and event rule CRUD for local validation.
- Supports polygon zones, direction lines,
counting_zone, andcounting_linesemantics. - Event rule
severityuses thelow/medium/highcontract. - Alert level is separate and uses
info/warning/critical. - Processing runs keep a config snapshot for reproducibility.
- Six configurable event rules: wrong-way driving, illegal parking, danger zone intrusion, pedestrian in vehicle lane, congestion, and flow counting.
- Persists
event_evidenceandrule_executionsfor review, debugging, and evaluation traceability. - Supports
event_rules_onlyrerun using existing trajectory/config data.
- Alert Center manages alert status, while Review Center manages event review status.
- Review Center supports confirmation, false positive, false negative, ignore, resolve, comments, and rerun request recording.
- Evaluation failed cases such as
id_switchandtrack_lostcan be linked through failed-case -> Bad Case workflows.
- Local event metrics include
event_accuracy,false_alarm_rate,event_recall,event_f1, and per-event metrics. - Detection, tracking, trajectory, event, flow-counting, and regression checks are scoped to local / synthetic validation data.
- Bad Case regression uses deterministic replay or stored rule replay, not full video-level retraining.
- Report exports cover CSV, JSON, PDF, bundle metadata, keyframe summary, and annotated-video references.
- Realtime is a preview metadata workflow for mock, upload, local file, and RTSP no-connect scenarios.
- Docker Compose provides the local delivery path for backend, frontend, migrations, SQLite, and ignored artifact directories.
Frontend
React / TypeScript / Vite
Dashboard, Analysis Detail, Zone Config, Alert, Review, Bad Case, Evaluation
Backend
FastAPI
API Routers -> Services -> Repositories -> SQLAlchemy Models
CV & Analytics
YOLOv8 Detector
DeepSORT Tracker
Trajectory Engine
Event Engine
Evaluation Service
Storage
SQLite Prototype
Local Artifacts
Docker-mounted Local Directories
SmartTraffic does not train a dedicated wrong-way, parking, congestion, or pedestrian-lane model. It detects objects, tracks them, derives trajectory semantics, and applies configurable rules.
| Event | Rule Basis |
|---|---|
| Wrong-way driving | Moving angle vs allowed direction |
| Illegal parking | Low speed + dwell time + no-parking zone |
| Danger zone intrusion | Object bottom-center inside danger zone |
| Pedestrian in vehicle lane | Person inside vehicle_lane |
| Congestion | Vehicle count + average speed + time window |
| Flow counting | Track crossing configured counting line |
Full endpoint details are documented in docs/api_reference.md.
- Health and config:
/health,/health/ready,/api/config - Videos and processing:
/api/videos,/api/processing/tasks - Analysis runs:
/api/analysis-runs - Detection, tracking, and trajectory results:
/api/detections,/api/tracks,/api/trajectories - Zones and rules:
/api/zones,/api/event-rules - Events and alerts:
/api/events,/api/alerts - Review and Bad Case:
/api/review,/api/bad-cases - Evaluation and reports:
/api/evaluation,/api/reports - Camera and realtime preview:
/api/cameras,/api/realtime
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000cd frontend
npm install
npm run devcp .env.example .env
docker compose config
docker compose up --buildDocker Compose is the local validation and demo delivery path. It starts the
FastAPI backend at http://localhost:8000, the Vite frontend at
http://localhost:5173, runs Alembic migrations at backend startup, and stores
SQLite / artifact output in ignored local directories such as results/.
For real local YOLOv8 detection, place yolov8n.pt in local_models/ and set
YOLO_MODEL_PATH=/app/local_models/yolov8n.pt, YOLO_DRY_RUN=false, and
DEEPSORT_DRY_RUN=true in the local .env.
Docker Desktop is required. On macOS, double-click
start_smarttraffic.command. On Windows, double-click start_smarttraffic.bat.
Use stop_smarttraffic.command on macOS or stop_smarttraffic.bat on Windows
to stop the local stack.
The full beginner guide is in docs/one_click_start.md.
python3 scripts/seed_demo_data.py
./backend/.venv/bin/python -m pytest backend/tests/test_seed_demo_data.py -qThe demo seed creates local toy config for 4 zones, 6 event rules, and 6 expected event examples. It is synthetic / sample / local validation only. Real videos, model weights, generated reports, and runtime artifacts are not committed.
Latest recorded validation:
| Check | Result |
|---|---|
| Git whitespace check | Passed |
| Backend tests | 480 passed, 4 warnings |
| Frontend tests | 85 passed |
| Frontend build | Passed |
| Mobile smoke check | 390x844 and 430x932 passed |
| Browser console check | No React duplicate key warning |
| Docker Compose config | Passed |
| Docker Compose build | Passed in final local delivery validation |
| Danger check | Passed |
| Demo seed test | Passed |
| Tracked forbidden-file scan | Passed |
The final manual validation used run_50007c86fd60 and verified detection,
tracking, trajectory, event generation, alert handling, review, Bad Case,
evaluation, and report export.
v1.0.0-smarttraffic-final-local-delivery: first final local delivery baseline.v1.0.1-spec-completion: spec-complete final local delivery baseline.v1.0.3-ui-showcase-polish: final UI showcase polish tag.v1.0.4-final-showcase-docs: final README and showcase documentation sync.v1.0.5-final-readme-showcase: final README visual showcase cleanup.
Earlier v0.9.x and v1.0.x tags are preserved as historical engineering milestones and are not moved.
Do not commit:
.env- secrets, tokens, passwords, API keys, or real RTSP URLs
- model weights
- large videos or uploaded videos
- generated results, reports, keyframes, or annotated videos
- local DB files such as
.db,.sqlite, or.sqlite3 - caches,
dist,node_modules, or virtual environments
- SmartTraffic is a local validation prototype.
- It is not a formal traffic enforcement system.
- It is not production-ready.
- It is not law-enforcement-grade.
- It is not a commercial deployment.
- It is not an official COCO, TrackEval, or real-world traffic benchmark.
- Reports are for analysis and review only, not enforcement decisions.
- Realtime is preview metadata only.
- Pixel speed is not calibrated real-world speed.
- Bad Case regression is deterministic replay / stored rule replay, not a full video-level rerun.
- SQLite and Docker Compose are for local prototype reproducibility.
SmartTraffic has reached its final local showcase state.
v1.0.3-ui-showcase-polishmarks the final UI showcase code baseline.v1.0.5-final-readme-showcasemarks the final README visual showcase cleanup.
The project is suitable for GitHub, portfolio, resume, and interview demonstration as a local validation prototype. Future work should move to separate enhancements such as real-video benchmarking, deployment hardening, official metric adapters, and stronger realtime stream support.