duy-phamduc68/TrafficLab-3D: Build 3D Traffic Twins from CCTV Footage

duy-phamduc68/TrafficLab-3D: Build 3D Traffic Twins from CCTV Footage

TrafficLab-3D is an open-source Python^{↗ Bright Coding Blog} project that transforms ordinary MP4 CCTV footage and a Google Maps location into interactive 3D digital-twin visualizations. Built by developer Yuk (Duy Pham), this tool targets students, independent researchers, and enthusiasts who lack access to expensive camera calibration rigs or synchronized satellite imagery. With 315 GitHub stars and an MIT license, it offers a complete pipeline: camera calibration, object detection and tracking inference, and synchronized side-by-side 3D visualization. The project remains an active proof-of-concept with v1.1 released as of May 2026, and the maintainer is openly seeking collaborators to refactor it into a modular, production-ready framework.

What is duy-phamduc68/TrafficLab-3D?

TrafficLab-3D is an end-to-end traffic analysis suite written in Python that bridges computer vision and geospatial visualization. It belongs to the emerging category of digital-twin tooling for transportation systems—specifically, the subset that operates without proprietary hardware or enterprise sensor networks.

The project is maintained by Yuk (Duy Pham), who develops under both personal (yuk068) and work (duy-phamduc68) GitHub accounts. The repository's MIT license and active commit history (last commit May 23, 2026) signal ongoing maintenance, though the README explicitly labels the current codebase as an experimental, monolithic prototype rather than a polished product.

What distinguishes TrafficLab-3D from academic papers or commercial traffic platforms is its accessibility-first design philosophy. The entire pipeline assumes only two inputs: (1) an MP4 video file from any CCTV camera, and (2) knowledge of where that camera sits on Google Maps. From these minimal prerequisites, users can construct calibrated projections, run YOLO-based detection and tracking, and generate synchronized 3D visualizations showing bounding boxes, speed estimates, and vehicle orientations overlaid on satellite imagery.

The project draws direct academic lineage from Rezaei et al. 2023, a paper on traffic monitoring methodology. Yuk has supplemented the code with extensive documentation: a full academic report, blog posts, and two YouTube guides demonstrating setup and usage.

Key Features

TrafficLab-3D organizes functionality across three integrated tabs with persistent state—users can switch between calibration, inference, and visualization without losing work.

Camera Calibration Pipeline — The most technically sophisticated component. TrafficLab-3D implements a three-phase calibration system to establish two-way geometric projection between CCTV and satellite domains:

• Phase 1 (Undistort): Lens distortion correction using the Brown-Conrady model with 5 coefficients, plus intrinsic matrix (K) configuration
• Phase 2 (Homography): Manual point-pair correspondence with RANSAC solver, producing a warped CCTV overlay on satellite imagery with FOV polygon visualization
• Phase 3 (Parallax): Camera position estimation from subject head/ground contact points and known heights, plus distance reference calibration for pixel-per-meter ratios

Optional SVG map integration and ROI masking extend this for custom map assets created in Adobe Illustrator.

Flexible Inference Hub — The Inference Tab manages batch production of compressed .json.gz output files, decoupling heavy computation from real-time rendering. Users configure detection models, trackers, and kinematic smoothing through YAML/JSON config files. The design explicitly supports swappable YOLO checkpoints (v8-s and v11-s models are provided) and multiple object trackers.

Synchronized 3D Visualization — The Visualization Tab renders side-by-side CCTV and satellite views with 3D bounding boxes, floor-projected boxes, speed annotations, and orientation indicators. A toolbar and keyboard shortcuts provide playback control.

Storage-Efficient Outputs — All inference results serialize to .json.gz format, reducing disk footprint for long-duration traffic recordings.

Use Cases

Academic Traffic Research — Graduate students and researchers can reconstruct vehicle trajectories and kinematics without institutional access to calibrated camera networks or LiDAR installations. The G Projection JSON format preserves reproducible geometric relationships for peer review.

