@mark1russell7/highways 0.4.2 → 0.5.1

package/src/highways/edge-paths/index.ts

@@ -0,0 +1,155 @@
+import { center, dist, 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 `edge-paths` (HWY-012 of the note on highways). */
+export interface EdgePathOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** An edge takes a path of other edges only when the path is this many times its own length or less. The default is 2. */
+  readonly distortion: number;
+  /** The weight of a link in the search is its length to this power. A larger power prefers paths of many short links. The default is 2. */
+  readonly power: number;
+  /** A highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `edge-paths`. */
+export const EDGE_PATH_DEFAULTS: Readonly<Required<Omit<EdgePathOptions, "margin" | "k">>> = Object.freeze({ distortion: 2, power: 2, minSize: 2 });
+
+/** One step of the path of an edge: the edge of the step and `true` when the path goes from its target to its source. */
+export interface PathStep {
+  readonly edge: string;
+  readonly back: boolean;
+}
+
+/**
+ * This function gives the edge paths of the graph (Wallinger and others 2022). The edges go in the order of their lengths, the longest first.
+ * An edge looks for the shortest path of other edges between its nodes, with the weight `length ^ power`. A path is good when its length is `distortion` times the length of the edge or less.
+ * The edges of a good path lock: they keep their own ways. An edge with a good path leaves the graph of the search. The map holds the path of each such edge.
+ */
+export function edgePaths(input: HighwayInput, o: Readonly<Pick<EdgePathOptions, "distortion" | "power">>): Map<string, PathStep[]> {
+  const nodes = new Map(input.graph.nodes.map((n) => [n.id, center(n.box)] as const));
+  const links = input.graph.edges
+    .filter((e) => e.source.node !== e.target.node && nodes.has(e.source.node) && nodes.has(e.target.node))
+    .map((e) => ({ id: e.id, s: e.source.node, t: e.target.node, len: dist(nodes.get(e.source.node)!, nodes.get(e.target.node)!) }));
+  const around = new Map<string, number[]>();
+  links.forEach((l, i) => {
+    for (const n of [l.s, l.t]) {
+      const list = around.get(n);
+      if (list) list.push(i);
+      else around.set(n, [i]);
+    }
+  });
+  const order = links.map((_, i) => i).sort((a, b) => links[b]!.len - links[a]!.len || (links[a]!.id < links[b]!.id ? -1 : 1));
+  const skip = new Uint8Array(links.length);
+  const lock = new Uint8Array(links.length);
+  const paths = new Map<string, PathStep[]>();
+  for (const i of order) {
+    if (lock[i]) continue;
+    const e = links[i]!;
+    skip[i] = 1;
+    const path = shortest(e.s, e.t, links, around, skip, o.power, o.distortion * e.len);
+    if (!path) {
+      skip[i] = 0;
+      continue;
+    }
+    for (const step of path) lock[step.index] = 1;
+    paths.set(e.id, path.map((step) => ({ edge: links[step.index]!.id, back: step.back })));
+  }
+  return paths;
+}
+
+/** This function gives the shortest path (Dijkstra) from the node `from` to the node `to` over the links that do not skip. It gives `undefined` when the length is more than `limit`. */
+function shortest(
+  from: string,
+  to: string,
+  links: readonly { s: string; t: string; len: number }[],
+  around: ReadonlyMap<string, readonly number[]>,
+  skip: Uint8Array,
+  power: number,
+  limit: number,
+): { index: number; back: boolean }[] | undefined {
+  const cost = new Map<string, number>([[from, 0]]);
+  const via = new Map<string, { index: number; back: boolean; prev: string }>();
+  const done = new Set<string>();
+  const open: { node: string; c: number }[] = [{ node: from, c: 0 }];
+  while (open.length > 0) {
+    let k = 0;
+    for (let j = 1; j < open.length; j++) if (open[j]!.c < open[k]!.c || (open[j]!.c === open[k]!.c && open[j]!.node < open[k]!.node)) k = j;
+    const { node } = open.splice(k, 1)[0]!;
+    if (done.has(node)) continue;
+    done.add(node);
+    if (node === to) break;
+    for (const index of around.get(node) ?? []) {
+      if (skip[index]) continue;
+      const l = links[index]!;
+      const back = l.t === node;
+      const next = back ? l.s : l.t;
+      if (done.has(next)) continue;
+      const c = cost.get(node)! + Math.pow(Math.max(l.len, 1e-9), power);
+      if (c < (cost.get(next) ?? Infinity)) {
+        cost.set(next, c);
+        via.set(next, { index, back, prev: node });
+        open.push({ node: next, c });
+      }
+    }
+  }
+  if (!via.has(to)) return undefined;
+  const out: { index: number; back: boolean }[] = [];
+  let length = 0;
+  for (let n = to; n !== from; ) {
+    const v = via.get(n)!;
+    out.push({ index: v.index, back: v.back });
+    length += links[v.index]!.len;
+    n = v.prev;
+  }
+  if (length > limit) return undefined;
+  return out.reverse();
+}
+
+/**
+ * This function gives the highways of the edge paths (HWY-012). An edge with a good path follows the ways of the edges of its path.
+ * Each edge of the path keeps its own way through the corner graph. So the ways share their links, and each shared stretch is a highway.
+ */
+export function edgePathPlan(input: HighwayInput, o: Readonly<EdgePathOptions>): 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 plugs = edgePlugs(input.graph);
+  const own = new Map<string, Point[]>();
+  for (const { edge, ps, pt } of plugs) {
+    const a = finder.out(ps);
+    const b = finder.out(pt);
+    own.set(edge.id, corners.path(a, b) ?? [a, b]);
+  }
+  const paths = edgePaths(input, o);
+  const ways: KeyedWay[] = [];
+  for (const { edge, ps, pt } of plugs) {
+    const path = paths.get(edge.id);
+    if (!path) {
+      ways.push({ edge: edge.id, key: "", points: own.get(edge.id)! });
+      continue;
+    }
+    const points: Point[] = [];
+    const join = (to: Point): void => {
+      const last = points[points.length - 1];
+      if (!last) {
+        points.push(to);
+        return;
+      }
+      if (dist(last, to) <= 1e-9) return;
+      const link = corners.path(last, to) ?? [last, to];
+      points.push(...link.slice(1));
+    };
+    join(finder.out(ps));
+    for (const step of path) {
+      const way = own.get(step.edge) ?? [];
+      const along = step.back ? [...way].reverse() : way;
+      if (along.length === 0) continue;
+      join(along[0]!);
+      points.push(...along.slice(1));
+    }
+    join(finder.out(pt));
+    ways.push({ edge: edge.id, key: "", points });
+  }
+  return sharedStretches(ways, { minSize: o.minSize, pull: (p) => corners.pull(p) });
+}

