@mark1russell7/highways 0.9.3 → 0.9.5

package/src/highways/slots/index.ts

@@ -0,0 +1,178 @@
+/**
+ * The highway strategy `slots` (RULE-047): a pull of each route toward the lane slots of the highway skeleton.
+ * An edge whose first route runs near a trunk of the plan joins that trunk when the pull is larger than its detour.
+ */
+import { checkProperties } from "../../bench/properties.ts";
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { outerGraph, type Graph } from "../../model.ts";
+import { byCollection } from "../../routers/trunks.ts";
+import { basePlan, firstRoutes, nearestPlace, tidyPlan, type HighwayBase } from "../base.ts";
+import { follow } from "../follow.ts";
+import { lengthBetween, memberAt, pointAt, type Highway, type HighwayInput, type HighwayPlan } from "../model.ts";
+
+/** The edges that can join a trunk: only the edges with the key of the trunk, or each edge. */
+export type SlotKeys = "same" | "any";
+
+/** The values of `SlotKeys`. */
+export const SLOT_KEYS: readonly SlotKeys[] = Object.freeze(["same", "any"]);
+
+/** The options of the highway strategy `slots` (RULE-047). */
+export interface SlotOptions {
+  /** The weight `k` of the pull, from 0.25 to 8. The default is 2. The name is not `k`, because `follow` reads `k` as an option of its ways. */
+  readonly pull: number;
+  /** The reach `r` of the pull, in units, from 8 to 64. A route point farther than this distance from a trunk gets no pull. The default is 24. */
+  readonly reach: number;
+  /** The distance between two lanes of a trunk, in units, from 2 to 8. The default is 4. */
+  readonly laneSpacing: number;
+  /** The largest stretch of a route after it joins a trunk: its new length over its first length, from 1.05 to 2. The default is 1.25. */
+  readonly maxStretch: number;
+  /** The edges that can join a trunk. The default is `same`. */
+  readonly keys: SlotKeys;
+  /** The plan that gives the trunks. The default is `shared-ways`. */
+  readonly from: HighwayBase;
+}
+
+/** The default options of the strategy `slots`. */
+export const SLOT_DEFAULTS: Readonly<SlotOptions> = Object.freeze({ pull: 2, reach: 24, laneSpacing: 4, maxStretch: 1.25, keys: "same", from: "shared-ways" });
+
+/** One sample of a route: a point and its length from the first point of the route. */
+interface Sample {
+  readonly p: Point;
+  readonly arc: number;
+}
+
+/** One possible join of an edge to a trunk: the trunk, the places on its spine, the pull and the detour. */
+export interface SlotJoin {
+  readonly highway: number;
+  readonly on: number;
+  readonly off: number;
+  /** The pull energy that the join removes: `k × Σ w(d) × (d - slot)² × step / r²`, in units of length. */
+  readonly pull: number;
+  /** The length that the join adds to the route, as an estimate. */
+  readonly detour: number;
+}
+
+/** This function gives points along a polyline, one at each `step` of length, and the last point. */
+function samplesOf(points: readonly Point[], step: number): Sample[] {
+  const out: Sample[] = [];
+  if (points.length === 0) return out;
+  out.push({ p: points[0]!, arc: 0 });
+  let walked = 0;
+  let next = step;
+  for (let i = 1; i < points.length; i++) {
+    const a = points[i - 1]!;
+    const b = points[i]!;
+    const len = dist(a, b);
+    while (len > 0 && next <= walked + len) {
+      const u = (next - walked) / len;
+      out.push({ p: { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u }, arc: next });
+      next += step;
+    }
+    walked += len;
+  }
+  if (walked > out[out.length - 1]!.arc + 1e-9) out.push({ p: points[points.length - 1]!, arc: walked });
+  return out;
+}
+
+/**
+ * This function gives the best join of one route to the trunk `h`, or `undefined`.
+ * The longest row of samples nearer than `reach` to the spine is the part of the route that the trunk pulls.
+ * The slot of the new lane is at `laneSpacing × (lanes + 1) / 2` from the spine. The weight is `w(d) = max(0, 1 - d / r)`.
+ */
+export function slotJoin(route: readonly Point[], h: Highway, index: number, o: Readonly<SlotOptions>): SlotJoin | undefined {
+  const step = Math.max(2, o.reach / 4);
+  const samples = samplesOf(route, step);
+  const offset = (o.laneSpacing * (h.lanes.length + 1)) / 2;
+  let best: { from: number; to: number } | undefined;
+  let start = -1;
+  const near = samples.map((s) => {
+    const at = nearestPlace(h.spine, s.p);
+    return { at, d: dist(s.p, pointAt(h.spine, at)) };
+  });
+  for (let i = 0; i <= samples.length; i++) {
+    const inside = i < samples.length && near[i]!.d < o.reach;
+    if (inside && start < 0) start = i;
+    if (!inside && start >= 0) {
+      if (!best || samples[i - 1]!.arc - samples[start]!.arc > samples[best.to]!.arc - samples[best.from]!.arc) best = { from: start, to: i - 1 };
+      start = -1;
+    }
+  }
+  if (!best || best.to <= best.from) return undefined;
+  const on = near[best.from]!.at;
+  const off = near[best.to]!.at;
+  const ride = lengthBetween(h.spine, Math.min(on, off), Math.max(on, off));
+  if (ride < 2 * o.reach || Math.abs(on - off) < 1e-9) return undefined;
+  let pull = 0;
+  for (let i = best.from; i <= best.to; i++) {
+    const d = near[i]!.d;
+    const w = Math.max(0, 1 - d / o.reach);
+    const gap = d - offset;
+    pull += w * gap * gap;
+  }
+  pull = (o.pull * pull * step) / (o.reach * o.reach);
+  const arc = samples[best.to]!.arc - samples[best.from]!.arc;
+  const detour = near[best.from]!.d + near[best.to]!.d + ride - arc;
+  return { highway: index, on, off, pull, detour };
+}
+
+/**
+ * This function gives the plan of the highway strategy `slots` (RULE-047, after the pull of force-directed edge bundling, Holten and van Wijk 2009).
+ * The trunks are the highways of the plan `from`. Each edge outside the plan gets a pull toward the slot of a new lane of a trunk near its first route.
+ * The energy of the pull is `E = k Σ w(d_i) ‖x_i - slot_i‖²` over the samples of the route, with `w(d) = max(0, 1 - d / r)`.
+ * The edge joins the trunk when the pull is larger than the length that the join adds, and the stretch stays under `maxStretch`.
+ * The edge takes the trunk with the largest gain, on the outer lane. An edge that does not fit stays off the trunks.
+ */
+export function slotPlan(input: HighwayInput, options: Partial<SlotOptions> = {}): HighwayPlan {
+  const o = { ...SLOT_DEFAULTS, ...options };
+  const graph = outerGraph(input.graph);
+  const first = basePlan({ ...input, graph }, o.from);
+  return slotsOf(graph, first, firstRoutes({ ...input, graph }), o);
+}
+
+/** This function adds the joins of `slotPlan` to the plan `first` of the graph. It reads all the options except `from`. A join that breaks a hard rule after `follow` leaves the plan. */
+export function slotsOf(graph: Graph, first: HighwayPlan, routes: ReadonlyMap<string, readonly Point[]>, options: Partial<SlotOptions> = {}): HighwayPlan {
+  const o = { ...SLOT_DEFAULTS, ...options };
+  if (first.highways.length === 0) return first;
+  const riders = new Set(first.highways.flatMap((h) => h.members.map((m) => m.edge)));
+  const added = first.highways.map(() => [] as { edge: string; on: number; off: number }[]);
+  const edges = [...graph.edges].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  for (const e of edges) {
+    if (riders.has(e.id)) continue;
+    const route = routes.get(e.id);
+    if (!route || route.length < 2) continue;
+    const length = polylineLength(route);
+    if (length <= 1e-9) continue;
+    const key = byCollection(e);
+    let best: SlotJoin | undefined;
+    first.highways.forEach((h, i) => {
+      if (o.keys === "same" && (key === undefined || h.key !== key)) return;
+      const j = slotJoin(route, h, i, o);
+      if (!j || j.pull <= j.detour || (length + Math.max(0, j.detour)) / length > o.maxStretch + 1e-9) return;
+      if (!best || j.pull - j.detour > best.pull - best.detour + 1e-9) best = j;
+    });
+    if (best) added[best.highway]!.push({ edge: e.id, on: best.on, off: best.off });
+  }
+  const build = (): HighwayPlan =>
+    tidyPlan({
+      highways: first.highways.map((h, i) => {
+        const more = added[i]!;
+        if (more.length === 0) return h;
+        return { ...h, lanes: [...h.lanes, ...more.map((m) => m.edge)], members: [...h.members, ...more.map((m) => memberAt(h.spine, m.edge, m.on, m.off, 0))] };
+      }),
+    });
+  // A join whose route after `follow` breaks a hard rule leaves the plan. A new break of a rider takes each join of its trunks off.
+  const before = new Set(checkProperties(graph, follow(graph, first), 1_000_000).flatMap((v) => (v.edge === undefined ? [] : [v.edge])));
+  for (let round = 0; round < 4; round++) {
+    if (added.every((list) => list.length === 0)) return first;
+    const plan = build();
+    const faulty = new Set(checkProperties(graph, follow(graph, plan), 1_000_000).flatMap((v) => (v.edge === undefined ? [] : [v.edge])));
+    const joined = new Set(added.flatMap((list) => list.map((m) => m.edge)));
+    const others = [...faulty].filter((e) => !joined.has(e) && !before.has(e));
+    if (![...faulty].some((e) => joined.has(e)) && others.length === 0) return plan;
+    first.highways.forEach((h, i) => {
+      const hit = others.some((e) => h.members.some((m) => m.edge === e));
+      added[i] = hit ? [] : added[i]!.filter((m) => !faulty.has(m.edge));
+    });
+  }
+  return first;
+}

