Route runs along an imported street or duct graph #9

Merged
jaylouisw merged 1 commit from feat/street-routing into main 2026-11-17 21:15:21 +00:00
Owner

What this changes

Issue #7: auto-design measured every run as straight-line distance × routeFactor. It now routes
along an imported street or duct network, and draws it there.

POST /api/import/network   (KML, KMZ or { edges })  → stats + edges
POST /api/design/synthesise { demand, headEnd, network }  → routed plan

The router (engine/street.js)

  1. Graph from KML/KMZ/JSON polylines. Vertices closer than joinToleranceM (1.5 m) are merged.
  2. Planarise: edges are split at vertices that land on their interior. This is the step that
    matters — a side street drawn from the main road has no shared vertex with it, so merging only
    coincident vertices leaves two disconnected components and every property on the side street comes
    back unreachable. That bug was found by the API test and is now pinned by its own case.
  3. Snap each property onto the nearest edge (splitting it), keeping the gap as spurM — the drop
    length. A property is not on the centreline and the design says so.
  4. Route: Dijkstra from the root, then the union of shortest paths to every terminal, pruned to
    the edges that serve one. Walking 40 pairwise routes and adding them up counts the shared trunk 40
    times; the union counts it once. It is not the optimal Steiner tree, and that is stated in the docs.
  5. Contract degree-2 junctions with nothing attached: a 40-vertex polyline is one cable run, with
    the geometry kept as the span's route and the length as one number.

Refactor

Every builder is now a tree over a routing provider (straight-line or street), so both paths share
the tree shape, the cable taper, the budget and the ranking. runs[] gained method and route;
routeMethod reports the network it routed on.

Refusals, not guesses

An address more than maxSnapM (default 250 m) from the network, or disconnected from the head-end,
makes that candidate infeasible naming the address ids — "2 address(es) are not on the street network or not reachable along it: d7, d19" — instead of being joined by a straight line. A head-end off the
network is refused the same way.

How it was verified

npm test                    # 17 suites, 156 assertions, 0 failed
node scripts/smoke-http.js  # all checks passed
node scripts/audit-parts.js # 37 parts validate

Route lengths are asserted against hand arithmetic on a T-shaped network: 69.59 m along the main road

  • 44.53 m up the side street (±5 m), a 14 m spur for a property 14 m off the centreline, and the tree's
    total ≈ 203 m where walking the three routes separately would be ~350 m.

The UI was driven end to end: KML imported through the file input (3 edges, 0.361 km), design run
(street-graph (3 edges, 0.361 km)), winner applied (18 nodes / 17 spans), and the canvas drawing the
detour as a polyline — 507 m straight-line against 577 m routed on the earlier 10-house case, which is
almost exactly the trip to the junction.

What it deliberately does not do

No map download (the graph is what you import — the server makes no outbound requests), no geocoding,
and no turn-by-turn directions. runs[].route is geometry, not navigation.

Closes #7