Urban Planning Demonstrations — Planners can rapidly prototype digital-twin visualizations for stakeholder presentations, using existing municipal CCTV feeds rather than deploying dedicated sensors. The satellite overlay provides immediate geographic context.

Independent Accident Reconstruction — Investigators with access to intersection camera footage can estimate vehicle speeds, trajectories, and sightlines using the parallax-based calibration and 3D bounding box outputs.

Computer Vision Education — The modular (intended) pipeline—distortion correction, homography estimation, multi-object tracking, 3D projection—serves as a teaching tool for applied geometry and video analytics. The academic report and blog posts provide theoretical grounding.

Smart City Prototyping — Municipalities exploring digital-twin initiatives can evaluate traffic monitoring approaches before committing to commercial platforms. The open-source license permits unrestricted adaptation.

Installation & Setup

TrafficLab-3D requires a Python environment managed through Conda. The maintainer provides an environment.yml file for reproducible dependency resolution.

Step 1: Clone the repository

git clone https://github.com/duy-phamduc68/TrafficLab-3D.git
cd TrafficLab-3D

Step 2: Create and activate the Conda environment

conda env create -f environment.yml
conda activate trafficlab  # inferred typical name; check environment.yml

The environment.yml pins core dependencies including PyTorch (for YOLO inference), OpenCV (for video I/O and geometric transforms), and Qt bindings (for the GUI tabs).

Step 3: Obtain pretrained models and sample data

Download from the Google Drive folder:

• Finetuned YOLOv8-s and YOLOv11-s .pt checkpoints → place in models/
• Pre-constructed location folders with G Projection files → place in location/
• Preprocessed .json.gz visualization-ready output (requires matching 119NH location folder)

Step 4: Launch the application

python main.py

The GUI opens with a Welcome tab; navigation to Calibration, Inference, and Visualization tabs proceeds via top-left controls.

Directory structure expected after setup:

TrafficLab-3D/
├── location/           # Per-location data: footage, projections, maps
├── models/             # YOLO .pt checkpoint files
├── trafficlab/         # Main Python package
├── output/             # Compressed inference results (.json.gz)
├── environment.yml     # Conda dependency specification
├── inference_config.yaml   # Detection/tracking parameters
├── prior_dimensions.json   # Vehicle dimension priors
└── main.py             # Application entry point

Real Code Examples

TrafficLab-3D's README emphasizes configuration-driven operation over extensive scripting. The primary user-facing "code" consists of YAML and JSON config files paired with the single launch command.

Basic launch command:

# Create environment from specification
conda env create -f environment.yml

# Run the GUI application
python main.py

This simplicity is intentional—the heavy lifting (calibration matrix computation, YOLO inference, tracking association, 3D projection) executes through the tabbed interface rather than imperative scripts.

Inference configuration (inference_config.yaml):

The README references this file for controlling detection models, tracker selection, and kinematic smoothing parameters. Users edit this directly rather than passing CLI flags:

# Example structure inferred from README description
# Actual keys depend on current version—inspect file after clone
model: yolov8s_custom.pt
tracker: botsort  # or alternative tracker
smoothing:
  speed_window: 5
  orientation_alpha: 0.3

Vehicle dimension priors (prior_dimensions.json):

This file supplies expected 3D dimensions for vehicle categories, enabling physically-grounded bounding box construction:

{
  "sedan": {"length": 4.5, "width": 1.8, "height": 1.4},
  "suv": {"length": 4.8, "width": 1.9, "height": 1.7},
  "bus": {"length": 12.0, "width": 2.5, "height": 3.2}
}

The README explicitly notes that users must "inspect" these files to customize behavior, reflecting the project's current documentation-through-configuration approach rather than extensive API documentation.

Location folder preparation (structural convention):

location/
└── 119NH/                    # Location code
    ├── footage/
    │   └── traffic.mp4       # CCTV footage
    ├── cctv_119NH.png        # CCTV reference frame (critical)
    ├── sat_119NH.png         # Satellite crop (critical)
    ├── G_projection_119NH.json   # Generated calibration output
    ├── layout_119NH.svg      # Optional: custom map overlay
    └── roi_119NH.png         # Optional: region-of-interest mask

