osmWorkflow/docs/native-preview-traffic-simulation.md

Native Preview Traffic Simulation

This document defines the portable preview contract for native road traffic demonstrations. It is not a legal navigation format or a full microscopic traffic simulator.

Data Flow

native-road/compiled.json + layers/
  -> native-preview-traffic-simulation/v1 descriptor
package/runtime/traffic-signals.json
  -> signal phase clock and stop constraints
descriptor + package/manifest.json
  -> Cesium preview vehicles, signals, queues, diagnostics

The descriptor is generated from native artifacts and is independent of QGIS/osm2streets. Copying the descriptor, package, and preview runtime to another platform is sufficient to reproduce the visual simulation.

Existing Signal Contract

Signal identity is signal_uid; it must not be renamed when display_id changes. phase_group selects the existing signal phase. mast_heading_deg, face_heading_deg, pose.*, stop-line coordinates, and enabled are consumed from package/runtime/traffic-signals.json. Disabled signals are absent from runtime control. Consumers must not recalculate lamp or pole geometry.

Vehicle Rules

Each vehicle advances along a route distance. Its target speed is the minimum of desired speed, signal-safe speed, and leader-safe speed. Red/yellow signals create a stop target before the native stop line. Following vehicles apply the configured minimum gap and decelerate behind the leader. The simulation is deterministic for a fixed descriptor, clock start, and settings.

The descriptor records WGS84 route coordinates. The static package remains local ENU and is placed by the package manifest. Consumers must use the package placement/model matrix for GLB assets and WGS84 coordinates for route entities; do not mix a fixed meters-per-degree approximation into either path.

Route geometry is taken from native-road/layers/lane_centerlines.geojson when that native layer is available, keyed by road_id; the compiled road centerline is only a compatibility fallback for old native outputs. Each road/connector boundary is checked in meters. Candidates with a missing connector or an endpoint gap over 35 m are omitted from routes and retained in rejectedRoutes with structured diagnostics. This prevents a malformed movement from becoming a visible diagonal track across an intersection.

diagnostics contains the route-generation warnings, while rejectedRoutes preserves the candidate id and the specific movement checks that failed. A consumer should display these as data-quality warnings rather than silently reconstructing a route from legacy QGIS files.

Migration Checklist

1. Load package/manifest.json and resolve all package-relative assets.
2. Load the traffic-signal runtime and preserve signal_uid/phase_group values.
3. Load the versioned simulation descriptor and verify its source hashes if reproducibility matters.
4. Implement the update loop using the descriptor settings and stop/leader constraints.
5. Place route coordinates in the same WGS84 scene as the package placement and preserve ENU model placement for static assets.
6. Expose route count, signal count, stopped vehicles, and queue length as diagnostics.

Rollback

Deleting or ignoring the optional simulation descriptor returns the native preview to a usable static scene with signal visualization but no vehicle cruise. The QGIS baseline remains available through qgis-original-baseline-20260818; it is not required by this contract.