TrafficLab 3D turns CCTV footage and a map pin into a traffic digital twin

A digital twin from a CCTV clip and a map pin

Traffic digital twins normally demand ingredients most people cannot get: camera calibration documents, synchronized high-quality satellite imagery, vendor tooling. TrafficLab 3D, by Yuk, is built around the opposite premise, stated in the README's first sentence: with only an mp4 clip from a CCTV camera and the knowledge of where that camera sits on Google Maps, anyone can produce a digital-twin style visualization of the traffic it watches.

The named audience is students, individual investigators and enthusiasts. The pipeline behind the promise is a genuine computer-vision stack: two-way projection between the camera and the satellite domain, YOLO-based object detection and tracking, and a rendering layer that shows 3D bounding boxes over the video and floor boxes with speed and orientation on the map. An academic report and a YouTube guide back the tool for anyone who wants the theory.

Proof of concept, stated plainly

Rare is the repository that opens its status section with this much candor. The README declares the codebase an experimental, monolithic prototype, functional for academic and demonstration purposes, and says the immediate goal is refactoring into a modular architecture using lessons from this proof of concept. Collaboration is invited with process attached: architecture advice via issues, an issue before any pull request, and a request to make contact before committing to the vision.

That framing should set your expectations as a user. The tool works, the release tag reads v1.1 with two published releases and the last push on 2026-08-06, and the YouTube demo shows real results. But you are running a PoC: expect rough edges, plan to read the source when something misbehaves, and do not build a production traffic-monitoring workflow on it without accepting the refactoring risk the author himself flags.

Calibration: three phases from lens to meters

The Calibration tab is the methodological core, producing a G Projection JSON file that ties the CCTV view to the satellite view. Phase one handles the lens: configure the intrinsics matrix, then correct distortion under the Brown-Conrady model with its five coefficients, validated before moving on.

Phase two establishes the ground plane: homography anchors are matched manually and solved with RANSAC, the warped camera view is overlaid on the satellite map to define the field of view, and validation is literal, click a ground point in the CCTV frame and see it land on the map. Phase three recovers scale and height: two subjects with known heights yield the camera position, and a distance measured on Google Maps sets the pixels-per-meter ratio. Optional stages add custom SVG alignment and a region-of-interest discard strategy, and a final validation checks that 2D boxes convert to 3D boxes and floor boxes before the projection is saved.

Inference and the JSON handoff

The Inference tab is where footage becomes data. Object detection models and trackers are swappable, with YOLO checkpoints sitting in the models directory and numerous kinetics and argument controls exposed in inference_config.yaml. The outputs are gzipped JSON files organized per model, tracker, configuration and location code.

That file format is the load-bearing design decision. The visualization engine consumes the JSON outputs rather than running detection live under rendering, so the expensive computation happens once and the twin view stays smooth. It also makes results inspectable and reproducible independent of the renderer: your tracking data is a file you can diff, re-analyze in Python, or feed to a different visualization entirely. For a research tool, publishing results as data instead of video is the difference between a demo and a dataset.

The twin view, and what it shows

The Visualization tab delivers the promised experience: a side-by-side, synchronized presentation where the CCTV feed shows 3D bounding boxes around vehicles while the satellite view shows their floor boxes with speed and orientation. Because both views render from the same G Projection and the same tracking JSON, the correspondence is not approximate; a car in the video and its marker on the map are the same record seen through two projections.

The interface spreads three main tabs, calibration, inference, visualization, plus a Location tab that scaffolds the folder structure a new camera needs, and the README notes you can move between tabs without losing work. For teaching, this is the quiet strength: a student can see exactly how a flat pixel observation becomes an oriented, speed-bearing object on a map, with every stage of the transformation inspectable in the files along the way.

Preparing a location

The workflow has inputs only you can provide, and the README is specific about them. Each camera lives under a location code folder holding the mp4 footage, and two files are marked critical: a CCTV snapshot image and a satellite image of the same scene, both named with the location code. The G Projection JSON the calibration produces lands alongside them, and optional assets include an SVG layout and an ROI mask, craftable in Adobe Illustrator with the blog post and video as guides.

The runtime is conda-based, with environment.yml defining the dependencies, and main.py as the entry point alongside prior_dimensions.json and inference_config.yaml in the repository root. The Location tab scaffolds the bare folder structure so you do not assemble it by hand. Budget the real effort where the README points it: choosing usable footage, capturing a matching satellite view, and sitting through the three calibration phases carefully, because every downstream number inherits their quality.

Running it: conda, main.py, and the shared Drive

The Getting Started section is two commands long, which is appropriate for a desktop research tool: create the conda environment from the checked-in environment.yml, then launch the program from the repository's single entry point:

conda env create -f environment.yml
python main.py

The README links a Google Drive with the assets that make the tool usable on day one: fine-tuned YOLOv8-s and YOLOv11-s checkpoints for the models folder, pre-constructed projections for several location codes, and a preprocessed .json.gz output ready for visualization. Loading those means you can see a finished digital twin before calibrating anything yourself, which is the correct order of operations for evaluating the tool.

Run behavior is configured through inference_config.yaml and prior_dimensions.json, and the README is direct that adjusting models and kinematics means inspecting those files yourself. The open problems section lists the known boundaries with unusual honesty: the method assumes a single flat planar scene, tracking output is taken as-is so occlusions make objects vanish, 3D boxes follow no vehicle model and can rotate or teleport, and crafting the initial G Projection remains tedious work.

Against vendor analytics and DIY homography

The commercial alternative is vendor traffic analytics: cameras with onboard detection, licensed dashboards, maintenance contracts. Those produce operational data at production reliability, and they cost accordingly, with the data often locked to the vendor's platform. TrafficLab 3D answers a different need: understanding and demonstrating the pipeline itself, on any camera you can record, with every intermediate artifact inspectable.

The DIY alternative is rolling your own with OpenCV: undistortion, homography, tracking are all documented techniques, and a capable developer can assemble them. What the DIY route relearns painfully is exactly what this repository encodes: the staged calibration with validations, the parallax trick for camera height, the pixels-per-meter bootstrap from a map measurement, and the file format that separates heavy inference from smooth rendering. For a class, a portfolio piece, or an intersection you personally care about, that head start is the product.

Editorial conclusion

TrafficLab 3D fits students, researchers and enthusiasts who want to turn accessible CCTV footage into a calibrated, synchronized 3D traffic visualization, and who accept a self-declared monolithic proof of concept as the price. Skip it for production traffic engineering, for uncalibrated multi-camera fusion, or anywhere reliability matters more than insight and demonstration. Verify the workflow end to end on one intersection: calibrate, run inference on a short clip, then open the twin view and check a vehicle's speed against what you can count by hand in the footage.

Frequently asked questions

Official sources

1. duy-phamduc68/TrafficLab-3D on GitHub
2. Issues
3. License: MIT
4. README
5. Releases