Note: The README contains limited traditional code examples. The above configurations represent the actual documented interface; users expecting a Python API will need to read source or await the planned modular refactor.

Advanced Usage & Best Practices

Calibration discipline: The G Projection quality determines all downstream accuracy. Invest time in Phase 2 (homography point pairs) and Phase 3 (parallax subject heights and distance references). The validation stages—clicking ground contact points to verify satellite correspondence—are not optional sanity checks; they are essential quality gates.

SVG map integration: For locations with complex road geometry, Adobe Illustrator-created SVG overlays improve visualization clarity. The affine transformation between SVG and satellite domains is computed in the optional SVG Stage. The blog post and YouTube guide detail this workflow.

Inference output management: The .json.gz format decouples compute from visualization. Generate outputs once, then explore multiple visualization configurations without re-running YOLO inference. This matters for long-duration footage where detection dominates runtime.

Kinematic smoothing: The README identifies raw tracker output as noisy. Configure speed and orientation smoothing in inference_config.yaml aggressively enough to suppress jitter, but not so aggressively that legitimate rapid maneuvers disappear. This tradeoff is scene-dependent.

Contribution pathway: The maintainer explicitly welcomes architectural advice via GitHub Issues before code PRs. Given the monolithic prototype state, structural refactoring proposals are as valuable as feature additions.

Comparison with Alternatives

TrafficLab-3D occupies a niche between research prototypes and commercial traffic platforms. Fair comparisons:

TrafficLab-3D's distinctive advantage is minimal hardware assumptions—any MP4 from any camera suffices. Its limitation is equally clear: manual calibration per location does not scale to city-wide deployment without significant automation, which the maintainer identifies as [INTERNAL_LINK: long-term-vision]. Commercial platforms require proprietary sensors but eliminate calibration labor. SUMO operates at a fundamentally different abstraction layer (simulation vs. empirical video). Raw OpenCV offers more flexibility but demands substantially more implementation effort for equivalent capability.

FAQ

What operating systems does TrafficLab-3D support? The README specifies Conda environment setup; Linux, macOS, and Windows are typically supported where PyTorch and Qt run. No explicit OS restrictions are documented.

Can I use my own YOLO models? Yes. Place .pt checkpoints in models/ and reference them in inference_config.yaml. The provided models are finetuned YOLOv8-s and YOLOv11-s variants.

Does TrafficLab-3D require internet connectivity? Google Maps imagery must be obtained separately; the tool operates offline once satellite images and footage are local.

What license governs use? MIT License—permissive for commercial and academic use with attribution.

How accurate are speed estimates? Accuracy depends on calibration quality, particularly Phase 3 parallax and distance reference. The README does not quote specific accuracy metrics; treat outputs as demonstrative rather than forensic-grade without validation.

Can multiple cameras cover one intersection? The current method assumes a single flat planar environment per location code. Multi-camera fusion is not documented.

Is there a Python API for batch processing? The current v1.1 is GUI-centric. The maintainer's roadmap targets modular refactoring that would enable programmatic use.

Conclusion

duy-phamduc68/TrafficLab-3D delivers a genuinely accessible entry point into traffic digital-twin construction, requiring nothing more than MP4 footage and geographic awareness. Its 315 GitHub stars and active maintenance reflect real developer interest, while the maintainer's transparency about prototype status builds trust. The tool excels for academic exploration, proof-of-concept demonstrations, and independent research where budget or institutional access would otherwise block computer vision experimentation.

The honest limitations—manual calibration tedium, single-plane assumption, noisy tracker outputs—are documented upfront rather than obscured. For practitioners needing production-grade, city-scale deployment, commercial alternatives remain necessary. For everyone else, TrafficLab-3D offers substantial capability at zero cost, with a clear contribution pathway for those interested in advancing the codebase toward its modular, scalable vision.

Explore the repository, review the academic report, and consider whether your use case fits this accessibility-first approach: https://github.com/duy-phamduc68/TrafficLab-3D