@mark1russell7/highways 0.4.2 → 0.5.0

package/src/bench/screen/measures.ts

@@ -45,6 +45,9 @@ const ROWS: readonly Row[] = [
   ["R11.q05", "R11", "route.plug-spacing.q05", "0 to 1", "higher", true],
   ["R13.outside", "R13", "route.outside", "count", "lower", false],
   ["R15.inflections", "R15", "route.inflections", "count for each route", "lower", false],
+  // MEAS3A, for the steps `router` and `highway`. R12 is the share of the ink near a parallel leg of other edges. A narrow channel between boxes moves it.
+  ["R12.share", "R12", "route.lane.separation", "0 to 1", "lower", true],
+  ["R14.share", "R14", "route.orthogonality", "0 to 1", "higher", false],
   ["ink", "R1", "route.ink", "units", "lower", true],
   // The bundles.
   ["B1.inkSaved", "B1", "route.bundle.ink-saved", "0 to 1", "higher", false],
@@ -54,6 +57,18 @@ const ROWS: readonly Row[] = [
   ["B3.median", "B3", "route.bundle.stretch.median", "ratio", "lower", false],
   ["B3.q95", "B3", "route.bundle.stretch.q95", "ratio", "lower", false],
   ["B6.max", "B6", "route.bundle.merge-angle.max", "degrees", "lower", false],
+  // MEAS3A, for the steps `router` and `highway`. B5, B8 and B9 read the runs and the trunks of the result. B8 is good or bad only in context, as B2.
+  ["B5.crossings", "B5", "route.bundle.lane-crossings", "count", "lower", false],
+  ["B7.ratio", "B7", "route.bundle.occupied-area", "ratio", "lower", false],
+  ["B8.runs", "B8", "route.bundle.runs", "count", "lower", false],
+  ["B8.median", "B8", "route.bundle.run-edges.median", "count", "higher", false],
+  ["B8.max", "B8", "route.bundle.run-edges.max", "count", "higher", false],
+  ["B9.median", "B9", "route.bundle.lane-fidelity.median", "ratio", "lower", false],
+  ["B9.max", "B9", "route.bundle.lane-fidelity.max", "ratio", "lower", false],
+  // M1 and M4 of the room, for the steps `router` and `highway`: the lanes of each shared segment open at `MEASURE_LANE_WIDTH`.
+  // The step `room` of `runSuite` gives the same keys for the boards that a room strategy opens.
+  ["M1.area", "M1", "route.lane.area", "ratio", "lower", false],
+  ["M4.laneThrough", "M4", "route.lane.through", "count", "lower", true],
   // The order fragility (W3 of MEAS3, from WILD-056): the spread of a measure over random orders of the edges. The placement can move it.
   ["W3.crossings", "W3", "route.order.crossings", "IQR over the median", "lower", true],
   ["W3.detour", "W3", "route.order.detour", "IQR over the median", "lower", true],
@@ -75,6 +90,9 @@ const ROWS: readonly Row[] = [
   ["Z10.ids", "Z10", "route.stability.highway-ids", "0 to 1", "higher", false],
   // The zoom levels and the groups. The default grouping rule reads the positions, so most of these measures depend on the placement.
   ["level-nesting", "Z6", "route.level.nesting", "count", "lower", false],
+  // MEAS3A, for the steps `router`, `highway` and `group`. Z2 is the count of the hard rule `link-ends`. Z9 needs a result with zoom levels.
+  ["Z2.linkEnds", "Z2", "route.level.link-ends", "count", "lower", false],
+  ["Z9.mean", "Z9", "route.level.link-agreement", "no unit", "lower", true],
   ["Z3.through", "Z3", "route.level.through", "count", "lower", true],
   ["Z3.length", "Z3", "route.level.link-length", "units", "lower", true],
   ["Z4.farItems", "Z4", "route.level.far-items", "count", "lower", true],

package/src/bench/screen/screen.ts

@@ -7,8 +7,11 @@ import { asRouter, createRegistry, getStrategy, listStrategies, register, STEPS,
 import { compareStep, type CompareRow, type CompareStep, type StepComparison } from "../compare.ts";
 import { bundledShare, bundleStretch, mergeAngle } from "../measures/bundles.ts";
 import { highwayEdits } from "../measures/highways.ts";
+import { laneArea, laneCrossings, laneFidelity, lanesThrough, occupiedArea, openLanes, orthogonality, routeSeparation, runProfile } from "../measures/lanes.ts";
+import { linkAgreement } from "../measures/levels.ts";
 import { orderFragility } from "../measures/order.ts";
 import { paretoFront, type Objective } from "../measures/pareto.ts";
+import { boardUnit } from "../measures/routes.ts";
 import { routeStability } from "../measures/stability.ts";
 import { quantile } from "../measures/stats.ts";
 import { checkLevels, checkProperties, TOLERANCE } from "../properties.ts";
@@ -208,6 +211,8 @@ const givesRoutes = (step: ScreenStep): step is "router" | "highway" => step ===
 /**
  * This function gives the values of a row of `compareStep`, with the measures of `measureQuality` for a router.
  * A router also gets the bundled share (B2), the merge angle (B6) and the bundle stretch (B3) against the routes `base` of `corners`.
+ * It also gets the measures of MEAS3A: R12, R14, B5, B7, B8, B9, M1 and M4. The lane measures open each shared segment at `MEASURE_LANE_WIDTH`.
+ * A result with zoom levels also gets the link agreement (Z9), for a router and for a grouping rule.
  */
 function rowValues(step: ScreenStep, graph: Graph, row: CompareRow, base: () => readonly Route[]): Record<string, number> {
   const values: Record<string, number> = { ...row.values };
@@ -224,6 +229,27 @@ function rowValues(step: ScreenStep, graph: Graph, row: CompareRow, base: () =>
     values["B3.median"] = st.median;
     values["B3.q95"] = st.q95;
     values["B6.max"] = mergeAngle(row.result.routes);
+    const routes = row.result.routes;
+    const open = openLanes(row.result);
+    values["R12.share"] = routeSeparation(routes);
+    values["R14.share"] = orthogonality(routes);
+    values["B5.crossings"] = laneCrossings(open.graph);
+    values["B7.ratio"] = occupiedArea(routes, boardUnit(graph));
+    const runs = runProfile(open.graph);
+    values["B8.runs"] = runs.runs;
+    values["B8.median"] = runs.median;
+    values["B8.max"] = runs.max;
+    const lf = laneFidelity(routes, open);
+    if (lf) {
+      values["B9.median"] = lf.median;
+      values["B9.max"] = lf.max;
+    }
+    values["M1.area"] = laneArea(graph, open);
+    values["M4.laneThrough"] = lanesThrough(graph, open);
+  }
+  if ((givesRoutes(step) || step === "group") && row.result?.levels) {
+    const la = linkAgreement(graph, row.result.levels, row.result.routes, boardUnit(graph));
+    if (la !== undefined) values["Z9.mean"] = la;
   }
   return values;
 }
@@ -350,6 +376,8 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
       }
       const { hard, deterministic } = rowRules(step, graph, row, again?.rows[i]);
       const values = rowValues(step, graph, row, cornersBase);
+      // Z2 is the count of the hard rule `link-ends`, as a measure. The steps `router`, `highway` and `group` check the rule.
+      if (hard["link-ends"] !== undefined) values["Z2.linkEnds"] = hard["link-ends"];
       if (shuffles > 0 && row.result) {
         const router = asRouter(strategy as Strategy<"router">, own[row.strategy]);
         const f = orderFragility(graph, (g) => router.route(g), { orders: shuffles, seed, base: row.result });

package/src/channels.ts

@@ -0,0 +1,56 @@
+import { dist, type Box, type Point } from "./geom.ts";
+import type { Obstacles } from "./visibility.ts";
+
+/** The largest distance that `channelWidth` looks on each side of a link. A wider channel counts as this width on that side. */
+export const CHANNEL_REACH = 64;
+
+/**
+ * This function gives the distance from `p` along the unit direction `d` to the box, or `Infinity` when the ray does not meet the box.
+ * A point inside the box gives 0. The function uses the slab test.
+ */
+export function rayToBox(p: Point, d: Point, box: Box): number {
+  let lo = 0;
+  let hi = Infinity;
+  for (const [o, v, min, max] of [
+    [p.x, d.x, box.x, box.x + box.w],
+    [p.y, d.y, box.y, box.y + box.h],
+  ] as const) {
+    if (Math.abs(v) < 1e-12) {
+      if (o < min || o > max) return Infinity;
+      continue;
+    }
+    const t1 = (min - o) / v;
+    const t2 = (max - o) / v;
+    lo = Math.max(lo, Math.min(t1, t2));
+    hi = Math.min(hi, Math.max(t1, t2));
+    if (lo > hi) return Infinity;
+  }
+  return lo;
+}
+
+/** This function gives the free distance from `p` along the unit direction `d` to the nearest box, up to `reach`. */
+function freeRay(obstacles: Obstacles, p: Point, d: Point, reach: number): number {
+  const q = { x: p.x + d.x * reach, y: p.y + d.y * reach };
+  let best = reach;
+  obstacles.query({ x: Math.min(p.x, q.x), y: Math.min(p.y, q.y), w: Math.abs(q.x - p.x), h: Math.abs(q.y - p.y) }, (n) => {
+    best = Math.min(best, rayToBox(p, d, n.box));
+  });
+  return best;
+}
+
+/**
+ * This function gives the width of the channel of the link from `a` to `b`. The width is the free space between the nearest boxes on the two sides.
+ * It measures the width at five points of the link, and gives the smallest. Each side counts up to `reach`.
+ * A link of length 0 gives the free space across the x axis at its point.
+ */
+export function channelWidth(obstacles: Obstacles, a: Point, b: Point, reach: number = CHANNEL_REACH): number {
+  const len = dist(a, b);
+  const n = len > 1e-9 ? { x: -(b.y - a.y) / len, y: (b.x - a.x) / len } : { x: 0, y: 1 };
+  const back = { x: -n.x, y: -n.y };
+  let width = Infinity;
+  for (const u of [0.1, 0.3, 0.5, 0.7, 0.9]) {
+    const p = { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u };
+    width = Math.min(width, freeRay(obstacles, p, n, reach) + freeRay(obstacles, p, back, reach));
+  }
+  return width;
+}

package/src/highways/diffusion/index.ts

@@ -0,0 +1,103 @@
+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 `diffusion` (HWY-020 of the note on highways). */
+export interface DiffusionOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** The share of the density that each step of the diffusion takes from the links next to a link. The default is 0.25. */
+  readonly a: number;
+  /** The number of steps of the diffusion. The default is 3. */
+  readonly steps: number;
+  /** The weight of the density in the cost of a link. The default is 1. */
+  readonly lambda: number;
+  /** The power of the discount of a dense link. The default is 1. */
+  readonly gamma: number;
+  /** A highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `diffusion`. */
+export const DIFFUSION_DEFAULTS: Readonly<Required<Omit<DiffusionOptions, "margin" | "k">>> = Object.freeze({ a: 0.25, steps: 3, lambda: 1, gamma: 1, minSize: 2 });
+
+/**
+ * This function gives the density of the edges on the links of the corner graph after the diffusion, as a share of the largest density.
+ * The density of a link starts as the number of first ways on it. Each step mixes it with the mean density of the links that share a corner with it:
+ * `rho_{k+1}(l) = (1 - a) rho_k(l) + a mean(rho_k(l'))`. The key of a link is `i * M + j` for the corners `i < j` of a graph of `M` corners.
+ */
+export function linkDensity(neighbours: (i: number) => readonly number[], corners: number, use: ReadonlyMap<number, number>, a: number, steps: number): Map<number, number> {
+  const M = corners;
+  const links: number[] = [];
+  for (let i = 0; i < M; i++) for (const j of neighbours(i)) if (j > i) links.push(i * M + j);
+  let rho = new Map<number, number>(links.map((l) => [l, use.get(l) ?? 0]));
+  const share = Math.max(0, Math.min(1, a));
+  for (let s = 0; s < Math.round(steps); s++) {
+    // The sum of the densities and the number of the links at each corner.
+    const sum = new Float64Array(M);
+    const deg = new Int32Array(M);
+    for (const [l, v] of rho) {
+      const i = Math.floor(l / M);
+      const j = l % M;
+      sum[i] = sum[i]! + v;
+      sum[j] = sum[j]! + v;
+      deg[i] = deg[i]! + 1;
+      deg[j] = deg[j]! + 1;
+    }
+    const next = new Map<number, number>();
+    for (const [l, v] of rho) {
+      const i = Math.floor(l / M);
+      const j = l % M;
+      const n = deg[i]! + deg[j]! - 2;
+      const mean = n > 0 ? (sum[i]! + sum[j]! - 2 * v) / n : v;
+      next.set(l, (1 - share) * v + share * mean);
+    }
+    rho = next;
+  }
+  let max = 0;
+  for (const v of rho.values()) max = Math.max(max, v);
+  if (max > 0) for (const [l, v] of rho) rho.set(l, v / max);
+  return rho;
+}
+
+/**
+ * This function gives the highways of the route-aware bundling on the corner graph (HWY-020).
+ * The first ways of the edges give the density of each link. A diffusion along the graph smooths it.
+ * Then each edge takes a shortest way where a dense link costs less: `cost(l) = len(l) / (1 + lambda rho(l))^gamma`, with `rho` from 0 to 1.
+ * Each stretch that `minSize` ways or more share after the second pass is one highway. The highways stay on the links of the corner graph.
+ */
+export function diffusionPlan(input: HighwayInput, o: Readonly<DiffusionOptions>): 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 number of first ways on each link.
+  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 rho = linkDensity((i) => corners.neighbours(i), M, use, o.a, o.steps);
+  const lambda = Math.max(0, o.lambda);
+  const gamma = Math.max(0, o.gamma);
+  const floor = 1 / Math.pow(1 + lambda, gamma);
+  const cost = (i: number, j: number, d: number): number => d / Math.pow(1 + lambda * (rho.get(link(i, j)) ?? 0), gamma);
+  // The second pass: the dense links cost less, so the ways come together on them.
+  const ways: KeyedWay[] = [];
+  plugs.forEach(({ edge }, n) => {
+    const [a, b] = ends[n]!;
+    const way = corners.path(a, b, cost, floor);
+    if (way) ways.push({ edge: edge.id, key: "diffusion", points: way });
+  });
+  return sharedStretches(ways, { minSize: o.minSize, pull: (p) => corners.pull(p) });
+}

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/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 });
+}