@mark1russell7/highways 0.4.2 → 0.5.1

package/src/highways/sbeb/index.ts

@@ -0,0 +1,303 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, type Point } from "../../geom.ts";
+import { byCollection } from "../../routers/trunks.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import { firstRoutes } from "../base.ts";
+import type { EdgeGroup } from "../grouped.ts";
+import type { DensityGrid, DensitySource } from "../kdeeb/index.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { QUICKBUNDLES_DEFAULTS, quickBundles, resample } from "../quickbundles/index.ts";
+import { edgePlugs } from "../stretches.ts";
+import { outOfBoxes, tracePlan } from "../trace.ts";
+
+/** The clusterer that gives the groups of edges: QuickBundles (HWY-026) with its defaults, or the collection of each edge. */
+export type SkeletonGroups = "quickbundles" | "keys";
+
+/** The values of `SkeletonGroups`. */
+export const SKELETON_GROUPS: readonly SkeletonGroups[] = Object.freeze(["quickbundles", "keys"]);
+
+/** The point that each sample point moves toward: the nearest point of the skeleton of its group, or of the mean polyline of its group. */
+export type SkeletonTarget = "skeleton" | "mean";
+
+/** The values of `SkeletonTarget`. */
+export const SKELETON_TARGETS: readonly SkeletonTarget[] = Object.freeze(["skeleton", "mean"]);
+
+/** The options of the highway strategy `sbeb` (HWY-009 of the notes). */
+export interface SbebOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** The clusterer of the groups. The default is `quickbundles`. */
+  readonly group: SkeletonGroups;
+  /** The first lines of the edges: their straight lines, or their first routes. The default is `lines`. */
+  readonly source: DensitySource;
+  /** The radius of the shape of a group, as a multiple of `boardUnit`. The default is 1.5. */
+  readonly radius: number;
+  /** The share of the distance to the target that a point moves in one step, from 0 to 1. The default is 0.5. */
+  readonly attraction: number;
+  /** The number of steps. The default is 4. */
+  readonly steps: number;
+  /** The share of the Laplacian smoothing of each polyline after each step, from 0 to 1. The default is 0.5. */
+  readonly smoothing: number;
+  /** The target of the points. The default is `skeleton`. */
+  readonly target: SkeletonTarget;
+  /** The side of a cell of the image of the shape, in units of the board. A large shape gets larger cells, up to 256 cells on a side. The default is 4. */
+  readonly cell: number;
+  /** The side of the grid that the points of the edges snap to after the steps, in units of the board. The default is 8. */
+  readonly snap: number;
+  /** A group with this number of edges or more moves, and a highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `sbeb`. */
+export const SBEB_DEFAULTS: Readonly<Required<Omit<SbebOptions, "margin" | "k">>> = Object.freeze({
+  group: "quickbundles",
+  source: "lines",
+  radius: 1.5,
+  attraction: 0.5,
+  steps: 4,
+  smoothing: 0.5,
+  target: "skeleton",
+  cell: 4,
+  snap: 8,
+  minSize: 2,
+});
+
+/** This function gives the group of each edge: the clusters of QuickBundles, or the collection of the edge. An edge without a collection has no group with `keys`. */
+export function skeletonGroups(input: HighwayInput, group: SkeletonGroups): Map<string, EdgeGroup> {
+  if (group === "quickbundles") return quickBundles(input, QUICKBUNDLES_DEFAULTS);
+  const out = new Map<string, EdgeGroup>();
+  for (const e of input.graph.edges) {
+    const key = byCollection(e);
+    if (key !== undefined) out.set(e.id, { key, flip: false });
+  }
+  return out;
+}
+
+/** This function gives the first line of each edge. The line goes from a point at `margin` out of the source plug to a point at `margin` out of the target plug. */
+export function firstLines(input: HighwayInput, finder: WayFinder, source: DensitySource, spacing: number): Map<string, Point[]> {
+  const routes = source === "routes" ? firstRoutes(input) : undefined;
+  const out = new Map<string, Point[]>();
+  for (const { edge, ps, pt } of edgePlugs(input.graph)) {
+    const a = finder.out(ps);
+    const b = finder.out(pt);
+    const route = routes?.get(edge.id);
+    const base = route && route.length > 2 ? [a, ...route.slice(1, -1), b] : [a, b];
+    let len = 0;
+    for (let i = 1; i < base.length; i++) len += dist(base[i - 1]!, base[i]!);
+    out.set(edge.id, resample(base, Math.max(2, Math.min(129, Math.ceil(len / Math.max(1e-3, spacing)) + 1))));
+  }
+  return out;
+}
+
+/** The image of the shape of a group and its skeleton. */
+export interface ShapeSkeleton {
+  readonly grid: DensityGrid;
+  /** The distance of each cell to the nearest cell outside the shape, in cells. A cell outside the shape has 0. */
+  readonly depth: Float64Array;
+  /** The value is 1 for each cell of the skeleton. */
+  readonly skeleton: Uint8Array;
+}
+
+/** This function gives the distance from the point `p` to the segment from `a` to `b`. */
+function segDist(p: Point, a: Point, b: Point): number {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const l2 = dx * dx + dy * dy;
+  const u = l2 > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / l2)) : 0;
+  return Math.hypot(p.x - a.x - u * dx, p.y - a.y - u * dy);
+}
+
+/** The steps to the 8 neighbours of a cell, as pairs of opposite steps: along x, along y and along the two diagonals. */
+const PAIRS: readonly (readonly [number, number])[] = [
+  [1, 0],
+  [0, 1],
+  [1, 1],
+  [1, -1],
+];
+
+/**
+ * This function gives the shape of a group and its skeleton (its medial axis). The shape is the union of the disks of radius `radius` along the lines, minus the boxes.
+ * The depth is a chamfer distance transform with the steps 1 and √2. A cell is on the skeleton when two conditions are true.
+ * Its depth is half of `radius` or more. Its depth is a ridge along one of the four pairs of opposite neighbours.
+ * A ridge is not lower than the two neighbours, and it is higher than one of them.
+ */
+export function shapeSkeleton(lines: readonly (readonly Point[])[], finder: WayFinder, radius: number, cell: number): ShapeSkeleton {
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const l of lines)
+    for (const p of l) {
+      x0 = Math.min(x0, p.x);
+      y0 = Math.min(y0, p.y);
+      x1 = Math.max(x1, p.x);
+      y1 = Math.max(y1, p.y);
+    }
+  const pad = radius + 2 * Math.max(1e-3, cell);
+  const c = Math.max(1e-3, cell, (x1 - x0 + 2 * pad) / 256, (y1 - y0 + 2 * pad) / 256);
+  const grid: DensityGrid = { cell: c, x0: x0 - pad, y0: y0 - pad, w: Math.max(1, Math.ceil((x1 - x0 + 2 * pad) / c)), h: Math.max(1, Math.ceil((y1 - y0 + 2 * pad) / c)) };
+  const { w, h } = grid;
+  const inside = new Uint8Array(w * h);
+  const mid = (x: number, y: number): Point => ({ x: grid.x0 + (x + 0.5) * c, y: grid.y0 + (y + 0.5) * c });
+  for (const l of lines)
+    for (let i = 1; i < l.length; i++) {
+      const a = l[i - 1]!;
+      const b = l[i]!;
+      const gx0 = Math.max(0, Math.floor((Math.min(a.x, b.x) - radius - grid.x0) / c));
+      const gx1 = Math.min(w - 1, Math.floor((Math.max(a.x, b.x) + radius - grid.x0) / c));
+      const gy0 = Math.max(0, Math.floor((Math.min(a.y, b.y) - radius - grid.y0) / c));
+      const gy1 = Math.min(h - 1, Math.floor((Math.max(a.y, b.y) + radius - grid.y0) / c));
+      for (let y = gy0; y <= gy1; y++) for (let x = gx0; x <= gx1; x++) if (!inside[y * w + x] && segDist(mid(x, y), a, b) <= radius) inside[y * w + x] = 1;
+    }
+  const boxPad = finder.margin / 2;
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) if (inside[y * w + x] && finder.obstacles.inside(mid(x, y), boxPad)) inside[y * w + x] = 0;
+  // The chamfer distance transform: one pass forward and one pass backward.
+  const depth = new Float64Array(w * h);
+  for (let i = 0; i < w * h; i++) depth[i] = inside[i] ? Infinity : 0;
+  const at = (x: number, y: number): number => (x < 0 || y < 0 || x >= w || y >= h ? 0 : depth[y * w + x]!);
+  const D = Math.SQRT2;
+  for (let y = 0; y < h; y++)
+    for (let x = 0; x < w; x++) {
+      const i = y * w + x;
+      if (!inside[i]) continue;
+      depth[i] = Math.min(depth[i]!, at(x - 1, y) + 1, at(x, y - 1) + 1, at(x - 1, y - 1) + D, at(x + 1, y - 1) + D);
+    }
+  for (let y = h - 1; y >= 0; y--)
+    for (let x = w - 1; x >= 0; x--) {
+      const i = y * w + x;
+      if (!inside[i]) continue;
+      depth[i] = Math.min(depth[i]!, at(x + 1, y) + 1, at(x, y + 1) + 1, at(x + 1, y + 1) + D, at(x - 1, y + 1) + D);
+    }
+  const skeleton = new Uint8Array(w * h);
+  const least = Math.max(1, (0.5 * radius) / c);
+  for (let y = 0; y < h; y++)
+    for (let x = 0; x < w; x++) {
+      const v = depth[y * w + x]!;
+      if (v < least) continue;
+      for (const [dx, dy] of PAIRS) {
+        const p = at(x + dx, y + dy);
+        const q = at(x - dx, y - dy);
+        if (v >= p && v >= q && (v > p || v > q)) {
+          skeleton[y * w + x] = 1;
+          break;
+        }
+      }
+    }
+  return { grid, depth, skeleton };
+}
+
+/** This function gives the middle of the skeleton cell nearest to `p`, within `reach` in units of the board, or `undefined`. */
+export function nearestSkeleton(s: ShapeSkeleton, p: Point, reach: number): Point | undefined {
+  const { grid: g, skeleton } = s;
+  const cx = Math.floor((p.x - g.x0) / g.cell);
+  const cy = Math.floor((p.y - g.y0) / g.cell);
+  const r = Math.ceil(reach / g.cell);
+  let best: Point | undefined;
+  let bestD = Infinity;
+  for (let y = Math.max(0, cy - r); y <= Math.min(g.h - 1, cy + r); y++)
+    for (let x = Math.max(0, cx - r); x <= Math.min(g.w - 1, cx + r); x++) {
+      if (!skeleton[y * g.w + x]) continue;
+      const q = { x: g.x0 + (x + 0.5) * g.cell, y: g.y0 + (y + 0.5) * g.cell };
+      const d = dist(p, q);
+      if (d < bestD && d <= reach) [best, bestD] = [q, d];
+    }
+  return best;
+}
+
+/** This function gives the mean polyline of lines in one direction, with `k` points. */
+export function meanLine(lines: readonly (readonly Point[])[], k: number): Point[] {
+  const n = Math.max(2, Math.round(k));
+  const sum = Array.from({ length: n }, () => ({ x: 0, y: 0 }));
+  for (const l of lines)
+    resample(l, n).forEach((p, i) => {
+      sum[i]!.x += p.x;
+      sum[i]!.y += p.y;
+    });
+  return sum.map((p) => ({ x: p.x / Math.max(1, lines.length), y: p.y / Math.max(1, lines.length) }));
+}
+
+/** This function gives the point of a polyline nearest to `p`. */
+export function nearestOnLine(line: readonly Point[], p: Point): Point {
+  let best = line[0]!;
+  let bestD = dist(p, best);
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!;
+    const b = line[i]!;
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const l2 = dx * dx + dy * dy;
+    const u = l2 > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / l2)) : 0;
+    const q = { x: a.x + u * dx, y: a.y + u * dy };
+    const d = dist(p, q);
+    if (d < bestD) [best, bestD] = [q, d];
+  }
+  return best;
+}
+
+/** This function gives the groups with `min` edges or more, as lists of edges. The groups are in the order of their first edges. */
+export function bigGroups(groups: ReadonlyMap<string, EdgeGroup>, min: number): { key: string; edges: { edge: string; flip: boolean }[] }[] {
+  const byKey = new Map<string, { edge: string; flip: boolean }[]>();
+  for (const [edge, g] of groups) {
+    const list = byKey.get(g.key);
+    if (list) list.push({ edge, flip: g.flip });
+    else byKey.set(g.key, [{ edge, flip: g.flip }]);
+  }
+  return [...byKey]
+    .filter(([, list]) => list.length >= Math.max(2, min))
+    .map(([key, edges]) => ({ key, edges }));
+}
+
+/**
+ * This function gives the polylines of the skeleton-based edge bundling (SBEB, Ersoy, Hurter, Paulovich, Cantareiro and Telea 2011). The ends of each polyline stay.
+ * In each step, each group of `minSize` edges or more draws its shape, and each inner point moves the share `attraction` toward its target.
+ * The share falls to 0 at the distance `2 radius`. A Laplacian smoothing keeps each polyline smooth, and a point in a box moves out of it.
+ * The edges outside such a group do not move.
+ */
+export function sbebLines(input: HighwayInput, finder: WayFinder, o: Readonly<SbebOptions>): Map<string, Point[]> {
+  const radius = Math.max(1e-3, o.radius * boardUnit(input.graph));
+  const lines = firstLines(input, finder, o.source, Math.max(4, 2 * o.cell));
+  const groups = bigGroups(skeletonGroups(input, o.group), o.minSize).map((g) => ({ ...g, edges: g.edges.filter((m) => lines.has(m.edge)) }));
+  const pad = finder.margin / 2;
+  const a = Math.max(0, Math.min(1, o.attraction));
+  const smooth = Math.max(0, Math.min(1, o.smoothing));
+  for (let step = 0; step < Math.max(0, Math.round(o.steps)); step++) {
+    for (const g of groups) {
+      if (g.edges.length < 2) continue;
+      const own = g.edges.map((m) => lines.get(m.edge)!);
+      const target: (p: Point) => Point | undefined =
+        o.target === "mean"
+          ? ((mean) => (p: Point) => nearestOnLine(mean, p))(meanLine(g.edges.map((m, i) => (m.flip ? [...own[i]!].reverse() : own[i]!)), 33))
+          : ((s) => (p: Point) => nearestSkeleton(s, p, 2 * radius))(shapeSkeleton(own, finder, radius, o.cell));
+      g.edges.forEach((m, i) => {
+        const l = own[i]!;
+        const moved = l.map((p, j) => {
+          if (j === 0 || j === l.length - 1) return p;
+          const s = target(p);
+          if (!s) return p;
+          const k = a * Math.max(0, 1 - dist(p, s) / (2 * radius));
+          return { x: p.x + k * (s.x - p.x), y: p.y + k * (s.y - p.y) };
+        });
+        const smoothed = moved.map((p, j) => {
+          if (j === 0 || j === moved.length - 1 || smooth === 0) return p;
+          const u = moved[j - 1]!;
+          const v = moved[j + 1]!;
+          return { x: (1 - smooth) * p.x + (smooth * (u.x + v.x)) / 2, y: (1 - smooth) * p.y + (smooth * (u.y + v.y)) / 2 };
+        });
+        lines.set(
+          m.edge,
+          smoothed.map((p, j) => (j === 0 || j === smoothed.length - 1 ? p : outOfBoxes(finder.obstacles, p, pad))),
+        );
+      });
+    }
+  }
+  return lines;
+}
+
+/**
+ * This function gives the highways of the skeleton-based edge bundling (HWY-009). The points of `sbebLines` snap to a grid of side `snap`.
+ * The ways go through the corner graph, and each stretch that `minSize` ways share is a highway.
+ */
+export function sbebPlan(input: HighwayInput, o: Readonly<SbebOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const lines = sbebLines(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: "sbeb" });
+}

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/snap.ts

