@mark1russell7/highways 0.4.1 → 0.5.0

package/src/highways/hdbscan/index.ts

@@ -0,0 +1,250 @@
+import { dist, type Point } from "../../geom.ts";
+import { flowDistance } from "../flow-clusters/index.ts";
+import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The distance of two edges: 1 less their compatibility of FDEB, or the flow distance in 4D of HWY-023. */
+export type EdgeDistance = "compatibility" | "flow";
+
+/** The values of `EdgeDistance`. */
+export const EDGE_DISTANCES: readonly EdgeDistance[] = Object.freeze(["compatibility", "flow"]);
+
+/** The options of the highway strategy `hdbscan` (HWY-028 of the note on highways). */
+export interface HdbscanOptions {
+  /** A cluster has this number of edges or more. The default is 3. */
+  readonly minClusterSize: number;
+  /** The core distance of an edge is the distance to its neighbour of this rank. The default is 3. */
+  readonly minSamples: number;
+  /** The distance of two edges. The default is `compatibility`. */
+  readonly distance: EdgeDistance;
+  /** The spine of each cluster. The default is `trunk`: one trunk from one area to the other area. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `hdbscan`. */
+export const HDBSCAN_DEFAULTS: Readonly<HdbscanOptions> = Object.freeze({ minClusterSize: 3, minSamples: 3, distance: "compatibility", spine: "trunk" });
+
+/** The largest number of edges in one distance matrix. A larger graph splits into blocks of edges in the order of their sources. */
+const BLOCK = 2500;
+
+/**
+ * This function gives the compatibility of two edges of FDEB (Holten and van Wijk 2009): `Ca Cs Cp Cv`, from 0 to 1.
+ * `Ca` is the angle, `Cs` the scale, `Cp` the position and `Cv` the visibility. The direction of an edge does not change the value.
+ */
+export function compatibility(p0: Point, p1: Point, q0: Point, q1: Point): number {
+  const lp = dist(p0, p1);
+  const lq = dist(q0, q1);
+  if (lp <= 1e-9 || lq <= 1e-9) return 0;
+  const ca = Math.abs(((p1.x - p0.x) * (q1.x - q0.x) + (p1.y - p0.y) * (q1.y - q0.y)) / (lp * lq));
+  const avg = (lp + lq) / 2;
+  const cs = 2 / (avg / Math.min(lp, lq) + Math.max(lp, lq) / avg);
+  const pm = { x: (p0.x + p1.x) / 2, y: (p0.y + p1.y) / 2 };
+  const qm = { x: (q0.x + q1.x) / 2, y: (q0.y + q1.y) / 2 };
+  const cp = avg / (avg + dist(pm, qm));
+  const cv = Math.min(visibility(p0, p1, q0, q1), visibility(q0, q1, p0, p1));
+  return ca * cs * cp * cv;
+}
+
+/** This function gives the visibility of the edge `q` from the edge `p` of FDEB: `max(1 - 2 |pm - im| / |i0 i1|, 0)`. The points `i` are the projection of `q` on the line of `p`. */
+function visibility(p0: Point, p1: Point, q0: Point, q1: Point): number {
+  const dx = p1.x - p0.x;
+  const dy = p1.y - p0.y;
+  const l2 = dx * dx + dy * dy;
+  const project = (q: Point): Point => {
+    const u = ((q.x - p0.x) * dx + (q.y - p0.y) * dy) / l2;
+    return { x: p0.x + u * dx, y: p0.y + u * dy };
+  };
+  const i0 = project(q0);
+  const i1 = project(q1);
+  const span = dist(i0, i1);
+  if (span <= 1e-9) return 0;
+  const im = { x: (i0.x + i1.x) / 2, y: (i0.y + i1.y) / 2 };
+  const pm = { x: (p0.x + p1.x) / 2, y: (p0.y + p1.y) / 2 };
+  return Math.max(1 - (2 * dist(pm, im)) / span, 0);
+}
+
+/**
+ * This function gives the HDBSCAN clusters of the points of a distance matrix (Campello, Moulavi and Sander 2013). The value -1 is noise.
+ * The core distance of a point is the distance to its `minSamples`-th nearest point. The mutual reachability is `max(core(a), core(b), d(a, b))`.
+ * The minimum spanning tree of the mutual reachability gives the tree of the clusters. A split with two parts of `minClusterSize` or more gives two clusters.
+ * The selection keeps the clusters with the largest stability, `sum (lambda_leave - lambda_birth)`, with `lambda = 1 / distance`. The root is not a cluster.
+ */
+export function hdbscanLabels(n: number, d: Float64Array, minClusterSize: number, minSamples: number): Int32Array {
+  const labels = new Int32Array(n).fill(-1);
+  const mcs = Math.max(2, Math.round(minClusterSize));
+  if (n < mcs || n < 2) return labels;
+  const k = Math.max(1, Math.min(n - 1, Math.round(minSamples)));
+  // The core distance of each point.
+  const core = new Float64Array(n);
+  const row = new Float64Array(n - 1);
+  for (let i = 0; i < n; i++) {
+    let c = 0;
+    for (let j = 0; j < n; j++) if (j !== i) row[c++] = d[i * n + j]!;
+    row.sort();
+    core[i] = row[k - 1]!;
+  }
+  const reach = (i: number, j: number): number => Math.max(core[i]!, core[j]!, d[i * n + j]!);
+  // The minimum spanning tree (Prim), with ties to the lower index.
+  const inTree = new Uint8Array(n);
+  const best = new Float64Array(n).fill(Infinity);
+  const from = new Int32Array(n).fill(-1);
+  const links: { a: number; b: number; w: number }[] = [];
+  let cur = 0;
+  inTree[0] = 1;
+  for (let step = 1; step < n; step++) {
+    let next = -1;
+    for (let j = 0; j < n; j++) {
+      if (inTree[j]) continue;
+      const w = reach(cur, j);
+      if (w < best[j]!) [best[j], from[j]] = [w, cur];
+      if (next < 0 || best[j]! < best[next]!) next = j;
+    }
+    inTree[next] = 1;
+    links.push({ a: from[next]!, b: next, w: best[next]! });
+    cur = next;
+  }
+  links.sort((p, q) => p.w - q.w || p.a - q.a || p.b - q.b);
+  // The single linkage tree: the node `n + i` is the merge `i`.
+  const parent = new Int32Array(2 * n - 1).fill(-1);
+  const left = new Int32Array(n - 1);
+  const right = new Int32Array(n - 1);
+  const height = new Float64Array(n - 1);
+  const size = new Int32Array(2 * n - 1).fill(1);
+  const uf = new Int32Array(2 * n - 1);
+  for (let i = 0; i < uf.length; i++) uf[i] = i;
+  const find = (i: number): number => {
+    while (uf[i] !== i) i = uf[i] = uf[uf[i]!]!;
+    return i;
+  };
+  links.forEach((l, i) => {
+    const ra = find(l.a);
+    const rb = find(l.b);
+    const node = n + i;
+    left[i] = ra;
+    right[i] = rb;
+    height[i] = l.w;
+    size[node] = size[ra]! + size[rb]!;
+    parent[ra] = node;
+    parent[rb] = node;
+    uf[ra] = node;
+    uf[rb] = node;
+  });
+  const root = 2 * n - 2;
+  const lambdaOf = (h: number): number => 1 / Math.max(h, 1e-9);
+  const leaves = (node: number): number[] => {
+    const out: number[] = [];
+    const stack = [node];
+    while (stack.length > 0) {
+      const x = stack.pop()!;
+      if (x < n) out.push(x);
+      else stack.push(left[x - n]!, right[x - n]!);
+    }
+    return out;
+  };
+  // The condensed tree. Each cluster has a birth lambda, a parent cluster, its stability and the points that leave it at their lambda.
+  const birth: number[] = [0];
+  const up: number[] = [-1];
+  const stability: number[] = [0];
+  const fall = new Int32Array(n).fill(0);
+  const queue: [node: number, cluster: number][] = [[root, 0]];
+  while (queue.length > 0) {
+    const [node, c] = queue.shift()!;
+    const i = node - n;
+    const lambda = lambdaOf(height[i]!);
+    const kids = [left[i]!, right[i]!];
+    const big = kids.filter((x) => size[x]! >= mcs);
+    if (big.length === 2) {
+      for (const x of kids) {
+        const id = birth.length;
+        birth.push(lambda);
+        up.push(c);
+        stability.push(0);
+        stability[c] = stability[c]! + size[x]! * (lambda - birth[c]!);
+        queue.push([x, id]);
+      }
+      continue;
+    }
+    for (const x of kids) {
+      if (big.includes(x)) {
+        if (x >= n) queue.push([x, c]);
+        else {
+          fall[x] = c;
+          stability[c] = stability[c]! + (lambda - birth[c]!);
+        }
+        continue;
+      }
+      for (const p of leaves(x)) {
+        fall[p] = c;
+        stability[c] = stability[c]! + (lambda - birth[c]!);
+      }
+    }
+  }
+  // The selection by the excess of mass, from the last cluster to the first. A child cluster always has a larger id than its parent.
+  const count = birth.length;
+  const chosen = new Uint8Array(count);
+  const value = [...stability];
+  const children: number[][] = Array.from({ length: count }, () => []);
+  for (let c = 1; c < count; c++) children[up[c]!]!.push(c);
+  for (let c = count - 1; c >= 1; c--) {
+    const sub = children[c]!.reduce((s, x) => s + value[x]!, 0);
+    if (children[c]!.length > 0 && sub > value[c]!) value[c] = sub;
+    else {
+      chosen[c] = 1;
+      const stack = [...children[c]!];
+      while (stack.length > 0) {
+        const x = stack.pop()!;
+        chosen[x] = 0;
+        stack.push(...children[x]!);
+      }
+    }
+  }
+  for (let p = 0; p < n; p++) {
+    let c = fall[p]!;
+    while (c > 0 && !chosen[c]) c = up[c]!;
+    labels[p] = c > 0 ? c : -1;
+  }
+  return labels;
+}
+
+/**
+ * This function gives the HDBSCAN clusters of the edges (HWY-028). The edges that are noise get no group.
+ * Each edge of a cluster gets `flip` when it goes opposite to the first edge of the cluster.
+ */
+export function hdbscanClusters(input: HighwayInput, o: Readonly<HdbscanOptions>): Map<string, EdgeGroup> {
+  const ends = edgePlugs(input.graph).map(({ edge, ps, pt }) => ({ edge: edge.id, s: ps.point, t: pt.point }));
+  const groups = new Map<string, EdgeGroup>();
+  const order = ends.length > BLOCK ? [...ends].sort((a, b) => a.s.x - b.s.x || a.s.y - b.s.y || (a.edge < b.edge ? -1 : 1)) : ends;
+  const between = (a: (typeof ends)[number], b: (typeof ends)[number]): number =>
+    o.distance === "flow" ? flowDistance(a.s, a.t, b.s, b.t, false).d : 1 - compatibility(a.s, a.t, b.s, b.t);
+  for (let from = 0; from < order.length; from += BLOCK) {
+    const block = order.slice(from, from + BLOCK);
+    const n = block.length;
+    const d = new Float64Array(n * n);
+    for (let i = 0; i < n; i++)
+      for (let j = i + 1; j < n; j++) {
+        const v = between(block[i]!, block[j]!);
+        d[i * n + j] = v;
+        d[j * n + i] = v;
+      }
+    const labels = hdbscanLabels(n, d, o.minClusterSize, o.minSamples);
+    const lead = new Map<number, number>();
+    block.forEach((e, i) => {
+      const c = labels[i]!;
+      if (c < 0) return;
+      if (!lead.has(c)) lead.set(c, i);
+      const l = block[lead.get(c)!]!;
+      const flip = (e.t.x - e.s.x) * (l.t.x - l.s.x) + (e.t.y - e.s.y) * (l.t.y - l.s.y) < 0;
+      groups.set(e.edge, { key: `c${from}:${c}`, flip });
+    });
+  }
+  return groups;
+}
+
+/**
+ * This function gives the highways of the HDBSCAN clusters (HWY-028). The clusters that live over a long range of densities are the highways.
+ * The number of highways is not fixed, and the noise edges stay alone.
+ */
+export function hdbscanPlan(input: HighwayInput, o: Readonly<HdbscanOptions>): HighwayPlan {
+  return groupedPlan(input, hdbscanClusters(input, o), { spine: o.spine, minSize: Math.max(2, Math.round(o.minClusterSize)) });
+}

package/src/highways/hough/index.ts

@@ -0,0 +1,182 @@
+import { dist, type Point } from "../../geom.ts";
+import type { WayOptions } from "../../ways.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { linePoint, snapPlan, type SnapLine } from "../snap.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The options of the highway strategy `hough` (HWY-024 of the note on highways). */
+export interface HoughOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** The width of the votes in the angle, in degrees. An edge joins a peak within this angle. The default is 8. */
+  readonly dTheta: number;
+  /** The width of the votes in the offset, in units of the board. An edge joins a peak when its middle is this near to the line. The default is 12. */
+  readonly dRho: number;
+  /** A peak with fewer edges than this number is not a corridor. The default is 3. */
+  readonly minVotes: number;
+  /** With `true`, the peaks are only horizontal or vertical lines. The default is `false`. */
+  readonly orthogonal: boolean;
+}
+
+/** The default options of the strategy `hough`. */
+export const HOUGH_DEFAULTS: Readonly<Required<Omit<HoughOptions, "margin" | "k">>> = Object.freeze({ dTheta: 8, dRho: 12, minVotes: 3, orthogonal: false });
+
+/** The line of one edge: its direction angle from 0 to pi, its offset along the normal, its middle and its ends. */
+interface EdgeLine {
+  readonly edge: string;
+  readonly theta: number;
+  readonly s: Point;
+  readonly t: Point;
+  readonly mid: Point;
+  readonly len: number;
+}
+
+/** A peak of the votes: its angle, its offset and the sum of its votes. */
+export interface HoughPeak {
+  readonly theta: number;
+  readonly rho: number;
+  readonly votes: number;
+}
+
+const DEG = Math.PI / 180;
+
+/** This function gives the offset of a point from the line through the origin with the direction angle `theta`. */
+const offsetOf = (p: Point, theta: number): number => -p.x * Math.sin(theta) + p.y * Math.cos(theta);
+
+/** This function gives the place of a point along the direction angle `theta`. */
+const placeOf = (p: Point, theta: number): number => p.x * Math.cos(theta) + p.y * Math.sin(theta);
+
+/** This function gives the difference of two direction angles, from 0 to pi / 2. */
+function angleGap(a: number, b: number): number {
+  const d = Math.abs(a - b) % Math.PI;
+  return Math.min(d, Math.PI - d);
+}
+
+/**
+ * This function gives the peaks of the votes of the lines (Duda and Hart 1972). Each line votes for its angle and its offset, with a weight of its length.
+ * A vote spreads as a Gaussian with the widths `dTheta / 2` and `dRho / 2`. The accumulator has bins of 1 degree and of `dRho / 4`.
+ * A peak is a bin with a larger sum than each other bin within `dTheta` and `dRho`. The peaks come in the order of their votes.
+ */
+export function houghPeaks(lines: readonly { theta: number; mid: Point; len: number }[], o: Readonly<Pick<HoughOptions, "dTheta" | "dRho" | "orthogonal">>): HoughPeak[] {
+  if (lines.length === 0) return [];
+  const thetas = o.orthogonal ? [0, 90] : Array.from({ length: 180 }, (_, i) => i);
+  const T = thetas.length;
+  const rhoStep = Math.max(1e-6, o.dRho / 4);
+  let maxRho = 0;
+  for (const l of lines) maxRho = Math.max(maxRho, Math.abs(l.mid.x) + Math.abs(l.mid.y));
+  const R = Math.ceil(maxRho / rhoStep) + 4;
+  const rows = 2 * R + 1;
+  const acc = new Float64Array(T * rows);
+  const wTheta = Math.max(1e-6, o.dTheta);
+  const sT = wTheta / 2;
+  const sR = o.dRho / 2;
+  const reachR = Math.ceil(o.dRho / rhoStep);
+  for (const l of lines) {
+    for (let ti = 0; ti < T; ti++) {
+      const gap = angleGap(thetas[ti]! * DEG, l.theta) / DEG;
+      if (gap > wTheta) continue;
+      const rho = offsetOf(l.mid, thetas[ti]! * DEG);
+      const center = Math.round(rho / rhoStep);
+      const wt = Math.exp(-(gap * gap) / (2 * sT * sT)) * l.len;
+      for (let r = center - reachR; r <= center + reachR; r++) {
+        if (r < -R || r > R) continue;
+        const dr = r * rhoStep - rho;
+        acc[ti * rows + r + R] = acc[ti * rows + r + R]! + wt * Math.exp(-(dr * dr) / (2 * sR * sR));
+      }
+    }
+  }
+  const reachT = o.orthogonal ? 0 : Math.ceil(wTheta);
+  const peaks: HoughPeak[] = [];
+  for (let ti = 0; ti < T; ti++)
+    for (let r = 0; r < rows; r++) {
+      const v = acc[ti * rows + r]!;
+      if (v <= 0) continue;
+      let top = true;
+      for (let dt = -reachT; dt <= reachT && top; dt++)
+        for (let dr = -reachR; dr <= reachR && top; dr++) {
+          if (dt === 0 && dr === 0) continue;
+          let tj = ti + dt;
+          let rj = r - R;
+          // The angle wraps at 180 degrees, and the offset changes its sign there.
+          if (tj < 0) [tj, rj] = [tj + T, -rj];
+          else if (tj >= T) [tj, rj] = [tj - T, -rj];
+          rj += dr;
+          if (rj < -R || rj > R) continue;
+          const w = acc[tj * rows + rj + R]!;
+          // A tie goes to the first bin in the order of the accumulator.
+          if (w > v || (w === v && tj * rows + rj + R < ti * rows + r)) top = false;
+        }
+      if (top) peaks.push({ theta: thetas[ti]! * DEG, rho: (r - R) * rhoStep, votes: v });
+    }
+  peaks.sort((a, b) => b.votes - a.votes || a.theta - b.theta || a.rho - b.rho);
+  return peaks;
+}
+
+/**
+ * This function gives the corridors of the votes (HWY-024). Each edge joins the first peak with an angle within `dTheta` and its middle within `dRho` of the line.
+ * The corridor runs over the common span of the projections of its edges on the line. Each edge snaps to the ends of that span.
+ * A member that makes the span shorter than four margins leaves, while the peak keeps `minVotes` edges.
+ */
+export function houghLines(input: HighwayInput, o: Readonly<HoughOptions>): SnapLine[] {
+  const margin = o.margin ?? 5;
+  const lines: EdgeLine[] = [];
+  for (const { edge, ps, pt } of edgePlugs(input.graph)) {
+    const s = ps.point;
+    const t = pt.point;
+    const len = dist(s, t);
+    if (len <= 1e-9) continue;
+    const theta = (((Math.atan2(t.y - s.y, t.x - s.x) % Math.PI) + Math.PI) % Math.PI);
+    lines.push({ edge: edge.id, theta, s, t, mid: { x: (s.x + t.x) / 2, y: (s.y + t.y) / 2 }, len });
+  }
+  const peaks = houghPeaks(lines, o);
+  const taken = new Set<string>();
+  const out: SnapLine[] = [];
+  const need = Math.max(2, Math.round(o.minVotes));
+  for (const [pi, p] of peaks.entries()) {
+    let members = lines.filter((l) => !taken.has(l.edge) && angleGap(l.theta, p.theta) <= o.dTheta * DEG && Math.abs(offsetOf(l.mid, p.theta) - p.rho) <= o.dRho);
+    const span = (list: readonly EdgeLine[]): [number, number] => {
+      let lo = -Infinity;
+      let hi = Infinity;
+      for (const l of list) {
+        const a = placeOf(l.s, p.theta);
+        const b = placeOf(l.t, p.theta);
+        lo = Math.max(lo, Math.min(a, b));
+        hi = Math.min(hi, Math.max(a, b));
+      }
+      return [lo, hi];
+    };
+    let [lo, hi] = span(members);
+    while (members.length >= need && hi - lo < 4 * margin) {
+      // The member that limits the span the most leaves.
+      let best = -1;
+      let gain = -Infinity;
+      members.forEach((_, i) => {
+        const [l2, h2] = span(members.filter((__, j) => j !== i));
+        if (h2 - l2 > gain) [gain, best] = [h2 - l2, i];
+      });
+      members = members.filter((_, j) => j !== best);
+      [lo, hi] = span(members);
+    }
+    if (members.length < need || hi - lo < 4 * margin) continue;
+    for (const l of members) taken.add(l.edge);
+    const a = linePoint(p.theta, p.rho, lo);
+    const b = linePoint(p.theta, p.rho, hi);
+    out.push({
+      key: `p${pi}`,
+      a,
+      b,
+      members: members.map((l) => {
+        const forward = placeOf(l.s, p.theta) <= placeOf(l.t, p.theta);
+        return { edge: l.edge, from: forward ? a : b, to: forward ? b : a, at: 0 };
+      }),
+    });
+  }
+  return out;
+}
+
+/**
+ * This function gives the highways of the Hough votes (HWY-024). The peaks of the votes of the straight lines of the edges are corridors.
+ * Each corridor is a spine through the corner graph, and its edges ride it over their common span.
+ */
+export function houghPlan(input: HighwayInput, o: Readonly<HoughOptions>): HighwayPlan {
+  const way = { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) };
+  return snapPlan(input, houghLines(input, o), { ...way, minSize: Math.max(2, Math.round(o.minVotes)) });
+}

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