package/src/highways/fdeb/index.ts

@@ -0,0 +1,193 @@
+import { dist, type Point } from "../../geom.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import { compatibility } from "../hdbscan/index.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+import { boxPush, outOfBoxes, tracePlan } from "../trace.ts";
+
+/** The options of the highway strategy `fdeb` (HWY-002 with RULE-002 of the notes). */
+export interface FdebOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** Two edges attract each other when their compatibility is this value or more. The default is 0.6. */
+  readonly compatibility: number;
+  /** The spring constant that keeps each edge smooth. The default is 0.1. */
+  readonly spring: number;
+  /** The number of cycles. Each cycle doubles the points of each edge and halves the step. The default is 5. */
+  readonly cycles: number;
+  /** The number of steps of the first cycle. Each later cycle has two thirds of the steps of the cycle before it. The default is 50. */
+  readonly iterations: number;
+  /** The weight of the push of the boxes (RULE-002). The value 0 turns it off. The default is 1. */
+  readonly repulsion: number;
+  /**
+   * The stretch budget of each edge (RULE-002). An edge whose polyline is longer than this value times its straight line gets no pull.
+   * `Infinity` sets no budget. The default is 1.25.
+   */
+  readonly pullLimit: number;
+  /** The side of the grid that the points of the edges snap to after the cycles, 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 `fdeb`. */
+export const FDEB_DEFAULTS: Readonly<Required<Omit<FdebOptions, "margin" | "k">>> = Object.freeze({
+  compatibility: 0.6,
+  spring: 0.1,
+  cycles: 5,
+  iterations: 50,
+  repulsion: 1,
+  pullLimit: 1.25,
+  snap: 8,
+  minSize: 2,
+});
+
+/** The largest number of partners of one edge. The partners with the largest compatibility stay. */
+const PARTNERS = 32;
+
+/** The first step of the points, as a share of the median length of the edges. */
+const STEP = 0.04;
+
+/** One straight edge: its two ends. */
+interface Segment {
+  readonly a: Point;
+  readonly b: Point;
+}
+
+/** One partner of an edge: its index, its compatibility, and `flip` when it goes the other way. */
+interface Partner {
+  readonly j: number;
+  readonly c: number;
+  readonly flip: boolean;
+}
+
+/**
+ * This function gives the partners of each edge: the edges with a compatibility of `threshold` or more, at most 32, the largest first.
+ * The search reads only the edges whose middles are near enough in x, so it does not test each pair of a large graph.
+ */
+function partnersOf(segments: readonly Segment[], threshold: number): Partner[][] {
+  const n = segments.length;
+  const len = segments.map((s) => dist(s.a, s.b));
+  const mid = segments.map((s) => ({ x: (s.a.x + s.b.x) / 2, y: (s.a.y + s.b.y) / 2 }));
+  const longest = len.reduce((m, l) => Math.max(m, l), 0);
+  const t = Math.max(1e-3, Math.min(1, threshold));
+  const order = Array.from({ length: n }, (_, i) => i).sort((i, j) => mid[i]!.x - mid[j]!.x || i - j);
+  const found: Partner[][] = Array.from({ length: n }, () => []);
+  for (let a = 0; a < n; a++) {
+    const i = order[a]!;
+    // `Cp >= t` needs a distance of the middles of `avg (1 / t - 1)` or less.
+    const reach = ((len[i]! + longest) / 2) * (1 / t - 1);
+    for (let b = a + 1; b < n; b++) {
+      const j = order[b]!;
+      if (mid[j]!.x - mid[i]!.x > reach) break;
+      const c = compatibility(segments[i]!.a, segments[i]!.b, segments[j]!.a, segments[j]!.b);
+      if (c < t) continue;
+      const si = segments[i]!;
+      const sj = segments[j]!;
+      const flip = (si.b.x - si.a.x) * (sj.b.x - sj.a.x) + (si.b.y - si.a.y) * (sj.b.y - sj.a.y) < 0;
+      found[i]!.push({ j, c, flip });
+      found[j]!.push({ j: i, c, flip });
+    }
+  }
+  return found.map((list) => list.sort((p, q) => q.c - p.c || p.j - q.j).slice(0, PARTNERS));
+}
+
+/** This function gives the length of a polyline. */
+const lengthOf = (p: readonly Point[]): number => {
+  let s = 0;
+  for (let i = 1; i < p.length; i++) s += dist(p[i - 1]!, p[i]!);
+  return s;
+};
+
+/** This function gives a polyline with a new point in the middle of each leg. */
+function subdivide(p: readonly Point[]): Point[] {
+  const out: Point[] = [p[0]!];
+  for (let i = 1; i < p.length; i++) {
+    const a = p[i - 1]!;
+    const b = p[i]!;
+    out.push({ x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }, b);
+  }
+  return out;
+}
+
+/**
+ * This function gives the polylines of the force-directed edge bundling (HWY-002, Holten and van Wijk 2009), with the box field of RULE-002.
+ * Each edge starts as the straight line between its two points out of the plugs. Each cycle doubles its points.
+ * In each step, a point moves by `step` times the mean pull to the matching points of its partners. The springs to its two neighbours also move it.
+ * The boxes push the points, and after each cycle a point in a box moves out of it. An edge over its stretch budget gets no pull in that step.
+ */
+export function fdebLines(input: HighwayInput, finder: WayFinder, o: Readonly<FdebOptions>): Map<string, Point[]> {
+  const plugs = edgePlugs(input.graph);
+  const segments = plugs.map(({ ps, pt }) => ({ a: finder.out(ps), b: finder.out(pt) }));
+  const n = segments.length;
+  const out = new Map<string, Point[]>();
+  if (n === 0) return out;
+  const partners = partnersOf(segments, o.compatibility);
+  const lengths = segments.map((s) => dist(s.a, s.b));
+  const sorted = [...lengths].sort((a, b) => a - b);
+  const median = sorted[Math.floor(sorted.length / 2)]!;
+  const pad = finder.margin / 2;
+  const reach = finder.margin * 2;
+  const budget = o.pullLimit > 0 ? o.pullLimit : Infinity;
+  let lines: Point[][] = segments.map((s) => [s.a, s.b]);
+  let step = STEP * median;
+  let iterations = Math.max(0, Math.round(o.iterations));
+  for (let cycle = 0; cycle < Math.max(0, Math.round(o.cycles)); cycle++) {
+    lines = lines.map(subdivide);
+    const P = lines[0]!.length;
+    for (let it = 0; it < iterations; it++) {
+      const next = lines.map((l) => [...l]);
+      for (let e = 0; e < n; e++) {
+        const line = lines[e]!;
+        const pull = lengths[e]! > 1e-9 && lengthOf(line) <= budget * lengths[e]!;
+        for (let i = 1; i < P - 1; i++) {
+          const p = line[i]!;
+          let fx = 0;
+          let fy = 0;
+          if (pull) {
+            let w = 0;
+            for (const q of partners[e]!) {
+              const m = lines[q.j]![q.flip ? P - 1 - i : i]!;
+              const d = dist(p, m);
+              if (d < 1e-9) continue;
+              fx += (q.c * (m.x - p.x)) / d;
+              fy += (q.c * (m.y - p.y)) / d;
+              w += q.c;
+            }
+            if (w > 0) {
+              fx /= w;
+              fy /= w;
+            }
+          }
+          if (o.repulsion > 0) {
+            const push = boxPush(finder.obstacles, p, reach);
+            fx += o.repulsion * push.x;
+            fy += o.repulsion * push.y;
+          }
+          const a = line[i - 1]!;
+          const b = line[i + 1]!;
+          const sx = o.spring * ((a.x + b.x) / 2 - p.x);
+          const sy = o.spring * ((a.y + b.y) / 2 - p.y);
+          next[e]![i] = { x: p.x + step * fx + sx, y: p.y + step * fy + sy };
+        }
+      }
+      lines = next;
+    }
+    // The hard projection of RULE-002: no point stays in a box.
+    lines = lines.map((l) => l.map((p, i) => (i === 0 || i === l.length - 1 ? p : outOfBoxes(finder.obstacles, p, pad))));
+    step /= 2;
+    iterations = Math.round((iterations * 2) / 3);
+  }
+  plugs.forEach(({ edge }, e) => out.set(edge.id, lines[e]!));
+  return out;
+}
+
+/**
+ * This function gives the highways of the force-directed edge bundling (HWY-002 with RULE-002).
+ * The points of the bundled polylines snap to a grid of side `snap`, so the points of one bundle come together.
+ * Each edge then goes through its points along the corner graph, and the stretches that `minSize` edges share become highways.
+ */
+export function fdebPlan(input: HighwayInput, o: Readonly<FdebOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const lines = fdebLines(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: "fdeb" });
+}

