@mark1russell7/highways 0.4.0 → 0.4.2

package/src/highways/quickbundles/index.ts

@@ -0,0 +1,117 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { firstRoutes } from "../base.ts";
+import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The line of each edge that QuickBundles compares: its first route, or the straight line between its plugs. */
+export type BundleLine = "routes" | "lines";
+
+/** The order of the edges in the one pass: the order of the graph, or the longest line first. */
+export type BundleOrder = "input" | "length";
+
+/** The options of the highway strategy `quickbundles` (HWY-026 of the note on highways). */
+export interface QuickBundlesOptions {
+  /** An edge joins a cluster when its distance to the centroid is this value or less, in units of the board. The default is 3. */
+  readonly theta: number;
+  /** The number of points of each line after the resampling. The default is 12. */
+  readonly points: number;
+  /** The line of each edge. The default is `routes`. */
+  readonly line: BundleLine;
+  /** The order of the edges. The default is `input`, so an added edge does not change the clusters before it. */
+  readonly order: BundleOrder;
+  /** A cluster with this number of edges or more gets highways. The default is 2. */
+  readonly minSize: number;
+  /** The spine of each cluster. The default is `shared`. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `quickbundles`. */
+export const QUICKBUNDLES_DEFAULTS: Readonly<QuickBundlesOptions> = Object.freeze({ theta: 3, points: 12, line: "routes", order: "input", minSize: 2, spine: "shared" });
+
+/** This function gives `k` points at equal steps of length along a polyline, from its first point to its last point. */
+export function resample(line: readonly Point[], k: number): Point[] {
+  const n = Math.max(2, Math.round(k));
+  if (line.length === 0) throw new Error("The polyline has no point.");
+  if (line.length === 1) return Array.from({ length: n }, () => line[0]!);
+  const at: number[] = [0];
+  for (let i = 1; i < line.length; i++) at.push(at[i - 1]! + dist(line[i - 1]!, line[i]!));
+  const total = at[at.length - 1]!;
+  const out: Point[] = [];
+  let j = 1;
+  for (let i = 0; i < n; i++) {
+    const s = (total * i) / (n - 1);
+    while (j < line.length - 1 && at[j]! < s) j++;
+    const a = line[j - 1]!;
+    const b = line[j]!;
+    const len = at[j]! - at[j - 1]!;
+    const u = len > 0 ? Math.max(0, Math.min(1, (s - at[j - 1]!) / len)) : 0;
+    out.push({ x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+  }
+  return out;
+}
+
+/**
+ * This function gives the MDF distance of two lines with the same number of points. It is the mean distance of their points.
+ * The function compares the points in the same direction and in the opposite direction, and keeps the smaller mean.
+ * `flip` is `true` when the opposite direction is smaller.
+ */
+export function mdf(p: readonly Point[], q: readonly Point[]): { d: number; flip: boolean } {
+  const n = p.length;
+  let direct = 0;
+  let back = 0;
+  for (let i = 0; i < n; i++) {
+    direct += dist(p[i]!, q[i]!);
+    back += dist(p[i]!, q[n - 1 - i]!);
+  }
+  return back < direct ? { d: back / n, flip: true } : { d: direct / n, flip: false };
+}
+
+/**
+ * This function gives the clusters of QuickBundles (Garyfallidis 2012) as groups of edges.
+ * In one pass, each edge joins the cluster with the nearest centroid when the MDF distance is `theta` units or less. Else it starts a cluster.
+ * The centroid is the running mean of the lines of the cluster, each in the direction of the centroid.
+ */
+export function quickBundles(input: HighwayInput, o: Readonly<QuickBundlesOptions>): Map<string, EdgeGroup> {
+  const graph = input.graph;
+  const limit = o.theta * boardUnit(graph);
+  const k = Math.max(2, Math.round(o.points));
+  const routes = o.line === "routes" ? firstRoutes(input) : undefined;
+  const lines = edgePlugs(graph).map(({ edge, ps, pt }) => ({ edge: edge.id, line: resample(routes?.get(edge.id) ?? [ps.point, pt.point], k) }));
+  if (o.order === "length") lines.sort((a, b) => polylineLength(b.line) - polylineLength(a.line) || (a.edge < b.edge ? -1 : a.edge > b.edge ? 1 : 0));
+  const clusters: { sum: { x: number; y: number }[]; n: number; centroid: Point[] }[] = [];
+  const groups = new Map<string, EdgeGroup>();
+  for (const { edge, line } of lines) {
+    let best = -1;
+    let bestD = Infinity;
+    let bestFlip = false;
+    clusters.forEach((c, ci) => {
+      const m = mdf(line, c.centroid);
+      if (m.d < bestD) [best, bestD, bestFlip] = [ci, m.d, m.flip];
+    });
+    if (best < 0 || bestD > limit) {
+      clusters.push({ sum: line.map((p) => ({ ...p })), n: 1, centroid: line });
+      groups.set(edge, { key: `q${clusters.length - 1}`, flip: false });
+      continue;
+    }
+    const c = clusters[best]!;
+    const oriented = bestFlip ? [...line].reverse() : line;
+    oriented.forEach((p, i) => {
+      c.sum[i]!.x += p.x;
+      c.sum[i]!.y += p.y;
+    });
+    c.n++;
+    c.centroid = c.sum.map((p) => ({ x: p.x / c.n, y: p.y / c.n }));
+    groups.set(edge, { key: `q${best}`, flip: bestFlip });
+  }
+  return groups;
+}
+
+/**
+ * This function gives the highways of QuickBundles (HWY-026). The clusters of `quickBundles` with `minSize` edges or more get highways.
+ * With the spine `shared`, the edges of each cluster share their ways through the corner graph. With `trunk`, each cluster gets one trunk.
+ */
+export function quickBundlesPlan(input: HighwayInput, o: Readonly<QuickBundlesOptions>): HighwayPlan {
+  return groupedPlan(input, quickBundles(input, o), { spine: o.spine, minSize: o.minSize });
+}

package/src/highways/road-classes/index.ts

@@ -0,0 +1,74 @@
+import type { Point } from "../../geom.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs, sharedStretches, type KeyedWay } from "../stretches.ts";
+
+/** The options of the highway strategy `road-classes` (HWY-034 with EDA-050 of the notes). */
+export interface RoadClassOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** A link is a highway link when its use is at this quantile of the use of the links, or higher. The default is 0.9. */
+  readonly quantile: number;
+  /** A highway link has this number of edges or more on it, and a highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+  /** The second pass gives each highway link this discount, as a share of its length. The default is 0.5. */
+  readonly discount: number;
+}
+
+/** The default options of the strategy `road-classes`. */
+export const ROAD_CLASS_DEFAULTS: Readonly<Required<Omit<RoadClassOptions, "margin" | "k">>> = Object.freeze({ quantile: 0.9, minSize: 2, discount: 0.5 });
+
+/** This function gives the quantile `q` of a list of numbers, with the nearest rank. An empty list gives `Infinity`. */
+function rank(values: readonly number[], q: number): number {
+  if (values.length === 0) return Infinity;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1))]!;
+}
+
+/**
+ * This function gives the highways of the road classes (HWY-034, EDA-050). It counts how many first ways use each link of the corner graph.
+ * The links with a use at the quantile `quantile` or higher, and at least `minSize`, are the highway links.
+ * They are the main roads of a road map.
+ * A second pass routes each edge again, with the discount on the highway links, so more edges join them.
+ * Each stretch of highway links that `minSize` ways or more share after the second pass is one highway.
+ */
+export function roadClassPlan(input: HighwayInput, o: Readonly<RoadClassOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const corners = finder.corners;
+  const id = new Map<Point, number>();
+  corners.points.forEach((p, i) => id.set(p, i));
+  const M = corners.points.length;
+  const link = (i: number, j: number): number => (i < j ? i * M + j : j * M + i);
+  const plugs = edgePlugs(input.graph);
+  const ends = plugs.map(({ ps, pt }) => [finder.out(ps), finder.out(pt)] as const);
+  // The first pass: the use of each link between two corners.
+  const use = new Map<number, number>();
+  for (const [a, b] of ends) {
+    const way = corners.path(a, b);
+    if (!way) continue;
+    const own = new Set<number>();
+    for (let i = 1; i < way.length; i++) {
+      const p = id.get(way[i - 1]!);
+      const q = id.get(way[i]!);
+      if (p !== undefined && q !== undefined) own.add(link(p, q));
+    }
+    for (const l of own) use.set(l, (use.get(l) ?? 0) + 1);
+  }
+  const floor = Math.max(2, o.minSize, rank([...use.values()], o.quantile));
+  const highway = new Set<number>();
+  for (const [l, n] of use) if (n >= floor) highway.add(l);
+  if (highway.size === 0) return { highways: [] };
+  // The second pass: the highway links cost less, so the edges near them join them.
+  const share = Math.min(1, Math.max(0.05, 1 - o.discount));
+  const cost = (i: number, j: number, d: number): number => (highway.has(link(i, j)) ? d * share : d);
+  const ways: KeyedWay[] = [];
+  plugs.forEach(({ edge }, n) => {
+    const [a, b] = ends[n]!;
+    const way = corners.path(a, b, cost, share);
+    if (way) ways.push({ edge: edge.id, key: "road", points: way });
+  });
+  const onHighway = (a: Point, b: Point): boolean => {
+    const p = id.get(a);
+    const q = id.get(b);
+    return p !== undefined && q !== undefined && highway.has(link(p, q));
+  };
+  return sharedStretches(ways, { minSize: o.minSize, link: onHighway, pull: (p) => corners.pull(p) });
+}