package/src/index.ts

@@ -19,9 +19,17 @@ export * from "./room/lanes.ts";
 export * from "./room/levels/index.ts";
 export * from "./plugs/facing/index.ts";
 export * from "./plugs/spread/index.ts";
+export * from "./plugs/leaders/index.ts";
 export * from "./plugs/fix.ts";
 export * from "./levels/depths/index.ts";
 export * from "./whole/pipeline/index.ts";
+export * from "./levels/venation/index.ts";
+export * from "./levels/detail/index.ts";
+export * from "./whole/portfolio/index.ts";
+export * from "./whole/curriculum/index.ts";
+export * from "./whole/preferences/index.ts";
+export * from "./whole/fireflies/index.ts";
+export * from "./whole/tracing/index.ts";
 export * from "./bench/properties.ts";
 export * from "./bench/quality.ts";
 export * from "./bench/links.ts";

package/src/levels/detail/index.ts

@@ -0,0 +1,140 @@
+/**
+ * The level strategy `detail` (WILD-016 with EDA-038): the level of detail of the bundles of each zoom level.
+ * Two legs of level links that are closer on the screen than `pxMin` pixels become one stroke, with a width that grows with the count.
+ */
+import { segmentHitsBox, type Point } from "../../geom.ts";
+import type { Level, LevelItem, LevelLink } from "../../model.ts";
+import { itemSizes, PICK } from "../../pick.ts";
+import type { LevelInput } from "../../strategies/model.ts";
+import { depthLevels, type DepthLevelOptions } from "../depths/index.ts";
+
+/** The growth of the width of a stroke with the number of its edges. */
+export type WidthScale = "linear" | "sqrt" | "log";
+
+/** The values of `WidthScale`. */
+export const WIDTH_SCALES: readonly WidthScale[] = Object.freeze(["linear", "sqrt", "log"]);
+
+/** The options of the level strategy `detail`: the options of `depths`, and the limits of the collapse. */
+export interface DetailOptions extends DepthLevelOptions {
+  /** Two parallel legs closer than this number of pixels on the screen become one stroke, from 0.5 to 4. The default is 3. */
+  readonly pxMin: number;
+  /** A stroke holds this number of edges or more, from 2 to 5. The default is 2. */
+  readonly minCount: number;
+  /** The width of a stroke of one edge, in pixels, from 1 to 4. The default is 1.5. A renderer reads it with `detailWidth`. */
+  readonly w0: number;
+  /** The growth of the width of a stroke with its count. The default is `log`. */
+  readonly widthScale: WidthScale;
+}
+
+/** The default options of the level strategy `detail`. */
+export const DETAIL_DEFAULTS: Readonly<DetailOptions> = Object.freeze({ pxMin: 3, minCount: 2, w0: 1.5, widthScale: "log" });
+
+/**
+ * This function gives the width of a stroke of `count` edges, in pixels (WILD-016). With `log`, it is `w0 × (1 + log2(count))`.
+ * With `sqrt`, it is `w0 × sqrt(count)`. With `linear`, it is `w0 × count`.
+ */
+export function detailWidth(count: number, o: Pick<DetailOptions, "w0" | "widthScale"> = DETAIL_DEFAULTS): number {
+  const c = Math.max(1, count);
+  if (o.widthScale === "linear") return o.w0 * c;
+  if (o.widthScale === "sqrt") return o.w0 * Math.sqrt(c);
+  return o.w0 * (1 + Math.log2(c));
+}
+
+/** One inner leg of a level link, parallel to an axis. It has the index of the link and of its first point, its axis and its place across the axis. */
+interface Leg {
+  readonly link: number;
+  readonly at: number;
+  /** With `x`, the leg is horizontal. */
+  readonly axis: "x" | "y";
+  readonly across: number;
+  readonly lo: number;
+  readonly hi: number;
+  readonly count: number;
+}
+
+/** This function gives the inner legs of the links that are parallel to an axis. The first and the last leg of a link touch its items, so they stay. */
+function legsOf(links: readonly LevelLink[]): Leg[] {
+  const out: Leg[] = [];
+  links.forEach((l, link) => {
+    const p = l.points;
+    for (let at = 1; at + 2 < p.length; at++) {
+      const a = p[at]!;
+      const b = p[at + 1]!;
+      if (Math.abs(a.y - b.y) <= 1e-9 && Math.abs(a.x - b.x) > 1e-9) out.push({ link, at, axis: "x", across: a.y, lo: Math.min(a.x, b.x), hi: Math.max(a.x, b.x), count: l.count });
+      else if (Math.abs(a.x - b.x) <= 1e-9 && Math.abs(a.y - b.y) > 1e-9) out.push({ link, at, axis: "y", across: a.x, lo: Math.min(a.y, b.y), hi: Math.max(a.y, b.y), count: l.count });
+    }
+  });
+  return out;
+}
+
+/** This function takes out the repeated points and the points in the middle of a straight run. The first and the last point stay. */
+function tidy(p: readonly Point[]): Point[] {
+  const out: Point[] = [];
+  for (const q of p) {
+    const last = out[out.length - 1];
+    if (last && Math.abs(last.x - q.x) <= 1e-9 && Math.abs(last.y - q.y) <= 1e-9) continue;
+    if (out.length >= 2) {
+      const a = out[out.length - 2]!;
+      const b = out[out.length - 1]!;
+      const cross = (b.x - a.x) * (q.y - b.y) - (b.y - a.y) * (q.x - b.x);
+      const dot = (b.x - a.x) * (q.x - b.x) + (b.y - a.y) * (q.y - b.y);
+      if (Math.abs(cross) <= 1e-9 && dot > 0) out.pop();
+    }
+    out.push(q);
+  }
+  if (out.length < 2 && p.length >= 2) return [p[0]!, p[p.length - 1]!];
+  return out;
+}
+
+/**
+ * This function collapses the legs of the links of one level that are closer than `tol` (WILD-016, EDA-038).
+ * The legs of each axis go in clusters along the axis across it. The leg with the largest count of a cluster is its stroke, and each other leg moves onto it.
+ * A cluster needs two legs whose projections overlap, and a count of `minCount` or more. A move that puts a leg through the box of an item does not happen.
+ */
+export function collapseLinks(items: readonly LevelItem[], links: readonly LevelLink[], tol: number, minCount: number): LevelLink[] {
+  if (!(tol > 0)) return [...links];
+  const points = links.map((l) => [...l.points]);
+  const boxes = items.map((i) => i.box);
+  const clear = (a: Point, b: Point): boolean => boxes.every((box) => !segmentHitsBox(a, b, box, 1e-3));
+  for (const axis of ["x", "y"] as const) {
+    const legs = legsOf(links.map((l, i) => ({ ...l, points: points[i]! })))
+      .filter((g) => g.axis === axis)
+      .sort((a, b) => a.across - b.across || a.lo - b.lo || a.link - b.link || a.at - b.at);
+    const done = new Set<Leg>();
+    for (const anchor of [...legs].sort((a, b) => b.count - a.count || b.hi - b.lo - (a.hi - a.lo) || a.link - b.link || a.at - b.at)) {
+      if (done.has(anchor)) continue;
+      const near = legs.filter((g) => !done.has(g) && g !== anchor && g.link !== anchor.link && Math.abs(g.across - anchor.across) < tol && Math.min(g.hi, anchor.hi) - Math.max(g.lo, anchor.lo) > 1e-9);
+      if (near.length === 0 || near.reduce((s, g) => s + g.count, anchor.count) < minCount) continue;
+      done.add(anchor);
+      for (const g of near) {
+        done.add(g);
+        const p = points[g.link]!;
+        const a = p[g.at]!;
+        const b = p[g.at + 1]!;
+        // The leg moves only when its two points are still where the scan found them: an earlier move of the same link can change them.
+        if (axis === "x" ? a.y !== g.across || b.y !== g.across : a.x !== g.across || b.x !== g.across) continue;
+        const a2 = axis === "x" ? { x: a.x, y: anchor.across } : { x: anchor.across, y: a.y };
+        const b2 = axis === "x" ? { x: b.x, y: anchor.across } : { x: anchor.across, y: b.y };
+        if (!clear(p[g.at - 1]!, a2) || !clear(a2, b2) || !clear(b2, p[g.at + 2]!)) continue;
+        p[g.at] = a2;
+        p[g.at + 1] = b2;
+      }
+    }
+  }
+  return links.map((l, i) => (points[i]!.every((q, k) => q === l.points[k]) ? l : { ...l, points: tidy(points[i]!) }));
+}
+
+/**
+ * This function gives the zoom levels of the level strategy `detail` (WILD-016 with EDA-038). The levels and their items are the levels of `depths`.
+ * A level with groups first shows at the scale `itemAt / size`, with `size` its median item (`pickLevel`). At that scale, `pxMin` pixels are `pxMin × size / itemAt` units.
+ * The links of the level collapse their legs that are closer than that length (`collapseLinks`). The last level stays as in `depths`.
+ */
+export function detailLevels(input: LevelInput, options: Readonly<DetailOptions>): Level[] {
+  const levels = depthLevels(input, options);
+  const sizes = itemSizes(levels);
+  return levels.map((level, i) => {
+    if (i === levels.length - 1) return level;
+    const tol = (options.pxMin * sizes[i]!) / PICK.itemAt;
+    return { ...level, links: collapseLinks(level.items, level.links, tol, options.minCount) };
+  });
+}