package/src/highways/fixtures.test-util.ts

@@ -0,0 +1,71 @@
+import { expect, it } from "vitest";
+import { checkProperties } from "../bench/properties.ts";
+import { inputGraph } from "../bench/screen/forms.ts";
+import { screenInputs } from "../bench/screen/set.ts";
+import { CASES } from "../cases.ts";
+import type { Box } from "../geom.ts";
+import type { Graph } from "../model.ts";
+import { STRATEGIES } from "../strategies/builtins.ts";
+import { getStrategy } from "../strategies/model.ts";
+import { checkPlan, type HighwayInput, type HighwayPlan } from "./model.ts";
+import { highwayRouterStrategy } from "./router.ts";
+
+/** This function gives a box at `x`, `y` with the size `w` by `h`. */
+export const box = (x: number, y: number, w = 40, h = 20): Box => ({ x, y, w, h });
+
+/** The case `case-hub-chain`. */
+export const hub: Graph = CASES.find((c) => c.name === "case-hub-chain")!.make();
+
+/** The input `screen-v1/small-clustered/s0`. */
+export const clustered: Graph = inputGraph(screenInputs().find((i) => i.id === "screen-v1/small-clustered/s0")!);
+
+/** Three edges from one area on the left to one area on the right (one of them reversed), and two edges from the top to the bottom. Two keys alternate. */
+export const flows: Graph = {
+  nodes: [
+    ...[0, 1, 2].flatMap((i) => [
+      { id: `l${i}`, box: box(0, 30 * i) },
+      { id: `r${i}`, box: box(600, 30 * i) },
+    ]),
+    ...[0, 1].flatMap((i) => [
+      { id: `u${i}`, box: box(250 + 60 * i, -400) },
+      { id: `d${i}`, box: box(250 + 60 * i, 400) },
+    ]),
+  ],
+  edges: [
+    { id: "a", source: { node: "l0" }, target: { node: "r0" }, data: { collection: "p" } },
+    { id: "b", source: { node: "l1" }, target: { node: "r1" }, data: { collection: "q" } },
+    { id: "c", source: { node: "r2" }, target: { node: "l2" }, data: { collection: "p" } },
+    { id: "x", source: { node: "u0" }, target: { node: "d0" }, data: { collection: "p" } },
+    { id: "y", source: { node: "u1" }, target: { node: "d1" }, data: { collection: "q" } },
+  ],
+};
+
+/** Three thin nodes on the left and three on the right, with three near horizontal edges between them. */
+export const parallel: Graph = {
+  nodes: [0, 1, 2].flatMap((i) => [
+    { id: `l${i}`, box: box(0, 8 * i, 40, 6) },
+    { id: `r${i}`, box: box(600, 8 * i, 40, 6) },
+  ]),
+  edges: [0, 1, 2].map((i) => ({ id: `e${i}`, source: { node: `l${i}` }, target: { node: `r${i}` } })),
+};
+
+/**
+ * This function adds the common tests of a highway strategy. The strategy is in the registry, and it gives a correct plan the same each time.
+ * Its routes break no hard rule after `follow`.
+ */
+export function commonTests<O extends object>(name: string, defaults: O, plan: (input: HighwayInput, o: O) => HighwayPlan, graphs: readonly Graph[]): void {
+  it("is in the registry, and gives a correct plan, the same each time", () => {
+    const strategy = getStrategy(STRATEGIES, "highway", name);
+    for (const graph of [...graphs, hub, clustered]) {
+      const made = strategy.run({ graph }, { ...defaults });
+      expect(checkPlan(graph, made)).toEqual([]);
+      expect(plan({ graph }, defaults)).toEqual(made);
+    }
+  });
+
+  it("gives routes with no break of a hard rule after follow", () => {
+    const router = highwayRouterStrategy(getStrategy(STRATEGIES, "highway", name));
+    expect(checkProperties(hub, router.run(hub), 1_000_000)).toEqual([]);
+    expect(checkProperties(clustered, router.run(clustered), 1_000_000)).toEqual([]);
+  });
+}

