@mark1russell7/highways 0.5.0 → 0.6.0

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/frechet/index.ts

@@ -0,0 +1,232 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { orderLanes } from "../../segments.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import { arcPlace, firstRoutes, orderAlongRoutes, tidyPlan } from "../base.ts";
+import { memberAt, type Highway, type HighwayInput, type HighwayMember, type HighwayPlan } from "../model.ts";
+
+/** The options of the highway strategy `frechet` (HWY-027 of the notes). */
+export interface FrechetOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** Two parts of routes are one bundle when their discrete Fréchet distance is this value or less, as a multiple of `boardUnit`. The default is 1. */
+  readonly eps: number;
+  /** A bundle has this number of edges or more, with the reference edge. The default is 2. */
+  readonly minSize: number;
+  /** The reference part of a bundle is this length or longer, as a multiple of `boardUnit`. The default is 2. */
+  readonly minLength: number;
+  /** The distance between two samples of a route, as a multiple of `boardUnit`. The default is 0.5. */
+  readonly step: number;
+  /** A search starts at each sample of this number along each route. The default is 2. */
+  readonly stride: number;
+}
+
+/** The default options of the strategy `frechet`. */
+export const FRECHET_DEFAULTS: Readonly<Required<Omit<FrechetOptions, "margin" | "k">>> = Object.freeze({
+  eps: 1,
+  minSize: 2,
+  minLength: 2,
+  step: 0.5,
+  stride: 2,
+});
+
+/** This function gives the points of a polyline at equal distances of `step` or less, with its first and its last point. */
+export function samplesOf(line: readonly Point[], step: number): Point[] {
+  if (line.length < 2) return [...line];
+  const out: Point[] = [line[0]!];
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!;
+    const b = line[i]!;
+    const n = Math.max(1, Math.ceil(dist(a, b) / Math.max(1e-9, step)));
+    for (let s = 1; s <= n; s++) out.push({ x: a.x + ((b.x - a.x) * s) / n, y: a.y + ((b.y - a.y) * s) / n });
+  }
+  return out;
+}
+
+/** The cells of one row of the free space that a monotone path reaches. Each cell is a sorted index of the other curve. */
+type Row = readonly number[];
+
+/**
+ * This function gives the next row of the free space of the discrete Fréchet distance. The curve `q` has a free start and a free end.
+ * A cell `(j, b)` is free when the distance of `p[j]` to `q[b]` is `eps` or less.
+ * A path reaches a free cell from `(j - 1, b)`, `(j - 1, b - 1)` or `(j, b - 1)`.
+ */
+export function nextRow(prev: Row, pj: Point, q: readonly Point[], eps: number): number[] {
+  const out: number[] = [];
+  if (prev.length === 0) return out;
+  const has = new Set(prev);
+  const last = prev[prev.length - 1]!;
+  let left = false;
+  for (let b = prev[0]!; b < q.length; b++) {
+    const reach: boolean = dist(pj, q[b]!) <= eps && (has.has(b) || has.has(b - 1) || left);
+    if (reach) out.push(b);
+    left = reach;
+    if (!reach && b > last) break;
+  }
+  return out;
+}
+
+/**
+ * This function tells if a part of `q` has a discrete Fréchet distance of `eps` or less to the whole of `p`. The part of `q` is free to start and to end anywhere.
+ * It uses the rows of `nextRow`.
+ */
+export function partWithin(p: readonly Point[], q: readonly Point[], eps: number): boolean {
+  if (p.length === 0) return true;
+  let row: number[] = [];
+  for (let b = 0; b < q.length; b++) if (dist(p[0]!, q[b]!) <= eps) row.push(b);
+  for (let j = 1; j < p.length && row.length > 0; j++) row = nextRow(row, p[j]!, q, eps);
+  return row.length > 0;
+}
+
+/** One bundle of the search: the reference edge, the part of its samples, and the other edges with their sense. */
+export interface FrechetBundle {
+  readonly edge: string;
+  readonly from: number;
+  readonly to: number;
+  readonly length: number;
+  /** The other edges. `back` is true when the edge goes along the reference part in the reverse sense. */
+  readonly members: readonly { readonly edge: string; readonly back: boolean }[];
+}
+
+/**
+ * This function gives the bundles of the search (HWY-027, after Buchin, Buchin, Gudmundsson, Löffler and Luo 2011, in a simple exact form).
+ * For each reference route and each start sample (at each `stride`), it grows the reference part one sample at a time.
+ * It keeps the other routes, in both senses, with a part at a discrete Fréchet distance of `eps` or less.
+ * It stops when fewer than `minSize - 1` routes remain.
+ * Each start gives the part with the best score: the number of edges times the length.
+ * The search uses the discrete distance on samples only. It does not use the continuous distance or the full free space diagram.
+ */
+export function frechetBundles(samples: ReadonlyMap<string, readonly Point[]>, eps: number, minSize: number, minLength: number, stride: number): FrechetBundle[] {
+  const edges = [...samples.keys()];
+  const curves = new Map<string, readonly Point[]>();
+  for (const e of edges) {
+    curves.set(`${e}\u0000f`, samples.get(e)!);
+    curves.set(`${e}\u0000b`, [...samples.get(e)!].reverse());
+  }
+  // A grid of the samples of each curve, with cells of the side `eps`, finds the first row of each start.
+  const cell = Math.max(1e-6, eps);
+  const grid = new Map<string, Set<string>>();
+  const cellKey = (p: Point): string => `${Math.floor(p.x / cell)},${Math.floor(p.y / cell)}`;
+  for (const [key, c] of curves)
+    for (const p of c) {
+      const k = cellKey(p);
+      let set = grid.get(k);
+      if (!set) grid.set(k, (set = new Set()));
+      set.add(key);
+    }
+  const near = (p: Point): string[] => {
+    const cx = Math.floor(p.x / cell);
+    const cy = Math.floor(p.y / cell);
+    const out = new Set<string>();
+    for (let dx = -1; dx <= 1; dx++) for (let dy = -1; dy <= 1; dy++) for (const k of grid.get(`${cx + dx},${cy + dy}`) ?? []) out.add(k);
+    return [...out].sort();
+  };
+  const need = Math.max(1, minSize - 1);
+  const out: FrechetBundle[] = [];
+  for (const r of edges) {
+    const p = samples.get(r)!;
+    const lengths = [0];
+    for (let i = 1; i < p.length; i++) lengths.push(lengths[i - 1]! + dist(p[i - 1]!, p[i]!));
+    for (let i = 0; i < p.length - 1; i += Math.max(1, Math.round(stride))) {
+      let rows = new Map<string, number[]>();
+      for (const key of near(p[i]!)) {
+        if (key.startsWith(`${r}\u0000`)) continue;
+        const q = curves.get(key)!;
+        const row: number[] = [];
+        q.forEach((s, b) => {
+          if (dist(p[i]!, s) <= eps) row.push(b);
+        });
+        if (row.length > 0) rows.set(key, row);
+      }
+      let best: FrechetBundle | undefined;
+      let bestScore = 0;
+      for (let j = i + 1; j < p.length; j++) {
+        const next = new Map<string, number[]>();
+        for (const [key, row] of rows) {
+          const n = nextRow(row, p[j]!, curves.get(key)!, eps);
+          if (n.length > 0) next.set(key, n);
+        }
+        rows = next;
+        // One edge counts once: its forward sense wins over its reverse sense.
+        const alive = new Map<string, boolean>();
+        for (const key of rows.keys()) {
+          const [edge, sense] = key.split("\u0000") as [string, string];
+          if (!alive.has(edge) || sense === "f") alive.set(edge, sense === "b");
+        }
+        if (alive.size < need) break;
+        const length = lengths[j]! - lengths[i]!;
+        const score = (alive.size + 1) * length;
+        if (length >= minLength && score > bestScore) {
+          bestScore = score;
+          best = { edge: r, from: i, to: j, length, members: [...alive].sort((a, b) => (a[0] < b[0] ? -1 : 1)).map(([edge, back]) => ({ edge, back })) };
+        }
+      }
+      if (best) out.push(best);
+    }
+  }
+  return out;
+}
+
+/**
+ * This function gives the highways of the subtrajectory clusters of the first routes (HWY-027). The samples of each route leave out its two end points.
+ * The bundles go in the order of their score, the best first. A bundle keeps the members whose part of the route is not on a bundle already.
+ * The spine of a highway is the reference part. Each member rides the whole spine, in its own sense.
+ */
+export function frechetPlan(input: HighwayInput, o: Readonly<FrechetOptions>): HighwayPlan {
+  const graph = input.graph;
+  const unit = boardUnit(graph);
+  const finder = new WayFinder(graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const routes = firstRoutes(input);
+  const step = Math.max(1e-3, o.step * unit);
+  const samples = new Map<string, Point[]>();
+  for (const e of graph.edges) {
+    const route = routes.get(e.id);
+    if (!route || route.length < 4) continue;
+    const s = samplesOf(route.slice(1, -1), step);
+    if (s.length >= 2) samples.set(e.id, s);
+  }
+  const minSize = Math.max(2, Math.round(o.minSize));
+  const bundles = frechetBundles(samples, Math.max(1e-3, o.eps * unit), minSize, Math.max(finder.margin, o.minLength * unit), o.stride);
+  bundles.sort((a, b) => (b.members.length + 1) * b.length - (a.members.length + 1) * a.length || (a.edge < b.edge ? -1 : a.edge > b.edge ? 1 : a.from - b.from));
+  // The used parts of each route, as places along the route.
+  const used = new Map<string, [number, number][]>();
+  const free = (edge: string, lo: number, hi: number): boolean => (used.get(edge) ?? []).every(([a, b]) => hi <= a || lo >= b);
+  const take = (edge: string, lo: number, hi: number): void => {
+    const list = used.get(edge);
+    if (list) list.push([lo, hi]);
+    else used.set(edge, [[lo, hi]]);
+  };
+  const highways: Highway[] = [];
+  for (const bundle of bundles) {
+    const spine = samples.get(bundle.edge)!.slice(bundle.from, bundle.to + 1);
+    if (polylineLength(spine) <= finder.margin) continue;
+    const own = routes.get(bundle.edge)!;
+    const span = (route: readonly Point[]): [number, number] => {
+      const a = arcPlace(route, spine[0]!);
+      const b = arcPlace(route, spine[spine.length - 1]!);
+      return [Math.min(a, b), Math.max(a, b)];
+    };
+    const [rlo, rhi] = span(own);
+    if (!free(bundle.edge, rlo, rhi)) continue;
+    const riders = bundle.members.filter((m) => {
+      const [lo, hi] = span(routes.get(m.edge)!);
+      return free(m.edge, lo, hi);
+    });
+    if (riders.length + 1 < minSize) continue;
+    const all = [{ edge: bundle.edge, back: false }, ...riders];
+    for (const m of all) take(m.edge, ...span(routes.get(m.edge)!));
+    const last = spine.length - 1;
+    const trip = (m: { edge: string; back: boolean }): Point[] => {
+      const r = routes.get(m.edge)!;
+      const [from, to] = [r[0]!, r[r.length - 1]!];
+      return m.back ? [to, ...spine, from] : [from, ...spine, to];
+    };
+    const lanes = orderLanes(
+      spine,
+      all.map((m) => ({ edge: m.edge, points: trip(m) })),
+      "bundle",
+    );
+    const back = new Map(all.map((m) => [m.edge, m.back]));
+    const members: HighwayMember[] = lanes.map((edge) => (back.get(edge) ? memberAt(spine, edge, last, 0) : memberAt(spine, edge, 0, last)));
+    highways.push({ id: `h${highways.length}`, key: `f${highways.length}`, spine, lanes, members });
+  }
+  return tidyPlan(orderAlongRoutes({ highways }, routes));
+}

package/src/highways/hierarchy/index.ts

@@ -0,0 +1,140 @@
+import { center, type Point } from "../../geom.ts";
+import { cutGroups, kdGroups, quadtreeGroups } from "../../groups/index.ts";
+import type { Section } from "../../sections.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 trees of sections that the strategy `hierarchy` can use. */
+export type HierarchyGroups = "quadtree" | "kd" | "cut";
+
+/** The values of `HierarchyGroups`. */
+export const HIERARCHY_GROUPS: readonly HierarchyGroups[] = Object.freeze(["quadtree", "kd", "cut"]);
+
+/** The options of the highway strategy `hierarchy` (HWY-001 of the notes). */
+export interface HierarchyOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** The tree of sections. The default is `quadtree`. */
+  readonly group: HierarchyGroups;
+  /** A section with more nodes splits. The default is 8. */
+  readonly cap: number;
+  /** The pull of the hubs, from 0 to 1 (Holten 2006). The value 0 gives the straight line, and 1 goes through each hub. The default is 0.85. */
+  readonly beta: number;
+  /** The largest number of hubs on each side of the lowest common section. `Infinity` uses all of them. The default is `Infinity`. */
+  readonly hubs: number;
+  /** The side of the grid that the hubs snap to, 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 `hierarchy`. */
+export const HIERARCHY_DEFAULTS: Readonly<Required<Omit<HierarchyOptions, "margin" | "k">>> = Object.freeze({
+  group: "quadtree",
+  cap: 8,
+  beta: 0.85,
+  hubs: Infinity,
+  snap: 8,
+  minSize: 2,
+});
+
+/** This function gives the tree of sections of the option `group`. */
+function treeOf(input: HighwayInput, group: HierarchyGroups, cap: number): Section {
+  const c = Math.max(1, Math.round(cap));
+  if (group === "kd") return kdGroups(input.graph, { cap: c });
+  if (group === "cut") return cutGroups(input.graph, { cap: c });
+  return quadtreeGroups(input.graph, { cap: c });
+}
+
+/**
+ * This function gives the hub of each section of the tree: the mean of the middles of the boxes of its nodes.
+ * A hub in a box moves to the nearest corner of the corner graph.
+ */
+function hubsOf(input: HighwayInput, root: Section, finder: WayFinder): Map<string, Point> {
+  const middles = input.graph.nodes.map((n) => center(n.box));
+  const hubs = new Map<string, Point>();
+  const visit = (s: Section): void => {
+    if (s.nodes.length > 0) {
+      let x = 0;
+      let y = 0;
+      for (const i of s.nodes) {
+        x += middles[i]!.x;
+        y += middles[i]!.y;
+      }
+      let hub = { x: x / s.nodes.length, y: y / s.nodes.length };
+      if (finder.obstacles.inside(hub, finder.margin / 2)) {
+        const j = finder.corners.nearest(hub);
+        if (j >= 0) hub = finder.corners.points[j]!;
+      }
+      hubs.set(s.id, hub);
+    }
+    for (const c of s.children) visit(c);
+  };
+  visit(root);
+  return hubs;
+}
+
+/** This function gives the chain of sections from the root to the leaf of each node, by the index of the node. */
+function chainsOf(root: Section, count: number): (readonly Section[])[] {
+  const chains: Section[][] = Array.from({ length: count }, () => []);
+  const visit = (s: Section, path: Section[]): void => {
+    const here = [...path, s];
+    if (s.children.length === 0) for (const i of s.nodes) chains[i] = here;
+    for (const c of s.children) visit(c, here);
+  };
+  visit(root, []);
+  return chains;
+}
+
+/**
+ * This function gives the control points of one edge. They are the sections from the leaf of the source up to the lowest common section, then down to the target leaf.
+ * The lowest common section is not in the chain (Holten 2006), so the edges do not all meet at the hub of the root.
+ * `hubs` limits the sections on each side. The sections nearest to the common section stay.
+ */
+export function controlChain(from: readonly Section[], to: readonly Section[], hubs: number): Section[] {
+  let lca = 0;
+  while (lca < from.length && lca < to.length && from[lca]!.id === to[lca]!.id) lca++;
+  // The first sections that differ are at the depth `lca`.
+  const limit = Number.isFinite(hubs) ? Math.max(0, Math.round(hubs)) : Infinity;
+  const up = from.slice(lca, lca + limit).reverse();
+  const down = to.slice(lca, lca + limit);
+  return [...up, ...down];
+}
+
+/**
+ * This function gives the highways of the hierarchical edge bundling (HWY-001, Holten 2006).
+ * The tree of sections gives a hub to each section. Each edge goes near the hubs of the sections between its two leaves.
+ * The waypoint of a hub is `beta hub + (1 - beta) p`, with `p` the point of the straight line at the same share of the chain.
+ * The waypoints snap to a grid of side `snap`, and the ways go through the corner graph. The stretches that `minSize` ways share become highways.
+ */
+export function hierarchyPlan(input: HighwayInput, o: Readonly<HierarchyOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const index = new Map(input.graph.nodes.map((n, i) => [n.id, i] as const));
+  const waypoints = new Map<string, Point[]>();
+  if (input.graph.nodes.length > 0) {
+    const root = treeOf(input, o.group, o.cap);
+    const hubs = hubsOf(input, root, finder);
+    const chains = chainsOf(root, input.graph.nodes.length);
+    const beta = Math.max(0, Math.min(1, o.beta));
+    for (const { edge, ps, pt } of edgePlugs(input.graph)) {
+      const s = index.get(edge.source.node);
+      const t = index.get(edge.target.node);
+      if (s === undefined || t === undefined) continue;
+      const chain = controlChain(chains[s] ?? [], chains[t] ?? [], o.hubs)
+        .map((c) => hubs.get(c.id))
+        .filter((p): p is Point => p !== undefined);
+      if (chain.length === 0) continue;
+      const a = finder.out(ps);
+      const b = finder.out(pt);
+      waypoints.set(
+        edge.id,
+        chain.map((h, i) => {
+          const u = (i + 1) / (chain.length + 1);
+          const line = { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u };
+          return { x: beta * h.x + (1 - beta) * line.x, y: beta * h.y + (1 - beta) * line.y };
+        }),
+      );
+    }
+  }
+  return tracePlan(input, finder, waypoints, { snap: o.snap, minSize: o.minSize, key: "hierarchy" });
+}

package/src/highways/index.ts

@@ -34,4 +34,68 @@ export { HOUGH_DEFAULTS, houghLines, houghPeaks, houghPlan, type HoughOptions, t
 export { densityRidges, lineDensity, RIDGE_DEFAULTS, ridgeLines, ridgePlan, type DensityImage, type Ridge, type RidgeOptions, type RidgeSource } from "./ridges/index.ts";
 export { compatibility, EDGE_DISTANCES, HDBSCAN_DEFAULTS, hdbscanClusters, hdbscanLabels, hdbscanPlan, type EdgeDistance, type HdbscanOptions } from "./hdbscan/index.ts";
 export { ARC_SOURCES, candidateArcs, HUB_ARC_DEFAULTS, hubArcPlan, type ArcSource, type HubArcOptions } from "./hub-arcs/index.ts";
+export { boxPush, innerPoints, outOfBoxes, tracePlan, waypointWay, type TraceOptions } from "./trace.ts";
+export { DIVIDED_DEFAULTS, divideHighway, dividedPlan, offsetLine, TRAFFIC_RULES, type DividedOptions, type TrafficRule } from "./divided/index.ts";
+export { controlChain, HIERARCHY_DEFAULTS, HIERARCHY_GROUPS, hierarchyPlan, type HierarchyGroups, type HierarchyOptions } from "./hierarchy/index.ts";
+export { FDEB_DEFAULTS, fdebLines, fdebPlan, type FdebOptions } from "./fdeb/index.ts";
+export { boxUnit, clusters1d, MESH_DEFAULTS, meshPlan, meshWaypoints, type MeshOptions } from "./mesh/index.ts";
+export {
+  DENSITY_KERNELS,
+  densityPlan,
+  fft,
+  KDEEB_DEFAULTS,
+  kdeebLines,
+  kdeebPlan,
+  pointDensity,
+  type AdvectionSettings,
+  type DensityGrid,
+  type DensityKernel,
+  type DensitySource,
+  type KdeebOptions,
+} from "./kdeeb/index.ts";
+export { CUBU_DEFAULTS, cubuPlan, type CubuOptions } from "./cubu/index.ts";
+export { MLS_FITS, MLSEB_DEFAULTS, mlsebLines, mlsebPlan, mlsPoint, type MlsebOptions, type MlsFit } from "./mlseb/index.ts";
+export {
+  bigGroups,
+  firstLines,
+  meanLine,
+  nearestOnLine,
+  nearestSkeleton,
+  SBEB_DEFAULTS,
+  sbebLines,
+  sbebPlan,
+  shapeSkeleton,
+  SKELETON_GROUPS,
+  SKELETON_TARGETS,
+  skeletonGroups,
+  type SbebOptions,
+  type ShapeSkeleton,
+  type SkeletonGroups,
+  type SkeletonTarget,
+} from "./sbeb/index.ts";
+export { AREA_DEFAULTS, AREA_WIDTHS, areaPlan, skeletonPath, type AreaOptions, type AreaWidth } from "./areas/index.ts";
+export { bicliqueGroups, CONFLUENT_DEFAULTS, confluentPlan, GROUP_SCOPES, greedyBicliques, nodeLinks, type Biclique, type ConfluentOptions, type GroupScope, type NodeLinks } from "./confluent/index.ts";
+export { jaccardIndex, MODULE_RULES, modulesOf, POWER_DEFAULTS, powerPlan, type ModuleRule, type PowerOptions } from "./power/index.ts";
+export { CROSSBAR_DEFAULTS, crossbarPlan, greedyCrossbars, routeCrossings, type Crossbar, type CrossbarOptions, type RouteCrossing } from "./crossbars/index.ts";
+export { FRECHET_DEFAULTS, frechetBundles, frechetPlan, nextRow, partWithin, samplesOf, type FrechetBundle, type FrechetOptions } from "./frechet/index.ts";
+export {
+  compatibilityMatrix,
+  edgeBlocks,
+  edgeEnds,
+  kMeans,
+  labelGroups,
+  SPECTRAL_DEFAULTS,
+  spectralClusters,
+  spectralLabels,
+  spectralPlan,
+  symmetricEigen,
+  type EdgeEnds,
+  type SpectralOptions,
+} from "./spectral/index.ts";
+export { edgeResistance, RESISTANCE_DEFAULTS, resistanceClusters, resistancePlan, type ResistanceOptions } from "./resistance/index.ts";
+export { LINK_COMMUNITY_DEFAULTS, linkCommunities, linkCommunityGroups, linkCommunityPlan, type LinkCommunityOptions, type LinkEdge } from "./link-communities/index.ts";
+export { cellSteps, nearestCentre, pointGroups, TERRITORY_DEFAULTS, TERRITORY_POINTS, territoryPlan, type CellStep, type TerritoryOptions, type TerritoryPoints } from "./territories/index.ts";
+export { coAssociation, CONSENSUS_DEFAULTS, CONSENSUS_LINKAGES, consensusGroups, consensusLabels, consensusPlan, type ConsensusLinkage, type ConsensusOptions } from "./consensus/index.ts";
+export { HUB_ALLOCATIONS, HUB_CANDIDATES, hubCandidates, P_HUB_DEFAULTS, pHubPlan, pMedian, type HubAllocation, type HubCandidates, type PHubOptions } from "./p-hub/index.ts";
+export { SCALE_SPACE_DEFAULTS, scaleClusters, scaleSpaceGroups, scaleSpacePlan, type ScaleCluster, type ScaleSpaceOptions } from "./scale-space/index.ts";
 export * from "./gates/index.ts";