@mark1russell7/highways 0.8.1 → 0.9.1

package/src/highways/interchanges/index.ts

@@ -0,0 +1,231 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { orderLanes } from "../../segments.ts";
+import { WayFinder } from "../../ways.ts";
+import { basePlan, firstRoutes, nearestPlace, tidyPlan } from "../base.ts";
+import { lengthBetween, memberAt, pointAt, type Highway, type HighwayInput, type HighwayMember, type HighwayPlan } from "../model.ts";
+import { spinePart } from "../snap.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The plan that gives the highways of the network: the plan of `corridors` or of `shared-ways`, with their defaults. */
+export type InterchangeBase = "corridors" | "shared-ways";
+
+/** The values of `InterchangeBase`. */
+export const INTERCHANGE_BASES: readonly InterchangeBase[] = Object.freeze(["corridors", "shared-ways"]);
+
+/** The options of the highway strategy `interchanges` (HWY-060 of the note on highways). */
+export interface InterchangeOptions {
+  /** The plan that gives the highways. The default is `corridors`. */
+  readonly from: InterchangeBase;
+  /** The cost of a change between two highways, in units of the board, from 0 to 8. The default is 2. */
+  readonly changeCost: number;
+  /** The largest number of interchanges, from 1 to 32. The default is 16. */
+  readonly interchanges: number;
+  /** The largest number of highways on the way of one edge, from 1 to 3. The default is 2. */
+  readonly perEdge: number;
+  /** Two highways get an interchange where they come this near, in units of the board. The default is 2. */
+  readonly radius: number;
+  /** The cost of a length on a highway against a length off the highways, from 0.1 to 1. The default is 0.5. */
+  readonly discount: number;
+  /** An edge rides the network only when its way is this many times its first route or less. The default is 1.5. */
+  readonly detour: number;
+}
+
+/** The default options of the strategy `interchanges`. */
+export const INTERCHANGE_DEFAULTS: Readonly<InterchangeOptions> = Object.freeze({ from: "corridors", changeCost: 2, interchanges: 16, perEdge: 2, radius: 2, discount: 0.5, detour: 1.5 });
+
+/** The largest number of candidate interchanges of the first pass. */
+const MAX_CANDIDATES = 64;
+
+/** One interchange: a place on the highway `h`, a place on the highway `g`, and the length of the link between the two places. */
+export interface Interchange {
+  readonly h: number;
+  readonly hAt: number;
+  readonly g: number;
+  readonly gAt: number;
+  readonly gap: number;
+}
+
+/** The nearest points of the segments `a b` and `c d`, as the parameters `s` and `t` from 0 to 1, with their distance. */
+function nearestOfSegments(a: Point, b: Point, c: Point, d: Point): { s: number; t: number; d: number } {
+  const ux = b.x - a.x;
+  const uy = b.y - a.y;
+  const vx = d.x - c.x;
+  const vy = d.y - c.y;
+  const at = (s: number, t: number): number => {
+    const dx = a.x + s * ux - (c.x + t * vx);
+    const dy = a.y + s * uy - (c.y + t * vy);
+    // `Math.sqrt` is exact on each platform. `Math.hypot` is not.
+    return Math.sqrt(dx * dx + dy * dy);
+  };
+  const clamp = (v: number): number => Math.min(1, Math.max(0, v));
+  const uu = ux * ux + uy * uy;
+  const vv = vx * vx + vy * vy;
+  const project = (p: Point, q: Point, x: number, y: number, len: number): number => (len > 0 ? clamp(((p.x - q.x) * x + (p.y - q.y) * y) / len) : 0);
+  // The four ends against the other segment, and the crossing point, give the nearest pair.
+  const tries: [number, number][] = [
+    [0, project(a, c, vx, vy, vv)],
+    [1, project(b, c, vx, vy, vv)],
+    [project(c, a, ux, uy, uu), 0],
+    [project(d, a, ux, uy, uu), 1],
+  ];
+  const den = ux * vy - uy * vx;
+  if (Math.abs(den) > 1e-12) {
+    const s = ((c.x - a.x) * vy - (c.y - a.y) * vx) / den;
+    const t = ((c.x - a.x) * uy - (c.y - a.y) * ux) / den;
+    if (s >= 0 && s <= 1 && t >= 0 && t <= 1) tries.push([s, t]);
+  }
+  let best = { s: 0, t: 0, d: Infinity };
+  for (const [s, t] of tries) {
+    const v = at(s, t);
+    if (v < best.d - 1e-12) best = { s, t, d: v };
+  }
+  return best;
+}
+
+/** This function gives the candidate interchanges: the nearest places of each pair of spines that come within `radius`, with a link in clear view. */
+export function interchangeCandidates(spines: readonly (readonly Point[])[], radius: number, clear: (a: Point, b: Point) => boolean): Interchange[] {
+  const out: Interchange[] = [];
+  for (let h = 0; h < spines.length; h++) {
+    for (let g = h + 1; g < spines.length; g++) {
+      const p = spines[h]!;
+      const q = spines[g]!;
+      let best: Interchange | undefined;
+      for (let i = 0; i + 1 < p.length; i++) {
+        for (let j = 0; j + 1 < q.length; j++) {
+          const n = nearestOfSegments(p[i]!, p[i + 1]!, q[j]!, q[j + 1]!);
+          if (n.d <= radius && (!best || n.d < best.gap - 1e-12)) best = { h, hAt: i + n.s, g, gAt: j + n.t, gap: n.d };
+        }
+      }
+      if (best && (best.gap <= 1e-9 || clear(pointAt(p, best.hAt), pointAt(q, best.gAt)))) out.push(best);
+    }
+  }
+  return out.sort((x, y) => x.gap - y.gap || x.h - y.h || x.g - y.g).slice(0, MAX_CANDIDATES);
+}
+
+/** One leg of the way of an edge: the highway and its two places. */
+interface Leg {
+  readonly h: number;
+  readonly on: number;
+  readonly off: number;
+}
+
+/** The best way of one edge over the network, with the interchanges that it uses. */
+interface Trip {
+  readonly legs: readonly Leg[];
+  readonly used: readonly number[];
+}
+
+/**
+ * This function gives the highways of a network with interchanges (HWY-060). The highways come from a plan. Two highways that come near get an interchange.
+ * Each edge takes its cheapest way: a ride on one highway, or on up to `perEdge` highways with a change at an interchange.
+ * A change costs `changeCost` units. The interchanges that the most edges use stay, up to `interchanges`.
+ */
+export function interchangePlan(input: HighwayInput, o: Readonly<InterchangeOptions>): HighwayPlan {
+  const graph = input.graph;
+  const base = basePlan(input, o.from);
+  const spines = base.highways.map((h) => h.spine);
+  if (spines.length === 0) return { highways: [] };
+  const finder = new WayFinder(graph.nodes);
+  const pad = finder.margin / 2;
+  const unit = boardUnit(graph);
+  const first = firstRoutes(input);
+  const change = Math.max(0, o.changeCost) * unit;
+  const perEdge = Math.min(3, Math.max(1, Math.round(o.perEdge)));
+  const disc = Math.min(1, Math.max(0.05, o.discount));
+  const ride = (h: number, a: number, b: number): number => lengthBetween(spines[h]!, Math.min(a, b), Math.max(a, b));
+  const edges = edgePlugs(graph).map((p) => {
+    const s = finder.out(p.ps);
+    const t = finder.out(p.pt);
+    const route = first.get(p.edge.id);
+    const ends = spines.map((spine) => {
+      const on = nearestPlace(spine, s);
+      const off = nearestPlace(spine, t);
+      return { on, off, rampIn: dist(s, pointAt(spine, on)), rampOut: dist(pointAt(spine, off), t) };
+    });
+    return { edge: p.edge.id, s, t, base: route ? polylineLength(route) : dist(s, t), ends };
+  });
+
+  // The cheapest way of one edge over the interchanges `list`. The cost counts a ride at `disc` times its length. Each leg is one margin long or more.
+  const tripOf = (e: (typeof edges)[number], list: readonly Interchange[]): Trip | undefined => {
+    const found: { cost: number; trip: Trip | undefined } = { cost: Infinity, trip: undefined };
+    const offer = (cost: number, length: number, trip: Trip): void => {
+      if (trip.legs.some((l) => ride(l.h, l.on, l.off) < finder.margin)) return;
+      if (cost >= e.base || length > o.detour * e.base) return;
+      if (cost < found.cost - 1e-9) [found.cost, found.trip] = [cost, trip];
+    };
+    spines.forEach((_, h) => {
+      const x = e.ends[h]!;
+      const r = ride(h, x.on, x.off);
+      offer(x.rampIn + disc * r + x.rampOut, x.rampIn + r + x.rampOut, { legs: [{ h, on: x.on, off: x.off }], used: [] });
+    });
+    if (perEdge < 2) return found.trip;
+    // Each interchange, in both directions: on `p` at its place `pAt`, then off at the place `qAt` of `q`.
+    const sides = list.flatMap((c, i) => [
+      { i, p: c.h, pAt: c.hAt, q: c.g, qAt: c.gAt, gap: c.gap },
+      { i, p: c.g, pAt: c.gAt, q: c.h, qAt: c.hAt, gap: c.gap },
+    ]);
+    for (const a of sides) {
+      const x = e.ends[a.p]!;
+      const y = e.ends[a.q]!;
+      const r1 = ride(a.p, x.on, a.pAt);
+      const r2 = ride(a.q, a.qAt, y.off);
+      offer(x.rampIn + disc * (r1 + r2) + a.gap + change + y.rampOut, x.rampIn + r1 + r2 + a.gap + y.rampOut, {
+        legs: [
+          { h: a.p, on: x.on, off: a.pAt },
+          { h: a.q, on: a.qAt, off: y.off },
+        ],
+        used: [a.i],
+      });
+      if (perEdge < 3) continue;
+      for (const b of sides) {
+        if (b.p !== a.q || b.q === a.p || b.i === a.i) continue;
+        const z = e.ends[b.q]!;
+        const r3 = ride(a.q, a.qAt, b.pAt);
+        const r4 = ride(b.q, b.qAt, z.off);
+        offer(x.rampIn + disc * (r1 + r3 + r4) + a.gap + b.gap + 2 * change + z.rampOut, x.rampIn + r1 + r3 + r4 + a.gap + b.gap + z.rampOut, {
+          legs: [
+            { h: a.p, on: x.on, off: a.pAt },
+            { h: a.q, on: a.qAt, off: b.pAt },
+            { h: b.q, on: b.qAt, off: z.off },
+          ],
+          used: [a.i, b.i],
+        });
+      }
+    }
+    return found.trip;
+  };
+
+  const clear = (a: Point, b: Point): boolean => finder.obstacles.clear(a, b, pad);
+  const candidates = interchangeCandidates(spines, Math.max(0, o.radius) * unit, clear);
+  // The first pass counts the edges at each candidate. The busiest candidates stay for the second pass.
+  const use = new Array<number>(candidates.length).fill(0);
+  for (const e of edges) for (const i of tripOf(e, candidates)?.used ?? []) use[i] = use[i]! + 1;
+  const kept = candidates
+    .map((c, i) => ({ c, i, n: use[i]! }))
+    .filter((x) => x.n > 0)
+    .sort((x, y) => y.n - x.n || x.i - y.i)
+    .slice(0, Math.max(1, Math.round(o.interchanges)))
+    .sort((x, y) => x.i - y.i)
+    .map((x) => x.c);
+
+  const riders = spines.map(() => [] as { edge: string; on: number; off: number; seq: number; points: Point[] }[]);
+  for (const e of edges) {
+    const trip = tripOf(e, kept);
+    if (!trip) continue;
+    trip.legs.forEach((l, seq) => riders[l.h]!.push({ edge: e.edge, on: l.on, off: l.off, seq, points: [e.s, ...spinePart(spines[l.h]!, l.on, l.off), e.t] }));
+  }
+  const highways: Highway[] = [];
+  spines.forEach((spine, h) => {
+    const list = riders[h]!;
+    if (list.length < 2) return;
+    const lanes = orderLanes(spine, list.map((r) => ({ edge: r.edge, points: r.points })), "bundle");
+    const byEdge = new Map(list.map((r) => [r.edge, r]));
+    const members: HighwayMember[] = lanes.map((edge) => {
+      const r = byEdge.get(edge)!;
+      return memberAt(spine, edge, r.on, r.off, r.seq);
+    });
+    highways.push({ id: `h${h}`, key: base.highways[h]!.key, spine, lanes, members });
+  });
+  return tidyPlan({ highways });
+}