package/src/levels/venation/index.ts

@@ -0,0 +1,191 @@
+import { center, dist, polylineLength, type Box, type Point } from "../../geom.ts";
+import { levelLinks, type ItemPair } from "../../levels.ts";
+import type { Level, LevelItem, LevelLink } from "../../model.ts";
+import type { LevelInput } from "../../strategies/model.ts";
+import { depthLevels, type DepthLevelOptions } from "../depths/index.ts";
+
+/** The graph of the backbone of a level: the relative neighbourhood graph, or the Gabriel graph of the centers of the items. */
+export type VenationBackbone = "rng" | "gabriel";
+
+/** The values of `VenationBackbone`. */
+export const VENATION_BACKBONES: readonly VenationBackbone[] = Object.freeze(["rng", "gabriel"]);
+
+/** The options of the level strategy `venation` (NAT-016 of the nature notes): the options of `depths`, and the options of the backbone. */
+export interface VenationOptions extends DepthLevelOptions {
+  /** The graph of the backbone. The relative neighbourhood graph has fewer links than the Gabriel graph. The default is `rng`. */
+  readonly backbone: VenationBackbone;
+  /** A later level link saves this share of the cost of a backbone link that an earlier level link uses, from 0 to 0.8. The default is 0.4. */
+  readonly discount: number;
+  /** A level link takes its way on the backbone only when that way is this many times its direct link or less. The default is 1.5. */
+  readonly detour: number;
+  /** A level with more items than this number keeps the links of `depths`. The default is 400. */
+  readonly maxItems: number;
+}
+
+/** The default options of the level strategy `venation`. */
+export const VENATION_DEFAULTS: Readonly<VenationOptions> = Object.freeze({ backbone: "rng", discount: 0.4, detour: 1.5, maxItems: 400 });
+
+/**
+ * This function gives the links of the backbone of the points, as pairs of indices `i < j` (NAT-016).
+ * With `rng`, the link `p q` exists when no third point `r` has `max(d(p, r), d(q, r)) < d(p, q)`.
+ * With `gabriel`, the link exists when no third point is inside the circle with the diameter `p q`.
+ */
+export function backboneLinks(points: readonly Point[], backbone: VenationBackbone): [number, number][] {
+  const out: [number, number][] = [];
+  const n = points.length;
+  const d2 = (a: Point, b: Point): number => (a.x - b.x) * (a.x - b.x) + (a.y - b.y) * (a.y - b.y);
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      const pq = d2(points[i]!, points[j]!);
+      let keep = true;
+      for (let r = 0; r < n && keep; r++) {
+        if (r === i || r === j) continue;
+        const pr = d2(points[i]!, points[r]!);
+        const qr = d2(points[j]!, points[r]!);
+        if (backbone === "rng" ? Math.max(pr, qr) < pq - 1e-9 : pr + qr < pq - 1e-9) keep = false;
+      }
+      if (keep) out.push([i, j]);
+    }
+  }
+  return out;
+}
+
+/**
+ * This function gives a way around the box `b`, inflated by `m`, from the point `a` to the point `c` of its boundary.
+ * The way goes along the shorter side of the inflated box. It holds the two points at `m` out from `a` and `c`, and the corners between them.
+ */
+export function aroundBox(b: Box, m: number, a: Point, c: Point): Point[] {
+  const x0 = b.x - m;
+  const y0 = b.y - m;
+  const x1 = b.x + b.w + m;
+  const y1 = b.y + b.h + m;
+  const w = x1 - x0;
+  const h = y1 - y0;
+  const per = 2 * (w + h);
+  // The point on the boundary of the inflated box nearest to `p`, and its place along the boundary, clockwise from the top left corner.
+  const onBoundary = (p: Point): { p: Point; t: number } => {
+    const cx = Math.min(x1, Math.max(x0, p.x));
+    const cy = Math.min(y1, Math.max(y0, p.y));
+    const dl = cx - x0;
+    const dr = x1 - cx;
+    const dt = cy - y0;
+    const db = y1 - cy;
+    const least = Math.min(dl, dr, dt, db);
+    if (least === dt) return { p: { x: cx, y: y0 }, t: cx - x0 };
+    if (least === dr) return { p: { x: x1, y: cy }, t: w + (cy - y0) };
+    if (least === db) return { p: { x: cx, y: y1 }, t: w + h + (x1 - cx) };
+    return { p: { x: x0, y: cy }, t: 2 * w + h + (y1 - cy) };
+  };
+  const corners: { p: Point; t: number }[] = [
+    { p: { x: x0, y: y0 }, t: 0 },
+    { p: { x: x1, y: y0 }, t: w },
+    { p: { x: x1, y: y1 }, t: w + h },
+    { p: { x: x0, y: y1 }, t: 2 * w + h },
+  ];
+  const A = onBoundary(a);
+  const C = onBoundary(c);
+  const ahead = (C.t - A.t + per) % per;
+  const out: Point[] = [A.p];
+  if (ahead <= per / 2) {
+    const list = corners.map((k) => ({ ...k, s: (k.t - A.t + per) % per })).filter((k) => k.s > 1e-9 && k.s < ahead - 1e-9);
+    for (const k of list.sort((p, q) => p.s - q.s)) out.push(k.p);
+  } else {
+    const back = per - ahead;
+    const list = corners.map((k) => ({ ...k, s: (A.t - k.t + per) % per })).filter((k) => k.s > 1e-9 && k.s < back - 1e-9);
+    for (const k of list.sort((p, q) => p.s - q.s)) out.push(k.p);
+  }
+  out.push(C.p);
+  return out.filter((p, i) => i === 0 || dist(p, out[i - 1]!) > 1e-9);
+}
+
+/**
+ * This function gives the links of one level along a closed venation backbone (NAT-016, after Runions and others, 2005).
+ * The backbone links the items by their relative neighbourhood graph or their Gabriel graph. Each backbone link goes around the other items.
+ * The level links go in the order of their counts, the largest first. Each one takes the cheapest way on the backbone, with the cost `L (1 - discount)` for a used backbone link.
+ * The way goes around each item between its two ends. A way longer than `detour` times the direct link, or a direct backbone link, keeps the direct link.
+ */
+export function venationLinks(items: readonly LevelItem[], direct: readonly LevelLink[], o: Readonly<VenationOptions>): LevelLink[] {
+  if (direct.length < 2 || items.length < 3 || items.length > o.maxItems) return [...direct];
+  const index = new Map(items.map((it, i) => [it.id, i]));
+  const links = backboneLinks(items.map((it) => center(it.box)), o.backbone);
+  const pairs: ItemPair[] = links.map(([i, j]) => ({ source: items[i]!.id, target: items[j]!.id, count: 1 }));
+  const routed = levelLinks(items, pairs, o);
+  const n = items.length;
+  const next: { to: number; link: number }[][] = Array.from({ length: n }, () => []);
+  const cost = routed.map((l) => polylineLength(l.points));
+  routed.forEach((l, k) => {
+    const i = index.get(l.source)!;
+    const j = index.get(l.target)!;
+    next[i]!.push({ to: j, link: k });
+    next[j]!.push({ to: i, link: k });
+  });
+  const direct2 = new Set(links.map(([i, j]) => `${i},${j}`));
+  const used = new Uint8Array(routed.length);
+  const share = 1 - Math.min(0.8, Math.max(0, o.discount));
+  const order = direct.map((_, k) => k).sort((p, q) => direct[q]!.count - direct[p]!.count || direct[p]!.source.localeCompare(direct[q]!.source) || direct[p]!.target.localeCompare(direct[q]!.target));
+  const margin = o.margin ?? 5;
+  const out = [...direct];
+  for (const k of order) {
+    const l = direct[k]!;
+    const s = index.get(l.source);
+    const t = index.get(l.target);
+    if (s === undefined || t === undefined) continue;
+    if (direct2.has(`${Math.min(s, t)},${Math.max(s, t)}`)) {
+      const at = next[s]!.find((x) => x.to === t);
+      if (at) used[at.link] = 1;
+      continue;
+    }
+    // Dijkstra on the backbone. The graph is small, so a scan for the least open item is enough.
+    const best = new Float64Array(n).fill(Infinity);
+    const from = new Int32Array(n).fill(-1);
+    const via = new Int32Array(n).fill(-1);
+    const done = new Uint8Array(n);
+    best[s] = 0;
+    for (;;) {
+      let u = -1;
+      for (let i = 0; i < n; i++) if (!done[i] && best[i]! < Infinity && (u < 0 || best[i]! < best[u]!)) u = i;
+      if (u < 0 || u === t) break;
+      done[u] = 1;
+      for (const x of next[u]!) {
+        const c = best[u]! + cost[x.link]! * (used[x.link] ? share : 1);
+        if (c < best[x.to]! - 1e-9) {
+          best[x.to] = c;
+          from[x.to] = u;
+          via[x.to] = x.link;
+        }
+      }
+    }
+    if (from[t]! < 0) continue;
+    const hops: { link: number; forward: boolean }[] = [];
+    for (let v = t; v !== s; v = from[v]!) hops.push({ link: via[v]!, forward: routed[via[v]!]!.target === items[v]!.id });
+    hops.reverse();
+    const points: Point[] = [];
+    hops.forEach((h, i) => {
+      const p = routed[h.link]!.points;
+      const seq = h.forward ? [...p] : [...p].reverse();
+      if (i > 0) {
+        // The way goes around the item between the end of the hop before and the start of this hop.
+        const item = items[index.get(h.forward ? routed[h.link]!.source : routed[h.link]!.target)!]!;
+        const around = aroundBox(item.box, margin, points[points.length - 1]!, seq[0]!);
+        // The first point stays: it is on the box of the source. A link between two items that touch has no length, so its two points are one point.
+        if (points.length > 1) points.pop();
+        points.push(...around);
+        seq.shift();
+      }
+      for (const q of seq) if (points.length === 0 || dist(q, points[points.length - 1]!) > 1e-9) points.push(q);
+    });
+    if (points.length < 2 || polylineLength(points) > o.detour * polylineLength(l.points)) continue;
+    for (const h of hops) used[h.link] = 1;
+    out[k] = { ...l, points };
+  }
+  return out;
+}
+
+/**
+ * This function gives the zoom levels of the level strategy `venation` (NAT-016). The levels and their items are the levels of `depths`.
+ * In each level with groups, the links take their ways along a closed venation backbone (`venationLinks`). The last level stays as in `depths`.
+ */
+export function venationLevels(input: LevelInput, options: Readonly<VenationOptions>): Level[] {
+  const levels = depthLevels(input, options);
+  return levels.map((level, i) => (i === levels.length - 1 ? level : { ...level, links: venationLinks(level.items, level.links, options) }));
+}