@@ -0,0 +1,181 @@
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { orderLanes } from "../../segments.ts";
+import { WayFinder } from "../../ways.ts";
+import { firstRoutes, nearestPlace, tidyPlan } from "../base.ts";
+import { lengthBetween, memberAt, pointAt, type Highway, type HighwayInput, type HighwayPlan } from "../model.ts";
+import { candidatePlan, type CandidateSource } from "../select/index.ts";
+import { spinePart } from "../snap.ts";
+import { edgePlugs, sharedStretches } from "../stretches.ts";
+
+/** A generator of candidate arcs: `runs` (the shared stretches of the first ways of all edges) or a generator of the strategy `select`. */
+export type ArcSource = "runs" | CandidateSource;
+
+/** The values of `ArcSource`. */
+export const ARC_SOURCES: readonly ArcSource[] = Object.freeze(["runs", "corridors", "quickbundles", "wspd", "road-classes", "flow-field", "od-cells", "shared-ways"]);
+
+/** The options of the highway strategy `hub-arcs` (HWY-042 of the note on highways). */
+export interface HubArcOptions {
+  /** The largest number of arcs (highways). The default is 12. */
+  readonly q: number;
+  /** The cost of a length on an arc against a length off the arcs, from 0 to 1. The default is 0.5. */
+  readonly alpha: number;
+  /** An edge rides an arc only when its legs plus its part of the arc are this many times its first route or less. The default is 1.25. */
+  readonly stretch: number;
+  /** The number of passes of the local search with one swap. The default is 1. */
+  readonly swaps: number;
+  /** An arc with fewer edges than this number is not a highway. The default is 2. */
+  readonly minSize: number;
+  /** The generators of the candidate arcs. The default is `runs`, `corridors` and `road-classes`. */
+  readonly generators: readonly ArcSource[];
+}
+
+/** The default options of the strategy `hub-arcs`. */
+export const HUB_ARC_DEFAULTS: Readonly<HubArcOptions> = Object.freeze({
+  q: 12,
+  alpha: 0.5,
+  stretch: 1.25,
+  swaps: 1,
+  minSize: 2,
+  generators: Object.freeze(["runs", "corridors", "road-classes"] as ArcSource[]),
+});
+
+/** The largest number of candidate arcs. The longest arcs stay. */
+const MAX_ARCS = 400;
+
+/** The place of one edge on one arc: where it joins and leaves, and the cost it saves against its first route. */
+interface Ride {
+  readonly on: number;
+  readonly off: number;
+  readonly save: number;
+}
+
+/** This function gives the candidate arcs: the spines of the plans of the generators, without the copies, with the longest first. */
+export function candidateArcs(input: HighwayInput, generators: readonly ArcSource[]): Point[][] {
+  const spines: Point[][] = [];
+  for (const g of generators) {
+    const plan = g === "runs" ? runsPlan(input) : candidatePlan(input, g);
+    for (const h of plan.highways) spines.push([...h.spine]);
+  }
+  const seen = new Set<string>();
+  const out: Point[][] = [];
+  for (const s of spines) {
+    if (s.length < 2 || polylineLength(s) <= 1e-6) continue;
+    const key = s.map((p) => `${Math.round(p.x)},${Math.round(p.y)}`).join(";");
+    const back = [...s].reverse().map((p) => `${Math.round(p.x)},${Math.round(p.y)}`).join(";");
+    if (seen.has(key) || seen.has(back)) continue;
+    seen.add(key);
+    out.push(s);
+  }
+  out.sort((a, b) => polylineLength(b) - polylineLength(a));
+  return out.slice(0, MAX_ARCS);
+}
+
+/** This function gives the shared stretches of the first ways of all edges, with no keys. */
+function runsPlan(input: HighwayInput): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes);
+  const ways = edgePlugs(input.graph).map(({ edge, ps, pt }) => {
+    const a = finder.out(ps);
+    const b = finder.out(pt);
+    return { edge: edge.id, key: "", points: finder.corners.path(a, b) ?? [a, b] };
+  });
+  return sharedStretches(ways, { minSize: 2, pull: (p) => finder.corners.pull(p) });
+}
+
+/**
+ * This function gives the highways of the hub arc location (Campbell, Ernst and Krishnamoorthy 2005). It chooses at most `q` arcs from the candidates.
+ * An edge on an arc costs its two legs plus `alpha` times its part of the arc. An edge off the arcs costs its first route.
+ * The greedy step adds the arc that saves the most cost. Then each swap pass changes one chosen arc for one other arc while the saving grows.
+ * Each edge rides the arc that saves the most for it.
+ */
+export function hubArcPlan(input: HighwayInput, o: Readonly<HubArcOptions>): HighwayPlan {
+  const margin = 5;
+  const routes = firstRoutes(input);
+  const plugs = edgePlugs(input.graph);
+  const arcs = candidateArcs(input, o.generators);
+  const q = Math.max(0, Math.round(o.q));
+  if (q === 0 || arcs.length === 0) return { highways: [] };
+  // The saving of each edge on each arc. A saving of 0 means that the edge does not ride the arc.
+  const rides: (Ride | undefined)[][] = arcs.map((spine) =>
+    plugs.map(({ edge, ps, pt }) => {
+      const first = routes.get(edge.id);
+      const base = first ? polylineLength(first) : dist(ps.point, pt.point);
+      const on = nearestPlace(spine, ps.point);
+      const off = nearestPlace(spine, pt.point);
+      const along = lengthBetween(spine, Math.min(on, off), Math.max(on, off));
+      if (along < margin) return undefined;
+      const legs = dist(ps.point, pointAt(spine, on)) + dist(pointAt(spine, off), pt.point);
+      if (legs + along > o.stretch * base) return undefined;
+      const save = base - (legs + o.alpha * along);
+      return save > 0 ? { on, off, save } : undefined;
+    }),
+  );
+  const n = plugs.length;
+  const total = (chosen: readonly number[]): number => {
+    let sum = 0;
+    for (let e = 0; e < n; e++) {
+      let best = 0;
+      for (const a of chosen) best = Math.max(best, rides[a]![e]?.save ?? 0);
+      sum += best;
+    }
+    return sum;
+  };
+  const chosen: number[] = [];
+  while (chosen.length < q) {
+    const now = total(chosen);
+    let pick = -1;
+    let gain = 1e-9;
+    for (let a = 0; a < arcs.length; a++) {
+      if (chosen.includes(a)) continue;
+      const g = total([...chosen, a]) - now;
+      if (g > gain) [gain, pick] = [g, a];
+    }
+    if (pick < 0) break;
+    chosen.push(pick);
+  }
+  for (let pass = 0; pass < Math.round(o.swaps); pass++) {
+    let better = false;
+    for (let i = 0; i < chosen.length; i++) {
+      const now = total(chosen);
+      let pick = -1;
+      let gain = 1e-9;
+      for (let a = 0; a < arcs.length; a++) {
+        if (chosen.includes(a)) continue;
+        const next = chosen.map((x, j) => (j === i ? a : x));
+        const g = total(next) - now;
+        if (g > gain) [gain, pick] = [g, a];
+      }
+      if (pick >= 0) {
+        chosen[i] = pick;
+        better = true;
+      }
+    }
+    if (!better) break;
+  }
+  // Each edge rides its best arc.
+  const riders = new Map<number, { edge: string; ride: Ride; points: Point[] }[]>();
+  plugs.forEach(({ edge, ps, pt }, e) => {
+    let best = -1;
+    for (const a of chosen) if ((rides[a]![e]?.save ?? 0) > (best < 0 ? 0 : rides[best]![e]!.save)) best = a;
+    if (best < 0) return;
+    const ride = rides[best]![e]!;
+    const list = riders.get(best) ?? [];
+    list.push({ edge: edge.id, ride, points: [ps.point, ...spinePart(arcs[best]!, ride.on, ride.off), pt.point] });
+    riders.set(best, list);
+  });
+  const highways: Highway[] = [];
+  for (const a of [...chosen].sort((x, y) => x - y)) {
+    const list = riders.get(a) ?? [];
+    if (list.length < Math.max(2, o.minSize)) continue;
+    const spine = arcs[a]!;
+    const lanes = orderLanes(spine, list.map((r) => ({ edge: r.edge, points: r.points })), "bundle");
+    const byEdge = new Map(list.map((r) => [r.edge, r.ride]));
+    highways.push({
+      id: `h${highways.length}`,
+      key: `a${a}`,
+      spine,
+      lanes,
+      members: lanes.map((edge) => memberAt(spine, edge, byEdge.get(edge)!.on, byEdge.get(edge)!.off)),
+    });
+  }
+  return tidyPlan({ highways });
+}

