@mark1russell7/highways 0.4.1 → 0.5.0

package/src/highways/road-classes/index.ts

@@ -0,0 +1,74 @@
+import type { Point } from "../../geom.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs, sharedStretches, type KeyedWay } from "../stretches.ts";
+
+/** The options of the highway strategy `road-classes` (HWY-034 with EDA-050 of the notes). */
+export interface RoadClassOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** A link is a highway link when its use is at this quantile of the use of the links, or higher. The default is 0.9. */
+  readonly quantile: number;
+  /** A highway link has this number of edges or more on it, and a highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+  /** The second pass gives each highway link this discount, as a share of its length. The default is 0.5. */
+  readonly discount: number;
+}
+
+/** The default options of the strategy `road-classes`. */
+export const ROAD_CLASS_DEFAULTS: Readonly<Required<Omit<RoadClassOptions, "margin" | "k">>> = Object.freeze({ quantile: 0.9, minSize: 2, discount: 0.5 });
+
+/** This function gives the quantile `q` of a list of numbers, with the nearest rank. An empty list gives `Infinity`. */
+function rank(values: readonly number[], q: number): number {
+  if (values.length === 0) return Infinity;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1))]!;
+}
+
+/**
+ * This function gives the highways of the road classes (HWY-034, EDA-050). It counts how many first ways use each link of the corner graph.
+ * The links with a use at the quantile `quantile` or higher, and at least `minSize`, are the highway links.
+ * They are the main roads of a road map.
+ * A second pass routes each edge again, with the discount on the highway links, so more edges join them.
+ * Each stretch of highway links that `minSize` ways or more share after the second pass is one highway.
+ */
+export function roadClassPlan(input: HighwayInput, o: Readonly<RoadClassOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const corners = finder.corners;
+  const id = new Map<Point, number>();
+  corners.points.forEach((p, i) => id.set(p, i));
+  const M = corners.points.length;
+  const link = (i: number, j: number): number => (i < j ? i * M + j : j * M + i);
+  const plugs = edgePlugs(input.graph);
+  const ends = plugs.map(({ ps, pt }) => [finder.out(ps), finder.out(pt)] as const);
+  // The first pass: the use of each link between two corners.
+  const use = new Map<number, number>();
+  for (const [a, b] of ends) {
+    const way = corners.path(a, b);
+    if (!way) continue;
+    const own = new Set<number>();
+    for (let i = 1; i < way.length; i++) {
+      const p = id.get(way[i - 1]!);
+      const q = id.get(way[i]!);
+      if (p !== undefined && q !== undefined) own.add(link(p, q));
+    }
+    for (const l of own) use.set(l, (use.get(l) ?? 0) + 1);
+  }
+  const floor = Math.max(2, o.minSize, rank([...use.values()], o.quantile));
+  const highway = new Set<number>();
+  for (const [l, n] of use) if (n >= floor) highway.add(l);
+  if (highway.size === 0) return { highways: [] };
+  // The second pass: the highway links cost less, so the edges near them join them.
+  const share = Math.min(1, Math.max(0.05, 1 - o.discount));
+  const cost = (i: number, j: number, d: number): number => (highway.has(link(i, j)) ? d * share : d);
+  const ways: KeyedWay[] = [];
+  plugs.forEach(({ edge }, n) => {
+    const [a, b] = ends[n]!;
+    const way = corners.path(a, b, cost, share);
+    if (way) ways.push({ edge: edge.id, key: "road", points: way });
+  });
+  const onHighway = (a: Point, b: Point): boolean => {
+    const p = id.get(a);
+    const q = id.get(b);
+    return p !== undefined && q !== undefined && highway.has(link(p, q));
+  };
+  return sharedStretches(ways, { minSize: o.minSize, link: onHighway, pull: (p) => corners.pull(p) });
+}

package/src/highways/router.ts

@@ -4,7 +4,7 @@ import type { WayOptions } from "../ways.ts";
 import { follow, type FollowOptions } from "./follow.ts";
 
 /** This function gives the options of the way finder in the options of a strategy: `margin` and `k`, when they are present. */