## What this changes Issue #7: auto-design measured every run as straight-line distance × `routeFactor`. It now routes along an imported street or duct network, and draws it there. ``` POST /api/import/network (KML, KMZ or { edges }) → stats + edges POST /api/design/synthesise { demand, headEnd, network } → routed plan ``` ### The router (`engine/street.js`) 1. **Graph** from KML/KMZ/JSON polylines. Vertices closer than `joinToleranceM` (1.5 m) are merged. 2. **Planarise**: edges are split at vertices that land on their interior. This is the step that matters — a side street drawn *from* the main road has no shared vertex with it, so merging only coincident vertices leaves two disconnected components and every property on the side street comes back unreachable. That bug was found by the API test and is now pinned by its own case. 3. **Snap** each property onto the nearest edge (splitting it), keeping the gap as `spurM` — the drop length. A property is not on the centreline and the design says so. 4. **Route**: Dijkstra from the root, then the **union of shortest paths** to every terminal, pruned to the edges that serve one. Walking 40 pairwise routes and adding them up counts the shared trunk 40 times; the union counts it once. It is not the optimal Steiner tree, and that is stated in the docs. 5. **Contract** degree-2 junctions with nothing attached: a 40-vertex polyline is one cable run, with the geometry kept as the span's `route` and the length as one number. ### Refactor Every builder is now a tree over a **routing provider** (straight-line or street), so both paths share the tree shape, the cable taper, the budget and the ranking. `runs[]` gained `method` and `route`; `routeMethod` reports the network it routed on. ### Refusals, not guesses An address more than `maxSnapM` (default 250 m) from the network, or disconnected from the head-end, makes that candidate infeasible naming the address ids — `"2 address(es) are not on the street network or not reachable along it: d7, d19"` — instead of being joined by a straight line. A head-end off the network is refused the same way. ## How it was verified ``` npm test # 17 suites, 156 assertions, 0 failed node scripts/smoke-http.js # all checks passed node scripts/audit-parts.js # 37 parts validate ``` Route lengths are asserted against hand arithmetic on a T-shaped network: 69.59 m along the main road + 44.53 m up the side street (±5 m), a 14 m spur for a property 14 m off the centreline, and the tree's total ≈ 203 m where walking the three routes separately would be ~350 m. The UI was driven end to end: KML imported through the file input (`3 edges, 0.361 km`), design run (`street-graph (3 edges, 0.361 km)`), winner applied (18 nodes / 17 spans), and the canvas drawing the detour as a polyline — 507 m straight-line against 577 m routed on the earlier 10-house case, which is almost exactly the trip to the junction. ## What it deliberately does not do No map download (the graph is what you import — the server makes no outbound requests), no geocoding, and no turn-by-turn directions. `runs[].route` is geometry, not navigation. Closes #7
feat: route runs along an imported street or duct graph
All checks were successful
CI / Test (Node 18) (pull_request) Successful in 31s
CI / Test (Node 20) (pull_request) Successful in 42s
CI / Server smoke test (pull_request) Successful in 42s
CI / Test (Node 22) (pull_request) Successful in 46s
CI / Docker build (pull_request) Successful in 56s
d0e5f35066
Auto-design measured every run as straight-line distance x routeFactor. This routes it along
real geometry instead, and draws it there.

Added:
- engine/street.js: a graph from KML, KMZ or JSON polylines. Vertices merged within a tolerance;
  edges split at vertices that land on their interior (a T-junction is the normal case in
  imported geometry, and merging only coincident vertices left the side street disconnected);
  properties snapped onto the nearest edge with the gap kept as the drop; Dijkstra; and the union
  of shortest paths from the root, pruned to the edges that serve a terminal and contracted
  between the points a planner actually marks.
- design.synthesise takes a network and switches every candidate to that router. Spans carry
  their street geometry as a route polyline, runs report the method they were measured with, and
  the canvas draws routed spans as polylines.
- POST /api/import/network builds a graph from KML/KMZ/JSON and hands back its stats and edges.
- UI: a street-network file input beside the auto-design controls, with the edge count and length.
- An address more than maxSnapM from the network, or disconnected from the head-end, makes the
  candidate infeasible with the address ids named, instead of being joined by a straight line.

Refactor: the synthesiser is now builders over a routing provider (straight-line or street), so
both paths share the tree, the cable taper, the budget and the ranking.

Fixed: a cluster medoid sits on its splitter site, so its tree edge measured 0 m and the model
refused the span. It is now the 1 m shortest real drop.

17 suites / 156 assertions green; smoke green; the UI driven end to end on a T-junction network
(3 edges, 0.361 km) - routed PON 1:8 applied, 18 nodes / 17 spans, canvas drawing the detour.

Closes #7
jaylouisw deleted branch feat/street-routing 2026-11-17 21:15:22 +00:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/glassforge!9
No description provided.