# Võ Văn Kiệt: data research and route to a digital twin

Research date: 19 September 2026. **Update:** a saved CCTV sample and a provisional vehicle-mix adjustment are now available in the [evidence gallery](cctv.html) and [parameter record](../data/calibration.json). The original roadmap below predates that sample; traffic rates and dynamics are still uncalibrated. Listing descriptions are evidence of availability, not independent verification of accuracy. No commercial assets have been purchased and no third-party city mesh is included in this repository.

## Recommended starting point

Use **OpenStreetMap road geometry + a simple 3D viewer now**, inspect the **Saigon 3D City** free model for visual context, and move traffic dynamics to **SUMO with its sublane model** once the selected corridor and measurements are established. A detailed facade mesh does not establish traffic accuracy. Lane widths, physical dividers, access, bottlenecks and entry flows matter more for this first street simulation.

The working prototype now uses a **1.18 km** canal-side section of Võ Văn Kiệt ending at **Nguyễn Thái Học / Cầu Ông Lãnh**. It is not the whole boulevard. Approximate city-side endpoints: **10.7638659, 106.6977418** and **10.7568608, 106.6897729**. The original southwest boundary is preserved. [View the area on OpenStreetMap](https://www.openstreetmap.org/#map=18/10.7578/106.6910).

## Available models and geodata

| Candidate | What the source offers | Fit and limitations |
| --- | --- | --- |
| [Ho Chi Minh City 2025 — Saigon 3D City, Sketchfab](https://sketchfab.com/3d-models/ho-chi-minh-city-2025-thanh-pho-ho-chi-minh-10e6d7c014a141b4a4adec54729d0968) | Free download listing; CC Attribution; roughly 311k triangles. Author describes central wards including Saigon, Ben Thanh and Xom Chieu. | Best free ready-made mesh lead found. Inspect downloaded extent, scale, georeferencing and exact corridor coverage before adoption. The mesh was not downloaded or inspected in this session. |
| [HCMC Vietnam 100 km — 3DExport](https://3dexport.com/3d-model-ho-chi-minh-city-vietnam-100km-315015) | Commercial GIS-derived city; description identifies 2022 data; OBJ, FBX, C4D and other formats. | Broad context candidate. Seller notes some AI-generated building shapes and C4D-specific texture setup. Do not interpret “accurate” marketing as a survey guarantee; inspect a corridor sample before buying. |
| [3D Ho Chi Minh — city and surroundings, META Group / TurboSquid](https://www.turbosquid.com/FullPreview/1482809) | Commercial city model; listing advertises metre units, 1:1 GIS geometry, Blender/3ds Max and interchange formats. | Another ready-made base mesh option. Source age, geometry detail and street coverage need checking. No purchase or fidelity assessment completed. |
| [OSM2World](https://osm2world.org/) | Open-source conversion from OSM to 3D, including glTF/GLB and OBJ output. | Recommended reproducible geometry pipeline. Quality is limited by source tagging; generated heights or facades are not observations. |
| [Geofabrik Vietnam extract](https://download.geofabrik.de/asia/vietnam.html) | OSM PBF and GIS extracts for Vietnam. | Useful when expanding to a district or city. For this small prototype, the public OSM map API sufficed. |
| [HCMC building footprints — NextGIS](https://data.nextgis.com/en/region/VN-SG/msbld/) | Regional packages combining Microsoft/Google-derived footprints and OSM buildings. | Candidate for filling missing footprints. Footprints alone do not provide facade geometry or verified building heights. Check product/source licences before integration. |
| [3DScan.vn — 12 Võ Văn Kiệt](https://3dscan.vn/3d-laser-scanning-as-built-survey-12-vo-van-kiet-district-1) | A provider describes an as-built laser scan of one commercial building. | Evidence of local survey capability, **not a public downloadable street scan**. Relevant if a paid, site-specific survey is eventually needed. |

I did not find and verify an openly downloadable, surveyed or photogrammetric model of this exact street segment. That does not establish that one does not exist. Generic city meshes should be inspected before spending time integrating them.

## What is actually built

- A local Three.js 3D viewer with four separate OSM-derived carriageway paths, 372 mapped building footprints, and a mapped canal polygon.
- Continuous lateral motion inside each route's usable width. Motorbikes and bicycles can travel side by side and seek gaps; vehicles have dimensions and a longitudinal following model. Painted lanes impose no movement constraints.
- Separate carriageways retain separate boundaries. The chosen OSM tags exclude two-wheelers from the main car routes and cars from the canal-side route. The city-side route is mixed. These are map-derived assumptions, not a statement that observed traffic always complies with rules.
- Motorbikes, bicycles, cars, trucks and buses; seeded synthetic demand; play/pause, speed, reset, demand and motorbike share controls; artificial downstream stop; overview, overhead, street and follow cameras.
- Simulation-state JSON export, with projected positions, assumptions and boundary demand rejected when the entry is full.
- GLB export of the static street model, with attribution and provenance in glTF extras. Traffic vehicles are not included in that static export.

This model is **a geographically grounded prototype, not yet a calibrated digital twin**. It has saved CCTV observations but no live inputs, validated traffic forecasts, intersection turns, pedestrians, signal timing, inter-carriageway interaction or surveyed elevations. Routes are independent, with open upstream/downstream boundaries. Adjacent road stubs are visual context only. Queue-hold lines are an artificial experiment, not mapped traffic signals.

### Geometry provenance

`data/street.json` preserves the original selected OSM way IDs and tags, retrieval time, coordinate origin, width assumptions and each building's height source. The projected local metre system uses X east, Z south, Y up; origin **[106.69098 longitude, 10.75780 latitude]**. It is a local approximation suitable for this short scene, not a survey CRS.

| Layer | Sourced | Estimated / omitted |
| --- | --- | --- |
| Roads | OSM centreline vertices, direction, access and lane tags | Widths 6.4 m / 9.0 m / 6.4 m / 3.2 m; curbs, markings and flat elevation |
| Buildings | OSM footprint polygons; height or level tags where present | 10.5 m fallback; 3.2 m per storey where only levels exist; plain materials, no facade detail |
| Water | OSM canal polygon | Flat water surface, colour and water level |
| Trees | No surveyed tree dataset | Illustrative placement and geometry |
| Traffic | Seven unique CCTV snapshots from the corridor-end camera; two excluded context frames | Provisional mix adjustments only; demand, speeds, acceleration, gaps and passing remain assumptions |

The map extract is small but contains full OSM ways crossing its bounds. Therefore some context meshes extend beyond the 1.18 km traffic corridor. Sparse buildings reflect missing map coverage; empty ground must not be interpreted as empty real-world land.

## How to make the traffic credible

1. **Fix the study boundary.** Use the extended 1.18 km segment or choose a longer junction-to-junction corridor. Confirm physical divider locations, usable road widths, entrances, parking, turning pockets and actual mode access from recent street imagery or a site visit.
2. **Collect a calibration sample.** Video with a known scale and clock, covering both directions and the desired time of day. Measure arrivals by mode, speed distributions, lateral positions, headways, queue lengths and travel times. Reserve another time interval for validation. Do not assume the current 72% motorbike / 8% bicycle input is a measured HCMC split.
3. **Use a mature mixed-traffic backend.** [SUMO's sublane model](https://sumo.dlr.de/docs/Simulation/SublaneModel.html) supports side-by-side two-wheelers and lateral motion. Start with `--lateral-resolution 0.2` (a modelling choice compatible with the prototype's assumed widths), appropriate vehicle dimensions, `minGapLat`, `latAlignment`, and calibrated lateral/longitudinal behaviour. Its stripe discretisation is computational, not a restriction to the painted lanes. Calibrate and compare; SUMO does not automatically reproduce HCMC traffic just because sublanes are enabled.
4. **Build and audit the network.** [OSMWebWizard](https://sumo.dlr.de/docs/Tutorials/OSMWebWizard.html) offers a quick OSM-to-SUMO scenario. Its generated demand is random. Edit the network and routes to match the actual street; check [bicycle modelling and access](https://sumo.dlr.de/docs/Simulation/Bicycles.html). Do not import every mapped lane as a strict one-vehicle traffic channel.
5. **Connect simulation to rendering.** Keep the current visual layer, replace agent state with SUMO output through TraCI or replay sampled trajectories, transform to the same local coordinates, and interpolate between timestamps. This integration is a next step, not present in this prototype.
6. **Validate before prediction.** Compare simulated vehicle counts, travel times, queue lengths and lateral distributions against the held-out observations. Report error ranges and scenarios where the model fails. Add live or periodically updated measurements only after offline validation.

## Reading frames with a vision-language model

`scripts/read_frames_gemma.py` sends each saved JPEG to a Gemma vision model and stores the vehicle
classes it reports, with the raw reply kept for inspection. `scripts/derive_parameters.mjs` pools
those counts into a selectable preset. This automates the *composition* judgement that was previously
made by eye, and nothing else.

What it legitimately fixes: the split of four-wheelers into cars, vans, trucks and buses, and the
split of two-wheelers into scooters and pedal bicycles. These are ratios within a visible population,
so no scale, clock or camera pose is needed.

What it cannot fix, and the derivation therefore refuses to fix:

- **Total flow.** A still frame gives an occupancy. Turning occupancy into veh/h needs the length of
  corridor the camera resolves, which is unsurveyed. The derivation reports demand across a band of
  assumed view lengths, and by default changes nothing. The band spans roughly a factor of two in
  demand over plausible lengths, which is the honest measure of how weak the inference is.
- **The corridor's motorbike share.** One oblique view weights the carriageways unequally, and the
  trunk carriageways here are tagged `motorcycle=no`, so the two-wheelers that dominate the corridor
  are largely on the routes the camera resolves worst. A whole-image share is not a mode split. It is
  recorded, not applied, unless `--apply-two-wheeler-share` is passed deliberately.
- **Speeds, headways, gaps, widths, signal timing.** Unchanged for the same reasons as before.

### Closing the loop live

`scripts/live_loop.mjs` runs the same derivation against a frame captured seconds earlier, smooths the
result and publishes it for the viewer to apply to the running simulation. Capture is a direct request
from the machine running it; no remote host is involved.

This makes the prototype a live loop, not a calibrated one. Two properties are worth separating:

- **The plumbing is sound.** `Simulation.applyOptions()` is atomic and does not discard the street, the
  published file carries `raw` beside `smoothed` with the frames behind both, an invalid publication is
  refused by the publisher and again by the viewer, and the occupancy-based demand fit stays gated on
  free-flowing traffic. A better estimator can be dropped in behind this interface unchanged.
- **The signal is not.** Smoothing stabilises the simulation without improving the reading, and a
  persistent bias is invisible to an EMA. Nothing in the loop measures speed, headway or acceleration,
  because the frames cannot carry them.

The honest description of the result is a digital twin whose *mix* follows a live camera through a
noisy, unvalidated estimator, on a corridor whose flow, speeds and behaviour remain assumed.

The model is a general vision-language model, not a trained traffic detector, and was not scored
against hand-labelled frames. Its error rate on 512 × 288 wet-pavement frames is unknown. Frames
about 12 s apart re-observe slow vehicles, so pooled counts are not independent samples and the
record reports the per-frame spread rather than a confidence interval. This pipeline does not replace
step 2 above: a calibration sample with a known scale and clock is still the only route to measured
arrivals, speeds and headways.

## Improving visual accuracy

Inspect the free central-HCMC mesh first. If it covers the corridor, align it using multiple known control points and verify scale, orientation and road height before replacing the simple buildings. Do not rescale the traffic model merely to fit an unverified visual asset. Where the model is incomplete, improve footprints and measured heights or obtain a licensed survey/photogrammetry dataset. Keep geometry provenance separate from assumptions throughout.

Map data: [© OpenStreetMap contributors, ODbL 1.0](https://www.openstreetmap.org/copyright). External mesh licence terms must be checked on acquisition. The current viewer does not request external map tiles, model downloads or fonts at runtime.

## Correction: apparent bridge junction in the original viewer

The original context-road renderer incorrectly drew all `highway` ways as flat roads, including `highway=construction`. The saved OSM extract contains **Cầu Nguyễn Khoái** bridge ways and associated ramps tagged as construction (including ways 1460163108, 1460163114 and adjoining links). That created a misleading large junction/canal crossing near Trần Đình Xu. It was not evidence of an operational bridge there, and identifying that rendered feature merely as “Võ Văn Kiệt – Trần Đình Xu” was incorrect.

Construction/proposed ways are now preserved under `excludedRoads` for provenance and excluded from operational scenery. The importer, viewer and exported GLB have been corrected. This is a correction to interpretation of the downloaded map tags; it does not independently establish the project's current construction progress.

Extension update: Cầu Ông Lãnh is now included as **elevated visual context**, using mapped alignment and assumed 6 m deck height / 85 m ramps. The under-construction Nguyễn Khoái geometry remains excluded. Camera 56de42f611f398ec0c481288 is now 2.9 m from the extended road geometry; the original Trần Đình Xu sample remains the source for the provisional mix. Traffic remains straight-through, without junction turns, bridge traffic or signal control.