@@ -0,0 +1,110 @@
+import { dist, polylineLength, type Point } from "../geom.ts";
+import { orderLanes } from "../segments.ts";
+import { WayFinder, type WayOptions } from "../ways.ts";
+import { nearestPlace, tidyPlan } from "./base.ts";
+import { lengthBetween, memberAt, pointAt, type Highway, type HighwayInput, type HighwayMember, type HighwayPlan } from "./model.ts";
+import { edgePlugs } from "./stretches.ts";
+
+/** One edge that snaps to a line: the points where it joins and leaves the line, and its place along its own way. */
+export interface SnapMember {
+  readonly edge: string;
+  /** The point on the line where the edge joins it. */
+  readonly from: Point;
+  /** The point on the line where the edge leaves it. */
+  readonly to: Point;
+  /** The place of the join along the edge, from 0 at the source to 1 at the target. It orders the highways of one edge. */
+  readonly at: number;
+}
+
+/** A straight line that a finder gives as the place of a highway, with the edges that snap to it. */
+export interface SnapLine {
+  readonly key: string;
+  readonly a: Point;
+  readonly b: Point;
+  readonly members: readonly SnapMember[];
+}
+
+/** The options of `snapPlan`. */
+export interface SnapOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** A highway has this number of edges or more. The value is 2 or more. */
+  readonly minSize: number;
+}
+
+/** This function gives the line `u d + rho n` of the direction angle `theta`, with `d = (cos, sin)` and the normal `n = (-sin, cos)`. */
+export function linePoint(theta: number, rho: number, u: number): Point {
+  const c = Math.cos(theta);
+  const s = Math.sin(theta);
+  return { x: u * c - rho * s, y: u * s + rho * c };
+}
+
+/**
+ * This function gives the highways of straight lines in the free space. Each line becomes a spine through the corner graph between its two ends.
+ * An end inside a box moves to the nearest corner of the graph.
+ * Each member joins the spine at the place nearest to its point `from`, and leaves it at the place nearest to its point `to`.
+ * A member whose part of the spine is shorter than the margin does not ride. A spine with fewer than `minSize` members is not a highway.
+ * An edge on several highways takes them in the order of `at`.
+ */
+export function snapPlan(input: HighwayInput, lines: readonly SnapLine[], o: Readonly<SnapOptions>): HighwayPlan {
+  const min = Math.max(2, o.minSize);
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const corners = finder.corners;
+  const plugs = new Map(edgePlugs(input.graph).map((p) => [p.edge.id, p] as const));
+  const pad = finder.margin / 2;
+  const free = (p: Point): Point => {
+    if (!finder.obstacles.inside(p, pad)) return p;
+    const i = corners.nearest(p);
+    return i >= 0 ? corners.points[i]! : p;
+  };
+  const highways: Highway[] = [];
+  const at = new Map<string, number>();
+  for (const line of lines) {
+    const a = free(line.a);
+    const b = free(line.b);
+    if (dist(a, b) <= finder.margin) continue;
+    const raw = corners.path(a, b);
+    if (!raw) continue;
+    const spine = corners.pull(raw);
+    if (spine.length < 2 || polylineLength(spine) <= 1e-6) continue;
+    const riders: { edge: string; on: number; off: number; points: Point[] }[] = [];
+    for (const m of line.members) {
+      const plug = plugs.get(m.edge);
+      if (!plug) continue;
+      const on = nearestPlace(spine, m.from);
+      const off = nearestPlace(spine, m.to);
+      if (lengthBetween(spine, Math.min(on, off), Math.max(on, off)) < finder.margin) continue;
+      riders.push({ edge: m.edge, on, off, points: [plug.ps.point, ...spinePart(spine, on, off), plug.pt.point] });
+    }
+    if (riders.length < min) continue;
+    const hi = highways.length;
+    for (const m of line.members) at.set(`${hi}\u0000${m.edge}`, m.at);
+    const lanes = orderLanes(spine, riders.map((r) => ({ edge: r.edge, points: r.points })), "bundle");
+    const byEdge = new Map(riders.map((r) => [r.edge, r]));
+    const members: HighwayMember[] = lanes.map((edge) => memberAt(spine, edge, byEdge.get(edge)!.on, byEdge.get(edge)!.off));
+    highways.push({ id: `h${hi}`, key: line.key, spine, lanes, members });
+  }
+  // The `seq` of each member follows `at` along its edge.
+  const trips = new Map<string, { h: number; at: number }[]>();
+  highways.forEach((h, hi) => {
+    for (const m of h.members) {
+      const list = trips.get(m.edge) ?? [];
+      list.push({ h: hi, at: at.get(`${hi}\u0000${m.edge}`) ?? 0 });
+      trips.set(m.edge, list);
+    }
+  });
+  const seq = new Map<string, number>();
+  for (const [edge, list] of trips) {
+    list.sort((p, q) => p.at - q.at || p.h - q.h);
+    list.forEach((x, k) => seq.set(`${x.h}\u0000${edge}`, k));
+  }
+  return tidyPlan({ highways: highways.map((h, hi) => ({ ...h, members: h.members.map((m) => ({ ...m, seq: seq.get(`${hi}\u0000${m.edge}`) ?? 0 })) })) });
+}
+
+/** This function gives the points of a spine from the place `on` to the place `off`, backward when `on` is larger. */
+export function spinePart(spine: readonly Point[], on: number, off: number): Point[] {
+  const lo = Math.min(on, off);
+  const hi = Math.max(on, off);
+  const out = [pointAt(spine, lo)];
+  for (let i = Math.floor(lo) + 1; i < hi; i++) out.push(spine[i]!);
+  out.push(pointAt(spine, hi));
+  return on <= off ? out : out.reverse();
+}