package/src/highways/router.ts

@@ -4,7 +4,7 @@ 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 {
+export 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 } : {}) };
 }

package/src/highways/select/index.ts

@@ -0,0 +1,162 @@
+import { dist, type Point } from "../../geom.ts";
+import { byCollection } from "../../routers/trunks.ts";
+import { firstRoutes, tidyPlan } from "../base.ts";
+import { CORRIDOR_DEFAULTS, corridorPlan } from "../corridors/index.ts";
+import { FLOW_FIELD_DEFAULTS, flowFieldPlan } from "../flow-field/index.ts";
+import { lengthBetween, type Highway, type HighwayInput, type HighwayPlan } from "../model.ts";
+import { OD_CELL_DEFAULTS, odCellPlan } from "../od-cells/index.ts";
+import { QUICKBUNDLES_DEFAULTS, quickBundlesPlan } from "../quickbundles/index.ts";
+import { ROAD_CLASS_DEFAULTS, roadClassPlan } from "../road-classes/index.ts";
+import { sharedWaysPlan } from "../shared-ways/index.ts";
+import { WSPD_DEFAULTS, wspdPlan } from "../wspd/index.ts";
+
+/** A generator of candidate highways: a highway strategy with its defaults. */
+export type CandidateSource = "corridors" | "quickbundles" | "wspd" | "road-classes" | "flow-field" | "od-cells" | "shared-ways";
+
+/** The values of `CandidateSource`. */
+export const CANDIDATE_SOURCES: readonly CandidateSource[] = Object.freeze(["corridors", "quickbundles", "wspd", "road-classes", "flow-field", "od-cells", "shared-ways"]);
+
+/** The options of the highway strategy `select` (HWY-045 of the note on highways). */
+export interface SelectOptions {
+  /** The generators of the candidates. The default is `corridors`, `quickbundles`, `wspd` and `road-classes`. */
+  readonly generators: readonly CandidateSource[];
+  /** The weight of the added length of the edges against the ink that a highway saves (lambda 3 of the note). The default is 1. */
+  readonly lambda: number;
+  /** The number of passes of the local search with one swap. The default is 2. */
+  readonly swaps: number;
+}
+
+/** The default options of the strategy `select`. */
+export const SELECT_DEFAULTS: Readonly<SelectOptions> = Object.freeze({ generators: Object.freeze(["corridors", "quickbundles", "wspd", "road-classes"] as CandidateSource[]), lambda: 1, swaps: 2 });
+
+/** This function gives the plan of a generator, with its defaults. */
+export function candidatePlan(input: HighwayInput, source: CandidateSource): HighwayPlan {
+  switch (source) {
+    case "corridors":
+      return corridorPlan(input, CORRIDOR_DEFAULTS);
+    case "quickbundles":
+      return quickBundlesPlan(input, QUICKBUNDLES_DEFAULTS);
+    case "wspd":
+      return wspdPlan(input, WSPD_DEFAULTS);
+    case "road-classes":
+      return roadClassPlan(input, ROAD_CLASS_DEFAULTS);
+    case "flow-field":
+      return flowFieldPlan(input, FLOW_FIELD_DEFAULTS);
+    case "od-cells":
+      return odCellPlan(input, OD_CELL_DEFAULTS);
+    case "shared-ways":
+      return sharedWaysPlan(input, { rule: byCollection });
+  }
+}
+
+/** This function gives the place along a polyline (as a length) of the point nearest to `p`, and the distance to it. */
+function project(line: readonly Point[], p: Point): { at: number; d: number } {
+  let best = { at: 0, d: line.length > 0 ? dist(line[0]!, p) : Infinity };
+  let walked = 0;
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!;
+    const b = line[i]!;
+    const len = dist(a, b);
+    const u = len > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * (b.x - a.x) + (p.y - a.y) * (b.y - a.y)) / (len * len))) : 0;
+    const d = dist(p, { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+    if (d < best.d) best = { at: walked + u * len, d };
+    walked += len;
+  }
+  return best;
+}
+
+/** One candidate highway, with the index of its generator, its edges and its net gain. */
+interface Candidate {
+  readonly highway: Highway;
+  readonly source: number;
+  readonly edges: readonly string[];
+  readonly net: number;
+}
+
+/**
+ * This function gives the ink that a highway saves. It is the sum of the spine lengths of the members, less the length of their union.
+ * The extra length of a member is its detour from its first route. The detour goes to the merge point, along the spine and back from the split point.
+ */
+export function candidateScore(h: Highway, routes: ReadonlyMap<string, readonly Point[]>): { gain: number; extra: number } {
+  const spans = h.members.map((m) => [Math.min(m.on, m.off), Math.max(m.on, m.off)] as const).sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  let sum = 0;
+  for (const [lo, hi] of spans) sum += lengthBetween(h.spine, lo, hi);
+  let union = 0;
+  let from = -1;
+  let to = -1;
+  for (const [lo, hi] of spans) {
+    if (lo > to) {
+      if (to > from) union += lengthBetween(h.spine, from, to);
+      [from, to] = [lo, hi];
+    } else to = Math.max(to, hi);
+  }
+  if (to > from) union += lengthBetween(h.spine, from, to);
+  let extra = 0;
+  for (const m of h.members) {
+    const route = routes.get(m.edge);
+    if (!route || route.length < 2) continue;
+    const a = project(route, m.merge);
+    const b = project(route, m.split);
+    const along = lengthBetween(h.spine, Math.min(m.on, m.off), Math.max(m.on, m.off));
+    extra += Math.max(0, a.d + along + b.d - Math.max(0, b.at - a.at));
+  }
+  return { gain: sum - union, extra };
+}
+
+/**
+ * This function gives the highways of the candidate generation and selection (HWY-045). Each generator proposes its highways as candidates.
+ * The net gain of a candidate is the ink that it saves, less `lambda` times the length that it adds to its edges.
+ * Two candidates of two generators conflict when they share an edge. The highways of one generator do not conflict.
+ *
+ * The selection takes the candidates by net gain for each edge, without a conflict. Then each pass of the local search
+ * swaps in a candidate. The swap occurs when the net gain of the candidate is more than the sum of the selected candidates in conflict with it.
+ */
+export function selectPlan(input: HighwayInput, o: Readonly<SelectOptions>): HighwayPlan {
+  const routes = firstRoutes(input);
+  const candidates: Candidate[] = [];
+  [...new Set(o.generators)].forEach((source, si) => {
+    for (const highway of candidatePlan(input, source).highways) {
+      const { gain, extra } = candidateScore(highway, routes);
+      candidates.push({ highway: { ...highway, key: `${source}:${highway.key}` }, source: si, edges: highway.members.map((m) => m.edge), net: gain - o.lambda * extra });
+    }
+  });
+  const onEdge = new Map<string, number[]>();
+  candidates.forEach((c, i) => {
+    for (const e of c.edges) {
+      const list = onEdge.get(e);
+      if (list) list.push(i);
+      else onEdge.set(e, [i]);
+    }
+  });
+  const conflicts = (i: number): Set<number> => {
+    const out = new Set<number>();
+    for (const e of candidates[i]!.edges) for (const j of onEdge.get(e) ?? []) if (j !== i && candidates[j]!.source !== candidates[i]!.source) out.add(j);
+    return out;
+  };
+  const order = candidates
+    .map((_, i) => i)
+    .filter((i) => candidates[i]!.net > 0)
+    .sort((a, b) => candidates[b]!.net / candidates[b]!.edges.length - candidates[a]!.net / candidates[a]!.edges.length || a - b);
+  const chosen = new Set<number>();
+  const fill = (): void => {
+    for (const i of order) if (!chosen.has(i) && ![...conflicts(i)].some((j) => chosen.has(j))) chosen.add(i);
+  };
+  fill();
+  for (let pass = 0; pass < Math.max(0, Math.round(o.swaps)); pass++) {
+    let changed = false;
+    for (const i of order) {
+      if (chosen.has(i)) continue;
+      const against = [...conflicts(i)].filter((j) => chosen.has(j));
+      const lost = against.reduce((s, j) => s + candidates[j]!.net, 0);
+      if (against.length > 0 && candidates[i]!.net > lost + 1e-9) {
+        for (const j of against) chosen.delete(j);
+        chosen.add(i);
+        changed = true;
+      }
+    }
+    fill();
+    if (!changed) break;
+  }
+  const highways = [...chosen].sort((a, b) => a - b).map((i) => candidates[i]!.highway);
+  return tidyPlan({ highways });
+}

