101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# 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/`.
|
|
|
|
```text
|
|
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.
|