@mark1russell7/highways 0.2.0 → 0.4.0

package/src/highways/corridors/index.ts

@@ -0,0 +1,305 @@
+import { center, dist, type Point } from "../../geom.ts";
+import { nodeIndex, type Graph, type Route } from "../../model.ts";
+import { placePlug } from "../../plugs.ts";
+import { orderLanes } from "../../segments.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import { memberAt, type Highway, type HighwayInput, type HighwayMember, type HighwayPlan } from "../model.ts";
+
+/**
+ * The options of the highway strategy `corridors` (HWY-031 of the note on highways).
+ * The options `margin` and `k` set the corner graph of the first ways, when the input has no first routes.
+ */
+export interface CorridorOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** Two edges join when their common links are this share of the shorter way, or longer. The default is 0.3. */
+  readonly rho: number;
+  /** A highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+  /** The number of hash functions of the MinHash signature of a way. The default is 64. */
+  readonly hashes: number;
+  /** The number of bands of the signature. Two ways with one equal band are a candidate pair. The default is 32. */
+  readonly bands: number;
+  /** Two link ends nearer than this grid size are one point. With 0, the default, only equal points are one point. */
+  readonly near: number;
+  /** The gap between two lanes. Two edges join only when their common links are longer than the break-even overlap for this gap. The default is 4. */
+  readonly lane: number;
+}
+
+/** The default options of the strategy `corridors`. */
+export const CORRIDOR_DEFAULTS: Readonly<Required<Omit<CorridorOptions, "margin" | "k">>> = Object.freeze({ rho: 0.3, minSize: 2, hashes: 64, bands: 32, near: 0, lane: 4 });
+
+/**
+ * The break-even overlap of two parallel edges for each unit of the lane gap, with the cost exponent 0.5 of the note.
+ * A shared stretch shorter than this times the gap adds ink.
+ */
+export const BREAK_EVEN: number = Math.sqrt((2 + Math.SQRT2) / (2 - Math.SQRT2));
+
+/** One link of a way: its key, its length and its ends in the order of the way. */
+interface Link {
+  readonly key: string;
+  readonly len: number;
+  /** The snapped first end of the link, in the order of the way. */
+  readonly a: string;
+  /** The index of the first end in the points of the way. */
+  readonly at: number;
+}
+
+/** The first way of an edge, with its links. */
+interface Way {
+  readonly edge: string;
+  readonly points: readonly Point[];
+  readonly links: readonly Link[];
+  /** The length of each link, by its key. */
+  readonly set: ReadonlyMap<string, number>;
+  readonly length: number;
+}
+
+/** This function gives the FNV-1a hash of a string, as an unsigned 32-bit number. */
+function fnv1a(text: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** This function mixes the bits of a 32-bit number (the finalizer of MurmurHash3). */
+function mix(x: number): number {
+  let h = x >>> 0;
+  h ^= h >>> 16;
+  h = Math.imul(h, 0x85ebca6b);
+  h ^= h >>> 13;
+  h = Math.imul(h, 0xc2b2ae35);
+  h ^= h >>> 16;
+  return h >>> 0;
+}
+
+/** This function gives the MinHash signature of a set of keys with `count` hash functions. */
+export function minHash(keys: Iterable<string>, count: number): number[] {
+  const sig = new Array<number>(count).fill(0xffffffff);
+  const seeds = Array.from({ length: count }, (_, i) => mix(Math.imul(i + 1, 0x9e3779b9)));
+  for (const key of keys) {
+    const base = fnv1a(key);
+    for (let i = 0; i < count; i++) {
+      const v = mix(base ^ seeds[i]!);
+      if (v < sig[i]!) sig[i] = v;
+    }
+  }
+  return sig;
+}
+
+/**
+ * This function gives the first way of each edge: the way through the corner graph, with the plugs at its ends.
+ * The router `corners` finds the same way before it drops the needless corners.
+ */
+function cornerWays(graph: Graph, options: Pick<WayOptions, "margin" | "k">): Route[] {
+  const byId = nodeIndex(graph);
+  const ways = new WayFinder(graph.nodes, options);
+  const out: Route[] = [];
+  for (const e of graph.edges) {
+    const s = byId.get(e.source.node);
+    const t = byId.get(e.target.node);
+    if (!s || !t) continue;
+    const ps = placePlug(s, e.source, center(t.box));
+    const pt = placePlug(t, e.target, center(s.box));
+    const raw = ways.corners.path(ways.out(ps), ways.out(pt));
+    out.push({ edge: e.id, points: raw ? [ps.point, ...raw, pt.point] : [ps.point, pt.point] });
+  }
+  return out;
+}
+
+/** This function gives the way of a route, with a key for each link. Two links with the same ends, in either order, have one key. */
+function wayOf(route: Route, near: number): Way {
+  const snap = (p: Point): string => (near > 0 ? `${Math.round(p.x / near)},${Math.round(p.y / near)}` : `${p.x},${p.y}`);
+  const links: Link[] = [];
+  const set = new Map<string, number>();
+  let length = 0;
+  for (let i = 1; i < route.points.length; i++) {
+    const p = route.points[i - 1]!;
+    const q = route.points[i]!;
+    const len = dist(p, q);
+    if (len <= 1e-9) continue;
+    const a = snap(p);
+    const b = snap(q);
+    if (a === b) continue;
+    const key = a < b ? `${a}|${b}` : `${b}|${a}`;
+    links.push({ key, len, a, at: i - 1 });
+    if (!set.has(key)) set.set(key, len);
+    length += len;
+  }
+  return { edge: route.edge, points: route.points, links, set, length };
+}
+
+/** This function gives the length of the common links of two ways. */
+function overlap(p: Way, q: Way): number {
+  const [small, large] = p.set.size <= q.set.size ? [p, q] : [q, p];
+  let sum = 0;
+  for (const [key, len] of small.set) if (large.set.has(key)) sum += len;
+  return sum;
+}
+
+/** This function gives the pairs of ways with one equal band of their signatures, as `i * n + j` with `i < j`, in order. */
+function candidates(ways: readonly Way[], hashes: number, bands: number): number[] {
+  const rows = Math.max(1, Math.floor(hashes / Math.max(1, bands)));
+  const count = Math.max(1, Math.floor(hashes / rows));
+  const n = ways.length;
+  const pairs = new Set<number>();
+  const buckets = new Map<string, number[]>();
+  ways.forEach((w, i) => {
+    if (w.set.size === 0) return;
+    const sig = minHash(w.set.keys(), rows * count);
+    for (let b = 0; b < count; b++) {
+      const key = `${b}:${sig.slice(b * rows, (b + 1) * rows).join(",")}`;
+      const list = buckets.get(key);
+      if (list) {
+        for (const j of list) pairs.add(j * n + i);
+        list.push(i);
+      } else buckets.set(key, [i]);
+    }
+  });
+  return [...pairs].sort((a, b) => a - b);
+}
+
+/** This function gives the root of an element of a union-find forest, and shortens the path. */
+function root(parent: number[], i: number): number {
+  while (parent[i] !== i) {
+    parent[i] = parent[parent[i]!]!;
+    i = parent[i]!;
+  }
+  return i;
+}
+
+/**
+ * This function gives the clusters of the ways. Two ways join when their common links are long.
+ * A cluster is a connected part of the joins.
+ * MinHash with bands finds the candidate pairs. The function then measures the overlap of each candidate pair.
+ * Each cluster keeps the order of the ways, and the clusters come in the order of their first way.
+ */
+function corridorClusters(ways: readonly Way[], o: Readonly<CorridorOptions>): number[][] {
+  const n = ways.length;
+  const parent = Array.from({ length: n }, (_, i) => i);
+  const floor = BREAK_EVEN * o.lane;
+  for (const pair of candidates(ways, o.hashes, o.bands)) {
+    const i = Math.floor(pair / n);
+    const j = pair % n;
+    const p = ways[i]!;
+    const q = ways[j]!;
+    if (overlap(p, q) >= Math.max(floor, o.rho * Math.min(p.length, q.length))) {
+      const a = root(parent, i);
+      const b = root(parent, j);
+      if (a !== b) parent[Math.max(a, b)] = Math.min(a, b);
+    }
+  }
+  const groups = new Map<number, number[]>();
+  for (let i = 0; i < n; i++) {
+    const r = root(parent, i);
+    const list = groups.get(r);
+    if (list) list.push(i);
+    else groups.set(r, [i]);
+  }
+  return [...groups.values()].filter((g) => g.length >= 2);
+}
+
+/**
+ * This function gives the highway of a pool of ways, or `undefined`. The core is the way with the most shared length.
+ * The spine is the stretch of the core with the largest saving. Each link of the spine has two ways of the pool or more.
+ * A member is a way of the pool whose links on the spine are long enough, all in one direction.
+ */
+function highwayOf(pool: readonly Way[], o: Readonly<CorridorOptions>): { core: Way; spine: Point[]; members: { way: Way; on: number; off: number }[] } | undefined {
+  const count = new Map<string, number>();
+  for (const w of pool) for (const key of w.set.keys()) count.set(key, (count.get(key) ?? 0) + 1);
+  const gain = (key: string, len: number): number => len * ((count.get(key) ?? 1) - 1);
+  let core: Way | undefined;
+  let best = 0;
+  for (const w of pool) {
+    let g = 0;
+    for (const [key, len] of w.set) g += gain(key, len);
+    if (g > best) [core, best] = [w, g];
+  }
+  if (!core) return undefined;
+  // The best stretch of shared links of the core, by the saving of each link (Kadane on a list with only good values in each stretch).
+  let from = -1;
+  let to = -1;
+  let top = 0;
+  let start = 0;
+  let sum = 0;
+  core.links.forEach((l, i) => {
+    if ((count.get(l.key) ?? 0) < 2) {
+      sum = 0;
+      start = i + 1;
+      return;
+    }
+    sum += gain(l.key, l.len);
+    if (sum > top) [top, from, to] = [sum, start, i];
+  });
+  if (from < 0) return undefined;
+  const chosen = core.links.slice(from, to + 1);
+  // The spine: the first end of each chosen link, then the last end of the last link.
+  const spine: Point[] = [core.points[chosen[0]!.at]!, ...chosen.map((l) => core.points[l.at + 1]!)];
+  const index = new Map<string, number>();
+  chosen.forEach((l, j) => {
+    if (!index.has(l.key)) index.set(l.key, j);
+  });
+  const spineLength = chosen.reduce((s, l) => s + l.len, 0);
+  const floor = BREAK_EVEN * o.lane;
+  const members: { way: Way; on: number; off: number }[] = [];
+  for (const w of pool) {
+    let first = -1;
+    let last = -1;
+    let forward: boolean | undefined;
+    let ok = true;
+    let shared = 0;
+    for (const l of w.links) {
+      const j = index.get(l.key);
+      if (j === undefined) continue;
+      const dir = l.a === chosen[j]!.a;
+      if (forward === undefined) forward = dir;
+      else if (forward !== dir) ok = false;
+      if (first < 0) first = j;
+      else if (forward ? j < last : j > last) ok = false;
+      last = j;
+      shared += l.len;
+    }
+    if (!ok || forward === undefined || shared < Math.max(floor, o.rho * Math.min(w.length, spineLength))) continue;
+    members.push(forward ? { way: w, on: first, off: last + 1 } : { way: w, on: first + 1, off: last });
+  }
+  return { core, spine, members };
+}
+
+/**
+ * This function gives the highways of corridor signatures (HWY-031). Each edge gets a first way: the route of `input.routes`, or its way through the corner graph.
+ * The signature of a way is the set of its links. Two edges join when their common links are at least `rho` times the shorter way, and longer than the break-even overlap.
+ * MinHash with `hashes` hash functions in `bands` bands finds the candidate pairs fast. Union-find gives the clusters.
+ *
+ * In each cluster, the spine is the longest common run of links of the way with the most shared length. Each edge on the spine joins it at its first common link and leaves it at its last one.
+ * The edges of the cluster that are not on the spine make the next highway, while `minSize` of them remain.
+ */
+export function corridorPlan(input: HighwayInput, o: Readonly<CorridorOptions>): HighwayPlan {
+  const routes = input.routes?.routes ?? cornerWays(input.graph, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const known = new Set(input.graph.edges.map((e) => e.id));
+  const ways = routes.filter((r) => known.has(r.edge)).map((r) => wayOf(r, o.near));
+  const highways: Highway[] = [];
+  corridorClusters(ways, o).forEach((cluster, c) => {
+    let pool = cluster.map((i) => ways[i]!);
+    while (pool.length >= Math.max(2, o.minSize)) {
+      const found = highwayOf(pool, o);
+      if (!found) break;
+      const { core, spine, members } = found;
+      if (members.length < Math.max(2, o.minSize)) {
+        // The core does not make a highway. The other ways can still make one.
+        pool = pool.filter((w) => w !== core);
+        continue;
+      }
+      const lanes = orderLanes(spine, members.map((m) => ({ edge: m.way.edge, points: m.way.points })), "bundle");
+      const byEdge = new Map(members.map((m) => [m.way.edge, m]));
+      const list: HighwayMember[] = lanes.map((edge) => {
+        const m = byEdge.get(edge)!;
+        return memberAt(spine, edge, m.on, m.off);
+      });
+      highways.push({ id: `h${highways.length}`, key: `c${c}`, spine, lanes, members: list });
+      const used = new Set(members.map((m) => m.way));
+      pool = pool.filter((w) => !used.has(w));
+    }
+  });
+  return { highways };
+}

package/src/highways/follow.ts

@@ -0,0 +1,155 @@
+import { center, dist, pointBoxDistance, type Point } from "../geom.ts";
+import { fixedPortPoint, nodeIndex, type End, type Graph, type Node, type Result, type Route, type SharedRun } from "../model.ts";
+import { placePlug } from "../plugs.ts";
+import { orderLanes, type RunOrder } from "../segments.ts";
+import { WayFinder, type WayOptions } from "../ways.ts";
+import { pointAt, type HighwayMember, type HighwayPlan } from "./model.ts";
+
+/** The options of `follow`. */
+export interface FollowOptions extends WayOptions {
+  /**
+   * These routes are the routes of the base router. Each edge outside the plan keeps its route from them.
+   * Without them, or for an edge without a route in them, `follow` routes the edge as the router `corners` does.
+   */
+  readonly routes?: Result;
+  /** The lane order of the shared runs. The default is `bundle`. */
+  readonly laneOrder?: RunOrder;
+}
+
+const SAME = 1e-6;
+
+const dedupe = (p: readonly Point[]): Point[] => p.filter((q, i) => i === 0 || dist(q, p[i - 1]!) > SAME);
+
+/** This function tells if a polyline holds the points of `part` in a row, in this order. */
+function holdsInOrder(p: readonly Point[], part: readonly Point[]): boolean {
+  for (let i = 0; i + part.length <= p.length; i++) {
+    let ok = true;
+    for (let j = 0; ok && j < part.length; j++) ok = dist(p[i + j]!, part[j]!) <= SAME;
+    if (ok) return true;
+  }
+  return false;
+}
+
+/** This function tells if a polyline holds the points of `part` in a row, in either direction. */
+const holds = (p: readonly Point[], part: readonly Point[]): boolean => holdsInOrder(p, part) || holdsInOrder(p, [...part].reverse());
+
+/**
+ * This function tells if a point of a spine can be the plug of an end. The point is on the box of the node.
+ * When the end has a fixed plug, the point is at that plug.
+ */
+function plugAt(node: Node, end: End, p: Point): boolean {
+  if (pointBoxDistance(p, node.box) > SAME) return false;
+  const fixed = fixedPortPoint(node, end);
+  return fixed === undefined || dist(fixed, p) <= SAME;
+}
+
+/** The stops of one spine: each point of the spine and each merge point and split point, by their place, in order. */
+type Stops = readonly (readonly [at: number, point: Point])[];
+
+/** This function gives the points of the stops from the place `on` to the place `off`. When `on` is larger than `off`, the points go backward. */
+function slice(stops: Stops, on: number, off: number): Point[] {
+  const lo = Math.min(on, off);
+  const hi = Math.max(on, off);
+  const out = stops.filter(([at]) => at >= lo && at <= hi).map(([, p]) => p);
+  return on <= off ? out : out.reverse();
+}
+
+/**
+ * This function routes the edges along a highway plan.
+ *
+ * An edge of a highway goes from its source plug to its merge point. Then it goes along the spine to its split point, and to its target plug.
+ * The ramps go around the boxes through the corner graph (`WayFinder.fromPlug` and `WayFinder.toPlug`).
+ * A spine point on the box of the node is the plug itself. When the end has a fixed plug, the point is at that plug.
+ *
+ * An edge on several highways takes them in the order of `seq`.
+ * A way through the corner graph goes from each split point to the next merge point.
+ * An edge outside the plan keeps its route from `options.routes`, or goes as in the router `corners`.
+ *
+ * The result has a shared run for each stretch of a spine where the same two edges or more go. Each run holds the points of its routes in a row.
+ * The same graph, plan and options give the same result.
+ */
+export function follow(graph: Graph, plan: HighwayPlan, options: FollowOptions = {}): Result {
+  const byId = nodeIndex(graph);
+  const ways = new WayFinder(graph.nodes, options);
+  const base = new Map((options.routes?.routes ?? []).map((r) => [r.edge, r.points]));
+  const lines: Stops[] = plan.highways.map((h) => {
+    const stops = new Map<number, Point>(h.spine.map((p, i) => [i, p]));
+    for (const m of h.members) for (const at of [m.on, m.off]) if (!stops.has(at)) stops.set(at, pointAt(h.spine, at));
+    return [...stops].sort((a, b) => a[0] - b[0]);
+  });
+  const trips = new Map<string, { h: number; m: HighwayMember }[]>();
+  plan.highways.forEach((h, hi) => {
+    for (const m of h.members) {
+      const list = trips.get(m.edge);
+      if (list) list.push({ h: hi, m });
+      else trips.set(m.edge, [{ h: hi, m }]);
+    }
+  });
+  for (const list of trips.values()) list.sort((a, b) => a.m.seq - b.m.seq || a.h - b.h);
+
+  const routes: Route[] = [];
+  for (const e of graph.edges) {
+    const s = byId.get(e.source.node);
+    const t = byId.get(e.target.node);
+    if (!s || !t) continue;
+    const trip = trips.get(e.id);
+    if (!trip) {
+      const known = base.get(e.id);
+      if (known) {
+        routes.push({ edge: e.id, points: known });
+        continue;
+      }
+      const ps = placePlug(s, e.source, center(t.box));
+      const pt = placePlug(t, e.target, center(s.box));
+      routes.push({ edge: e.id, points: ways.between(ps, pt, new Set<Node>([s, t])) });
+      continue;
+    }
+    const out: Point[] = [];
+    let at: Point | undefined;
+    for (const { h, m } of trip) {
+      const piece = slice(lines[h]!, m.on, m.off);
+      const first = piece[0]!;
+      if (at === undefined) {
+        if (!plugAt(s, e.source, first)) {
+          const ps = placePlug(s, e.source, first);
+          out.push(...(ways.fromPlug(ps, first) ?? [ps.point, first]));
+        }
+      } else if (dist(at, first) > SAME) {
+        const way = ways.corners.path(at, first);
+        out.push(...(way ? ways.corners.pull(way) : [at, first]));
+      }
+      out.push(...piece);
+      at = piece[piece.length - 1]!;
+    }
+    if (at !== undefined && !plugAt(t, e.target, at)) {
+      const pt = placePlug(t, e.target, at);
+      out.push(...(ways.toPlug(at, pt) ?? [at, pt.point]));
+    }
+    routes.push({ edge: e.id, points: dedupe(out) });
+  }
+
+  // The runs: each stretch between two stops of a spine, with the same two edges or more on it, joined with the next stretch of the same edges.
+  const routeOf = new Map(routes.map((r) => [r.edge, r]));
+  const runs: SharedRun[] = [];
+  plan.highways.forEach((h, hi) => {
+    const stops = lines[hi]!;
+    const usersOf = (k: number): string[] =>
+      h.members
+        .filter((m) => routeOf.has(m.edge) && Math.min(m.on, m.off) <= stops[k]![0] && Math.max(m.on, m.off) >= stops[k + 1]![0])
+        .map((m) => m.edge)
+        .sort();
+    let k = 0;
+    while (k < stops.length - 1) {
+      const users = usersOf(k);
+      let end = k + 1;
+      while (end < stops.length - 1 && usersOf(end).join("\u0000") === users.join("\u0000")) end++;
+      const points = dedupe(stops.slice(k, end + 1).map(([, p]) => p));
+      k = end;
+      if (users.length < 2 || points.length < 2) continue;
+      const mine = users.map((id) => routeOf.get(id)!).filter((r) => holds(r.points, points));
+      if (mine.length < 2) continue;
+      runs.push({ id: `r${runs.length}`, key: h.key, points, edges: orderLanes(points, mine, options.laneOrder ?? "bundle") });
+    }
+  });
+  return runs.length > 0 ? { routes, runs } : { routes };
+}

package/src/highways/index.ts

@@ -0,0 +1,7 @@
+export { checkPlan, lengthBetween, memberAt, pointAt, type Highway, type HighwayInput, type HighwayMember, type HighwayPlan } from "./model.ts";
+export { follow, type FollowOptions } from "./follow.ts";
+export { planOfResult } from "./result.ts";
+export { highwayRouter, highwayRouterStrategy } from "./router.ts";
+export { keysPlan, type KeysOptions } from "./keys/index.ts";
+export { sharedWaysPlan, type SharedWaysOptions } from "./shared-ways/index.ts";
+export { BREAK_EVEN, CORRIDOR_DEFAULTS, corridorPlan, minHash, type CorridorOptions } from "./corridors/index.ts";

package/src/highways/keys/index.ts

@@ -0,0 +1,15 @@
+import { trunksRouter, type TrunksOptions } from "../../routers/trunks.ts";
+import { planOfResult } from "../result.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+
+/** The options of the highway strategy `keys`: the options of the router `trunks`, without the name and the limit of the benchmark. */
+export type KeysOptions = Omit<TrunksOptions, "name" | "maxNodes">;
+
+/**
+ * This function gives the highways that the router `trunks` decides. A rule gives each edge a key.
+ * The edges from one plug with one key share a trunk to a split point. The edges that go on together share a run past it.
+ * Each trunk and each run becomes one highway. The function does not change the router: it reads its bundles and its runs.
+ */
+export function keysPlan(input: HighwayInput, options: KeysOptions): HighwayPlan {
+  return planOfResult(trunksRouter({ ...options, name: "keys" }).route(input.graph));
+}

package/src/highways/model.ts

@@ -0,0 +1,111 @@
+import { dist, type Point } from "../geom.ts";
+import type { Graph, Result } from "../model.ts";
+
+/** The input of a highway strategy: the boxes and the edges, and optionally the first routes of a router. */
+export interface HighwayInput {
+  readonly graph: Graph;
+  /**
+   * These routes are the first routes, from a router. A strategy that reads first routes makes them itself when this value is absent.
+   * The strategy `corridors` makes the ways of the corner graph, as the router `corners` finds them.
+   */
+  readonly routes?: Result;
+}
+
+/**
+ * One edge of a highway. The edge joins the spine at the merge point and leaves it at the split point.
+ * A place on the spine is the index of a point of the spine plus the share of the next leg. Point `i` of the spine is at `i`.
+ * When `on` is larger than `off`, the edge goes along the spine from its last point to its first point.
+ */
+export interface HighwayMember {
+  readonly edge: string;
+  /** The place of the merge point on the spine. */
+  readonly on: number;
+  /** The place of the split point on the spine. */
+  readonly off: number;
+  /** The point where the edge joins the spine. */
+  readonly merge: Point;
+  /** The point where the edge leaves the spine. */
+  readonly split: Point;
+  /**
+   * The place of this highway in the trip of the edge, from 0. An edge can go along several highways, one after the other.
+   * `follow` takes the highways of an edge in the order of this value.
+   */
+  readonly seq: number;
+}
+
+/** A highway: a shared way that a bundle of edges follows, from their merge points to their split points. */
+export interface Highway {
+  readonly id: string;
+  /** The key of the highway, for example the key of the grouping rule or the index of a cluster. */
+  readonly key: string;
+  /** The spine: the polyline that the edges follow, in free space. */
+  readonly spine: readonly Point[];
+  /** The edges in lane order. Lane 0 is on the left of the spine, from its first point to its last point. The y axis points down. */
+  readonly lanes: readonly string[];
+  /** The edges with their merge points and their split points, in the order of `lanes`. */
+  readonly members: readonly HighwayMember[];
+}
+
+/** The output of a highway strategy: the highways, as data. `follow` routes the edges along them. */
+export interface HighwayPlan {
+  readonly highways: readonly Highway[];
+}
+
+/** This function gives the point at a place on a polyline. A place outside the polyline gives its nearest end. */
+export function pointAt(line: readonly Point[], at: number): Point {
+  if (line.length === 0) throw new Error("The polyline has no point.");
+  if (at <= 0) return line[0]!;
+  if (at >= line.length - 1) return line[line.length - 1]!;
+  const i = Math.floor(at);
+  const u = at - i;
+  const a = line[i]!;
+  if (u === 0) return a;
+  const b = line[i + 1]!;
+  return { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u };
+}
+
+/** This function gives the length of a polyline from the place `from` to the place `to`, with `from` not larger than `to`. */
+export function lengthBetween(line: readonly Point[], from: number, to: number): number {
+  if (to <= from) return 0;
+  let sum = 0;
+  let prev = pointAt(line, from);
+  for (let i = Math.floor(from) + 1; i < to; i++) {
+    const p = line[i]!;
+    sum += dist(prev, p);
+    prev = p;
+  }
+  return sum + dist(prev, pointAt(line, to));
+}
+
+/** This function gives a member of a highway with its merge point and its split point at the places `on` and `off` of the spine. */
+export function memberAt(spine: readonly Point[], edge: string, on: number, off: number, seq = 0): HighwayMember {
+  return { edge, on, off, merge: pointAt(spine, on), split: pointAt(spine, off), seq };
+}
+
+/**
+ * This function lists the problems of a plan against its graph. A good plan gives an empty list.
+ * Each highway has a spine of two points or more, and two members or more. Each member is an edge of the graph, with `on` and `off` on the spine and apart.
+ * An edge is a member of a highway one time at most.
+ */
+export function checkPlan(graph: Graph, plan: HighwayPlan): string[] {
+  const edges = new Set(graph.edges.map((e) => e.id));
+  const out: string[] = [];
+  const ids = new Set<string>();
+  for (const h of plan.highways) {
+    if (ids.has(h.id)) out.push(`Two highways have the id "${h.id}".`);
+    ids.add(h.id);
+    const last = h.spine.length - 1;
+    if (h.spine.length < 2) out.push(`The highway "${h.id}" has a spine with fewer than two points.`);
+    if (h.members.length < 2) out.push(`The highway "${h.id}" has fewer than two members.`);
+    const seen = new Set<string>();
+    for (const m of h.members) {
+      if (!edges.has(m.edge)) out.push(`The highway "${h.id}" has the member "${m.edge}", which is not an edge of the graph.`);
+      if (seen.has(m.edge)) out.push(`The highway "${h.id}" has the member "${m.edge}" two times.`);
+      seen.add(m.edge);
+      if (!(m.on >= 0 && m.on <= last && m.off >= 0 && m.off <= last)) out.push(`The member "${m.edge}" of the highway "${h.id}" has a place off the spine.`);
+      if (m.on === m.off) out.push(`The member "${m.edge}" of the highway "${h.id}" joins and leaves the spine at one place.`);
+    }
+    if (h.lanes.length !== h.members.length || h.lanes.some((e) => !seen.has(e))) out.push(`The lanes of the highway "${h.id}" are not its members.`);
+  }
+  return out;
+}

package/src/highways/result.ts

@@ -0,0 +1,34 @@
+import type { Result } from "../model.ts";
+import { segmentsOf } from "../segments.ts";
+import { memberAt, type Highway, type HighwayMember, type HighwayPlan } from "./model.ts";
+
+/**
+ * This function gives the highways of a result of a router: one highway for each shared run and for each trunk of a bundle.
+ * The spine is the points of the run or of the trunk. Each edge of the run is a member, from one end of the spine to the other end, in the way of its route.
+ * The member `seq` is the place of the shared stretch in the route of the edge. The lanes keep the lane order of the router.
+ *
+ * Thus `follow` routes each edge along the shared stretches of the router. A route that does not hold its run is not a member.
+ */
+export function planOfResult(result: Result): HighwayPlan {
+  const graph = segmentsOf(result);
+  const keys = new Map<string, string>([...(result.runs ?? []).map((r) => [r.id, r.key] as const), ...(result.bundles ?? []).map((b) => [b.id, b.key] as const)]);
+  const shared = graph.segments.filter((s) => s.count > 1);
+  const ids = new Set(shared.map((s) => s.id));
+  const place = new Map<string, { seq: number; reverse: boolean }>();
+  for (const path of graph.paths) {
+    let seq = 0;
+    for (const ref of path.segments) if (ids.has(ref.segment)) place.set(`${ref.segment}\u0000${path.edge}`, { seq: seq++, reverse: ref.reverse });
+  }
+  const highways: Highway[] = [];
+  for (const s of shared) {
+    const last = s.points.length - 1;
+    const members: HighwayMember[] = [];
+    for (const edge of s.edges) {
+      const at = place.get(`${s.id}\u0000${edge}`);
+      if (at) members.push(at.reverse ? memberAt(s.points, edge, last, 0, at.seq) : memberAt(s.points, edge, 0, last, at.seq));
+    }
+    if (members.length < 2) continue;
+    highways.push({ id: `h${highways.length}`, key: keys.get(s.id) ?? s.id, spine: s.points, lanes: members.map((m) => m.edge), members });
+  }
+  return { highways };
+}

package/src/highways/router.ts

@@ -0,0 +1,40 @@
+import type { Graph, Result, Router } from "../model.ts";
+import { defineStrategy, type Strategy } from "../strategies/model.ts";
+import type { WayOptions } from "../ways.ts";
+import { follow, type FollowOptions } from "./follow.ts";
+
+/** This function gives the options of the way finder in the options of a strategy: `margin` and `k`, when they are present. */
+function wayOptionsOf(options: object): WayOptions {
+  const o = options as { margin?: unknown; k?: unknown };
+  return { ...(typeof o.margin === "number" ? { margin: o.margin } : {}), ...(typeof o.k === "number" ? { k: o.k } : {}) };
+}
+
+/**
+ * This function gives a router that runs a highway strategy and then `follow`. The strategy gets the graph without first routes.
+ * The way finder of `follow` takes `margin` and `k` from the options of the strategy, and then from `followOptions`.
+ * The router keeps the name and the `maxNodes` of the strategy.
+ */
+export function highwayRouter<O extends object>(strategy: Strategy<"highway", O>, options?: Partial<O>, followOptions: FollowOptions = {}): Router {
+  return {
+    name: strategy.name,
+    ...(strategy.maxNodes === undefined ? {} : { maxNodes: strategy.maxNodes }),
+    route: (graph: Graph): Result => follow(graph, strategy.run({ graph }, options), { ...followOptions, ...wayOptionsOf({ ...strategy.defaults, ...options }) }),
+  };
+}
+
+/**
+ * This function gives a router strategy that runs a highway strategy and then `follow`.
+ * The router strategy has the name, the options and the schema of the highway strategy.
+ * The benchmark and the screen race such a router with the other routers.
+ */
+export function highwayRouterStrategy<O extends object>(strategy: Strategy<"highway", O>): Strategy<"router", O> {
+  return defineStrategy<"router", O>({
+    step: "router",
+    name: strategy.name,
+    describe: strategy.describe,
+    defaults: strategy.defaults as O,
+    ...(strategy.schema === undefined ? {} : { schema: strategy.schema }),
+    ...(strategy.maxNodes === undefined ? {} : { maxNodes: strategy.maxNodes }),
+    run: (graph: Graph, options: Readonly<O>): Result => follow(graph, strategy.run({ graph }, options), wayOptionsOf(options)),
+  });
+}