Native Road Compiler Workbench Design

Architecture

The native compiler is an additive pipeline path. It owns a separate output directory under an area and never writes into osm2streets_web_out/.

OSM XML + native-road-overrides.json
          |
          v
      Canonical Road Model
      roads / endpoints / junction candidates / provenance
          |
          v
      Native Geometry Compiler
      road surfaces / initial junction surfaces / diagnostics
          |
          +--> native-road/compiled.json
          +--> native-road/layers/*.geojson
          +--> native-road/diagnostics.json
          +--> native-road/comparison.json
          |
          v
      Road Workbench HTTP service
      browser map + inspect/edit/save API

The canonical model is the authority. Render layers, browser display data, and future Blender compatibility adapters are derived from it.

Commands And Ownership

npm run road:compile -- --config <area-config> performs no browser work. It reads OSM plus the persisted override file, writes a staged native-road result, validates it, and atomically promotes the result directory.
npm run road:workbench -- --config <area-config> compiles first unless --no-compile is supplied, then starts a local HTTP server scoped to that one area.
The server exposes read-only compiler artifacts and one explicit save API for validated overrides. It does not expose arbitrary filesystem paths.
Existing build:area, intermediates, QGIS, Blender, Cesium, and package paths remain unchanged in the first iteration.

Data Contracts

Canonical road model

Each road direction carries a stable ID derived from OSM identifiers, source way IDs, endpoint node IDs, centerline, explicit/inferred attributes, applied override IDs, and diagnostics. Junction candidates likewise use their OSM node ID when available. Values include provenance such as tag:lanes:forward, inferred:highway-default, or override:<id>.

Override file

<area>/native-road-overrides.json is versioned and human-reviewable. It contains an array of uniquely identified changes whose targets are stable road or endpoint IDs. Supported v1 records are road parameter overrides and junction-connection decisions. The save endpoint validates schema, target existence, finite values, and duplicate/conflicting edits before atomic write.

Compiler artifacts

<area>/native-road/compiled.json is the workbench's single read model. layers/ contains generated GeoJSON with source/provenance properties. diagnostics.json contains severity, stable subject ID, source IDs, rule, message, and optional geometry. comparison.json reports counts and coverage against available osm2streets layers; it does not claim quality solely from visual differences.

Browser Workbench

The browser uses no framework or map runtime in v1. A Canvas/SVG map renders fit-to-data OSM centerlines, native surfaces, optional osm2streets reference layers, diagnostics, selected-object provenance, and overrides. This keeps the first interactive path dependency-free and permits precise local coordinates.

The user can select a road or endpoint, edit only v1 fields, inspect the resulting override record, explicitly save it, and recompile/reload. Saved state is visibly differentiated from unsaved state. The workbench must not offer freehand final-polygon editing, since that would break reproducibility.

Geometry And Validation

V1 produces road segments from projected centerline offsets and terminal cross-sections. It only generates a junction surface when endpoints satisfy the supported ordinary T/cross shape and geometry checks; otherwise it emits a diagnostic rather than inventing an invalid polygon. Validation detects dangling endpoints, unclosed/self-intersecting rings, non-finite coordinates, unsupported multi-level intersections, and source/topology ambiguity. Small numerical cleanup may be explicit and recorded; semantic failures are never silently repaired.

Compatibility And Rollout

The first compiler's layers use existing render-layer names where meaningful, but are stored separately. A later, explicitly enabled Blender provider option may consume native layers after comparison gates pass. Delete/replace behavior is out of scope; rollback is selecting the existing osm2streets pipeline.

4.3 KiB Raw Blame History