package/src/highways/search/index.ts

@@ -0,0 +1,170 @@
+import { ambiguity, bundleStretch, inkSaved, mergeAngle } from "../../bench/measures/bundles.ts";
+import type { Point } from "../../geom.ts";
+import type { Graph, Route } from "../../model.ts";
+import { WayFinder } from "../../ways.ts";
+import { nearestPlace, orderAlongRoutes, tidyPlan, firstRoutes } from "../base.ts";
+import { follow } from "../follow.ts";
+import { memberAt, type Highway, type HighwayInput, type HighwayPlan } from "../model.ts";
+import { candidatePlan, type CandidateSource } from "../select/index.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The options of the highway strategy `search` (HWY-059 of the note on highways). */
+export interface SearchOptions {
+  /** The plan where the search starts. The default is `corridors`. */
+  readonly from: CandidateSource;
+  /** The generators of the highways that the move `add` takes. The default is `quickbundles` and `road-classes`. */
+  readonly pool: readonly CandidateSource[];
+  /** The number of plans that the search measures, from 0 to 400. The value 0 gives the start plan. The default is 16. */
+  readonly evaluations: number;
+  /** The first temperature of the annealing, on the scale of the score. Each sweep of 4 moves multiplies it by 0.95. The default is 0.02. */
+  readonly temperature: number;
+  /** The weight of the ink that the routes save (B1). The default is 1. */
+  readonly inkWeight: number;
+  /** The weight of the 0.95 quantile of the stretch against the first routes (B3). The default is 0.5. */
+  readonly stretchWeight: number;
+  /** The weight of the ambiguity (B4). The default is 0.5. */
+  readonly ambiguityWeight: number;
+  /** The weight of the largest merge angle (B6), divided by 180 degrees. The default is 0.25. */
+  readonly angleWeight: number;
+  /** The seed of the moves. The default is 1. */
+  readonly seed: number;
+}
+
+/** The default options of the strategy `search`. */
+export const SEARCH_DEFAULTS: Readonly<SearchOptions> = Object.freeze({
+  from: "corridors",
+  pool: Object.freeze(["quickbundles", "road-classes"] as CandidateSource[]),
+  evaluations: 16,
+  temperature: 0.02,
+  inkWeight: 1,
+  stretchWeight: 0.5,
+  ambiguityWeight: 0.5,
+  angleWeight: 0.25,
+  seed: 1,
+});
+
+/** The moves of the search. */
+export type SearchMove = "add" | "drop" | "edge" | "point";
+
+/** The values of `SearchMove`, in the order of the draw. */
+export const SEARCH_MOVES: readonly SearchMove[] = Object.freeze(["add", "drop", "edge", "point"]);
+
+/** The number of moves of one sweep of the annealing. */
+const SWEEP = 4;
+
+/** This function gives a seeded random source with values from 0 to 1 (mulberry32). */
+function random(seed: number): () => number {
+  let a = Math.floor(seed) >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * This function gives the score of the routes of a plan: `w1 B1 - w3 B3 - w4 B4 - w6 B6 / 180`. Higher is better.
+ * B3 is the 0.95 quantile of the stretch against the first routes. The score reads only the graph and the routes of the plan.
+ */
+export function searchScore(graph: Graph, routes: readonly Route[], first: readonly Route[], o: Readonly<SearchOptions>): number {
+  const ink = inkSaved(routes);
+  const stretch = bundleStretch(routes, first).q95;
+  const amb = o.ambiguityWeight > 0 ? ambiguity(graph, routes).value : 0;
+  const angle = o.angleWeight > 0 ? mergeAngle(routes) / 180 : 0;
+  return o.inkWeight * ink - o.stretchWeight * stretch - o.ambiguityWeight * amb - o.angleWeight * angle;
+}
+
+/**
+ * The function `acceptance` gives the chance to keep a worse plan, for a loss `y` of 0 or more on the scale of the temperature.
+ * It is `1 / (1 + y + y² / 2)`, near `exp(-y)` for a small loss.
+ * It uses only exact arithmetic, so each platform keeps the same plans.
+ */
+function acceptance(y: number): number {
+  return 1 / (1 + y + (y * y) / 2);
+}
+
+/**
+ * This function gives the highways of a local search over the set of highways (HWY-059). The search starts at the plan of `from`.
+ * Each move adds a highway of the pool, drops a highway, moves one edge to another highway, or moves one point of a spine.
+ * The annealing keeps a worse plan with the chance `acceptance(-delta / T)`. The best plan that the search measures is the result.
+ *
+ * The score reads only this graph and its routes. Thus the search does not fit to the inputs of a screen.
+ */
+export function searchPlan(input: HighwayInput, o: Readonly<SearchOptions>): HighwayPlan {
+  const graph = input.graph;
+  const start = tidyPlan(candidatePlan(input, o.from));
+  const budget = Math.max(0, Math.floor(o.evaluations));
+  if (budget === 0 || graph.edges.length === 0) return start;
+  const pool: Highway[] = [];
+  for (const source of o.pool) if (source !== o.from) pool.push(...candidatePlan(input, source).highways);
+  const finder = new WayFinder(graph.nodes);
+  const pad = finder.margin / 2;
+  const plugs = new Map(edgePlugs(graph).map((p) => [p.edge.id, p] as const));
+  const routes = firstRoutes(input);
+  const first = follow(graph, { highways: [] }).routes;
+  const scoreOf = (plan: HighwayPlan): number => searchScore(graph, follow(graph, plan).routes, first, o);
+  const next = random(o.seed);
+  const pick = <T>(list: readonly T[]): T => list[Math.floor(next() * list.length) % list.length]!;
+  const tidy = (highways: Highway[]): HighwayPlan => tidyPlan(orderAlongRoutes({ highways }, routes));
+
+  /** This function gives the plan after one move, or `undefined` when the move does not apply. */
+  const moved = (plan: HighwayPlan, move: SearchMove): HighwayPlan | undefined => {
+    const list = [...plan.highways];
+    if (move === "add") {
+      const known = new Set(list.map((h) => h.spine.map((p) => `${p.x},${p.y}`).join(";")));
+      const fresh = pool.filter((h) => !known.has(h.spine.map((p) => `${p.x},${p.y}`).join(";")));
+      if (fresh.length === 0) return undefined;
+      return tidy([...list, pick(fresh)]);
+    }
+    if (list.length === 0) return undefined;
+    const i = Math.floor(next() * list.length) % list.length;
+    const h = list[i]!;
+    if (move === "drop") return tidy(list.filter((_, j) => j !== i));
+    if (move === "edge") {
+      // One member leaves its highway and rides the nearest other highway that does not carry it.
+      if (list.length < 2 || h.members.length < 3) return undefined;
+      const m = pick(h.members);
+      const plug = plugs.get(m.edge);
+      if (!plug) return undefined;
+      const others = list.map((g, j) => ({ g, j })).filter((x) => x.j !== i && !x.g.members.some((y) => y.edge === m.edge));
+      if (others.length === 0) return undefined;
+      const s = plug.ps.point;
+      const t = plug.pt.point;
+      const to = pick(others);
+      const on = nearestPlace(to.g.spine, s);
+      const off = nearestPlace(to.g.spine, t);
+      if (Math.abs(on - off) < 1e-6) return undefined;
+      list[i] = { ...h, members: h.members.filter((y) => y.edge !== m.edge), lanes: h.lanes.filter((e) => e !== m.edge) };
+      list[to.j] = { ...to.g, members: [...to.g.members, memberAt(to.g.spine, m.edge, on, off, m.seq)], lanes: [...to.g.lanes, m.edge] };
+      return tidy(list);
+    }
+    // The move `point`: one point of the spine moves by two margins on one axis, when the spine stays in clear view.
+    const k = Math.floor(next() * h.spine.length) % h.spine.length;
+    const step = 2 * finder.margin * (next() < 0.5 ? -1 : 1);
+    const p = h.spine[k]!;
+    const q: Point = next() < 0.5 ? { x: p.x + step, y: p.y } : { x: p.x, y: p.y + step };
+    const spine = h.spine.map((x, j) => (j === k ? q : x));
+    if (!finder.obstacles.clearPath(spine, pad)) return undefined;
+    list[i] = { ...h, spine, members: h.members.map((m) => memberAt(spine, m.edge, m.on, m.off, m.seq)) };
+    return tidy(list);
+  };
+
+  let current = start;
+  let currentScore = scoreOf(start);
+  let best = start;
+  let bestScore = currentScore;
+  let temperature = Math.max(0, o.temperature);
+  for (let n = 1, tries = 0; n < budget && tries < 4 * budget; tries++) {
+    const plan = moved(current, pick(SEARCH_MOVES));
+    if (!plan) continue;
+    n++;
+    const score = scoreOf(plan);
+    const delta = score - currentScore;
+    if (delta >= 0 || (temperature > 0 && next() < acceptance(-delta / temperature))) [current, currentScore] = [plan, score];
+    if (score > bestScore + 1e-12) [best, bestScore] = [plan, score];
+    if (n % SWEEP === 0) temperature *= 0.95;
+  }
+  return best;
+}

package/src/highways/snap.ts

@@ -28,6 +28,8 @@ export interface SnapLine {
 export interface SnapOptions extends Pick<WayOptions, "margin" | "k"> {
   /** A highway has this number of edges or more. The value is 2 or more. */
   readonly minSize: number;
+  /** With `true`, a line in clear view is its own spine, with no path through the corner graph. The default is `false`. */
+  readonly direct?: boolean;
 }
 
 /** This function gives the line `u d + rho n` of the direction angle `theta`, with `d = (cos, sin)` and the normal `n = (-sin, cos)`. */
@@ -61,9 +63,9 @@ export function snapPlan(input: HighwayInput, lines: readonly SnapLine[], o: Rea
     const a = free(line.a);
     const b = free(line.b);
     if (dist(a, b) <= finder.margin) continue;
-    const raw = corners.path(a, b);
+    const raw = o.direct === true && finder.obstacles.clear(a, b, pad) ? [a, b] : corners.path(a, b);
     if (!raw) continue;
-    const spine = corners.pull(raw);
+    const spine = o.direct === true && raw.length === 2 ? raw : corners.pull(raw);
     if (spine.length < 2 || polylineLength(spine) <= 1e-6) continue;
     const riders: { edge: string; on: number; off: number; points: Point[] }[] = [];
     for (const m of line.members) {

package/src/highways/soft-keys/index.ts

@@ -1,5 +1,5 @@
 import type { GroupRule } from "../../model.ts";
-import { byCollection } from "../../routers/trunks.ts";
+import { byCollection, groupRuleOf, type GroupRuleName } from "../../routers/trunks.ts";
 import { chainClusters, flowDistance, type Linkage } from "../flow-clusters/index.ts";
 import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
 import type { HighwayInput, HighwayPlan } from "../model.ts";
@@ -7,8 +7,11 @@ import { edgePlugs } from "../stretches.ts";
 
 /** The options of the highway strategy `soft-keys` (HWY-019 of the note on highways). */
 export interface SoftKeyOptions {
-  /** The rule that gives the key of each edge. The default is `byCollection`: the string `data.collection`. */
-  readonly rule: GroupRule;
+  /**
+   * The rule that gives the key of each edge, or the name of a built-in rule (`GROUP_RULE_NAMES`). The default is `byCollection`: the string `data.collection`.
+   * With `all`, each edge has one key, so the keys add no distance.
+   */
+  readonly rule: GroupRule | GroupRuleName;
   /** The distance that two different keys add. `Infinity` keeps the edges of two keys apart, as the hard keys do. The default is 0.25. */
   readonly lambda: number;
   /** Two clusters join while their distance is this value or less. The default is 0.5. */
@@ -54,11 +57,12 @@ export function softDistance(geom: number, keyA: string | undefined, keyB: strin
  * Each edge of a cluster gets the key of the cluster. It gets `flip` when it goes opposite to the first edge of the cluster.
  */
 export function softKeyClusters(input: HighwayInput, o: Readonly<SoftKeyOptions>): Map<string, EdgeGroup> {
+  const rule = groupRuleOf(o.rule);
   const ends = edgePlugs(input.graph).map(({ edge, ps, pt }) => ({
     edge: edge.id,
     s: ps.point,
     t: pt.point,
-    key: o.rule(edge),
+    key: rule(edge),
     values: o.attributes.map((a) => {
       const v = edge.data?.[a];
       return typeof v === "number" && Number.isFinite(v) ? v : undefined;

package/src/highways/steiner/index.ts

@@ -0,0 +1,215 @@
+import { polylineLength, type Point } from "../../geom.ts";
+import { byCollection } from "../../routers/trunks.ts";
+import { WayFinder } from "../../ways.ts";
+import { firstRoutes } from "../base.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs, sharedStretches, type KeyedWay } from "../stretches.ts";
+
+/** The groups of the trees: the edges from one source node, or the edges of one collection. */
+export type SteinerGroup = "source" | "key";
+
+/** The values of `SteinerGroup`. */
+export const STEINER_GROUPS: readonly SteinerGroup[] = Object.freeze(["source", "key"]);
+
+/** The method of the tree: the iterated 1-Steiner method on the Hanan grid, or the spanning tree of the terminals alone. */
+export type SteinerMethod = "one-steiner" | "spanning";
+
+/** The values of `SteinerMethod`. */
+export const STEINER_METHODS: readonly SteinerMethod[] = Object.freeze(["one-steiner", "spanning"]);
+
+/** The metric of the tree: rectilinear (two directions) or octilinear (four directions). */
+export type SteinerMetric = "rectilinear" | "octilinear";
+
+/** The values of `SteinerMetric`. */
+export const STEINER_METRICS: readonly SteinerMetric[] = Object.freeze(["rectilinear", "octilinear"]);
+
+/** The options of the highway strategy `steiner` (HWY-036 of the note on highways, with EDA-015). */
+export interface SteinerOptions {
+  /** The groups of the trees. The default is `source`. */
+  readonly group: SteinerGroup;
+  /** The method of the tree. The default is `one-steiner`. */
+  readonly method: SteinerMethod;
+  /** A group with more terminals than this number gets the spanning tree alone. The default is 12. */
+  readonly maxGroup: number;
+  /** The metric of the tree. The default is `rectilinear`. */
+  readonly metric: SteinerMetric;
+  /** An edge rides the tree only when its path in the tree is this many times its first route or less. The default is 1.5. */
+  readonly detour: number;
+  /** A stretch of a tree with fewer edges than this number is not a highway. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `steiner`. */
+export const STEINER_DEFAULTS: Readonly<SteinerOptions> = Object.freeze({ group: "source", method: "one-steiner", maxGroup: 12, metric: "rectilinear", detour: 1.5, minSize: 2 });
+
+/** This function gives the distance of two points in the metric. */
+function metricDistance(a: Point, b: Point, metric: SteinerMetric): number {
+  const dx = Math.abs(a.x - b.x);
+  const dy = Math.abs(a.y - b.y);
+  return metric === "rectilinear" ? dx + dy : Math.max(dx, dy) + (Math.SQRT2 - 1) * Math.min(dx, dy);
+}
+
+/** This function gives the links of the spanning tree of the points (Prim), as pairs of indices, and the sum of their lengths. */
+export function spanningTree(points: readonly Point[], metric: SteinerMetric): { links: [number, number][]; cost: number } {
+  const n = points.length;
+  if (n < 2) return { links: [], cost: 0 };
+  const inTree = new Uint8Array(n);
+  const best = new Float64Array(n).fill(Infinity);
+  const from = new Int32Array(n).fill(-1);
+  best[0] = 0;
+  const links: [number, number][] = [];
+  let cost = 0;
+  for (let k = 0; k < n; k++) {
+    let u = -1;
+    for (let i = 0; i < n; i++) if (!inTree[i] && (u < 0 || best[i]! < best[u]!)) u = i;
+    inTree[u] = 1;
+    if (from[u]! >= 0) {
+      links.push([from[u]!, u]);
+      cost += best[u]!;
+    }
+    for (let i = 0; i < n; i++) {
+      if (inTree[i]) continue;
+      const d = metricDistance(points[u]!, points[i]!, metric);
+      if (d < best[i]!) {
+        best[i] = d;
+        from[i] = u;
+      }
+    }
+  }
+  return { links, cost };
+}
+
+/**
+ * This function gives a Steiner tree of the terminals by the iterated 1-Steiner method (Kahng and Robins). The candidates are the points of the Hanan grid.
+ * Each round adds the candidate that makes the spanning tree shortest, and drops each added point with two links or fewer.
+ * The test `free` removes the candidates in the boxes. The result has the terminals first, then the added points.
+ */
+export function oneSteiner(terminals: readonly Point[], metric: SteinerMetric, free: (p: Point) => boolean): { points: Point[]; links: [number, number][] } {
+  const points = [...terminals];
+  const xs = [...new Set(terminals.map((p) => p.x))].sort((a, b) => a - b);
+  const ys = [...new Set(terminals.map((p) => p.y))].sort((a, b) => a - b);
+  const taken = new Set(terminals.map((p) => `${p.x},${p.y}`));
+  const candidates: Point[] = [];
+  for (const x of xs) for (const y of ys) if (!taken.has(`${x},${y}`) && free({ x, y })) candidates.push({ x, y });
+  let tree = spanningTree(points, metric);
+  for (let round = 0; round < terminals.length; round++) {
+    let best = -1;
+    let bestCost = tree.cost - 1e-9 * Math.max(1, tree.cost);
+    candidates.forEach((c, i) => {
+      const cost = spanningTree([...points, c], metric).cost;
+      if (cost < bestCost) [best, bestCost] = [i, cost];
+    });
+    if (best < 0) break;
+    points.push(candidates[best]!);
+    candidates.splice(best, 1);
+    tree = spanningTree(points, metric);
+    // An added point with two links or fewer saves nothing, so it leaves the tree.
+    for (;;) {
+      const degree = new Array<number>(points.length).fill(0);
+      for (const [a, b] of tree.links) {
+        degree[a] = degree[a]! + 1;
+        degree[b] = degree[b]! + 1;
+      }
+      let drop = -1;
+      for (let i = terminals.length; i < points.length; i++) if (degree[i]! <= 2) drop = i;
+      if (drop < 0) break;
+      points.splice(drop, 1);
+      tree = spanningTree(points, metric);
+    }
+  }
+  return { points, links: tree.links };
+}
+
+/**
+ * This function gives the polyline of one link of the tree. A rectilinear link is an L in clear view, else a path through the corner graph.
+ * An octilinear link is a straight piece and a diagonal piece. The same link gives the same points each time.
+ */
+function linkPath(a: Point, b: Point, metric: SteinerMetric, finder: WayFinder): Point[] {
+  const pad = finder.margin / 2;
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const tries: Point[][] = [];
+  if (Math.abs(dx) < 1e-9 || Math.abs(dy) < 1e-9) tries.push([a, b]);
+  else if (metric === "rectilinear") tries.push([a, { x: b.x, y: a.y }, b], [a, { x: a.x, y: b.y }, b]);
+  else {
+    const d = Math.min(Math.abs(dx), Math.abs(dy));
+    const diag = { x: a.x + Math.sign(dx) * d, y: a.y + Math.sign(dy) * d };
+    const late = { x: b.x - Math.sign(dx) * d, y: b.y - Math.sign(dy) * d };
+    tries.push([a, diag, b], [a, late, b]);
+  }
+  for (const t of tries) if (finder.obstacles.clearPath(t, pad)) return t.filter((p, i) => i === 0 || p.x !== t[i - 1]!.x || p.y !== t[i - 1]!.y);
+  const way = finder.corners.path(a, b);
+  return way ? finder.corners.pull(way) : [a, b];
+}
+
+/**
+ * This function gives the highways of obstacle-avoiding Steiner trees (HWY-036 with EDA-015). Each group of edges gets one tree over the points out of its plugs.
+ * The links of the tree are rectilinear or octilinear, and they go around the boxes. Each edge takes its path in the tree, when that path is short enough.
+ * The stretches of the tree that two edges or more share become highways.
+ */
+export function steinerPlan(input: HighwayInput, o: Readonly<SteinerOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes);
+  const pad = finder.margin / 2;
+  const first = firstRoutes(input);
+  const groups = new Map<string, { edge: string; s: Point; t: Point; base: number }[]>();
+  for (const p of edgePlugs(input.graph)) {
+    const key = o.group === "key" ? (byCollection(p.edge) ?? `\u0000${p.edge.source.node}`) : p.edge.source.node;
+    const s = finder.out(p.ps);
+    const t = finder.out(p.pt);
+    const route = first.get(p.edge.id);
+    const list = groups.get(key) ?? [];
+    list.push({ edge: p.edge.id, s, t, base: route ? polylineLength(route) : metricDistance(s, t, "rectilinear") });
+    groups.set(key, list);
+  }
+  const ways: KeyedWay[] = [];
+  for (const key of [...groups.keys()].sort()) {
+    const list = groups.get(key)!;
+    if (list.length < 2) continue;
+    const index = new Map<string, number>();
+    const terminals: Point[] = [];
+    const at = (p: Point): number => {
+      const k = `${p.x},${p.y}`;
+      let i = index.get(k);
+      if (i === undefined) {
+        index.set(k, (i = terminals.length));
+        terminals.push(p);
+      }
+      return i;
+    };
+    const ends = list.map((e) => [at(e.s), at(e.t)] as const);
+    const tree = o.method === "one-steiner" && terminals.length <= o.maxGroup ? oneSteiner(terminals, o.metric, (p) => !finder.obstacles.inside(p, pad)) : { points: terminals, ...spanningTree(terminals, o.metric) };
+    const n = tree.points.length;
+    const next: { to: number; path: Point[] }[][] = Array.from({ length: n }, () => []);
+    for (const [a, b] of tree.links) {
+      const path = linkPath(tree.points[a]!, tree.points[b]!, o.metric, finder);
+      next[a]!.push({ to: b, path });
+      next[b]!.push({ to: a, path: [...path].reverse() });
+    }
+    list.forEach((e, k) => {
+      const [s, t] = ends[k]!;
+      // The path in the tree from `s` to `t`, by a search from `s`.
+      const back = new Int32Array(n).fill(-2);
+      const via: (Point[] | undefined)[] = new Array(n);
+      back[s] = -1;
+      const queue = [s];
+      while (queue.length > 0) {
+        const u = queue.shift()!;
+        if (u === t) break;
+        for (const x of next[u]!) {
+          if (back[x.to] !== -2) continue;
+          back[x.to] = u;
+          via[x.to] = x.path;
+          queue.push(x.to);
+        }
+      }
+      if (back[t] === -2 || s === t) return;
+      const pieces: Point[][] = [];
+      for (let v = t; v !== s; v = back[v]!) pieces.push(via[v]!);
+      const points: Point[] = [];
+      for (const piece of pieces.reverse()) for (const p of piece) if (points.length === 0 || p.x !== points[points.length - 1]!.x || p.y !== points[points.length - 1]!.y) points.push(p);
+      if (polylineLength(points) > o.detour * e.base) return;
+      ways.push({ edge: e.edge, key, points });
+    });
+  }
+  return sharedStretches(ways, { minSize: o.minSize });
+}