package/src/plugs/leaders/index.ts

@@ -0,0 +1,42 @@
+/**
+ * The plug strategy `leaders` (EDA-041): boundary leaders of the labeling of maps, used as the stubs of the plugs.
+ * Each wall places its plugs in an order that gives leaders with no crossing, and the least length of the leaders.
+ */
+import type { PlugInput, PlugPair } from "../../strategies/model.ts";
+import { spreadWith, SPREAD_DEFAULTS } from "../spread/index.ts";
+
+/**
+ * The type of leader of a plug. With `s`, the order of a wall is the order of the angles of the far ends, as in `spread`.
+ * With `po`, the stub leaves along the normal and turns once, so the order is the order of the far ends along the wall.
+ * With `opo`, the plugs of a wall go at even places, in the order of the angles.
+ */
+export type LeaderType = "s" | "po" | "opo";
+
+/** The values of `LeaderType`. */
+export const LEADER_TYPES: readonly LeaderType[] = Object.freeze(["s", "po", "opo"]);
+
+/** The options of the plug strategy `leaders`. */
+export interface LeaderOptions {
+  /** The type of leader. The default is `po`. */
+  readonly leader: LeaderType;
+  /** The least gap between two plugs of one wall, from 2 to 8. The default is 8. */
+  readonly slotSpacing: number;
+  /** The distance from a plug to a corner of its box, or a quarter of the wall when the wall is short. The default is 6. */
+  readonly inset: number;
+  /** The number of passes that sort each wall again by the new places of the far ends, from 0 to 4. The default is 2. */
+  readonly rounds: number;
+}
+
+/** The defaults of the plug strategy `leaders`. */
+export const LEADER_DEFAULTS: Readonly<LeaderOptions> = Object.freeze({ leader: "po", slotSpacing: 8, inset: SPREAD_DEFAULTS.inset, rounds: SPREAD_DEFAULTS.rounds });
+
+/**
+ * This function gives the plugs of the plug strategy `leaders` (EDA-041, after Bekos 2007). A fixed plug stays at its point, and a plug with a side stays on that side.
+ * Each free plug goes on the side that faces the other end. The plugs of each wall keep at least `slotSpacing` between two of them.
+ * The type of leader sets their order and their places. The output has one entry for each edge with two known nodes, in the order of the edges.
+ */
+export function leaderEnds(input: PlugInput, options: Partial<LeaderOptions> = {}): PlugPair[] {
+  const o = { ...LEADER_DEFAULTS, ...options };
+  const spread = { plugGap: o.slotSpacing, inset: o.inset, rounds: o.rounds };
+  return spreadWith(input, spread, o.leader === "s" ? undefined : o.leader);
+}

