@mark1russell7/highways 0.4.2 → 0.5.1

package/src/highways/mlseb/index.ts

@@ -0,0 +1,204 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, type Point } from "../../geom.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import { firstRoutes } from "../base.ts";
+import type { DensitySource } from "../kdeeb/index.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { resample } from "../quickbundles/index.ts";
+import { edgePlugs } from "../stretches.ts";
+import { outOfBoxes, tracePlan } from "../trace.ts";
+
+/** The local fit of the moving least squares: a line, or a parabola in the frame of the line. */
+export type MlsFit = "line" | "parabola";
+
+/** The values of `MlsFit`. */
+export const MLS_FITS: readonly MlsFit[] = Object.freeze(["line", "parabola"]);
+
+/** The options of the highway strategy `mlseb` (HWY-008 of the notes). */
+export interface MlsebOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** The first lines of the edges: their straight lines, or their first routes. The default is `lines`. */
+  readonly source: DensitySource;
+  /** The radius of the fit at the first step, as a multiple of `boardUnit`: the median short side of the boxes. The default is 2. */
+  readonly radius: number;
+  /** Each step multiplies the radius by this value. The default is 0.8. */
+  readonly decay: number;
+  /** The number of steps. The default is 6. */
+  readonly steps: number;
+  /** The local fit. The default is `line`. */
+  readonly fit: MlsFit;
+  /** The weight of the angle, from 0 to 1. With 1, a sample at a right angle to the point has no weight. The default is 1. */
+  readonly angleWeight: number;
+  /** The spacing of the sample points of each edge, in units of the board. The default is 8. */
+  readonly spacing: number;
+  /** The side of the grid that the points of the edges snap to after the steps, in units of the board. The default is 8. */
+  readonly snap: number;
+  /** A highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `mlseb`. */
+export const MLSEB_DEFAULTS: Readonly<Required<Omit<MlsebOptions, "margin" | "k">>> = Object.freeze({
+  source: "lines",
+  radius: 2,
+  decay: 0.8,
+  steps: 6,
+  fit: "line",
+  angleWeight: 1,
+  spacing: 8,
+  snap: 8,
+  minSize: 2,
+});
+
+/** One sample point of an edge, with the unit tangent of its edge there. */
+interface Sample {
+  readonly p: Point;
+  readonly tx: number;
+  readonly ty: number;
+}
+
+/** This function gives the unit tangent of a polyline at its point `i`, from the point before it to the point after it. */
+function tangent(line: readonly Point[], i: number): { tx: number; ty: number } {
+  const a = line[Math.max(0, i - 1)]!;
+  const b = line[Math.min(line.length - 1, i + 1)]!;
+  const l = Math.hypot(b.x - a.x, b.y - a.y);
+  return l > 1e-12 ? { tx: (b.x - a.x) / l, ty: (b.y - a.y) / l } : { tx: 1, ty: 0 };
+}
+
+/**
+ * This function gives the point of the moving least squares fit at the point `p`. The weight of a sample `q` is `exp(-|q-p|^2 / r^2)`.
+ * The angle term multiplies it by `1 - a + a |cos|`, with `cos` the cosine of the angle between the two tangents.
+ * The fit `line` gives the projection of `p` on the weighted line of the samples. The fit `parabola` fits `s = c0 + c1 t + c2 t^2` in the frame of that line.
+ * Without weight, the function gives `p`.
+ */
+export function mlsPoint(p: Point, t: { tx: number; ty: number }, near: readonly Sample[], r: number, angleWeight: number, fit: MlsFit): Point {
+  const a = Math.max(0, Math.min(1, angleWeight));
+  const ws: number[] = [];
+  let sw = 0;
+  let cx = 0;
+  let cy = 0;
+  for (const s of near) {
+    const d2 = (s.p.x - p.x) ** 2 + (s.p.y - p.y) ** 2;
+    const w = Math.exp(-d2 / (r * r)) * (1 - a + a * Math.abs(s.tx * t.tx + s.ty * t.ty));
+    ws.push(w);
+    sw += w;
+    cx += w * s.p.x;
+    cy += w * s.p.y;
+  }
+  if (sw <= 1e-12) return p;
+  cx /= sw;
+  cy /= sw;
+  let sxx = 0;
+  let syy = 0;
+  let sxy = 0;
+  near.forEach((s, i) => {
+    const w = ws[i]!;
+    sxx += w * (s.p.x - cx) ** 2;
+    syy += w * (s.p.y - cy) ** 2;
+    sxy += w * (s.p.x - cx) * (s.p.y - cy);
+  });
+  const theta = 0.5 * Math.atan2(2 * sxy, sxx - syy);
+  const ux = Math.cos(theta);
+  const uy = Math.sin(theta);
+  const tp = (p.x - cx) * ux + (p.y - cy) * uy;
+  if (fit === "line") return { x: cx + tp * ux, y: cy + tp * uy };
+  // The parabola: the normal equations of the weighted least squares in the frame (u, n), with n = (-uy, ux).
+  const m = [0, 0, 0, 0, 0];
+  const v = [0, 0, 0];
+  near.forEach((s, i) => {
+    const w = ws[i]!;
+    const tq = (s.p.x - cx) * ux + (s.p.y - cy) * uy;
+    const sq = -(s.p.x - cx) * uy + (s.p.y - cy) * ux;
+    let pw = w;
+    for (let k = 0; k < 5; k++) {
+      m[k] = m[k]! + pw;
+      if (k < 3) v[k] = v[k]! + pw * sq;
+      pw *= tq;
+    }
+  });
+  const A = [
+    [m[0]!, m[1]!, m[2]!],
+    [m[1]!, m[2]!, m[3]!],
+    [m[2]!, m[3]!, m[4]!],
+  ];
+  const c = solve3(A, v);
+  if (!c) return { x: cx + tp * ux, y: cy + tp * uy };
+  const sp = c[0]! + c[1]! * tp + c[2]! * tp * tp;
+  return { x: cx + tp * ux - sp * uy, y: cy + tp * uy + sp * ux };
+}
+
+/** This function solves a system of three linear equations by Cramer's rule. A system without one solution gives `undefined`. */
+function solve3(A: readonly (readonly number[])[], b: readonly number[]): number[] | undefined {
+  const det = (m: readonly (readonly number[])[]): number =>
+    m[0]![0]! * (m[1]![1]! * m[2]![2]! - m[1]![2]! * m[2]![1]!) - m[0]![1]! * (m[1]![0]! * m[2]![2]! - m[1]![2]! * m[2]![0]!) + m[0]![2]! * (m[1]![0]! * m[2]![1]! - m[1]![1]! * m[2]![0]!);
+  const d = det(A);
+  const scale = Math.abs(A[0]![0]!) * Math.abs(A[1]![1]!) * Math.abs(A[2]![2]!);
+  if (!Number.isFinite(d) || Math.abs(d) <= 1e-12 * Math.max(1, scale)) return undefined;
+  return [0, 1, 2].map((k) => det(A.map((row, i) => row.map((x, j) => (j === k ? b[i]! : x)))) / d);
+}
+
+/**
+ * This function gives the polylines of the moving least squares bundling (MLSEB, Wu, Zeng, Zhu and Yu 2017). The ends of each polyline stay.
+ * In each step, each inner point moves to the local fit of the samples of all edges within the radius. Then the radius shrinks by `decay`.
+ * A move is at most the radius. A point in a box moves out of it.
+ */
+export function mlsebLines(input: HighwayInput, finder: WayFinder, o: Readonly<MlsebOptions>): Map<string, Point[]> {
+  const plugs = edgePlugs(input.graph);
+  const out = new Map<string, Point[]>();
+  if (plugs.length === 0) return out;
+  const routes = o.source === "routes" ? firstRoutes(input) : undefined;
+  const spacing = Math.max(1e-3, o.spacing);
+  let lines: Point[][] = plugs.map(({ edge, ps, pt }) => {
+    const a = finder.out(ps);
+    const b = finder.out(pt);
+    const route = routes?.get(edge.id);
+    const base = route && route.length > 2 ? [a, ...route.slice(1, -1), b] : [a, b];
+    let len = 0;
+    for (let i = 1; i < base.length; i++) len += dist(base[i - 1]!, base[i]!);
+    return resample(base, Math.max(2, Math.min(129, Math.ceil(len / spacing) + 1)));
+  });
+  const pad = finder.margin / 2;
+  let r = Math.max(1e-3, o.radius * boardUnit(input.graph));
+  for (let step = 0; step < Math.max(0, Math.round(o.steps)); step++) {
+    // The grid of the samples, with cells of side `r`. A sample within `2 r` is in the 5 by 5 cells around a point.
+    const grid = new Map<string, Sample[]>();
+    const cellOf = (p: Point): [number, number] => [Math.floor(p.x / r), Math.floor(p.y / r)];
+    for (const l of lines)
+      l.forEach((p, i) => {
+        const [gx, gy] = cellOf(p);
+        const k = `${gx},${gy}`;
+        const s = { p, ...tangent(l, i) };
+        const list = grid.get(k);
+        if (list) list.push(s);
+        else grid.set(k, [s]);
+      });
+    const reach = 2 * r;
+    lines = lines.map((l) =>
+      l.map((p, i) => {
+        if (i === 0 || i === l.length - 1) return p;
+        const [gx, gy] = cellOf(p);
+        const near: Sample[] = [];
+        for (let dy = -2; dy <= 2; dy++)
+          for (let dx = -2; dx <= 2; dx++) for (const s of grid.get(`${gx + dx},${gy + dy}`) ?? []) if (dist(s.p, p) <= reach) near.push(s);
+        let q = mlsPoint(p, tangent(l, i), near, r, o.angleWeight, o.fit);
+        const d = dist(p, q);
+        if (d > r) q = { x: p.x + ((q.x - p.x) * r) / d, y: p.y + ((q.y - p.y) * r) / d };
+        return outOfBoxes(finder.obstacles, q, pad);
+      }),
+    );
+    r *= Math.max(0, Math.min(1, o.decay));
+    if (r <= 1e-3) break;
+  }
+  plugs.forEach(({ edge }, e) => out.set(edge.id, lines[e]!));
+  return out;
+}
+
+/**
+ * This function gives the highways of the moving least squares bundling (HWY-008). The points of `mlsebLines` snap to a grid of side `snap`.
+ * The ways go through the corner graph, and each stretch that `minSize` ways share is a highway.
+ */
+export function mlsebPlan(input: HighwayInput, o: Readonly<MlsebOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const lines = mlsebLines(input, finder, o);
+  const waypoints = new Map([...lines].map(([edge, l]) => [edge, l.slice(1, -1)] as const));
+  return tracePlan(input, finder, waypoints, { snap: o.snap, minSize: o.minSize, key: "mlseb" });
+}