-function wayOptionsOf(options: object): WayOptions {
+export function wayOptionsOf(options: object): WayOptions {
   const o = options as { margin?: unknown; k?: unknown };
   return { ...(typeof o.margin === "number" ? { margin: o.margin } : {}), ...(typeof o.k === "number" ? { k: o.k } : {}) };
 }

package/src/highways/select/index.ts

@@ -0,0 +1,162 @@
+import { dist, type Point } from "../../geom.ts";
+import { byCollection } from "../../routers/trunks.ts";
+import { firstRoutes, tidyPlan } from "../base.ts";
+import { CORRIDOR_DEFAULTS, corridorPlan } from "../corridors/index.ts";
+import { FLOW_FIELD_DEFAULTS, flowFieldPlan } from "../flow-field/index.ts";
+import { lengthBetween, type Highway, type HighwayInput, type HighwayPlan } from "../model.ts";
+import { OD_CELL_DEFAULTS, odCellPlan } from "../od-cells/index.ts";
+import { QUICKBUNDLES_DEFAULTS, quickBundlesPlan } from "../quickbundles/index.ts";
+import { ROAD_CLASS_DEFAULTS, roadClassPlan } from "../road-classes/index.ts";
+import { sharedWaysPlan } from "../shared-ways/index.ts";
+import { WSPD_DEFAULTS, wspdPlan } from "../wspd/index.ts";
+
+/** A generator of candidate highways: a highway strategy with its defaults. */
+export type CandidateSource = "corridors" | "quickbundles" | "wspd" | "road-classes" | "flow-field" | "od-cells" | "shared-ways";
+
+/** The values of `CandidateSource`. */
+export const CANDIDATE_SOURCES: readonly CandidateSource[] = Object.freeze(["corridors", "quickbundles", "wspd", "road-classes", "flow-field", "od-cells", "shared-ways"]);
+
+/** The options of the highway strategy `select` (HWY-045 of the note on highways). */
+export interface SelectOptions {
+  /** The generators of the candidates. The default is `corridors`, `quickbundles`, `wspd` and `road-classes`. */
+  readonly generators: readonly CandidateSource[];
+  /** The weight of the added length of the edges against the ink that a highway saves (lambda 3 of the note). The default is 1. */
+  readonly lambda: number;
+  /** The number of passes of the local search with one swap. The default is 2. */
+  readonly swaps: number;
+}
+
+/** The default options of the strategy `select`. */
+export const SELECT_DEFAULTS: Readonly<SelectOptions> = Object.freeze({ generators: Object.freeze(["corridors", "quickbundles", "wspd", "road-classes"] as CandidateSource[]), lambda: 1, swaps: 2 });
+
+/** This function gives the plan of a generator, with its defaults. */
+export function candidatePlan(input: HighwayInput, source: CandidateSource): HighwayPlan {
+  switch (source) {
+    case "corridors":
+      return corridorPlan(input, CORRIDOR_DEFAULTS);
+    case "quickbundles":
+      return quickBundlesPlan(input, QUICKBUNDLES_DEFAULTS);
+    case "wspd":
+      return wspdPlan(input, WSPD_DEFAULTS);
+    case "road-classes":
+      return roadClassPlan(input, ROAD_CLASS_DEFAULTS);
+    case "flow-field":
+      return flowFieldPlan(input, FLOW_FIELD_DEFAULTS);
+    case "od-cells":
+      return odCellPlan(input, OD_CELL_DEFAULTS);
+    case "shared-ways":
+      return sharedWaysPlan(input, { rule: byCollection });
+  }
+}
+
+/** This function gives the place along a polyline (as a length) of the point nearest to `p`, and the distance to it. */
+function project(line: readonly Point[], p: Point): { at: number; d: number } {
+  let best = { at: 0, d: line.length > 0 ? dist(line[0]!, p) : Infinity };
+  let walked = 0;
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!;
+    const b = line[i]!;
+    const len = dist(a, b);
+    const u = len > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * (b.x - a.x) + (p.y - a.y) * (b.y - a.y)) / (len * len))) : 0;
+    const d = dist(p, { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+    if (d < best.d) best = { at: walked + u * len, d };
+    walked += len;
+  }
+  return best;
+}
+
+/** One candidate highway, with the index of its generator, its edges and its net gain. */
+interface Candidate {
+  readonly highway: Highway;
+  readonly source: number;
+  readonly edges: readonly string[];
+  readonly net: number;
+}
+
+/**
+ * This function gives the ink that a highway saves. It is the sum of the spine lengths of the members, less the length of their union.
+ * The extra length of a member is its detour from its first route. The detour goes to the merge point, along the spine and back from the split point.
+ */
+export function candidateScore(h: Highway, routes: ReadonlyMap<string, readonly Point[]>): { gain: number; extra: number } {
+  const spans = h.members.map((m) => [Math.min(m.on, m.off), Math.max(m.on, m.off)] as const).sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  let sum = 0;
+  for (const [lo, hi] of spans) sum += lengthBetween(h.spine, lo, hi);
+  let union = 0;
+  let from = -1;
+  let to = -1;
+  for (const [lo, hi] of spans) {
+    if (lo > to) {
+      if (to > from) union += lengthBetween(h.spine, from, to);
+      [from, to] = [lo, hi];
+    } else to = Math.max(to, hi);
+  }
+  if (to > from) union += lengthBetween(h.spine, from, to);
+  let extra = 0;
+  for (const m of h.members) {
+    const route = routes.get(m.edge);
+    if (!route || route.length < 2) continue;
+    const a = project(route, m.merge);
+    const b = project(route, m.split);
+    const along = lengthBetween(h.spine, Math.min(m.on, m.off), Math.max(m.on, m.off));
+    extra += Math.max(0, a.d + along + b.d - Math.max(0, b.at - a.at));
+  }
+  return { gain: sum - union, extra };
+}
+
+/**
+ * This function gives the highways of the candidate generation and selection (HWY-045). Each generator proposes its highways as candidates.
+ * The net gain of a candidate is the ink that it saves, less `lambda` times the length that it adds to its edges.
+ * Two candidates of two generators conflict when they share an edge. The highways of one generator do not conflict.
+ *
+ * The selection takes the candidates by net gain for each edge, without a conflict. Then each pass of the local search
+ * swaps in a candidate. The swap occurs when the net gain of the candidate is more than the sum of the selected candidates in conflict with it.
+ */
+export function selectPlan(input: HighwayInput, o: Readonly<SelectOptions>): HighwayPlan {
+  const routes = firstRoutes(input);
+  const candidates: Candidate[] = [];
+  [...new Set(o.generators)].forEach((source, si) => {
+    for (const highway of candidatePlan(input, source).highways) {
+      const { gain, extra } = candidateScore(highway, routes);
+      candidates.push({ highway: { ...highway, key: `${source}:${highway.key}` }, source: si, edges: highway.members.map((m) => m.edge), net: gain - o.lambda * extra });
+    }
+  });
+  const onEdge = new Map<string, number[]>();
+  candidates.forEach((c, i) => {
+    for (const e of c.edges) {
+      const list = onEdge.get(e);
+      if (list) list.push(i);
+      else onEdge.set(e, [i]);
+    }
+  });
+  const conflicts = (i: number): Set<number> => {
+    const out = new Set<number>();
+    for (const e of candidates[i]!.edges) for (const j of onEdge.get(e) ?? []) if (j !== i && candidates[j]!.source !== candidates[i]!.source) out.add(j);
+    return out;
+  };
+  const order = candidates
+    .map((_, i) => i)
+    .filter((i) => candidates[i]!.net > 0)
+    .sort((a, b) => candidates[b]!.net / candidates[b]!.edges.length - candidates[a]!.net / candidates[a]!.edges.length || a - b);
+  const chosen = new Set<number>();
+  const fill = (): void => {
+    for (const i of order) if (!chosen.has(i) && ![...conflicts(i)].some((j) => chosen.has(j))) chosen.add(i);
+  };
+  fill();
+  for (let pass = 0; pass < Math.max(0, Math.round(o.swaps)); pass++) {
+    let changed = false;
+    for (const i of order) {
+      if (chosen.has(i)) continue;
+      const against = [...conflicts(i)].filter((j) => chosen.has(j));
+      const lost = against.reduce((s, j) => s + candidates[j]!.net, 0);
+      if (against.length > 0 && candidates[i]!.net > lost + 1e-9) {
+        for (const j of against) chosen.delete(j);
+        chosen.add(i);
+        changed = true;
+      }
+    }
+    fill();
+    if (!changed) break;
+  }
+  const highways = [...chosen].sort((a, b) => a - b).map((i) => candidates[i]!.highway);
+  return tidyPlan({ highways });
+}

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 });
+}