package/src/plugs/spread/index.ts

@@ -84,6 +84,20 @@ function keyOf(box: Box, side: Side, far: Point): number {
   return along >= 0 ? 2 - p : -2 - p;
 }
 
+/**
+ * This function gives the sort key of a far point for a po-leader (EDA-041): its place on the axis along the wall.
+ * A far point behind the wall gets the key of `keyOf` with a large shift, so it goes to an end of the wall.
+ */
+function poKeyOf(box: Box, side: Side, far: Point): number {
+  const c = center(box);
+  const n = SIDE_NORMAL[side];
+  const out = (far.x - c.x) * n.x + (far.y - c.y) * n.y;
+  const along = alongOf(side) === "y" ? far.y : far.x;
+  if (out > 0) return along;
+  const k = keyOf(box, side, far);
+  return k >= 0 ? 1e12 + k : -1e12 + k;
+}
+
 /**
  * This function places `ideal.length` plugs in their given order on the segment from `lo` to `hi`. Two neighbours are at least `gap` apart.
  * The gap shrinks evenly when the segment is too short. The sum of the squares of the moves from the ideal places is the least.
@@ -102,7 +116,7 @@ function placeInOrder(ideal: readonly number[], lo: number, hi: number, gap: num
  * Each slot goes into the part of its ideal place, and the parts keep the order of the slots. In each part, two plugs and a plug and a fixed plug are at least `gap` apart.
  * The gap of a part shrinks evenly when the part is too short.
  */