package/src/highways/nested/index.ts

@@ -0,0 +1,143 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { 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 { mdf, resample, type BundleLine, type BundleOrder } from "../quickbundles/index.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The options of the highway strategy `nested` (HWY-052 of the note on highways). */
+export interface NestedOptions {
+  /** The scale of the closest level, in units of the board. An edge joins a cluster when its distance to the centroid is this value or less. The default is 3. */
+  readonly theta: number;
+  /** The scale of each level is this value times the scale of the next closer level. The default is 2. */
+  readonly ratio: number;
+  /** The number of levels. The default is 3. */
+  readonly levels: number;
+  /** The level of the plan. Level 0 is the closest level, and level `levels - 1` is the far level. The default is 0. */
+  readonly level: 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`. */
+  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 `nested`. */
+export const NESTED_DEFAULTS: Readonly<NestedOptions> = Object.freeze({
+  theta: 3,
+  ratio: 2,
+  levels: 3,
+  level: 0,
+  points: 12,
+  line: "routes",
+  order: "input",
+  minSize: 2,
+  spine: "shared",
+});
+
+interface Line {
+  readonly edge: string;
+  readonly line: readonly Point[];
+}
+
+/**
+ * This function puts lines in clusters in one pass, as QuickBundles does. Each line joins the cluster with the nearest centroid when the distance is `limit` or less.
+ * It gives the index of the cluster of each line, and `flip` when the line goes against the centroid.
+ */
+function clusterLines(lines: readonly Line[], limit: number): { cluster: number; flip: boolean }[] {
+  const clusters: { sum: { x: number; y: number }[]; n: number; centroid: Point[] }[] = [];
+  return lines.map(({ line }) => {
+    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] });
+      return { cluster: clusters.length - 1, flip: false };
+    }
+    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 }));
+    return { cluster: best, flip: bestFlip };
+  });
+}
+
+/**
+ * This function gives the groups of edges of each level, from the closest level (index 0) to the far level.
+ * The far level puts all the edges in clusters at the scale `theta × ratio^(levels - 1)`.
+ * Each closer level puts the edges of each cluster of the level above in clusters, at its own scale. Thus each group of a level is in one group of the level above.
+ */
+export function nestedGroups(input: HighwayInput, o: Readonly<NestedOptions>): Map<string, EdgeGroup>[] {
+  const graph = input.graph;
+  const unit = boardUnit(graph);
+  const levels = Math.max(1, Math.round(o.levels));
+  const k = Math.max(2, Math.round(o.points));
+  const routes = o.line === "routes" ? firstRoutes(input) : undefined;
+  const lines: Line[] = 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 out: Map<string, EdgeGroup>[] = [];
+  // Each part is a list of lines with one key of the level above. The far level has one part with all the lines.
+  let parts: { key: string; lines: Line[] }[] = [{ key: "n", lines }];
+  for (let d = levels - 1; d >= 0; d--) {
+    const limit = o.theta * o.ratio ** d * unit;
+    const groups = new Map<string, EdgeGroup>();
+    const next: { key: string; lines: Line[] }[] = [];
+    for (const part of parts) {
+      const found = clusterLines(part.lines, limit);
+      const children = new Map<number, Line[]>();
+      found.forEach(({ cluster, flip }, i) => {
+        const key = `${part.key}.${cluster}`;
+        groups.set(part.lines[i]!.edge, { key, flip });
+        const list = children.get(cluster);
+        if (list) list.push(part.lines[i]!);
+        else children.set(cluster, [part.lines[i]!]);
+      });
+      for (const [cluster, list] of children) next.push({ key: `${part.key}.${cluster}`, lines: list });
+    }
+    out.unshift(groups);
+    parts = next;
+  }
+  return out;
+}
+
+/**
+ * This function gives the number of groups of the closer level `fine` with edges in two groups or more of the level `coarse`.
+ * An edge that is not in `coarse` does not count. The groups of `nestedGroups` give 0.
+ */
+export function nestingViolations(coarse: ReadonlyMap<string, EdgeGroup>, fine: ReadonlyMap<string, EdgeGroup>): number {
+  const parents = new Map<string, Set<string>>();
+  for (const [edge, g] of fine) {
+    const up = coarse.get(edge);
+    if (!up) continue;
+    const set = parents.get(g.key);
+    if (set) set.add(up.key);
+    else parents.set(g.key, new Set([up.key]));
+  }
+  let n = 0;
+  for (const set of parents.values()) if (set.size > 1) n++;
+  return n;
+}
+
+/**
+ * This function gives the highways of one level of the nested clusters (HWY-052). The level is `o.level`, with 0 as the closest level.
+ * The clusters of that level with `minSize` edges or more get highways, as in the strategy `quickbundles`.
+ */
+export function nestedPlan(input: HighwayInput, o: Readonly<NestedOptions>): HighwayPlan {
+  const levels = nestedGroups(input, o);
+  const level = Math.max(0, Math.min(levels.length - 1, Math.round(o.level)));
+  return groupedPlan(input, levels[level]!, { spine: o.spine, minSize: o.minSize });
+}

package/src/highways/p-hub/index.ts

@@ -0,0 +1,248 @@
+import { center, dist, polylineLength, type Point } from "../../geom.ts";
+import { buildSections, type Section } from "../../sections.ts";
+import { WayFinder } from "../../ways.ts";
+import { firstRoutes } from "../base.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { snapPlan, type SnapLine, type SnapMember } from "../snap.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The allocation of the edges to the hubs: `single` (each node to its nearest hub) or `multiple` (each edge to its best pair of hubs). */
+export type HubAllocation = "single" | "multiple";
+
+/** The values of `HubAllocation`. */
+export const HUB_ALLOCATIONS: readonly HubAllocation[] = Object.freeze(["single", "multiple"]);
+
+/** The candidate points of the hubs: the corners of the corner graph, or the centres of the cells of the tree of sections. */
+export type HubCandidates = "corners" | "sections";
+
+/** The values of `HubCandidates`. */
+export const HUB_CANDIDATES: readonly HubCandidates[] = Object.freeze(["corners", "sections"]);
+
+/** The options of the highway strategy `p-hub` (HWY-041 of the note on highways). */
+export interface PHubOptions {
+  /** The number of hubs. The value 0 gives the root of the number of nodes, rounded. The default is 0. */
+  readonly p: number;
+  /** The cost of a length on a link between two hubs against a length off the links, from 0 to 1. The default is 0.5. */
+  readonly alpha: number;
+  /** The allocation of the edges to the hubs. The default is `single`. */
+  readonly allocation: HubAllocation;
+  /** The candidate points of the hubs. The default is `corners`. */
+  readonly candidates: HubCandidates;
+  /** An edge rides a link only when its way through the two hubs is this many times its first route or less. The default is 1.25. */
+  readonly detour: number;
+  /** The number of passes of the local search with one swap of a hub. The default is 1. */
+  readonly swaps: number;
+  /** A link with fewer edges than this number is not a highway. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `p-hub`. */
+export const P_HUB_DEFAULTS: Readonly<PHubOptions> = Object.freeze({ p: 0, alpha: 0.5, allocation: "single", candidates: "corners", detour: 1.25, swaps: 1, minSize: 2 });
+
+/** The largest number of candidate points. A larger set keeps each `k`-th point. */
+const MAX_CANDIDATES = 300;
+
+/** One edge for the hub location: its two plug points, the centres of its two nodes, and the length of its first route. */
+interface HubEdge {
+  readonly edge: string;
+  readonly s: Point;
+  readonly t: Point;
+  readonly u: string;
+  readonly v: string;
+  readonly base: number;
+}
+
+/** This function gives the centres of the cells of each section of the tree. */
+function sectionCentres(root: Section): Point[] {
+  const out: Point[] = [];
+  const walk = (s: Section): void => {
+    out.push(center(s.cell));
+    s.children.forEach(walk);
+  };
+  walk(root);
+  return out;
+}
+
+/** This function gives the candidate points of the hubs, at most `MAX_CANDIDATES`, without the copies. */
+export function hubCandidates(input: HighwayInput, candidates: HubCandidates): Point[] {
+  const raw = candidates === "sections" ? sectionCentres(buildSections(input.graph.nodes)) : [...new WayFinder(input.graph.nodes).corners.points];
+  const seen = new Set<string>();
+  const points = raw.filter((p) => {
+    const key = `${Math.round(p.x)},${Math.round(p.y)}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  if (points.length <= MAX_CANDIDATES) return points;
+  const k = Math.ceil(points.length / MAX_CANDIDATES);
+  return points.filter((_, i) => i % k === 0);
+}
+
+/**
+ * This function chooses `p` points of `candidates` as the p-median of `points`. The greedy step adds the candidate that lowers the sum of the distances most.
+ * Then at most 4 passes of swaps lower the sum more. The result is the indices of the chosen candidates.
+ */
+export function pMedian(points: readonly Point[], candidates: readonly Point[], p: number): number[] {
+  const chosen: number[] = [];
+  const near = points.map(() => Infinity);
+  while (chosen.length < Math.min(p, candidates.length)) {
+    let pick = -1;
+    let best = Infinity;
+    for (let c = 0; c < candidates.length; c++) {
+      if (chosen.includes(c)) continue;
+      let sum = 0;
+      for (let i = 0; i < points.length; i++) sum += Math.min(near[i]!, dist(points[i]!, candidates[c]!));
+      if (sum < best - 1e-9) [best, pick] = [sum, c];
+    }
+    if (pick < 0) break;
+    chosen.push(pick);
+    points.forEach((q, i) => {
+      near[i] = Math.min(near[i]!, dist(q, candidates[pick]!));
+    });
+  }
+  // The swaps of Teitz and Bart: one chosen candidate changes for one other candidate while the sum falls.
+  // The nearest and the second nearest chosen candidate of each point give the sum after a swap in one pass over the points.
+  const d = candidates.map((c) => points.map((q) => dist(q, c)));
+  let first: number[] = [];
+  let second: number[] = [];
+  const nearTwo = (): void => {
+    first = points.map(() => -1);
+    second = points.map(() => -1);
+    points.forEach((_, p) => {
+      chosen.forEach((_, j) => {
+        const v = d[chosen[j]!]![p]!;
+        if (first[p]! < 0 || v < d[chosen[first[p]!]!]![p]!) [second[p], first[p]] = [first[p]!, j];
+        else if (second[p]! < 0 || v < d[chosen[second[p]!]!]![p]!) second[p] = j;
+      });
+    });
+  };
+  const at = (j: number, p: number): number => (j < 0 ? Infinity : d[chosen[j]!]![p]!);
+  nearTwo();
+  let sum = points.reduce((s, _, p) => s + at(first[p]!, p), 0);
+  for (let pass = 0; pass < 4; pass++) {
+    let better = false;
+    for (let i = 0; i < chosen.length; i++)
+      for (let c = 0; c < candidates.length; c++) {
+        if (chosen.includes(c)) continue;
+        let v = 0;
+        for (let p = 0; p < points.length; p++) v += Math.min(d[c]![p]!, first[p] === i ? at(second[p]!, p) : at(first[p]!, p));
+        if (v < sum - 1e-9) {
+          [sum, better] = [v, true];
+          chosen[i] = c;
+          nearTwo();
+        }
+      }
+    if (!better) break;
+  }
+  return chosen;
+}
+
+/** The two hubs of one edge, and its cost and its length on them. */
+interface HubTrip {
+  readonly h: number;
+  readonly k: number;
+  readonly cost: number;
+}
+
+/**
+ * This function gives the trip of each edge through the hubs `hubs`, or `undefined` for an edge that does not ride.
+ * The cost of a trip is `d(s, h) + alpha d(h, k) + d(k, t)`. An edge rides only when `h` and `k` differ and the cost is below its first route.
+ * Also, its length `d(s, h) + d(h, k) + d(k, t)` must be `detour` times its first route or less.
+ */
+function hubTrips(edges: readonly HubEdge[], nodes: ReadonlyMap<string, Point>, hubs: readonly Point[], o: Readonly<PHubOptions>): (HubTrip | undefined)[] {
+  const nearest = (p: Point): number => {
+    let best = 0;
+    for (let i = 1; i < hubs.length; i++) if (dist(p, hubs[i]!) < dist(p, hubs[best]!)) best = i;
+    return best;
+  };
+  const home = new Map<string, number>();
+  for (const [id, c] of nodes) home.set(id, nearest(c));
+  return edges.map((e) => {
+    const trip = (h: number, k: number): HubTrip | undefined => {
+      if (h === k) return undefined;
+      const a = dist(e.s, hubs[h]!);
+      const m = dist(hubs[h]!, hubs[k]!);
+      const b = dist(hubs[k]!, e.t);
+      const cost = a + o.alpha * m + b;
+      if (cost >= e.base || a + m + b > o.detour * e.base) return undefined;
+      return { h, k, cost };
+    };
+    if (o.allocation === "single") return trip(home.get(e.u)!, home.get(e.v)!);
+    let best: HubTrip | undefined;
+    for (let h = 0; h < hubs.length; h++)
+      for (let k = 0; k < hubs.length; k++) {
+        const t = trip(h, k);
+        if (t && (!best || t.cost < best.cost - 1e-9)) best = t;
+      }
+    return best;
+  });
+}
+
+/** This function gives the total cost of the edges: the cost of each trip, or the first route of an edge that does not ride. */
+function totalCost(edges: readonly HubEdge[], trips: readonly (HubTrip | undefined)[]): number {
+  return edges.reduce((s, e, i) => s + (trips[i]?.cost ?? e.base), 0);
+}
+
+/**
+ * This function gives the highways of the hub location (HWY-041, the p-hub median of O'Kelly 1987). The p-median of the plugs chooses `p` hubs from the candidates.
+ * Each swap pass changes one hub for one other candidate while the total cost falls. Each link between two hubs with `minSize` edges or more is a highway.
+ * The edges that ride a link snap to it, from their first hub to their second hub.
+ */
+export function pHubPlan(input: HighwayInput, o: Readonly<PHubOptions>): HighwayPlan {
+  const graph = input.graph;
+  if (graph.nodes.length === 0) return { highways: [] };
+  const routes = firstRoutes(input);
+  const edges: HubEdge[] = edgePlugs(graph).map(({ edge, ps, pt }) => {
+    const first = routes.get(edge.id);
+    return { edge: edge.id, s: ps.point, t: pt.point, u: edge.source.node, v: edge.target.node, base: first ? polylineLength(first) : dist(ps.point, pt.point) };
+  });
+  const nodes = new Map(graph.nodes.map((n) => [n.id, center(n.box)] as const));
+  const candidates = hubCandidates(input, o.candidates);
+  const p = Math.round(o.p) > 0 ? Math.round(o.p) : Math.max(2, Math.round(Math.sqrt(graph.nodes.length)));
+  if (candidates.length < 2 || edges.length === 0) return { highways: [] };
+  const chosen = pMedian(
+    edges.flatMap((e) => [e.s, e.t]),
+    candidates,
+    p,
+  );
+  const hubsOf = (list: readonly number[]): Point[] => list.map((c) => candidates[c]!);
+  let trips = hubTrips(edges, nodes, hubsOf(chosen), o);
+  let cost = totalCost(edges, trips);
+  for (let pass = 0; pass < Math.max(0, Math.round(o.swaps)); pass++) {
+    let better = false;
+    for (let i = 0; i < chosen.length; i++) {
+      let pick = -1;
+      let pickTrips = trips;
+      for (let c = 0; c < candidates.length; c++) {
+        if (chosen.includes(c)) continue;
+        const next = chosen.map((x, j) => (j === i ? c : x));
+        const t = hubTrips(edges, nodes, hubsOf(next), o);
+        const v = totalCost(edges, t);
+        if (v < cost - 1e-9) [cost, pick, pickTrips] = [v, c, t];
+      }
+      if (pick >= 0) {
+        chosen[i] = pick;
+        trips = pickTrips;
+        better = true;
+      }
+    }
+    if (!better) break;
+  }
+  const hubs = hubsOf(chosen);
+  const links = new Map<string, { a: number; b: number; members: SnapMember[] }>();
+  edges.forEach((e, i) => {
+    const t = trips[i];
+    if (!t) return;
+    const [a, b] = t.h < t.k ? [t.h, t.k] : [t.k, t.h];
+    const key = `${a}:${b}`;
+    const link = links.get(key) ?? { a, b, members: [] };
+    link.members.push({ edge: e.edge, from: hubs[t.h]!, to: hubs[t.k]!, at: 0 });
+    links.set(key, link);
+  });
+  const min = Math.max(2, Math.round(o.minSize));
+  const lines: SnapLine[] = [...links.values()]
+    .filter((l) => l.members.length >= min)
+    .sort((x, y) => x.a - y.a || x.b - y.b)
+    .map((l) => ({ key: `hub${l.a}-${l.b}`, a: hubs[l.a]!, b: hubs[l.b]!, members: l.members }));
+  return snapPlan(input, lines, { minSize: min });
+}