package/src/highways/flow-clusters/index.ts

@@ -0,0 +1,143 @@
+import { dist, type Point } from "../../geom.ts";
+import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The linkage of the hierarchical clustering: the distance of two clusters from the distances of their edges. */
+export type Linkage = "average" | "complete" | "single";
+
+/** The values of `Linkage`. */
+export const LINKAGES: readonly Linkage[] = Object.freeze(["average", "complete", "single"]);
+
+/** The options of the highway strategy `flow-clusters` (HWY-023 of the note on highways). */
+export interface FlowClusterOptions {
+  /** Two clusters join while their distance is this value or less. The distance is a share of the length of the shorter edge. The default is 0.3. */
+  readonly tau: number;
+  /** The linkage. The default is `average`. */
+  readonly linkage: Linkage;
+  /** With `true`, the source of one edge only compares with the source of the other edge. The default is `false`. */
+  readonly directed: boolean;
+  /** 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 `trunk`: one flow line from one area to the other area. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `flow-clusters`. */
+export const FLOW_CLUSTER_DEFAULTS: Readonly<FlowClusterOptions> = Object.freeze({ tau: 0.3, linkage: "average", directed: false, minSize: 2, 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 flow distance of two edges (Zhu and Guo 2014): `max(|s_e - s_f|, |t_e - t_f|) / min(len e, len f)`.
+ * Without `directed`, it is the smaller value of the two directions of `f`, and `flip` is `true` when the opposite direction is smaller.
+ */
+export function flowDistance(s1: Point, t1: Point, s2: Point, t2: Point, directed: boolean): { d: number; flip: boolean } {
+  const len = Math.max(1e-9, Math.min(dist(s1, t1), dist(s2, t2)));
+  const direct = Math.max(dist(s1, s2), dist(t1, t2)) / len;
+  if (directed) return { d: direct, flip: false };
+  const back = Math.max(dist(s1, t2), dist(t1, s2)) / len;
+  return back < direct ? { d: back, flip: true } : { d: direct, flip: false };
+}
+
+/**
+ * This function clusters the points of a distance matrix with the chain of nearest neighbours. The linkage is reducible, so the chain gives the same tree as the greedy order.
+ * The clusters join while their distance is `tau` or less. The function gives the cluster of each point, as the index of a point of the cluster.
+ */
+export function chainClusters(n: number, d: Float64Array, tau: number, linkage: Linkage): Int32Array {
+  const size = new Int32Array(n).fill(1);
+  const alive = new Uint8Array(n).fill(1);
+  const parent = new Int32Array(n);
+  for (let i = 0; i < n; i++) parent[i] = i;
+  // A cluster that has no neighbour within `tau` is done: under a reducible linkage, its distances only grow.
+  const done = new Uint8Array(n);
+  const find = (i: number): number => {
+    while (parent[i] !== i) i = parent[i] = parent[parent[i]!]!;
+    return i;
+  };
+  const chain: number[] = [];
+  for (;;) {
+    if (chain.length === 0) {
+      let start = -1;
+      for (let i = 0; i < n && start < 0; i++) if (alive[i] && !done[i]) start = i;
+      if (start < 0) break;
+      chain.push(start);
+    }
+    const a = chain[chain.length - 1]!;
+    let b = -1;
+    let best = Infinity;
+    for (let j = 0; j < n; j++) {
+      if (j === a || !alive[j] || done[j]) continue;
+      const v = d[a * n + j]!;
+      if (v < best || (v === best && j < b)) [best, b] = [v, j];
+    }
+    const prev = chain.length >= 2 ? chain[chain.length - 2]! : -1;
+    if (b < 0 || best > tau) {
+      done[a] = 1;
+      chain.length = 0;
+      continue;
+    }
+    if (prev >= 0 && d[a * n + prev]! <= best) {
+      // `a` and `prev` are nearest neighbours of each other: they join.
+      chain.length -= 2;
+      const [i, j] = a < prev ? [a, prev] : [prev, a];
+      for (let k = 0; k < n; k++) {
+        if (!alive[k] || k === i || k === j) continue;
+        const di = d[i * n + k]!;
+        const dj = d[j * n + k]!;
+        const v = linkage === "single" ? Math.min(di, dj) : linkage === "complete" ? Math.max(di, dj) : (size[i]! * di + size[j]! * dj) / (size[i]! + size[j]!);
+        d[i * n + k] = v;
+        d[k * n + i] = v;
+      }
+      size[i] = size[i]! + size[j]!;
+      alive[j] = 0;
+      parent[j] = i;
+      continue;
+    }
+    chain.push(b);
+  }
+  const out = new Int32Array(n);
+  for (let i = 0; i < n; i++) out[i] = find(i);
+  return out;
+}
+
+/**
+ * This function gives the flow clusters of the edges (HWY-023). It clusters the edges as points in 4D, with the cut at `tau`.
+ * 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 flowClusters(input: HighwayInput, o: Readonly<FlowClusterOptions>): 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>();
+  // A large graph splits into blocks of `BLOCK` edges, in the order of the x of the sources.
+  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;
+  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 = flowDistance(block[i]!.s, block[i]!.t, block[j]!.s, block[j]!.t, o.directed).d;
+        d[i * n + j] = v;
+        d[j * n + i] = v;
+      }
+    const cluster = chainClusters(n, d, o.tau, o.linkage);
+    const first = new Map<number, number>();
+    block.forEach((e, i) => {
+      const c = cluster[i]!;
+      if (!first.has(c)) first.set(c, i);
+      const lead = block[first.get(c)!]!;
+      const flip = i === first.get(c) ? false : flowDistance(lead.s, lead.t, e.s, e.t, o.directed).flip;
+      groups.set(e.edge, { key: `f${from + first.get(c)!}`, flip });
+    });
+  }
+  return groups;
+}
+
+/**
+ * This function gives the highways of the flow clusters (HWY-023). The clusters of `flowClusters` with `minSize` edges or more get highways.
+ * With the spine `trunk`, each cluster gets one trunk from one area to the other area. With `shared`, the edges of a cluster share their ways.
+ */
+export function flowClusterPlan(input: HighwayInput, o: Readonly<FlowClusterOptions>): HighwayPlan {
+  return groupedPlan(input, flowClusters(input, o), { spine: o.spine, minSize: o.minSize });
+}