-function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number, hi: number, gap: number): void {
+function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number, hi: number, gap: number, idealOf: (s: Slot) => number = (s) => s.ideal): void {
   const cuts = [...new Set(fixed.filter((f) => f > lo - 1e-9 && f < hi + 1e-9))].sort((a, b) => a - b);
   // The part i is from cuts[i - 1] to cuts[i]. The first part starts at lo, and the last part ends at hi.
   const ends = [lo, ...cuts, hi];
@@ -110,7 +124,7 @@ function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number,
   let part = 0;
   for (const s of slots) {
     let p = 0;
-    while (p < cuts.length && s.ideal > cuts[p]!) p++;
+    while (p < cuts.length && idealOf(s) > cuts[p]!) p++;
     part = Math.max(part, p);
     parts[part]!.push(s);
   }
@@ -125,7 +139,7 @@ function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number,
     const lower = a + fa * s;
     const upper = Math.max(lower, b - fb * s);
     const at = placeInOrder(
-      list.map((x) => x.ideal),
+      list.map((x) => idealOf(x)),
       lower,
       upper,
       s,
@@ -144,6 +158,21 @@ function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number,
  * The output has one entry for each edge with two known nodes, in the order of the edges.
  */
 export function spreadEnds(input: PlugInput, options: SpreadOptions = {}): PlugPair[] {
+  return spreadWith(input, options);
+}
+
+/**
+ * The order and the places of the plugs of one wall in the strategy `leaders` (EDA-041).
+ * With `po`, the sort key of a far end in front of the wall is its place on the axis along the wall.
+ * With `opo`, the plugs of a wall go at even places in the order of the keys of `spread`.
+ */
+export type WallLeader = "po" | "opo";
+
+/**
+ * This function does the work of `spreadEnds`, and of the strategy `leaders` with the argument `leader`.
+ * Without `leader`, it gives the plugs of `spread`.
+ */
+export function spreadWith(input: PlugInput, options: SpreadOptions = {}, leader?: WallLeader): PlugPair[] {
   const { graph } = input;
   const gap = options.plugGap ?? SPREAD_DEFAULTS.plugGap;
   const inset = options.inset ?? SPREAD_DEFAULTS.inset;
@@ -206,11 +235,16 @@ export function spreadEnds(input: PlugInput, options: SpreadOptions = {}): PlugP
   for (let round = 0; round <= rounds; round++) {
     for (const wall of walls.values()) {
       const [lo, hi] = roomOf(wall.node.box, wall.side, inset);
-      const keys = new Map<Slot, number>(wall.slots.map((s) => [s, keyOf(wall.node.box, wall.side, resolve(s.far!).point)]));
+      const key = leader === "po" ? poKeyOf : keyOf;
+      const keys = new Map<Slot, number>(wall.slots.map((s) => [s, key(wall.node.box, wall.side, resolve(s.far!).point)]));
       const tie = (a: Slot, b: Slot): number => (round === 0 ? a.rank[0] - b.rank[0] || a.rank[1] - b.rank[1] : order.get(a)! - order.get(b)!);
       const sorted = [...wall.slots].sort((a, b) => keys.get(a)! - keys.get(b)! || tie(a, b));
       sorted.forEach((s, i) => order.set(s, i));
-      placeWall(sorted, wall.fixed, lo, hi, gap);
+      if (leader === "opo") {
+        // The even places: the plugs split the room into equal parts, so the plug spacing of the wall is the largest that it can be.
+        const even = new Map<Slot, number>(sorted.map((s, i) => [s, lo + ((i + 0.5) * (hi - lo)) / sorted.length]));
+        placeWall(sorted, wall.fixed, lo, hi, gap, (s) => even.get(s)!);
+      } else placeWall(sorted, wall.fixed, lo, hi, gap);
     }
   }
   return ends.map((x) => ({ edge: x.edge, source: resolve(x.source), target: resolve(x.target) }));