package/src/highways/index.ts

@@ -5,3 +5,33 @@ export { highwayRouter, highwayRouterStrategy } from "./router.ts";
 export { keysPlan, type KeysOptions } from "./keys/index.ts";
 export { sharedWaysPlan, type SharedWaysOptions } from "./shared-ways/index.ts";
 export { BREAK_EVEN, CORRIDOR_DEFAULTS, corridorPlan, minHash, type CorridorOptions } from "./corridors/index.ts";
+export { basePlan, HIGHWAY_BASES, type HighwayBase } from "./base.ts";
+export { MEET_DEFAULTS, meetMember, meetPlan, type MeetOptions } from "./meet/index.ts";
+export { meetingPoints, WEISZFELD_DEFAULTS, weiszfeldPlan, type WeiszfeldOptions } from "./weiszfeld/index.ts";
+export { STUB_DEFAULTS, stubPlan, type StubEnds, type StubOptions } from "./stubs/index.ts";
+export { ZIPPER_DEFAULTS, zipLegs, zipperPlan, type Zip, type ZipLimits, type ZipperOptions } from "./zipper/index.ts";
+export { LEVEL_HIGHWAY_DEFAULTS, levelHighwayPlan, type LevelHighwayOptions } from "./level-links/index.ts";
+export { edgePlugs, sharedStretches, type EdgePlugs, type KeyedWay, type SharedStretchOptions } from "./stretches.ts";
+export { GROUP_SPINES, groupedPlan, weberPoint, type EdgeGroup, type GroupedOptions, type GroupSpine } from "./grouped.ts";
+export { mdf, QUICKBUNDLES_DEFAULTS, quickBundles, quickBundlesPlan, resample, type BundleLine, type BundleOrder, type QuickBundlesOptions } from "./quickbundles/index.ts";
+export { ROAD_CLASS_DEFAULTS, roadClassPlan, type RoadClassOptions } from "./road-classes/index.ts";
+export { FLOW_FIELD_DEFAULTS, flowFieldPlan, type FieldEnd, type FlowFieldOptions } from "./flow-field/index.ts";
+export { SplitTree, WSPD_DEFAULTS, wspdGroups, wspdPlan, type SplitCell, type WspdOptions } from "./wspd/index.ts";
+export { OD_CELL_DEFAULTS, odCellPlan, odGroups, type OdCellOptions } from "./od-cells/index.ts";
+export { CANDIDATE_SOURCES, candidatePlan, candidateScore, SELECT_DEFAULTS, selectPlan, type CandidateSource, type SelectOptions } from "./select/index.ts";
+export { MINGLE_DEFAULTS, mingleBundles, minglePlan, type MingleOptions } from "./mingle/index.ts";
+export { SPIRAL_DEFAULTS, spiralJoin, spiralPlan, spiralTree, type SpiralNode, type SpiralOptions } from "./spiral/index.ts";
+export { FLOW_CLUSTER_DEFAULTS, flowClusterPlan, flowClusters, flowDistance, chainClusters, LINKAGES, type FlowClusterOptions, type Linkage } from "./flow-clusters/index.ts";
+export { characteristicPoints, representative, segmentClusters, segmentDistance, TRACLUS_DEFAULTS, traclusPlan, type RouteSegment, type TraclusOptions } from "./traclus/index.ts";
+export { DIFFUSION_DEFAULTS, diffusionPlan, linkDensity, type DiffusionOptions } from "./diffusion/index.ts";
+export { NESTED_DEFAULTS, nestedGroups, nestedPlan, nestingViolations, type NestedOptions } from "./nested/index.ts";
+export { channelOverflows, LANES_DEFAULTS, lanesPlan, type LanesOptions } from "./lanes/index.ts";
+export { GROWTH_DEFAULTS, growthPlan, type GrowthOptions, type GrowthOrder } from "./growth/index.ts";
+export { EDGE_PATH_DEFAULTS, edgePathPlan, edgePaths, type EdgePathOptions, type PathStep } from "./edge-paths/index.ts";
+export { SOFT_KEY_DEFAULTS, softDistance, softKeyClusters, softKeyPlan, type SoftKeyOptions } from "./soft-keys/index.ts";
+export { linePoint, snapPlan, spinePart, type SnapLine, type SnapMember, type SnapOptions } from "./snap.ts";
+export { HOUGH_DEFAULTS, houghLines, houghPeaks, houghPlan, type HoughOptions, type HoughPeak } from "./hough/index.ts";
+export { densityRidges, lineDensity, RIDGE_DEFAULTS, ridgeLines, ridgePlan, type DensityImage, type Ridge, type RidgeOptions, type RidgeSource } from "./ridges/index.ts";
+export { compatibility, EDGE_DISTANCES, HDBSCAN_DEFAULTS, hdbscanClusters, hdbscanLabels, hdbscanPlan, type EdgeDistance, type HdbscanOptions } from "./hdbscan/index.ts";
+export { ARC_SOURCES, candidateArcs, HUB_ARC_DEFAULTS, hubArcPlan, type ArcSource, type HubArcOptions } from "./hub-arcs/index.ts";
+export * from "./gates/index.ts";