The Problem

TrafficLab-3D solves a specific accessibility gap: building a digital-twin style traffic visualization normally requires calibrated cameras, synchronized satellite imagery, and specialized CV expertise. This tool lets someone with only an mp4 CCTV clip and a Google Maps location produce a 3D traffic visualization with object detection, tracking, and speed/orientation overlays.

What This Does

The repo is a Python desktop application (PyQt-based GUI) that runs a multi-stage calibration pipeline. It establishes a two-way projection between a CCTV frame and a satellite image, then runs object detection/tracking and renders synchronized 2D/3D views. The trafficlab/gui/tabs/calibration_stage/ directory contains the stage-by-stage calibration flow (lens, undistort, homography, ROI, validation). The trafficlab/inference/pipeline.py and trafficlab/visualization/ modules handle detection and rendering.

The scripts/ folder has utility tools: cut_batch_clips.py for preprocessing footage, upgrade_roi.py and upgrade_g_projection.py for migrating calibration data.

How It Is Wired

Execution starts at main.py:8 (main function), which reaches 22 functions. It launches the MainWindow (trafficlab/gui/main_window.py). The GUI is tab-based, with the three primary tabs in trafficlab/gui/tabs/: tab_calibration.py, tab_inference.py, and tab_visualization.py.

The most connected module is trafficlab/gui/tabs/calibration_stage/undistort_stage.py — 10 modules import it, and it has 0 outgoing dependencies. It's the hub of the calibration flow. The final_stage.py file is the densest: 42 functions, called from 11 other files, defining _parse_transform and _extract_segments.

The internal call graph shows fitToView (called from 9 places) and load_pixmap (8 places) as the highest-blast-radius functions — change either and the calibration UI breaks broadly. The traced external effect path is short: main -> cut_video reaches subprocess.run and os.makedirs in just 2 hops. The inference session (trafficlab/gui/inference_session.py) calls into 23 internal functions but has no external I/O mapped.

How To Use It

Setup: The repo has environment.yml (Conda) and inference_config.yaml. No lockfile or Dockerfile is present. The README recommends reading it fully before running.

Configuration: Place footage and satellite images in location/{location_code}/ per the README structure. inference_config.yaml controls detection/tracking settings. YOLO checkpoints go in models/.

Running: python main.py

The README documents the CLI but no explicit install command is given beyond the environment file. The calibration stage is interactive — you'll walk through undistortion, lens, homography, and ROI stages in the GUI.

Real-World Use

A researcher has a traffic camera mp4 and knows the intersection on Google Maps. They create location/main_st/ with the footage and satellite screenshot, run python main.py, calibrate through the GUI stages, run inference, and export a synchronized 3D visualization with bounding boxes and speed vectors — useful for presentations, teaching, or preliminary traffic analysis without a full CV stack.

Code Health & Issues

Static analysis (not opinion) found 41 issues: 4 high, 37 medium.

  • High — Deep nesting (16 instances): undistort_stage.py, tab_inference.py, tab_visualization.py have max indentation depth 7; control flow is hard to follow.
  • High — Duplicated code (125 repeated 6-line blocks across 19 files): calibration stage files (dist_stage.py, homa_stage.py, pars_stage.py, roi_stage.py) repeat logic that should be shared helpers.
  • Medium — Broad exception handling (19 instances): undistort_stage.py, views.py, cctv_renderer.py swallow errors indiscriminately.
  • Medium — Oversized files (3): undistort_stage.py at 639 lines, plus final_stage.py and tab_visualization.py.
  • Medium — Files opened without context manager (2): scripts/icon_ascii_art.py, scripts/upgrade_roi.py.

SDLC gaps: no tests, no CI/CD, no Dockerfile. media/demo.gif is 6.1MB — should move to LFS or object storage. No committed secrets found.

The Bottom Line

A functional, well-scoped tool for its niche — the calibration pipeline is genuinely useful for non-experts. The codebase is workable but needs refactoring (deduplication, exception handling) and basic engineering hygiene (tests, CI) before it's maintainable at scale. Best suited for students, researchers, or individual developers who want a working traffic visualization demo without building the CV stack from scratch.