package/src/highways/soft-keys/index.ts

@@ -0,0 +1,114 @@
+import type { GroupRule } from "../../model.ts";
+import { byCollection } from "../../routers/trunks.ts";
+import { chainClusters, flowDistance, type Linkage } from "../flow-clusters/index.ts";
+import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The options of the highway strategy `soft-keys` (HWY-019 of the note on highways). */
+export interface SoftKeyOptions {
+  /** The rule that gives the key of each edge. The default is `byCollection`: the string `data.collection`. */
+  readonly rule: GroupRule;
+  /** The distance that two different keys add. `Infinity` keeps the edges of two keys apart, as the hard keys do. The default is 0.25. */
+  readonly lambda: number;
+  /** Two clusters join while their distance is this value or less. The default is 0.5. */
+  readonly tau: number;
+  /** The names of number fields of `data` that add a distance. The default is no field. */
+  readonly attributes: readonly string[];
+  /** The weight of each field of `attributes`. The distance of a field is its difference over its range. The default is 1. */
+  readonly weight: number;
+  /** The linkage of the clustering. The default is `average`. */
+  readonly linkage: Linkage;
+  /** 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`: the router `shared` with the cluster as the key. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `soft-keys`. */
+export const SOFT_KEY_DEFAULTS: Readonly<SoftKeyOptions> = Object.freeze({
+  rule: byCollection,
+  lambda: 0.25,
+  tau: 0.5,
+  attributes: Object.freeze([]) as readonly string[],
+  weight: 1,
+  linkage: "average",
+  minSize: 2,
+  spine: "shared",
+});
+
+/** The largest number of edges in one distance matrix. A larger graph splits into blocks of edges in the order of their sources. */
+const BLOCK = 2500;
+
+/**
+ * This function gives the soft-key distance of two edges (Peysakhovich, Hurter and Telea 2015): `d = d_geom + lambda [key(e) != key(f)] + sum_a w |a(e) - a(f)| / range(a)`.
+ * `d_geom` is the flow distance of HWY-023. The key term is 0 when an edge has no key.
+ */
+export function softDistance(geom: number, keyA: string | undefined, keyB: string | undefined, lambda: number, attributes: number): number {
+  const key = keyA !== undefined && keyB !== undefined && keyA !== keyB ? lambda : 0;
+  return geom + key + attributes;
+}
+
+/**
+ * This function gives the soft-key clusters of the edges (HWY-019). It clusters the edges with `softDistance`, with the cut at `tau`.
+ * Each edge of a cluster gets the key of the cluster. It gets `flip` when it goes opposite to the first edge of the cluster.
+ */
+export function softKeyClusters(input: HighwayInput, o: Readonly<SoftKeyOptions>): Map<string, EdgeGroup> {
+  const ends = edgePlugs(input.graph).map(({ edge, ps, pt }) => ({
+    edge: edge.id,
+    s: ps.point,
+    t: pt.point,
+    key: o.rule(edge),
+    values: o.attributes.map((a) => {
+      const v = edge.data?.[a];
+      return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+    }),
+  }));
+  // The range of each field, so that each field adds a distance from 0 to `weight`.
+  const ranges = o.attributes.map((_, ai) => {
+    const values = ends.map((e) => e.values[ai]).filter((v): v is number => v !== undefined);
+    return values.length > 1 ? Math.max(...values) - Math.min(...values) : 0;
+  });
+  const extra = (a: (typeof ends)[number], b: (typeof ends)[number]): number => {
+    let sum = 0;
+    ranges.forEach((range, ai) => {
+      const va = a.values[ai];
+      const vb = b.values[ai];
+      if (range > 0 && va !== undefined && vb !== undefined) sum += (o.weight * Math.abs(va - vb)) / range;
+    });
+    return sum;
+  };
+  const groups = new Map<string, EdgeGroup>();
+  const order = ends.length > BLOCK ? [...ends].sort((a, b) => a.s.x - b.s.x || a.s.y - b.s.y || (a.edge < b.edge ? -1 : 1)) : ends;
+  for (let from = 0; from < order.length; from += BLOCK) {
+    const block = order.slice(from, from + BLOCK);
+    const n = block.length;
+    const d = new Float64Array(n * n);
+    for (let i = 0; i < n; i++)
+      for (let j = i + 1; j < n; j++) {
+        const a = block[i]!;
+        const b = block[j]!;
+        const v = softDistance(flowDistance(a.s, a.t, b.s, b.t, false).d, a.key, b.key, o.lambda, extra(a, b));
+        d[i * n + j] = v;
+        d[j * n + i] = v;
+      }
+    const cluster = chainClusters(n, d, o.tau, o.linkage);
+    const first = new Map<number, number>();
+    block.forEach((e, i) => {
+      const c = cluster[i]!;
+      if (!first.has(c)) first.set(c, i);
+      const lead = block[first.get(c)!]!;
+      const flip = i === first.get(c) ? false : flowDistance(lead.s, lead.t, e.s, e.t, false).flip;
+      groups.set(e.edge, { key: `k${from + first.get(c)!}`, flip });
+    });
+  }
+  return groups;
+}
+
+/**
+ * This function gives the highways of the soft keys (HWY-019). The key of an edge is one more term of the distance, not a hard split.
+ * Edges of two keys still share a highway when they are very near, and edges of one key do not bundle when they are far.
+ */
+export function softKeyPlan(input: HighwayInput, o: Readonly<SoftKeyOptions>): HighwayPlan {
+  return groupedPlan(input, softKeyClusters(input, o), { spine: o.spine, minSize: o.minSize });
+}