package/src/highways/stretches.ts

@@ -0,0 +1,141 @@
+import { center, dist, type Point } from "../geom.ts";
+import { nodeIndex, type Edge, type Graph } from "../model.ts";
+import { placePlug, type Plug } from "../plugs.ts";
+import { orderLanes } from "../segments.ts";
+import { tidyPlan } from "./base.ts";
+import { memberAt, type Highway, type HighwayMember, type HighwayPlan } from "./model.ts";
+
+/** An edge with its two plugs, as the router `corners` places them. */
+export interface EdgePlugs {
+  readonly edge: Edge;
+  readonly ps: Plug;
+  readonly pt: Plug;
+}
+
+/** This function gives the plugs of each edge of the graph, in the order of the edges. An edge with an unknown node is not in the list. */
+export function edgePlugs(graph: Graph): EdgePlugs[] {
+  const byId = nodeIndex(graph);
+  const out: EdgePlugs[] = [];
+  for (const e of graph.edges) {
+    const s = byId.get(e.source.node);
+    const t = byId.get(e.target.node);
+    if (!s || !t) continue;
+    out.push({ edge: e, ps: placePlug(s, e.source, center(t.box)), pt: placePlug(t, e.target, center(s.box)) });
+  }
+  return out;
+}
+
+/** The way of one edge through the corner graph, with a key. Only the ways with one key share a highway. */
+export interface KeyedWay {
+  readonly edge: string;
+  readonly key: string;
+  /** The points of the way, without the plugs. Two ways share a link when the link has the same two points. */
+  readonly points: readonly Point[];
+}
+
+/** The options of `sharedStretches`. */
+export interface SharedStretchOptions {
+  /** A highway has this number of edges or more. The value is 2 or more. */
+  readonly minSize: number;
+  /** This function tells if a link can be part of a highway. Without it, each link can. */
+  readonly link?: (a: Point, b: Point) => boolean;
+  /** This function removes the needless corners of a spine. Without it, the spine keeps each point of the stretch. */
+  readonly pull?: (points: readonly Point[]) => Point[];
+}
+
+const pointKey = (p: Point): string => `${p.x},${p.y}`;
+const linkKey = (a: string, b: string): string => (a < b ? `${a}|${b}` : `${b}|${a}`);
+
+/** This function removes each point of a polyline that is equal to the point before it. */
+const dedupe = (p: readonly Point[]): Point[] => p.filter((q, i) => i === 0 || dist(q, p[i - 1]!) > 1e-9);
+
+/**
+ * This function gives a highway for each stretch that two ways or more of one key share. A way is a polyline through the corner graph.
+ * Each way breaks into stretches where the set of the ways on its links stays the same. The router `shared` makes its runs in the same way.
+ * A stretch with fewer than `minSize` ways is not a highway. Each way joins the spine at one end of the stretch and leaves it at the other end.
+ * The `seq` of each member follows the order of the stretches along the way.
+ */
+export function sharedStretches(ways: readonly KeyedWay[], o: Readonly<SharedStretchOptions>): HighwayPlan {
+  const min = Math.max(2, o.minSize);
+  const clean = ways.map((w) => ({ ...w, points: dedupe(w.points) }));
+  const users = new Map<string, string[]>();
+  const usable = (a: Point, b: Point): boolean => o.link?.(a, b) ?? true;
+  for (const w of clean) {
+    const own = new Set<string>();
+    for (let i = 1; i < w.points.length; i++) {
+      const a = w.points[i - 1]!;
+      const b = w.points[i]!;
+      if (usable(a, b)) own.add(`${w.key}\u0000${linkKey(pointKey(a), pointKey(b))}`);
+    }
+    for (const k of own) {
+      const list = users.get(k);
+      if (list) list.push(w.edge);
+      else users.set(k, [w.edge]);
+    }
+  }
+  interface Stretch {
+    readonly key: string;
+    readonly points: readonly Point[];
+    readonly members: { edge: string; forward: boolean; at: number }[];
+  }
+  const stretches = new Map<string, Stretch>();
+  const wayOf = new Map<string, readonly Point[]>();
+  for (const w of clean) {
+    wayOf.set(w.edge, w.points);
+    const sig = (i: number): string => {
+      const a = w.points[i]!;
+      const b = w.points[i + 1]!;
+      if (!usable(a, b)) return "";
+      const list = users.get(`${w.key}\u0000${linkKey(pointKey(a), pointKey(b))}`) ?? [];
+      return list.length < min ? "" : [...list].sort().join("\u0001");
+    };
+    let start = 0;
+    for (let i = 0; i < w.points.length - 1; i++) {
+      const s = sig(i);
+      if (i + 1 < w.points.length - 1 && sig(i + 1) === s) continue;
+      const from = start;
+      start = i + 1;
+      if (s === "") continue;
+      const a = pointKey(w.points[from]!);
+      const b = pointKey(w.points[i + 1]!);
+      if (a === b) continue;
+      const id = `${w.key}\u0000${s}\u0000${linkKey(a, b)}`;
+      const piece = w.points.slice(from, i + 2);
+      let found = stretches.get(id);
+      if (!found) stretches.set(id, (found = { key: w.key, points: a < b ? piece : [...piece].reverse(), members: [] }));
+      if (!found.members.some((m) => m.edge === w.edge)) found.members.push({ edge: w.edge, forward: a < b, at: from });
+    }
+  }
+  // The order of the stretches of each way gives the `seq` of its members.
+  const kept = [...stretches.values()].filter((s) => s.members.length >= min);
+  const order = new Map<string, { s: number; at: number }[]>();
+  kept.forEach((s, si) => {
+    for (const m of s.members) {
+      const list = order.get(m.edge);
+      if (list) list.push({ s: si, at: m.at });
+      else order.set(m.edge, [{ s: si, at: m.at }]);
+    }
+  });
+  const seq = new Map<string, number>();
+  for (const [edge, list] of order) {
+    list.sort((p, q) => p.at - q.at || p.s - q.s);
+    list.forEach((x, k) => seq.set(`${x.s}\u0000${edge}`, k));
+  }
+  const highways: Highway[] = kept.map((s, si) => {
+    const spine = o.pull ? o.pull(s.points) : [...s.points];
+    const last = spine.length - 1;
+    const lanes = orderLanes(
+      s.points,
+      s.members.map((m) => ({ edge: m.edge, points: wayOf.get(m.edge)! })),
+      "bundle",
+    );
+    const byEdge = new Map(s.members.map((m) => [m.edge, m]));
+    const members: HighwayMember[] = lanes.map((edge) => {
+      const m = byEdge.get(edge)!;
+      const k = seq.get(`${si}\u0000${edge}`) ?? 0;
+      return m.forward ? memberAt(spine, edge, 0, last, k) : memberAt(spine, edge, last, 0, k);
+    });
+    return { id: `h${si}`, key: s.key, spine, lanes, members };
+  });
+  return tidyPlan({ highways });
+}

