Traffic Engine

Project Overview

Traffic Engine is a production-grade computer vision platform that transforms raw traffic camera footage into structured, actionable traffic data — vehicle counts, directional flows, per-category breakdowns, and timestamped crossing events — without relying on any cloud service or external infrastructure. It addresses a problem that transport planners, municipal authorities, consultancies, and highway operators have historically solved through either expensive purpose-built roadside hardware or manual, clipboard-and-counter field surveys: both approaches are slow, costly, and error-prone at scale.

The platform takes any recorded video from an existing CCTV camera, drone, or mobile phone, and produces professional traffic survey outputs in minutes rather than days. By localising all processing to the operator's own workstation, it eliminates recurring data-transfer fees, protects footage from leaving the client's environment — an important consideration for government and infrastructure clients — and enables fieldwork in bandwidth-constrained locations.

Crucially, the system has been tuned for the characteristics of road traffic in South Asian markets, where vehicle classes, road discipline, and occlusion patterns differ meaningfully from the Western datasets most off-the-shelf traffic analytics tools are trained on. Categories such as two-wheelers, three-wheelers, auto-rickshaws, and several distinct commercial vehicle classes are recognised natively rather than being forced into generic 'car/truck/bus' buckets. The result is a tool that produces counts consultants and planners can actually use in their deliverables, rather than numbers that need a manual correction pass before being trusted.

From a business perspective, Traffic Engine replaces a process that typically involves multiple surveyors, several days of field deployment, and post-processing spreadsheets with a single operator, a laptop, and a few hours of compute time — while producing a richer, more auditable data product at the end of it.

Key Features & Functionality

End users can point the application at a folder of recorded videos, mark a counting line by clicking two points on a preview frame, and begin processing. From there the platform handles detection, tracking, counting, and reporting automatically.

The core user-facing capabilities include automated vehicle counting across bidirectional flow with per-category totals for each direction; multi-video batch processing so operators can queue several independent surveys in parallel; interactive line placement directly on a live video preview so each survey site can be configured visually in seconds; and multi-gate and multi-lane analytics on a single video, enabling junction studies and lane-level breakdowns from the same footage.

Speed estimation is derived from the time taken to cross between reference lines, producing km/h figures per vehicle. Every run produces a polished deliverable set: an annotated video overlay, a self-contained HTML report viewer, summary spreadsheets, detailed crossing logs, and a machine-readable JSON export suitable for integration into client dashboards. In-application model training lets advanced users fine-tune the underlying detection model on their own site-specific footage without leaving the tool.

The emphasis throughout is on producing a single, polished output set per video that an analyst can hand directly to a client without post-processing.

Technology Stack

Traffic Engine is built on a modern Python computer-vision stack, with a native desktop front-end layered on top.

• Computer vision & deep learning: the Ultralytics YOLO framework for object detection, with ByteTrack-based multi-object tracking for consistent identity across frames. PyTorch underpins the inference runtime, with optional GPU acceleration when available.
• Image and video I/O: OpenCV for frame-level processing and video encoding, supplemented by NumPy and SciPy for the geometric and numerical work that sits between detection and counting.
• Desktop interface: PySide6 (Qt 6) for a cross-platform native application.
• Configuration & serialisation: YAML for human-editable configuration, JSON for structured outputs and persistent UI state, and CSV for spreadsheet-friendly reports.
• Reporting: a self-contained HTML viewer rendered alongside each run's results, requiring no web server and no external dependencies to open.

The stack was chosen to keep the entire pipeline on one machine, be friendly to air-gapped deployments, and remain approachable for future maintenance by any competent Python engineer.

Technical Complexity & Challenges

On the surface, 'count vehicles crossing a line' sounds like a textbook computer vision exercise. In practice, producing counts that are trustworthy enough for transport planning involves solving several interacting problems, each of which forced deliberate engineering decisions.

The first challenge is identity stability. Modern detectors produce reliable bounding boxes, but individual track identities can flicker — a motorcycle briefly occluded by a bus, for example, may reappear as a new track. Without care, this causes the same vehicle to be counted twice. The engine layers additional guards on top of the base tracker to suppress duplicate counts that arise from identity jitter, while still correctly counting genuinely distinct vehicles that happen to pass close together.

The second challenge is counting geometry. Naive line-crossing logic breaks down at line endpoints, under oblique camera angles, and when vehicles briefly hover on the boundary. The platform instead uses a zone-based approach with a configurable tolerance band around the operator-drawn line, combined with a robust geometric formulation that does not depend on segment endpoints. This produces stable counts across a wide range of camera placements without per-site tuning.

