@mark1russell7/highways 0.4.2 → 0.5.1

package/src/highways/link-communities/index.ts

@@ -0,0 +1,189 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, type Point } from "../../geom.ts";
+import { groupedPlan, weberPoint, type EdgeGroup, type GroupSpine } from "../grouped.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The options of the highway strategy `link-communities` (HWY-030 of the note on highways). */
+export interface LinkCommunityOptions {
+  /** The cut of the tree of the edges. The value 0 cuts at the best partition density. A value above 0 keeps the joins with this similarity or more. The default is 0. */
+  readonly threshold: number;
+  /** A community with this number of edges or more gets highways, after the check of the geometry. The default is 2. */
+  readonly minSize: number;
+  /** The largest distance of an end of an edge to the Weber point of its end of the community, in units of the board. The default is 6. */
+  readonly spread: number;
+  /** The spine of each community. The default is `shared`. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `link-communities`. */
+export const LINK_COMMUNITY_DEFAULTS: Readonly<LinkCommunityOptions> = Object.freeze({ threshold: 0, minSize: 2, spread: 6, spine: "shared" });
+
+/** One pair of edges with a common node, and its similarity. */
+interface EdgePair {
+  readonly e: number;
+  readonly f: number;
+  readonly s: number;
+}
+
+/** The ends of one edge as node indices. */
+export interface LinkEdge {
+  readonly u: number;
+  readonly v: number;
+}
+
+/**
+ * This function gives the similarity of each pair of edges with a common node `k` (Ahn, Bagrow and Lehmann 2010).
+ * For the edges `(i, k)` and `(j, k)`, the value is `|N+(i) ∩ N+(j)| / |N+(i) ∪ N+(j)|`. `N+(i)` is the node `i` and its neighbours.
+ * Two parallel edges get the value 1. A loop has no pair.
+ */
+function edgePairs(n: number, edges: readonly LinkEdge[]): EdgePair[] {
+  const near: Set<number>[] = Array.from({ length: n }, (_, i) => new Set([i]));
+  const at: number[][] = Array.from({ length: n }, () => []);
+  edges.forEach(({ u, v }, e) => {
+    if (u === v) return;
+    near[u]!.add(v);
+    near[v]!.add(u);
+    at[u]!.push(e);
+    at[v]!.push(e);
+  });
+  const jaccard = (i: number, j: number): number => {
+    const a = near[i]!;
+    const b = near[j]!;
+    let both = 0;
+    for (const x of a) if (b.has(x)) both++;
+    return both / (a.size + b.size - both);
+  };
+  const out = new Map<string, EdgePair>();
+  for (let k = 0; k < n; k++) {
+    const list = at[k]!;
+    for (let x = 0; x < list.length; x++)
+      for (let y = x + 1; y < list.length; y++) {
+        const e = Math.min(list[x]!, list[y]!);
+        const f = Math.max(list[x]!, list[y]!);
+        if (e === f) continue;
+        const key = `${e},${f}`;
+        if (out.has(key)) continue;
+        const oe = edges[e]!.u === k ? edges[e]!.v : edges[e]!.u;
+        const of = edges[f]!.u === k ? edges[f]!.v : edges[f]!.u;
+        out.set(key, { e, f, s: oe === of ? 1 : jaccard(oe, of) });
+      }
+  }
+  return [...out.values()].sort((p, q) => q.s - p.s || p.e - q.e || p.f - q.f);
+}
+
+/**
+ * This function gives the link communities of the edges: the single linkage of the edges by their similarity.
+ * With `threshold` 0, the cut is at the level of the best partition density `D = (2/M) Σ m_c (m_c - n_c + 1) / ((n_c - 2)(n_c - 1))`.
+ * When the best `D` is above 0, the first level with it applies. When it is 0 (a forest), the last level applies.
+ * The result is the community of each edge, as the index of an edge of the community. A loop is alone.
+ */
+export function linkCommunities(n: number, edges: readonly LinkEdge[], threshold: number): Int32Array {
+  const m = edges.length;
+  const pairs = edgePairs(n, edges);
+  const parent = new Int32Array(m);
+  for (let i = 0; i < m; i++) parent[i] = i;
+  const find = (i: number): number => {
+    while (parent[i] !== i) i = parent[i] = parent[parent[i]!]!;
+    return i;
+  };
+  let cut = threshold;
+  if (!(threshold > 0)) {
+    // The partition density after each level of the tree.
+    const edgeCount = new Int32Array(m).fill(1);
+    const nodes: Set<number>[] = edges.map(({ u, v }) => new Set([u, v]));
+    const term = (c: number): number => {
+      const mc = edgeCount[c]!;
+      const nc = nodes[c]!.size;
+      return nc <= 2 ? 0 : (mc * (mc - nc + 1)) / ((nc - 2) * (nc - 1));
+    };
+    let sum = 0;
+    const levels: { s: number; d: number }[] = [];
+    for (let i = 0; i < pairs.length; ) {
+      const s = pairs[i]!.s;
+      if (s <= 0) break;
+      for (; i < pairs.length && pairs[i]!.s === s; i++) {
+        const a = find(pairs[i]!.e);
+        const b = find(pairs[i]!.f);
+        if (a === b) continue;
+        sum -= term(a) + term(b);
+        const [big, small] = nodes[a]!.size >= nodes[b]!.size ? [a, b] : [b, a];
+        parent[small] = big;
+        edgeCount[big] = edgeCount[big]! + edgeCount[small]!;
+        for (const x of nodes[small]!) nodes[big]!.add(x);
+        nodes[small] = new Set();
+        sum += term(big);
+      }
+      levels.push({ s, d: (2 / m) * sum });
+    }
+    const best = levels.reduce((b, l) => Math.max(b, l.d), 0);
+    cut = best > 1e-12 ? levels.find((l) => l.d >= best - 1e-12)!.s : (levels[levels.length - 1]?.s ?? Infinity);
+    for (let i = 0; i < m; i++) parent[i] = i;
+  }
+  for (const p of pairs) {
+    if (p.s < cut || p.s <= 0) break;
+    const a = find(p.e);
+    const b = find(p.f);
+    if (a !== b) parent[Math.max(a, b)] = Math.min(a, b);
+  }
+  const out = new Int32Array(m);
+  for (let i = 0; i < m; i++) out[i] = find(i);
+  return out;
+}
+
+/**
+ * This function gives the edge groups of the link communities (HWY-030). The hub of a community is its node with the most edges.
+ * Each edge goes from its end at the hub, or else in the direction of the hub edges. The check of the geometry removes each edge with an end
+ * farther than `spread` units from the Weber point of that end of the community. A community with fewer than `minSize` edges after the check gets no group.
+ */
+export function linkCommunityGroups(input: HighwayInput, o: Readonly<LinkCommunityOptions>): Map<string, EdgeGroup> {
+  const graph = input.graph;
+  const index = new Map(graph.nodes.map((v, i) => [v.id, i] as const));
+  const plugs = edgePlugs(graph);
+  const edges: LinkEdge[] = plugs.map(({ edge }) => ({ u: index.get(edge.source.node)!, v: index.get(edge.target.node)! }));
+  const label = linkCommunities(graph.nodes.length, edges, o.threshold);
+  const limit = Math.max(0, o.spread) * boardUnit(graph);
+  const min = Math.max(2, Math.round(o.minSize));
+  const members = new Map<number, number[]>();
+  label.forEach((c, i) => {
+    if (edges[i]!.u === edges[i]!.v) return;
+    const list = members.get(c);
+    if (list) list.push(i);
+    else members.set(c, [i]);
+  });
+  const groups = new Map<string, EdgeGroup>();
+  for (const [c, list] of members) {
+    if (list.length < min) continue;
+    const degree = new Map<number, number>();
+    for (const i of list) for (const x of [edges[i]!.u, edges[i]!.v]) degree.set(x, (degree.get(x) ?? 0) + 1);
+    let hub = -1;
+    for (const [x, d] of degree) if (hub < 0 || d > degree.get(hub)! || (d === degree.get(hub)! && x < hub)) hub = x;
+    // The mean direction of the edges at the hub, out of the hub.
+    let dx = 0;
+    let dy = 0;
+    for (const i of list) {
+      const { ps, pt } = plugs[i]!;
+      const sign = edges[i]!.u === hub ? 1 : edges[i]!.v === hub ? -1 : 0;
+      dx += sign * (pt.point.x - ps.point.x);
+      dy += sign * (pt.point.y - ps.point.y);
+    }
+    const oriented = list.map((i) => {
+      const { ps, pt } = plugs[i]!;
+      const flip = edges[i]!.u === hub ? false : edges[i]!.v === hub ? true : (pt.point.x - ps.point.x) * dx + (pt.point.y - ps.point.y) * dy < 0;
+      const a: Point = flip ? pt.point : ps.point;
+      const b: Point = flip ? ps.point : pt.point;
+      return { i, flip, a, b };
+    });
+    const wa = weberPoint(oriented.map((x) => x.a));
+    const wb = weberPoint(oriented.map((x) => x.b));
+    const kept = oriented.filter((x) => dist(x.a, wa) <= limit && dist(x.b, wb) <= limit);
+    if (kept.length < min) continue;
+    for (const x of kept) groups.set(plugs[x.i]!.edge.id, { key: `lc${c}`, flip: x.flip });
+  }
+  return groups;
+}
+
+/** This function gives the highways of the link communities of the line graph (HWY-030). Each community that passes the check of the geometry gets highways. */
+export function linkCommunityPlan(input: HighwayInput, o: Readonly<LinkCommunityOptions>): HighwayPlan {
+  return groupedPlan(input, linkCommunityGroups(input, o), { spine: o.spine, minSize: Math.max(2, Math.round(o.minSize)) });
+}

package/src/highways/mesh/index.ts

@@ -0,0 +1,209 @@
+import { dist, type Point } from "../../geom.ts";
+import type { Graph } from "../../model.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+import { tracePlan } from "../trace.ts";
+
+/** The options of the highway strategy `mesh` (HWY-004 of the notes). */
+export interface MeshOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** The side of a cell of the mesh, in units of the boxes: the median of the smaller side of each box. The default is 4. */
+  readonly cell: number;
+  /** A cluster of crossings on one segment of the mesh has at most about this number of edges. The default is 8. */
+  readonly capacity: number;
+  /** Two clusters nearer than this value, in units of the boxes, become one. The default is 1. */
+  readonly merge: number;
+  /** The largest angle in degrees between a line and the main direction of a cell. A line with a larger angle does not cross the mesh there. The default is 45. */
+  readonly angle: number;
+  /** A highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `mesh`. */
+export const MESH_DEFAULTS: Readonly<Required<Omit<MeshOptions, "margin" | "k">>> = Object.freeze({
+  cell: 4,
+  capacity: 8,
+  merge: 1,
+  angle: 45,
+  minSize: 2,
+});
+
+/** The number of bins of the histogram of the angles. Each bin is 10 degrees wide. */
+const BINS = 18;
+
+/** This function gives the median of the smaller side of each box of the graph, or 1 for a graph without boxes. */
+export function boxUnit(graph: Graph): number {
+  const sides = graph.nodes.map((n) => Math.min(n.box.w, n.box.h)).sort((a, b) => a - b);
+  return sides.length > 0 ? Math.max(1e-3, sides[Math.floor(sides.length / 2)]!) : 1;
+}
+
+/** This function gives the shares `t` of the segment `a b` and `u` of the segment `c d` at their crossing. Segments that do not cross give `undefined`. */
+function crossing(a: Point, b: Point, c: Point, d: Point): { t: number; u: number } | undefined {
+  const rx = b.x - a.x;
+  const ry = b.y - a.y;
+  const sx = d.x - c.x;
+  const sy = d.y - c.y;
+  const den = rx * sy - ry * sx;
+  if (Math.abs(den) < 1e-12) return undefined;
+  const t = ((c.x - a.x) * sy - (c.y - a.y) * sx) / den;
+  const u = ((c.x - a.x) * ry - (c.y - a.y) * rx) / den;
+  const eps = 1e-9;
+  return t >= -eps && t <= 1 + eps && u >= -eps && u <= 1 + eps ? { t: Math.max(0, Math.min(1, t)), u: Math.max(0, Math.min(1, u)) } : undefined;
+}
+
+/** This function gives the clusters of the values by a 1D k-means with `k` centres, then joins the centres nearer than `merge`. The result gives the centre of each value. */
+export function clusters1d(values: readonly number[], k: number, merge: number): number[] {
+  const n = values.length;
+  if (n === 0) return [];
+  const sorted = [...values].sort((a, b) => a - b);
+  const count = Math.max(1, Math.min(n, k));
+  let centres = Array.from({ length: count }, (_, i) => sorted[Math.min(n - 1, Math.floor(((i + 0.5) * n) / count))]!);
+  const nearest = (v: number): number => {
+    let best = 0;
+    for (let i = 1; i < centres.length; i++) if (Math.abs(centres[i]! - v) < Math.abs(centres[best]! - v)) best = i;
+    return best;
+  };
+  for (let it = 0; it < 20; it++) {
+    const sum = centres.map(() => 0);
+    const num = centres.map(() => 0);
+    for (const v of values) {
+      const i = nearest(v);
+      sum[i] = sum[i]! + v;
+      num[i] = num[i]! + 1;
+    }
+    const next = centres.map((c, i) => (num[i]! > 0 ? sum[i]! / num[i]! : c));
+    const moved = next.some((c, i) => Math.abs(c - centres[i]!) > 1e-9);
+    centres = next;
+    if (!moved) break;
+  }
+  // The join of the near centres: the weighted mean of each run of centres closer than `merge`.
+  const weight = centres.map(() => 0);
+  for (const v of values) {
+    const i = nearest(v);
+    weight[i] = weight[i]! + 1;
+  }
+  const order = centres
+    .map((c, i) => ({ c, w: weight[i]! }))
+    .filter((x) => x.w > 0)
+    .sort((p, q) => p.c - q.c);
+  const joined: { c: number; w: number }[] = [];
+  for (const x of order) {
+    const last = joined[joined.length - 1];
+    if (last && x.c - last.c < merge) {
+      const w = last.w + x.w;
+      last.c = (last.c * last.w + x.c * x.w) / w;
+      last.w = w;
+    } else joined.push({ ...x });
+  }
+  centres = joined.map((x) => x.c);
+  return values.map((v) => centres[nearest(v)]!);
+}
+
+/** One cell of the mesh: its place in the grid, the histogram of the angles of its lines, and the lines through it. */
+interface MeshCell {
+  readonly cx: number;
+  readonly cy: number;
+  readonly bins: number[];
+  /** The sum of the angles of the lines in each bin. */
+  readonly angles: number[];
+  readonly lines: Set<number>;
+}
+
+/**
+ * This function gives the waypoints of the control mesh (HWY-004, GBEC of Cui, Zhou, Qu, Wong and Li 2008).
+ * A grid of cells covers the board. The main direction of each cell is the peak of a histogram of the angles of the straight lines through it.
+ * The segment of the mesh in a cell goes through its middle, across that direction. The crossings of the lines with the segment form clusters by a 1D k-means.
+ * The centre of the cluster of each crossing is a waypoint of its edge. The waypoints of an edge are in the order of the edge.
+ */
+export function meshWaypoints(input: HighwayInput, finder: WayFinder, o: Readonly<MeshOptions>): Map<string, Point[]> {
+  const plugs = edgePlugs(input.graph);
+  const out = new Map<string, Point[]>();
+  if (plugs.length === 0) return out;
+  const unit = boxUnit(input.graph);
+  const side = Math.max(1e-3, o.cell * unit);
+  const lines = plugs.map(({ ps, pt }) => ({ a: finder.out(ps), b: finder.out(pt) }));
+  let x0 = Infinity;
+  let y0 = Infinity;
+  for (const l of lines) {
+    x0 = Math.min(x0, l.a.x, l.b.x);
+    y0 = Math.min(y0, l.a.y, l.b.y);
+  }
+  const cells = new Map<string, MeshCell>();
+  lines.forEach((l, e) => {
+    const len = dist(l.a, l.b);
+    if (len <= 1e-9) return;
+    const ang = ((Math.atan2(l.b.y - l.a.y, l.b.x - l.a.x) % Math.PI) + Math.PI) % Math.PI;
+    const bin = Math.min(BINS - 1, Math.floor((ang / Math.PI) * BINS));
+    const steps = Math.max(1, Math.ceil((2 * len) / side));
+    for (let s = 0; s <= steps; s++) {
+      const u = s / steps;
+      const cx = Math.floor((l.a.x + (l.b.x - l.a.x) * u - x0) / side);
+      const cy = Math.floor((l.a.y + (l.b.y - l.a.y) * u - y0) / side);
+      const id = `${cx},${cy}`;
+      let cell = cells.get(id);
+      if (!cell) {
+        cell = { cx, cy, bins: new Array<number>(BINS).fill(0), angles: new Array<number>(BINS).fill(0), lines: new Set() };
+        cells.set(id, cell);
+      }
+      if (!cell.lines.has(e)) {
+        cell.lines.add(e);
+        cell.bins[bin] = cell.bins[bin]! + 1;
+        cell.angles[bin] = cell.angles[bin]! + ang;
+      }
+    }
+  });
+  const capacity = Math.max(1, o.capacity);
+  const maxAngle = (Math.max(0, Math.min(90, o.angle)) * Math.PI) / 180;
+  const marks: { t: number; p: Point }[][] = lines.map(() => []);
+  for (const id of [...cells.keys()].sort()) {
+    const cell = cells.get(id)!;
+    if (cell.lines.size < 2) continue;
+    let peak = 0;
+    for (let i = 1; i < BINS; i++) if (cell.bins[i]! > cell.bins[peak]!) peak = i;
+    // The main direction is the mean angle of the lines in the peak bin.
+    const theta = cell.angles[peak]! / cell.bins[peak]!;
+    const mid = { x: x0 + (cell.cx + 0.5) * side, y: y0 + (cell.cy + 0.5) * side };
+    const across = { x: -Math.sin(theta), y: Math.cos(theta) };
+    // The segment goes from side to side of the cell.
+    const half = side / 2 / Math.max(Math.abs(across.x), Math.abs(across.y));
+    const c = { x: mid.x - across.x * half, y: mid.y - across.y * half };
+    const d = { x: mid.x + across.x * half, y: mid.y + across.y * half };
+    const hits: { e: number; t: number; u: number }[] = [];
+    for (const e of [...cell.lines].sort((p, q) => p - q)) {
+      const l = lines[e]!;
+      const len = dist(l.a, l.b);
+      const cos = Math.abs(((l.b.x - l.a.x) * Math.cos(theta) + (l.b.y - l.a.y) * Math.sin(theta)) / len);
+      if (Math.acos(Math.min(1, cos)) > maxAngle + 1e-9) continue;
+      const x = crossing(l.a, l.b, c, d);
+      if (x) hits.push({ e, t: x.t, u: x.u });
+    }
+    if (hits.length < 2) continue;
+    const centres = clusters1d(
+      hits.map((h) => h.u * 2 * half),
+      Math.ceil(hits.length / capacity),
+      Math.max(0, o.merge) * unit,
+    );
+    const size = new Map<number, number>();
+    for (const v of centres) size.set(v, (size.get(v) ?? 0) + 1);
+    hits.forEach((h, i) => {
+      const v = centres[i]!;
+      if ((size.get(v) ?? 0) < 2) return;
+      marks[h.e]!.push({ t: h.t, p: { x: c.x + across.x * v, y: c.y + across.y * v } });
+    });
+  }
+  plugs.forEach(({ edge }, e) => {
+    const list = marks[e]!.sort((p, q) => p.t - q.t).map((m) => m.p);
+    if (list.length > 0) out.set(edge.id, list);
+  });
+  return out;
+}
+
+/**
+ * This function gives the highways of the control mesh (HWY-004). Each edge goes through the centres of its clusters on the mesh, along the corner graph.
+ * The centres of one cluster are one point, so the edges of a cluster share the ways between them. The stretches that `minSize` ways share become highways.
+ */
+export function meshPlan(input: HighwayInput, o: Readonly<MeshOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const waypoints = meshWaypoints(input, finder, o);
+  return tracePlan(input, finder, waypoints, { snap: 0, minSize: o.minSize, key: "mesh" });
+}

package/src/highways/mingle/index.ts

@@ -0,0 +1,171 @@
+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";
+import { meetingPoints } from "../weiszfeld/index.ts";
+
+/** The options of the highway strategy `mingle` (HWY-003 of the note on highways). */
+export interface MingleOptions {
+  /** Each bundle looks for a merge among this number of nearest bundles in 4D. The default is 8. */
+  readonly k: number;
+  /** The largest turn of an edge at a meeting point, in degrees. A larger turn moves the meeting point along the trunk. The default is 40. */
+  readonly maxTurn: number;
+  /** The number of levels of merges. The default is 6. */
+  readonly levels: number;
+  /** The weight of the trunk in the ink. With 1, the trunk costs its length one time. The default is 1. */
+  readonly weight: number;
+  /** A bundle with this number of edges or more gets highways. The default is 2. */
+  readonly minSize: number;
+  /** The spine of each bundle. The default is `trunk`: one trunk between the two meeting points. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `mingle`. */
+export const MINGLE_DEFAULTS: Readonly<MingleOptions> = Object.freeze({ k: 8, maxTurn: 40, levels: 6, weight: 1, minSize: 2, spine: "trunk" });
+
+/** One bundle of MINGLE: its edges with their direction, the ends on each side, the two meeting points and the ink. */
+interface Bundle {
+  readonly edges: readonly { readonly edge: string; readonly flip: boolean }[];
+  readonly a: readonly Point[];
+  readonly b: readonly Point[];
+  readonly m1: Point;
+  readonly m2: Point;
+  readonly ink: number;
+}
+
+/** The number of steps of Weiszfeld for the meeting points of a bundle. */
+const STEPS = 12;
+
+/** This function gives the turn in degrees from the direction `p` to `q` to the direction `q` to `r`. A leg of length 0 gives no turn. */
+function turnAt(p: Point, q: Point, r: Point): number {
+  const ux = q.x - p.x;
+  const uy = q.y - p.y;
+  const vx = r.x - q.x;
+  const vy = r.y - q.y;
+  if (Math.hypot(ux, uy) < 1e-9 || Math.hypot(vx, vy) < 1e-9) return 0;
+  return (Math.abs(Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy)) * 180) / Math.PI;
+}
+
+/** The number of steps of the bisection that moves a meeting point to the turn limit. */
+const SLIDE_STEPS = 24;
+
+/** This function gives the point at the share `t` of the way from `p` to `q`. */
+function lerp(p: Point, q: Point, t: number): Point {
+  return { x: p.x + t * (q.x - p.x), y: p.y + t * (q.y - p.y) };
+}
+
+/**
+ * This function moves the meeting point `m` along the trunk to the meeting point `far`. It stops when each end of `ends` turns at most `maxTurn` degrees at `m`.
+ * The turn of each end gets smaller when `m` moves to `far`, so a bisection finds the smallest move. The point stays at most at the middle of the trunk.
+ * The function gives `undefined` when the middle of the trunk does not obey the limit.
+ */
+function slide(m: Point, far: Point, ends: readonly Point[], maxTurn: number): Point | undefined {
+  const worst = (p: Point): number => Math.max(...ends.map((e) => turnAt(e, p, far)));
+  if (worst(m) <= maxTurn) return m;
+  if (worst(lerp(m, far, 0.5)) > maxTurn) return undefined;
+  let lo = 0;
+  let hi = 0.5;
+  for (let s = 0; s < SLIDE_STEPS; s++) {
+    const mid = (lo + hi) / 2;
+    if (worst(lerp(m, far, mid)) <= maxTurn) hi = mid;
+    else lo = mid;
+  }
+  return lerp(m, far, hi);
+}
+
+/**
+ * This function gives the bundle of the ends `a` and `b`, with its meeting points and its ink. A turn that is too large gives `undefined`.
+ * The ink is `Σ |a_i - M1| + w |M1 - M2| + Σ |M2 - b_i|`. Each edge turns at most `maxTurn` degrees at `M1` and at `M2`.
+ * As in MINGLE, a meeting point with a larger turn moves along the trunk to the other meeting point, until the turns obey the limit.
+ */
+function bundleOf(edges: Bundle["edges"], a: readonly Point[], b: readonly Point[], o: Readonly<MingleOptions>): Bundle | undefined {
+  const [w1, w2] = meetingPoints(a, b, o.weight, STEPS);
+  if (dist(w1, w2) < 1e-6) return undefined;
+  const m1 = slide(w1, w2, a, o.maxTurn);
+  const m2 = slide(w2, w1, b, o.maxTurn);
+  if (!m1 || !m2) return undefined;
+  let ink = o.weight * dist(m1, m2);
+  for (let i = 0; i < a.length; i++) ink += dist(a[i]!, m1) + dist(m2, b[i]!);
+  return { edges, a, b, m1, m2, ink };
+}
+
+/** This function gives the bundle of `p` and `q`, with `q` turned around when `flip` is `true`. */
+function merged(p: Bundle, q: Bundle, flip: boolean, o: Readonly<MingleOptions>): Bundle | undefined {
+  const edges = [...p.edges, ...q.edges.map((e) => ({ edge: e.edge, flip: e.flip !== flip }))];
+  return bundleOf(edges, [...p.a, ...(flip ? q.b : q.a)], [...p.b, ...(flip ? q.a : q.b)], o);
+}
+
+/** This function gives the 4D distance of two bundles by their meeting points, and `flip` when the opposite direction is nearer. */
+function distance4(p: Bundle, q: Bundle): { d: number; flip: boolean } {
+  const direct = Math.hypot(dist(p.m1, q.m1), dist(p.m2, q.m2));
+  const back = Math.hypot(dist(p.m1, q.m2), dist(p.m2, q.m1));
+  return back < direct ? { d: back, flip: true } : { d: direct, flip: false };
+}
+
+/**
+ * This function gives the bundles of MINGLE (Gansner, Hu, North and Scheidegger 2011) as groups of edges.
+ * Each edge is a point in 4D: its two plugs. At each level, each bundle examines its `k` nearest bundles in 4D.
+ * A merge saves ink when the ink of the joint bundle is less than the sum of the two inks. The merges with the largest gain go first.
+ * A bundle merges one time at most in a level. The levels stop after `levels` levels, or when no merge saves ink.
+ */
+export function mingleBundles(input: HighwayInput, o: Readonly<MingleOptions>): Map<string, EdgeGroup> {
+  let bundles: Bundle[] = edgePlugs(input.graph).map(({ edge, ps, pt }) => ({
+    edges: [{ edge: edge.id, flip: false }],
+    a: [ps.point],
+    b: [pt.point],
+    m1: ps.point,
+    m2: pt.point,
+    ink: dist(ps.point, pt.point),
+  }));
+  const k = Math.max(1, Math.round(o.k));
+  for (let level = 0; level < Math.round(o.levels); level++) {
+    const offers: { i: number; j: number; gain: number; joint: Bundle }[] = [];
+    const tried = new Set<number>();
+    const n = bundles.length;
+    bundles.forEach((p, i) => {
+      const near = bundles
+        .map((q, j) => ({ j, ...distance4(p, q) }))
+        .filter((x) => x.j !== i)
+        .sort((x, y) => x.d - y.d || x.j - y.j)
+        .slice(0, k);
+      for (const { j, flip } of near) {
+        const lo = Math.min(i, j);
+        const hi = Math.max(i, j);
+        if (tried.has(lo * n + hi)) continue;
+        tried.add(lo * n + hi);
+        const joint = merged(bundles[lo]!, bundles[hi]!, flip, o);
+        if (!joint) continue;
+        const gain = bundles[lo]!.ink + bundles[hi]!.ink - joint.ink;
+        if (gain > 1e-9) offers.push({ i: lo, j: hi, gain, joint });
+      }
+    });
+    if (offers.length === 0) break;
+    offers.sort((x, y) => y.gain - x.gain || x.i - y.i || x.j - y.j);
+    const used = new Set<number>();
+    const next: Bundle[] = [];
+    for (const x of offers) {
+      if (used.has(x.i) || used.has(x.j)) continue;
+      used.add(x.i);
+      used.add(x.j);
+      next.push(x.joint);
+    }
+    bundles.forEach((p, i) => {
+      if (!used.has(i)) next.push(p);
+    });
+    bundles = next;
+  }
+  const groups = new Map<string, EdgeGroup>();
+  bundles.forEach((p, i) => {
+    for (const e of p.edges) groups.set(e.edge, { key: `m${i}`, flip: e.flip });
+  });
+  return groups;
+}
+
+/**
+ * This function gives the highways of MINGLE (HWY-003). The bundles of `mingleBundles` with `minSize` edges or more get highways.
+ * With the spine `trunk`, each bundle gets one trunk between its two meeting points, through the corner graph.
+ * With `shared`, the edges of each bundle share their ways through the corner graph.
+ */
+export function minglePlan(input: HighwayInput, o: Readonly<MingleOptions>): HighwayPlan {
+  return groupedPlan(input, mingleBundles(input, o), { spine: o.spine, minSize: o.minSize });
+}