package/src/highways/stubs/index.ts

@@ -0,0 +1,117 @@
+import { center, dist, pointBoxDistance, type Point } from "../../geom.ts";
+import { nodeIndex, type Node } from "../../model.ts";
+import { pointOnSide, SIDE_NORMAL, sideToward } from "../../plugs.ts";
+import { WayFinder } from "../../ways.ts";
+import { basePlan, tidyPlan, tripsOf, type HighwayBase } from "../base.ts";
+import { memberAt, type Highway, type HighwayInput, type HighwayPlan } from "../model.ts";
+
+/** The ends of the edges that get stubs: the source ends, the target ends, or both. */
+export type StubEnds = "source" | "target" | "both";
+
+/** The options of the highway strategy `stubs` (HWY-015 with WILD-005 of the notes). */
+export interface StubOptions {
+  /** The plan that the stubs go into. The default is `shared-ways`. */
+  readonly from: HighwayBase;
+  /** The ends of one side of a box whose directions are in a window of this angle share a stub, in degrees. The default is 30. */
+  readonly omega: number;
+  /** The length of a stub is this share of the distance to the nearest other end. The default is 0.25. */
+  readonly sigma: number;
+  /** The ends that get stubs. The default is `both`. */
+  readonly ends: StubEnds;
+  /** A stub has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `stubs`. */
+export const STUB_DEFAULTS: Readonly<StubOptions> = Object.freeze({ from: "shared-ways", omega: 30, sigma: 0.25, ends: "both", minSize: 2 });
+
+/** One end of an edge that can get a stub. */
+interface StubEnd {
+  readonly edge: string;
+  readonly node: Node;
+  readonly other: Node;
+  /** The angle from the normal of the side to the direction of the other node, in radians. A negative angle turns to the left. */
+  readonly turn: number;
+  /** The first merge point of the edge in the plan, from this end, or `undefined`. */
+  readonly merge: Point | undefined;
+}
+
+/**
+ * This function gives the highways of the plan `from`, with a stub at the ends of the edges (HWY-015, WILD-005).
+ * The ends on one side of one box are sorted by the direction of their other node. A run of ends in a window of `omega` makes a group.
+ * Each group of `minSize` ends or more shares one plug and one stub along the normal of the side. Then the edges fan out.
+ *
+ * The length of the stub is `sigma` times the distance to the nearest other node, and half that distance at most.
+ * It is two times the margin of the way finder at least, and the stub stays out of the other boxes. Else the group gets no stub.
+ * An end with a fixed plug or a side of its own gets no stub. An end whose first highway starts on its box, or near it, keeps the plan.
+ */
+export function stubPlan(input: HighwayInput, o: Readonly<StubOptions>): HighwayPlan {
+  const graph = input.graph;
+  const plan = basePlan(input, o.from);
+  const trips = tripsOf(plan);
+  const byId = nodeIndex(graph);
+  const ways = new WayFinder(graph.nodes);
+  const margin = ways.margin;
+  const omega = (Math.max(0, o.omega) * Math.PI) / 180;
+  const groups = new Map<string, StubEnd[]>();
+  const add = (kind: "source" | "target", node: Node, other: Node, edge: string, merge: Point | undefined): void => {
+    const side = sideToward(node.box, center(other.box));
+    const n = SIDE_NORMAL[side];
+    const c = center(node.box);
+    const d = center(other.box);
+    const dx = d.x - c.x;
+    const dy = d.y - c.y;
+    const turn = Math.atan2(n.x * dy - n.y * dx, n.x * dx + n.y * dy);
+    const key = `${node.id}\u0000${kind}\u0000${side}`;
+    const list = groups.get(key);
+    const end: StubEnd = { edge, node, other, turn, merge };
+    if (list) list.push(end);
+    else groups.set(key, [end]);
+  };
+  for (const e of graph.edges) {
+    const s = byId.get(e.source.node);
+    const t = byId.get(e.target.node);
+    if (!s || !t || s === t) continue;
+    const trip = trips.get(e.id);
+    if (o.ends !== "target" && e.source.port === undefined) add("source", s, t, e.id, trip?.[0]?.m.merge);
+    if (o.ends !== "source" && e.target.port === undefined) add("target", t, s, e.id, trip?.[trip.length - 1]?.m.split);
+  }
+
+  const stubs: Highway[] = [];
+  for (const [key, list] of [...groups].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) {
+    const [, kind, side] = key.split("\u0000") as [string, "source" | "target", keyof typeof SIDE_NORMAL];
+    list.sort((a, b) => a.turn - b.turn || (a.edge < b.edge ? -1 : 1));
+    // The runs of ends in a window of omega.
+    const runs: StubEnd[][] = [];
+    for (const end of list) {
+      const run = runs[runs.length - 1];
+      if (run && end.turn - run[0]!.turn <= omega) run.push(end);
+      else runs.push([end]);
+    }
+    for (const run of runs) {
+      if (run.length < Math.max(2, o.minSize)) continue;
+      const node = run[0]!.node;
+      const n = SIDE_NORMAL[side];
+      const toward = { x: run.reduce((s, r) => s + center(r.other.box).x, 0) / run.length, y: run.reduce((s, r) => s + center(r.other.box).y, 0) / run.length };
+      const plug = pointOnSide(node.box, side, toward);
+      const span = Math.min(...run.map((r) => dist(plug, center(r.other.box))));
+      const gap = Math.min(...run.map((r) => pointBoxDistance(plug, r.other.box)));
+      let len = Math.min(Math.max(0, o.sigma) * span, gap / 2);
+      const skip = new Set([node]);
+      const tip = (l: number): Point => ({ x: plug.x + n.x * l, y: plug.y + n.y * l });
+      while (len >= 2 * margin && !ways.obstacles.clear(tip(margin / 2), tip(len), margin / 2, skip)) len /= 2;
+      if (len < 2 * margin) continue;
+      // An end whose highway starts on the box, or near the tip, keeps the plan.
+      const kept = run.filter((r) => r.merge === undefined || pointBoxDistance(r.merge, node.box) > 2 * len);
+      if (kept.length < Math.max(2, o.minSize)) continue;
+      const end = tip(len);
+      const spine = kind === "source" ? [plug, end] : [end, plug];
+      // Lane 0 is on the left of the spine. At a source, the left lane turns most to the left. At a target, the order turns over.
+      const lanes = kept.map((r) => r.edge);
+      if (kind === "target") lanes.reverse();
+      const seq = kind === "source" ? -1 : Number.MAX_SAFE_INTEGER;
+      stubs.push({ id: "", key: `stub:${node.id}:${kind}:${side}`, spine, lanes, members: lanes.map((edge) => memberAt(spine, edge, 0, 1, seq)) });
+    }
+  }
+  return tidyPlan({ highways: [...plan.highways, ...stubs] });
+}