@mark1russell7/highways 0.5.0 → 0.5.1

package/src/highways/scale-space/index.ts

@@ -0,0 +1,135 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import type { Point } from "../../geom.ts";
+import { firstRoutes } from "../base.ts";
+import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { mdf, resample, type BundleLine } from "../quickbundles/index.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The options of the highway strategy `scale-space` (HWY-053 of the note on highways). */
+export interface ScaleSpaceOptions {
+  /** The first scale, in units of the board. The default is 1.5. */
+  readonly theta: number;
+  /** The scale of each next scale is this value times the scale before it. The default is the root of 2. */
+  readonly ratio: number;
+  /** The number of scales. The default is 8. */
+  readonly scales: number;
+  /** The scale of the plan, from 0 (the first scale). With the defaults, the scale 2 is 3 units, as in the level 0 of `nested`. The default is 2. */
+  readonly level: number;
+  /** A cluster gets highways only when its persistence `ln(σ_death / σ_birth)` is this value or more. The default is 0.6: two steps of the root of 2. */
+  readonly p0: number;
+  /** The number of points of each line after the resampling. The default is 12. */
+  readonly points: number;
+  /** The line of each edge. The default is `routes`. */
+  readonly line: BundleLine;
+  /** A cluster with this number of edges or more gets highways. The default is 2. */
+  readonly minSize: number;
+  /** The spine of each cluster. The default is `shared`. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `scale-space`. */
+export const SCALE_SPACE_DEFAULTS: Readonly<ScaleSpaceOptions> = Object.freeze({
+  theta: 1.5,
+  ratio: Math.SQRT2,
+  scales: 8,
+  level: 2,
+  p0: 0.6,
+  points: 12,
+  line: "routes",
+  minSize: 2,
+  spine: "shared",
+});
+
+/** One cluster of one scale: its edges (as indices), and the scales of its birth and its death. */
+export interface ScaleCluster {
+  readonly members: readonly number[];
+  /** The first scale of the cluster. A cluster of the first scale has the birth 0. */
+  readonly birth: number;
+  /** The first scale where the cluster joins a larger one. A cluster that lives past the last scale has the death `scales`. */
+  readonly death: number;
+}
+
+/**
+ * This function gives the clusters of the single linkage of `n` items at each scale. The distance `d(i, j)` of each pair is in `pairs`.
+ * At the scale `s`, two items with a distance of `limits[s]` or less are in one cluster. Thus each cluster of a scale is in one cluster of each larger scale.
+ * The result has the clusters of each scale with 2 items or more, with their birth and their death.
+ */
+export function scaleClusters(n: number, pairs: readonly { i: number; j: number; d: number }[], limits: readonly number[]): ScaleCluster[][] {
+  const parent = new Int32Array(n);
+  for (let i = 0; i < n; i++) parent[i] = i;
+  const find = (i: number): number => {
+    while (parent[i] !== i) i = parent[i] = parent[parent[i]!]!;
+    return i;
+  };
+  const sorted = [...pairs].sort((a, b) => a.d - b.d || a.i - b.i || a.j - b.j);
+  // The member sets of each scale, as sorted keys.
+  const levels: number[][][] = [];
+  let next = 0;
+  for (const limit of limits) {
+    for (; next < sorted.length && sorted[next]!.d <= limit; next++) {
+      const a = find(sorted[next]!.i);
+      const b = find(sorted[next]!.j);
+      if (a !== b) parent[Math.max(a, b)] = Math.min(a, b);
+    }
+    const sets = new Map<number, number[]>();
+    for (let i = 0; i < n; i++) {
+      const r = find(i);
+      const list = sets.get(r);
+      if (list) list.push(i);
+      else sets.set(r, [i]);
+    }
+    levels.push([...sets.values()].filter((s) => s.length >= 2));
+  }
+  const keyOf = (s: readonly number[]): string => s.join(",");
+  const keys = levels.map((sets) => new Set(sets.map(keyOf)));
+  return levels.map((sets, s) =>
+    sets.map((members) => {
+      const key = keyOf(members);
+      let birth = s;
+      while (birth > 0 && keys[birth - 1]!.has(key)) birth--;
+      let death = s + 1;
+      while (death < levels.length && keys[death]!.has(key)) death++;
+      return { members, birth, death };
+    }),
+  );
+}
+
+/**
+ * This function gives the groups of the edges at the scale `level` that persist (HWY-053). The scale `s` is `theta × ratio^s` units of the board.
+ * A cluster of the level gets a group when its persistence `(death - birth) × ln(ratio)` is `p0` or more. Each edge of a group gets `flip` against the first edge of the group.
+ */
+export function scaleSpaceGroups(input: HighwayInput, o: Readonly<ScaleSpaceOptions>): Map<string, EdgeGroup> {
+  const graph = input.graph;
+  const unit = boardUnit(graph);
+  const scales = Math.max(1, Math.round(o.scales));
+  const ratio = Math.max(1.01, o.ratio);
+  const limits = Array.from({ length: scales }, (_, s) => o.theta * ratio ** s * unit);
+  const k = Math.max(2, Math.round(o.points));
+  const routes = o.line === "routes" ? firstRoutes(input) : undefined;
+  const lines: { edge: string; line: Point[] }[] = edgePlugs(graph).map(({ edge, ps, pt }) => ({ edge: edge.id, line: resample(routes?.get(edge.id) ?? [ps.point, pt.point], k) }));
+  const top = limits[limits.length - 1]!;
+  const pairs: { i: number; j: number; d: number }[] = [];
+  for (let i = 0; i < lines.length; i++)
+    for (let j = i + 1; j < lines.length; j++) {
+      const d = mdf(lines[i]!.line, lines[j]!.line).d;
+      if (d <= top) pairs.push({ i, j, d });
+    }
+  const level = Math.max(0, Math.min(scales - 1, Math.round(o.level)));
+  const clusters = scaleClusters(lines.length, pairs, limits)[level]!;
+  const groups = new Map<string, EdgeGroup>();
+  clusters.forEach((c, ci) => {
+    if ((c.death - c.birth) * Math.log(ratio) < o.p0 - 1e-9) return;
+    const lead = lines[c.members[0]!]!.line;
+    for (const i of c.members) groups.set(lines[i]!.edge, { key: `s${level}.${ci}`, flip: mdf(lines[i]!.line, lead).flip });
+  });
+  return groups;
+}
+
+/**
+ * This function gives the highways of one scale of the scale space with persistence (HWY-053). Only the clusters that live over `p0` of the log scale get highways.
+ * A short-lived cluster is noise, so a zoom level shows only the stable structure.
+ */
+export function scaleSpacePlan(input: HighwayInput, o: Readonly<ScaleSpaceOptions>): HighwayPlan {
+  return groupedPlan(input, scaleSpaceGroups(input, o), { spine: o.spine, minSize: Math.max(2, Math.round(o.minSize)) });
+}

package/src/highways/spectral/index.ts

@@ -0,0 +1,391 @@
+import type { Point } from "../../geom.ts";
+import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
+import { compatibility } from "../hdbscan/index.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The options of the highway strategy `spectral` (HWY-029 of the note on highways). */
+export interface SpectralOptions {
+  /** Two edges are a pair of the graph only when their compatibility is this value or more. The default is 0.5. */
+  readonly c0: number;
+  /** The number of clusters of each part of the graph. The value 0 lets the largest eigengap choose it. The default is 0. */
+  readonly clusters: number;
+  /** The eigengap chooses at most this number of clusters in each part of the graph. The default is 16. */
+  readonly kMax: number;
+  /** 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 trunk from one area to the other area. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `spectral`. */
+export const SPECTRAL_DEFAULTS: Readonly<SpectralOptions> = Object.freeze({ c0: 0.5, clusters: 0, kMax: 16, minSize: 2, spine: "trunk" });
+
+/** The largest number of edges in one part of the graph. A larger part splits into blocks of edges in the order of their sources. */
+const BLOCK = 400;
+
+/** The ends of one edge of the board. */
+export interface EdgeEnds {
+  readonly edge: string;
+  readonly s: Point;
+  readonly t: Point;
+}
+
+/** This function gives the ends of each edge of the input: the points of its two plugs. */
+export function edgeEnds(input: HighwayInput): EdgeEnds[] {
+  return edgePlugs(input.graph).map(({ edge, ps, pt }) => ({ edge: edge.id, s: ps.point, t: pt.point }));
+}
+
+/**
+ * This function gives the eigenvalues and the eigenvectors of a symmetric matrix of `n` rows (the Householder steps and the QL steps of JAMA).
+ * The values are in increasing order. The column `j` of `vectors` (the values `vectors[i * n + j]`) is the unit vector of the value `j`.
+ */
+export function symmetricEigen(n: number, a: Float64Array): { values: Float64Array; vectors: Float64Array } {
+  const V = Float64Array.from(a);
+  const d = new Float64Array(n);
+  const e = new Float64Array(n);
+  if (n === 0) return { values: d, vectors: V };
+  if (n === 1) return { values: Float64Array.of(a[0]!), vectors: Float64Array.of(1) };
+  const at = (i: number, j: number): number => V[i * n + j]!;
+  const set = (i: number, j: number, v: number): void => {
+    V[i * n + j] = v;
+  };
+  // The reduction to a tridiagonal matrix.
+  for (let j = 0; j < n; j++) d[j] = at(n - 1, j);
+  for (let i = n - 1; i > 0; i--) {
+    let scale = 0;
+    let h = 0;
+    for (let k = 0; k < i; k++) scale += Math.abs(d[k]!);
+    if (scale === 0) {
+      e[i] = d[i - 1]!;
+      for (let j = 0; j < i; j++) {
+        d[j] = at(i - 1, j);
+        set(i, j, 0);
+        set(j, i, 0);
+      }
+    } else {
+      for (let k = 0; k < i; k++) {
+        d[k] = d[k]! / scale;
+        h += d[k]! * d[k]!;
+      }
+      let f = d[i - 1]!;
+      let g = Math.sqrt(h);
+      if (f > 0) g = -g;
+      e[i] = scale * g;
+      h -= f * g;
+      d[i - 1] = f - g;
+      for (let j = 0; j < i; j++) e[j] = 0;
+      for (let j = 0; j < i; j++) {
+        f = d[j]!;
+        set(j, i, f);
+        g = e[j]! + at(j, j) * f;
+        for (let k = j + 1; k <= i - 1; k++) {
+          g += at(k, j) * d[k]!;
+          e[k] = e[k]! + at(k, j) * f;
+        }
+        e[j] = g;
+      }
+      f = 0;
+      for (let j = 0; j < i; j++) {
+        e[j] = e[j]! / h;
+        f += e[j]! * d[j]!;
+      }
+      const hh = f / (h + h);
+      for (let j = 0; j < i; j++) e[j] = e[j]! - hh * d[j]!;
+      for (let j = 0; j < i; j++) {
+        f = d[j]!;
+        g = e[j]!;
+        for (let k = j; k <= i - 1; k++) set(k, j, at(k, j) - (f * e[k]! + g * d[k]!));
+        d[j] = at(i - 1, j);
+        set(i, j, 0);
+      }
+    }
+    d[i] = h;
+  }
+  for (let i = 0; i < n - 1; i++) {
+    set(n - 1, i, at(i, i));
+    set(i, i, 1);
+    const h = d[i + 1]!;
+    if (h !== 0) {
+      for (let k = 0; k <= i; k++) d[k] = at(k, i + 1) / h;
+      for (let j = 0; j <= i; j++) {
+        let g = 0;
+        for (let k = 0; k <= i; k++) g += at(k, i + 1) * at(k, j);
+        for (let k = 0; k <= i; k++) set(k, j, at(k, j) - g * d[k]!);
+      }
+    }
+    for (let k = 0; k <= i; k++) set(k, i + 1, 0);
+  }
+  for (let j = 0; j < n; j++) {
+    d[j] = at(n - 1, j);
+    set(n - 1, j, 0);
+  }
+  set(n - 1, n - 1, 1);
+  e[0] = 0;
+  // The QL steps with implicit shifts.
+  for (let i = 1; i < n; i++) e[i - 1] = e[i]!;
+  e[n - 1] = 0;
+  let f = 0;
+  let tst1 = 0;
+  const eps = 2 ** -52;
+  for (let l = 0; l < n; l++) {
+    tst1 = Math.max(tst1, Math.abs(d[l]!) + Math.abs(e[l]!));
+    let m = l;
+    while (m < n - 1 && Math.abs(e[m]!) > eps * tst1) m++;
+    if (m > l) {
+      for (let iter = 0; iter < 64; iter++) {
+        let g = d[l]!;
+        let p = (d[l + 1]! - g) / (2 * e[l]!);
+        let r = Math.hypot(p, 1);
+        if (p < 0) r = -r;
+        d[l] = e[l]! / (p + r);
+        d[l + 1] = e[l]! * (p + r);
+        const dl1 = d[l + 1]!;
+        let h = g - d[l]!;
+        for (let i = l + 2; i < n; i++) d[i] = d[i]! - h;
+        f += h;
+        p = d[m]!;
+        let c = 1;
+        let c2 = c;
+        let c3 = c;
+        const el1 = e[l + 1]!;
+        let s = 0;
+        let s2 = 0;
+        for (let i = m - 1; i >= l; i--) {
+          c3 = c2;
+          c2 = c;
+          s2 = s;
+          g = c * e[i]!;
+          h = c * p;
+          r = Math.hypot(p, e[i]!);
+          e[i + 1] = s * r;
+          s = e[i]! / r;
+          c = p / r;
+          p = c * d[i]! - s * g;
+          d[i + 1] = h + s * (c * g + s * d[i]!);
+          for (let k = 0; k < n; k++) {
+            const hk = at(k, i + 1);
+            set(k, i + 1, s * at(k, i) + c * hk);
+            set(k, i, c * at(k, i) - s * hk);
+          }
+        }
+        p = (-s * s2 * c3 * el1 * e[l]!) / dl1;
+        e[l] = s * p;
+        d[l] = c * p;
+        if (Math.abs(e[l]!) <= eps * tst1) break;
+      }
+    }
+    d[l] = d[l]! + f;
+    e[l] = 0;
+  }
+  // The values in increasing order, with their vectors.
+  for (let i = 0; i < n - 1; i++) {
+    let k = i;
+    let p = d[i]!;
+    for (let j = i + 1; j < n; j++)
+      if (d[j]! < p) {
+        k = j;
+        p = d[j]!;
+      }
+    if (k !== i) {
+      d[k] = d[i]!;
+      d[i] = p;
+      for (let j = 0; j < n; j++) {
+        const t = at(j, i);
+        set(j, i, at(j, k));
+        set(j, k, t);
+      }
+    }
+  }
+  return { values: d, vectors: V };
+}
+
+/**
+ * This function puts the rows of a matrix of `n` rows and `k` columns into `k` clusters (the steps of Lloyd).
+ * The first centre is row 0. Each next centre is the row farthest from the centres that exist. The result is the cluster of each row.
+ */
+export function kMeans(n: number, k: number, rows: Float64Array, iterations = 50): Int32Array {
+  const label = new Int32Array(n);
+  if (k <= 1 || n <= 1) return label;
+  const dim = rows.length / n;
+  const d2 = (i: number, c: Float64Array, ci: number): number => {
+    let s = 0;
+    for (let j = 0; j < dim; j++) {
+      const v = rows[i * dim + j]! - c[ci * dim + j]!;
+      s += v * v;
+    }
+    return s;
+  };
+  const centres = new Float64Array(k * dim);
+  for (let j = 0; j < dim; j++) centres[j] = rows[j]!;
+  const near = new Float64Array(n).fill(Infinity);
+  let count = 1;
+  for (; count < k; count++) {
+    let far = -1;
+    let best = -1;
+    for (let i = 0; i < n; i++) {
+      near[i] = Math.min(near[i]!, d2(i, centres, count - 1));
+      if (near[i]! > best) [best, far] = [near[i]!, i];
+    }
+    if (best <= 1e-12) break;
+    for (let j = 0; j < dim; j++) centres[count * dim + j] = rows[far * dim + j]!;
+  }
+  for (let iter = 0; iter < iterations; iter++) {
+    let moved = false;
+    for (let i = 0; i < n; i++) {
+      let c = 0;
+      let best = Infinity;
+      for (let ci = 0; ci < count; ci++) {
+        const v = d2(i, centres, ci);
+        if (v < best - 1e-12) [best, c] = [v, ci];
+      }
+      if (label[i] !== c) [label[i], moved] = [c, true];
+    }
+    if (!moved && iter > 0) break;
+    const sums = new Float64Array(count * dim);
+    const sizes = new Int32Array(count);
+    for (let i = 0; i < n; i++) {
+      sizes[label[i]!]!++;
+      for (let j = 0; j < dim; j++) sums[label[i]! * dim + j] = sums[label[i]! * dim + j]! + rows[i * dim + j]!;
+    }
+    for (let ci = 0; ci < count; ci++) if (sizes[ci]! > 0) for (let j = 0; j < dim; j++) centres[ci * dim + j] = sums[ci * dim + j]! / sizes[ci]!;
+  }
+  return label;
+}
+
+/**
+ * This function gives the spectral clusters of the points of a weight matrix (von Luxburg 2007, with the normalization of Ng, Jordan and Weiss).
+ * Each connected part of the graph is one problem. `L_sym = I - D^-1/2 W D^-1/2`.
+ * The number of clusters `k` of a part is `clusters`, or the place of the largest gap of the first `kMax + 1` eigenvalues.
+ * The first `k` eigenvectors, with each row at the length 1, go into `kMeans`. The result is the cluster of each point, and -1 for a point with no pair.
+ */
+export function spectralLabels(n: number, w: Float64Array, o: Readonly<Pick<SpectralOptions, "clusters" | "kMax">>): Int32Array {
+  const labels = new Int32Array(n).fill(-1);
+  // The connected parts of the graph.
+  const part = new Int32Array(n).fill(-1);
+  const parts: number[][] = [];
+  for (let i = 0; i < n; i++) {
+    if (part[i]! >= 0) continue;
+    let alone = true;
+    for (let j = 0; j < n && alone; j++) if (j !== i && w[i * n + j]! > 0) alone = false;
+    if (alone) continue;
+    const list = [i];
+    part[i] = parts.length;
+    for (let q = 0; q < list.length; q++) {
+      const a = list[q]!;
+      for (let b = 0; b < n; b++)
+        if (part[b]! < 0 && b !== a && w[a * n + b]! > 0) {
+          part[b] = parts.length;
+          list.push(b);
+        }
+    }
+    list.sort((x, y) => x - y);
+    parts.push(list);
+  }
+  let next = 0;
+  for (const list of parts) {
+    const m = list.length;
+    if (m <= 2) {
+      for (const i of list) labels[i] = next;
+      next++;
+      continue;
+    }
+    const deg = list.map((i) => list.reduce((s, j) => s + (i === j ? 0 : w[i * n + j]!), 0));
+    const a = new Float64Array(m * m);
+    for (let x = 0; x < m; x++)
+      for (let y = 0; y < m; y++) {
+        const v = x === y ? 0 : w[list[x]! * n + list[y]!]! / Math.sqrt(deg[x]! * deg[y]!);
+        a[x * m + y] = (x === y ? 1 : 0) - v;
+      }
+    const { values, vectors } = symmetricEigen(m, a);
+    let k = Math.max(1, Math.min(m, Math.round(o.clusters)));
+    if (Math.round(o.clusters) <= 0) {
+      k = 1;
+      let gap = -Infinity;
+      const top = Math.max(1, Math.min(Math.round(o.kMax), m - 1));
+      for (let i = 1; i <= top; i++) {
+        const g = values[i]! - values[i - 1]!;
+        if (g > gap + 1e-12) [gap, k] = [g, i];
+      }
+    }
+    if (k <= 1) {
+      for (const i of list) labels[i] = next;
+      next++;
+      continue;
+    }
+    const rows = new Float64Array(m * k);
+    for (let x = 0; x < m; x++) {
+      let len = 0;
+      for (let j = 0; j < k; j++) len += vectors[x * m + j]! ** 2;
+      len = Math.sqrt(len) || 1;
+      for (let j = 0; j < k; j++) rows[x * k + j] = vectors[x * m + j]! / len;
+    }
+    const found = kMeans(m, k, rows);
+    const ids = new Map<number, number>();
+    list.forEach((i, x) => {
+      const c = found[x]!;
+      if (!ids.has(c)) ids.set(c, next++);
+      labels[i] = ids.get(c)!;
+    });
+  }
+  return labels;
+}
+
+/** This function gives the matrix of the compatibility of the pairs of edges, with 0 for a pair below `c0`. Then a `scale` changes the value of each pair that stays. */
+export function compatibilityMatrix(ends: readonly EdgeEnds[], c0: number, scale?: (i: number, j: number) => number): Float64Array {
+  const n = ends.length;
+  const w = new Float64Array(n * n);
+  for (let i = 0; i < n; i++)
+    for (let j = i + 1; j < n; j++) {
+      const raw = compatibility(ends[i]!.s, ends[i]!.t, ends[j]!.s, ends[j]!.t);
+      if (raw < c0) continue;
+      const c = raw * (scale ? scale(i, j) : 1);
+      if (c <= 0) continue;
+      w[i * n + j] = c;
+      w[j * n + i] = c;
+    }
+  return w;
+}
+
+/**
+ * This function gives the edge groups of the clusters of the edges of one matrix. Each edge of a cluster gets `flip` when it goes opposite to the first edge of the cluster.
+ * An edge with the label -1 gets no group.
+ */
+export function labelGroups(ends: readonly EdgeEnds[], labels: Int32Array, prefix: string, groups: Map<string, EdgeGroup>): void {
+  const lead = new Map<number, number>();
+  ends.forEach((e, i) => {
+    const c = labels[i]!;
+    if (c < 0) return;
+    if (!lead.has(c)) lead.set(c, i);
+    const l = ends[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: `${prefix}${c}`, flip });
+  });
+}
+
+/** This function splits the edges into blocks of at most `BLOCK` edges, in the order of their sources. A small graph is one block. */
+export function edgeBlocks<T extends EdgeEnds>(ends: readonly T[]): T[][] {
+  if (ends.length <= BLOCK) return [[...ends]];
+  const order = [...ends].sort((a, b) => a.s.x - b.s.x || a.s.y - b.s.y || (a.edge < b.edge ? -1 : 1));
+  const out: T[][] = [];
+  for (let from = 0; from < order.length; from += BLOCK) out.push(order.slice(from, from + BLOCK));
+  return out;
+}
+
+/** This function gives the spectral clusters of the edges (HWY-029). A pair of edges is in the graph when its compatibility of FDEB is `c0` or more. */
+export function spectralClusters(input: HighwayInput, o: Readonly<SpectralOptions>): Map<string, EdgeGroup> {
+  const groups = new Map<string, EdgeGroup>();
+  edgeBlocks(edgeEnds(input)).forEach((block, b) => {
+    const labels = spectralLabels(block.length, compatibilityMatrix(block, o.c0), o);
+    labelGroups(block, labels, `p${b}:`, groups);
+  });
+  return groups;
+}
+
+/**
+ * This function gives the highways of the spectral clusters of the compatibility graph (HWY-029). The eigengap gives the number of highways of each part.
+ * The clusters with `minSize` edges or more get highways.
+ */
+export function spectralPlan(input: HighwayInput, o: Readonly<SpectralOptions>): HighwayPlan {
+  return groupedPlan(input, spectralClusters(input, o), { spine: o.spine, minSize: Math.max(2, Math.round(o.minSize)) });
+}

package/src/highways/territories/index.ts

@@ -0,0 +1,150 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { firstRoutes } from "../base.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { snapPlan, type SnapLine, type SnapMember } from "../snap.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The characteristic points of the territories: the plugs, the bends of the first routes, or both. */
+export type TerritoryPoints = "plugs" | "bends" | "both";
+
+/** The values of `TerritoryPoints`. */
+export const TERRITORY_POINTS: readonly TerritoryPoints[] = Object.freeze(["plugs", "bends", "both"]);
+
+/** The options of the highway strategy `territories` (HWY-033 of the note on highways). */
+export interface TerritoryOptions {
+  /** The radius of a group of points, in units of the board. The default is 4. */
+  readonly radius: number;
+  /** A flow between two cells becomes a highway when this number of edges or more cross it. The default is 2. */
+  readonly minSize: number;
+  /** The characteristic points. The default is `both`. */
+  readonly points: TerritoryPoints;
+}
+
+/** The default options of the strategy `territories`. */
+export const TERRITORY_DEFAULTS: Readonly<TerritoryOptions> = Object.freeze({ radius: 4, minSize: 2, points: "both" });
+
+/**
+ * This function puts points into groups of the radius `r` (Andrienko and Andrienko 2011). Each point joins the group with the nearest centre within `r`.
+ * Else it starts a new group. The centre of a group is the mean of its points. A second pass puts each point into the group of its nearest centre.
+ * The result is the centres of the groups that keep points.
+ */
+export function pointGroups(points: readonly Point[], r: number): Point[] {
+  const sums: { x: number; y: number; n: number }[] = [];
+  const centre = (g: { x: number; y: number; n: number }): Point => ({ x: g.x / g.n, y: g.y / g.n });
+  for (const p of points) {
+    let best = -1;
+    let bestD = Infinity;
+    sums.forEach((g, i) => {
+      const d = dist(p, centre(g));
+      if (d < bestD) [best, bestD] = [i, d];
+    });
+    if (best >= 0 && bestD <= r) {
+      const g = sums[best]!;
+      g.x += p.x;
+      g.y += p.y;
+      g.n++;
+    } else sums.push({ x: p.x, y: p.y, n: 1 });
+  }
+  const first = sums.map(centre);
+  const again = first.map(() => ({ x: 0, y: 0, n: 0 }));
+  for (const p of points) {
+    const i = nearestCentre(first, p);
+    again[i]!.x += p.x;
+    again[i]!.y += p.y;
+    again[i]!.n++;
+  }
+  return again.filter((g) => g.n > 0).map(centre);
+}
+
+/** This function gives the index of the centre nearest to `p`. The first of two equal centres wins. */
+export function nearestCentre(centres: readonly Point[], p: Point): number {
+  let best = -1;
+  let bestD = Infinity;
+  centres.forEach((c, i) => {
+    const d = dist(p, c);
+    if (d < bestD) [best, bestD] = [i, d];
+  });
+  return best;
+}
+
+/** One crossing of a route from the cell `from` into the cell `to`, at the share `at` of the length of the route. */
+export interface CellStep {
+  readonly from: number;
+  readonly to: number;
+  readonly at: number;
+}
+
+/**
+ * This function gives the crossings of the cells of a polyline. The cells are the Voronoi cells of the centres.
+ * It samples the polyline at the spacing `step`, and gives each change of the nearest centre.
+ */
+export function cellSteps(line: readonly Point[], centres: readonly Point[], step: number): CellStep[] {
+  const total = polylineLength(line);
+  if (line.length < 2 || centres.length === 0 || total <= 0) return [];
+  const out: CellStep[] = [];
+  let cell = nearestCentre(centres, line[0]!);
+  let walked = 0;
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!;
+    const b = line[i]!;
+    const len = dist(a, b);
+    const n = Math.max(1, Math.ceil(len / Math.max(1e-6, step)));
+    for (let k = 1; k <= n; k++) {
+      const t = k / n;
+      const c = nearestCentre(centres, { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t });
+      if (c !== cell) {
+        out.push({ from: cell, to: c, at: (walked + len * t) / total });
+        cell = c;
+      }
+    }
+    walked += len;
+  }
+  return out;
+}
+
+/**
+ * This function gives the highways of the territories of the flows (HWY-033, Andrienko and Andrienko 2011).
+ * The characteristic points form groups of the radius `radius`. The centres of the groups make Voronoi cells.
+ * Each first route becomes a list of crossings between neighbour cells.
+ *
+ * A pair of cells with `minSize` crossings or more is a line from centre to centre. The edges that cross it snap to it. The centres of the cells are the interchanges.
+ */
+export function territoryPlan(input: HighwayInput, o: Readonly<TerritoryOptions>): HighwayPlan {
+  const graph = input.graph;
+  const unit = boardUnit(graph);
+  const r = Math.max(0.5, o.radius) * unit;
+  const routes = firstRoutes(input);
+  const plugs = edgePlugs(graph);
+  const points: Point[] = [];
+  for (const { edge, ps, pt } of plugs) {
+    if (o.points !== "bends") points.push(ps.point, pt.point);
+    if (o.points !== "plugs") {
+      const route = routes.get(edge.id) ?? [];
+      for (let i = 1; i < route.length - 1; i++) points.push(route[i]!);
+    }
+  }
+  if (points.length === 0) return { highways: [] };
+  const centres = pointGroups(points, r);
+  // The crossings of each pair of cells, in the order of the edges.
+  const flows = new Map<string, { a: number; b: number; members: SnapMember[] }>();
+  for (const { edge, ps, pt } of plugs) {
+    const route = routes.get(edge.id) ?? [ps.point, pt.point];
+    const seen = new Set<string>();
+    for (const s of cellSteps(route, centres, r / 4)) {
+      const [a, b] = s.from < s.to ? [s.from, s.to] : [s.to, s.from];
+      const key = `${a}:${b}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const flow = flows.get(key) ?? { a, b, members: [] };
+      flow.members.push({ edge: edge.id, from: centres[s.from]!, to: centres[s.to]!, at: s.at });
+      flows.set(key, flow);
+    }
+  }
+  const min = Math.max(2, Math.round(o.minSize));
+  const lines: SnapLine[] = [...flows.values()]
+    .filter((f) => f.members.length >= min)
+    .sort((p, q) => p.a - q.a || p.b - q.b)
+    .map((f) => ({ key: `t${f.a}-${f.b}`, a: centres[f.a]!, b: centres[f.b]!, members: f.members }));
+  return snapPlan(input, lines, { minSize: min });
+}