The third challenge is performance versus accuracy trade-offs. Running a large detection model on every frame of a long video is wasteful; running a small model at a low frame rate misses vehicles. The engine uses an adaptive strategy that invests more compute near the counting zone and less in uninteresting regions of the timeline, and it automatically rescales oversized footage to keep inference costs predictable while mapping detections back to the original resolution so outputs remain pixel-accurate.

The fourth challenge is category fidelity. Off-the-shelf detection models are trained on generic class sets that do not map cleanly to the vehicle taxonomy local planners actually care about. The platform defines a canonical category system as a single source of truth and routes every detection through a normalisation layer, so reports are consistent regardless of which underlying model weights are in use.

Finally, the platform was architected to be re-runnable and auditable. Every processed video produces a self-describing results folder; configuration is persisted per slot; and the pipeline emits structured logs at a level of detail sufficient for support engineers to diagnose a disputed count without needing access to the original footage.

Design & User Experience

The design philosophy is best summarised as 'a field tool, not a framework.' The target user is a traffic engineer or survey analyst, not a machine-learning researcher. Accordingly, the interface was designed so a new user can open the application, load a video, draw a line, and produce a usable report within their first session.

The desktop application organises its workflow around independent processing slots, each representing a separate survey site with its own video source, counting line, and settings. This mirrors how consulting teams actually work: multiple sites under study concurrently, each with its own context. A slot is configured visually — folders are browsed rather than typed, videos are previewed rather than guessed, and counting lines are drawn with two clicks on a representative frame.

Runtime feedback is emphasised throughout. Progress, estimated time remaining, and running counts are surfaced live while processing, so operators are never left wondering whether the system is working. On completion, the deliverable report is opened automatically, making the 'press start, come back, share results' loop as frictionless as possible. A dark, restrained visual style keeps the focus on video content rather than on chrome, and settings are disclosed progressively: sensible defaults cover most jobs, while advanced tuning controls are available for specialists without cluttering the primary workflow.

Scale & Scope

The codebase comprises roughly 15,600 lines of Python spread across around 35 modules, organised into cleanly separated layers: a core utilities layer for coordinate mapping and video I/O, an engine layer for detection, tracking, counting, analytics, and export, a desktop UI layer built on Qt 6, and ancillary tooling for diagnostics and maintenance.

The engine layer alone contains approximately 18 modules covering the end-to-end inference pipeline — from frame ingestion through adaptive scheduling, detection, identity tracking, counting logic, lane and gate analytics, overlay rendering, batch orchestration, and multi-format export. The UI layer adds roughly another 10 modules, including an interactive video canvas, background workers for non-blocking processing and model training, and persistent per-slot configuration. The system supports multiple detection model variants so clients can trade accuracy against throughput, a configurable counting pipeline with a wide range of tunable parameters, and five distinct output artefacts produced for every processed video.

Business Impact & Use Case

Traffic Engine serves organisations that need high-quality traffic volume and composition data but do not want to install permanent roadside sensors or outsource video footage to third parties. Typical users include transport planning and engineering consultancies preparing traffic impact assessments, junction studies, corridor analyses, and feasibility reports; municipal and highway authorities seeking periodic or on-demand counts from existing CCTV infrastructure without a capital outlay on new hardware; infrastructure developers and toll operators validating design assumptions, benchmarking demand, and auditing manual survey contractors' figures; and academic and research teams studying traffic behaviour, vehicle mix, or the effect of interventions on real-world road networks.

The value delivered is tangible: a task that might otherwise require a surveyor in the field with a counter for a full working day, followed by data entry back in the office, collapses into a few hours of operator time and an auto-generated report pack. Because the system runs entirely on the client's own machine, sensitive footage — which can include number plates, faces, and locations of strategic assets — never leaves their control, sidestepping a class of procurement and compliance objections that cloud-based traffic analytics products regularly encounter.

Development Approach

The project was developed with a strong emphasis on modularity, maintainability, and the ability to hand the codebase to a new engineer without a lengthy onboarding. Core concerns — detection, tracking, counting, analytics, overlay rendering, export, and UI — are separated into their own modules with well-defined responsibilities, so changes in one area have limited blast radius into the others.

A single source of truth pattern is used for concepts that would otherwise drift across the codebase: vehicle categories, configuration defaults, and result schemas all live in one place and are referenced everywhere else. This makes future enhancements — adding a new vehicle class, supporting a new export format, or re-branding report outputs — substantially lower-risk than in an ad-hoc codebase.

Configuration is externalised into human-readable files, keeping behavioural changes out of the source tree and making it straightforward to version-control per-client profiles. Structured logging at the pipeline level provides operational observability: support engineers can reconstruct exactly what happened on a given run without needing the original video. The engineering discipline also shows up in the output contract — every processed video produces a self-contained results folder with predictable contents, which makes the system easy to integrate into downstream client systems and equally easy to archive for audit. Together, these choices reflect a tool built for repeated professional use over time — not a one-off research demo.