@mark1russell7/highways 0.1.5 → 0.2.0

package/package.json

@@ -9,7 +9,7 @@
     "directory": "packages/core"
   },
   "homepage": "https://mark1russell7.github.io/highways/",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "type": "module",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

package/src/bench/sections.ts

@@ -0,0 +1,121 @@
+import type { Graph, Result } from "../model.ts";
+import { sectionsRouter, type SectionsOptions } from "../routers/sections.ts";
+import { groupStrategies } from "../strategies/builtins.ts";
+import type { Strategy } from "../strategies/model.ts";
+import { sameData } from "./run.ts";
+import { measureLevelFaults, measureRouteFaults, sumFaults, type LinkFaults } from "./links.ts";
+
+// The core runs in any host, so it reads the clock without the types of Node or the browser.
+const now = (): number => (globalThis as { performance?: { now(): number } }).performance?.now() ?? Date.now();
+
+/** The options of one setting of the router `sections`, without the name. */
+export type SectionsSettingOptions = Omit<SectionsOptions, "name" | "maxNodes">;
+
+/** One setting of a sweep of the router `sections`. */
+export interface SectionsSetting {
+  /** The name of the setting in the column `setting`. */
+  readonly name: string;
+  readonly options: SectionsSettingOptions;
+}
+
+/** One row of a sweep of the router `sections`: one setting on one board, and the measures of its routes and of its zoom levels. */
+export interface SectionsBenchRow {
+  readonly fixture: string;
+  readonly setting: string;
+  /** The faults of the routes of the edges (`measureRouteFaults`). */
+  readonly faults: LinkFaults;
+  /** The sum of the faults of the levels with groups (`measureLevelFaults` and `sumFaults`). */
+  readonly levelFaults: LinkFaults;
+  /** The sum of the overlaps of the levels with groups. */
+  readonly overlaps: number;
+  /** The number of routes that go through hubs: the routes that are not the same as the direct route of their edge. */
+  readonly hubRoutes: number;
+  /** The number of shared stretches of way of the result (`runs`). */
+  readonly runs: number;
+  /** The number of zoom levels, with the last level of single nodes. */
+  readonly levels: number;
+  /** The number of items of the far view: the first level with more than one item. */
+  readonly farItems: number;
+  /** The time of one route, in milliseconds. */
+  readonly ms: number;
+}
+
+/** This function gives the number of items of the first level with more than one item, or 0 for a result without levels. */
+function farItems(result: Result): number {
+  return result.levels?.find((l) => l.items.length > 1)?.items.length ?? 0;
+}
+
+/**
+ * This function measures the router `sections` on one board with each setting. The first row is the fair baseline: the defaults, with no option.
+ * The direct routes come from the hub limit 0, so `hubRoutes` counts the routes that use the hubs.
+ */
+export function sweepSections(fixture: string, graph: Graph, settings: readonly SectionsSetting[]): SectionsBenchRow[] {
+  const all: SectionsSetting[] = [{ name: "defaults", options: {} }, ...settings];
+  return all.map((s) => {
+    const direct = sectionsRouter({ ...s.options, name: "direct", stretch: 0, stretchPad: 0 }).route(graph);
+    const t0 = now();
+    const result = sectionsRouter({ ...s.options, name: s.name }).route(graph);
+    const ms = now() - t0;
+    const levelFaults = measureLevelFaults(result);
+    return {
+      fixture,
+      setting: s.name,
+      faults: measureRouteFaults(graph, result),
+      levelFaults: sumFaults(levelFaults),
+      overlaps: levelFaults.reduce((n, f) => n + f.overlaps, 0),
+      hubRoutes: result.routes.filter((r, i) => !sameData(r.points, direct.routes[i]?.points)).length,
+      runs: result.runs?.length ?? 0,
+      levels: result.levels?.length ?? 0,
+      farItems: farItems(result),
+      ms,
+    };
+  });
+}
+
+/** The values of the hub limit (`stretch`) of the sweep of CUSTOM. The default is 2. */
+export const STRETCH_SWEEP: readonly number[] = [1.25, 1.5, 2, 3, Infinity];
+
+/** This function gives the settings of the sweep of the hub limit: one setting for each value of `stretch`. */
+export function stretchSettings(values: readonly number[] = STRETCH_SWEEP): SectionsSetting[] {
+  return values.map((stretch) => ({ name: `stretch ${stretch}`, options: { stretch } }));
+}
+
+/** The values of `hubSlack` of the sweep of CUSTOM. The default is 80. */
+export const SLACK_SWEEP: readonly number[] = [0, 40, 80, 160, Infinity];
+
+/** This function gives the settings of the sweep of the slack of the hubs: one setting for each value of `hubSlack`. */
+export function slackSettings(values: readonly number[] = SLACK_SWEEP): SectionsSetting[] {
+  return values.map((hubSlack) => ({ name: `hubSlack ${hubSlack}`, options: { hubSlack } }));
+}
+
+/** The values of the section limit (`cap`) of the sweep of CUSTOM. The default is 8. */
+export const CAP_SWEEP: readonly number[] = [4, 6, 8, 12, 16];
+
+/** This function gives the settings of the sweep of the section limit: one setting for each value of `cap`. */
+export function capSettings(values: readonly number[] = CAP_SWEEP): SectionsSetting[] {
+  return values.map((cap) => ({ name: `cap ${cap}`, options: { cap } }));
+}
+
+/**
+ * This function gives one setting for each grouping rule: the router `sections` with the strategy as its option `group`.
+ * The map `options` gives the options of a strategy by its name.
+ */
+export function groupSettings(
+  strategies: readonly Strategy<"group">[] = Object.values(groupStrategies),
+  options: Readonly<Record<string, object>> = {},
+): SectionsSetting[] {
+  return strategies.map((group) => ({ name: `group ${group.name}`, options: { group, ...(options[group.name] ? { groupOptions: options[group.name] } : {}) } }));
+}
+
+/** This function writes the rows of `sweepSections` as a Markdown table. */
+export function formatSections(rows: readonly SectionsBenchRow[]): string {
+  const head =
+    "| fixture | setting | through | out and back | worst detour | outside | hub routes | runs | levels | far items | level through | level out and back | level outside | level overlaps | ms |";
+  const line = "|---|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|";
+  const body = rows.map((r) => {
+    const f = r.faults;
+    const l = r.levelFaults;
+    return `| ${r.fixture} | ${r.setting} | ${f.through} | ${f.backtrack} | ${f.worstDetour.toFixed(2)} | ${f.outside} | ${r.hubRoutes} | ${r.runs} | ${r.levels} | ${r.farItems} | ${l.through} | ${l.backtrack} | ${l.outside} | ${r.overlaps} | ${r.ms.toFixed(1)} |`;
+  });
+  return [head, line, ...body].join("\n");
+}

package/src/groups/index.ts

@@ -0,0 +1,2 @@
+export { quadtreeGroups } from "./quadtree/index.ts";
+export { byDataGroup, keyedSections, keyGroups, type KeyOptions, type NodeKey } from "./keys/index.ts";

package/src/groups/keys/index.ts

@@ -0,0 +1,81 @@
+import type { Box } from "../../geom.ts";
+import type { Graph, Node } from "../../model.ts";
+import { buildSections, type Section, type SectionOptions } from "../../sections.ts";
+
+/** A key rule gives the key of the group of a node. A node without a key is a group alone. */
+export type NodeKey = (node: Node, index: number) => string | undefined;
+
+/** The options of the grouping rule `keys`. */
+export interface KeyOptions {
+  /** This function gives the key of the group of each node. The default is `byDataGroup`. */
+  readonly key?: NodeKey;
+  /**
+   * With this value, a group with more nodes than its `cap` splits into the cells of a quadtree, as `buildSections` does.
+   * Without it, each group is one leaf. The default is no split.
+   */
+  readonly split?: SectionOptions;
+}
+
+/** This key rule gives the string `data.group` of the node, or `undefined` when the node has no such string. */
+export const byDataGroup: NodeKey = (node) => {
+  const group = node.data?.["group"];
+  return typeof group === "string" ? group : undefined;
+};
+
+/** This function gives the bounding box of the boxes of the nodes of the list. */
+function boundsOf(nodes: readonly Node[], list: readonly number[]): Box {
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const i of list) {
+    const b = nodes[i]!.box;
+    x0 = Math.min(x0, b.x);
+    y0 = Math.min(y0, b.y);
+    x1 = Math.max(x1, b.x + b.w);
+    y1 = Math.max(y1, b.y + b.h);
+  }
+  return list.length ? { x: x0, y: y0, w: x1 - x0, h: y1 - y0 } : { x: 0, y: 0, w: 0, h: 0 };
+}
+
+/**
+ * This function gives the tree of sections of the grouping rule `keys`. The root holds each node. Each child of the root holds the nodes of one key,
+ * in the order of their first node. The id of a group is `s:` and its key. A node without a key is a group alone, with the id `s#` and its index.
+ * Thus the far view of the router `sections` shows one item for each group.
+ */
+export function keyedSections(nodes: readonly Node[], options: KeyOptions = {}): Section {
+  const key = options.key ?? byDataGroup;
+  const groups = new Map<string, number[]>();
+  nodes.forEach((n, i) => {
+    const k = key(n, i);
+    const id = k === undefined ? `s#${i}` : `s:${k}`;
+    const list = groups.get(id);
+    if (list) list.push(i);
+    else groups.set(id, [i]);
+  });
+  const children = [...groups].map(([id, list]) => group(nodes, id, list, options.split));
+  return { id: "s", depth: 0, cell: boundsOf(nodes, nodes.map((_, i) => i)), nodes: nodes.map((_, i) => i), children };
+}
+
+/** This function gives the section of one group at depth 1. With `split`, the section has the quadtree of its nodes below it. */
+function group(nodes: readonly Node[], id: string, list: readonly number[], split: SectionOptions | undefined): Section {
+  if (!split) return { id, depth: 1, cell: boundsOf(nodes, list), nodes: list, children: [] };
+  const tree = buildSections(
+    list.map((i) => nodes[i]!),
+    split,
+  );
+  // The quadtree numbers the nodes of the group from 0. Each section gets the indices of the graph, one more level and the id of the group before its path.
+  const rebase = (s: Section): Section => ({
+    id: s.id === "s" ? id : `${id}/${s.id.slice(1)}`,
+    depth: s.depth + 1,
+    cell: s.cell,
+    nodes: s.nodes.map((j) => list[j]!),
+    children: s.children.map(rebase),
+  });
+  return rebase(tree);
+}
+
+/** This function gives the tree of sections of the grouping rule `keys` for a graph. */
+export function keyGroups(graph: Graph, options: KeyOptions = {}): Section {
+  return keyedSections(graph.nodes, options);
+}

package/src/groups/quadtree/index.ts

@@ -0,0 +1,10 @@
+import type { Graph } from "../../model.ts";
+import { buildSections, type Section, type SectionOptions } from "../../sections.ts";
+
+/**
+ * This function gives the tree of sections of the grouping rule `quadtree`: the cells of a quadtree of the plane (`buildSections`).
+ * It is the default grouping rule of the router `sections`.
+ */
+export function quadtreeGroups(graph: Graph, options: SectionOptions = {}): Section {
+  return buildSections(graph.nodes, options);
+}

package/src/index.ts

@@ -10,6 +10,8 @@ export * from "./visibility.ts";
 export * from "./ways.ts";
 export * from "./segments.ts";
 export * from "./sections.ts";
+export * from "./groups/index.ts";
+export * from "./pick.ts";
 export * from "./routers/index.ts";
 export * from "./room/index.ts";
 export * from "./room/lanes.ts";
@@ -19,4 +21,5 @@ export * from "./bench/links.ts";
 export * from "./bench/run.ts";
 export * from "./bench/curves.ts";
 export * from "./bench/room.ts";
+export * from "./bench/sections.ts";
 export * from "./strategies/index.ts";

package/src/levels.ts

@@ -28,8 +28,19 @@ interface LevelWays extends Ways {
   readonly free: Map<Node, FreePlugs>;
 }
 
-/** The margin of the second corner graph. A gap between two boxes wider than approximately 1.5 times this margin lets a link through. */
-const TIGHT_MARGIN = 1;
+/** The options of the links of a level: the options of the ways, and two limits of the level links. */
+export interface LevelLinkOptions extends WayOptions {
+  /**
+   * The margin of the second corner graph. A gap between two boxes wider than approximately 1.5 times this margin lets a link through.
+   * The second graph uses the smaller of this value and `margin`. The default is 1.
+   */
+  readonly tightMargin?: number;
+  /** A plug stays at least this far from the corners of its side. The level links use the smaller of this value and `margin`. The default is 6. */
+  readonly plugInset?: number;
+}
+
+/** The default values of the two limits of `LevelLinkOptions`. */
+export const LEVEL_LINK_DEFAULTS: Readonly<Required<Pick<LevelLinkOptions, "tightMargin" | "plugInset">>> = Object.freeze({ tightMargin: 1, plugInset: 6 });
 
 const EPS = 1e-6;
 
@@ -60,12 +71,12 @@ function tidy(p: readonly Point[]): Point[] {
  * A link starts on the boundary of the box of its source and ends on the boundary of the box of its target.
  * It goes around the boxes of the other items. Where there is space, its legs are parallel to the axes.
  */
-export function levelLinks(items: readonly LevelItem[], pairs: readonly ItemPair[], options: WayOptions = {}): LevelLink[] {
+export function levelLinks(items: readonly LevelItem[], pairs: readonly ItemPair[], options: LevelLinkOptions = {}): LevelLink[] {
   if (pairs.length === 0) return [];
   const nodes: Node[] = items.map((i) => ({ id: i.id, box: i.box }));
   const byId = new Map(nodes.map((n) => [n.id, n]));
   const ways = levelWays(nodes, options);
-  const inset = Math.min(6, ways.margin);
+  const inset = Math.min(options.plugInset ?? LEVEL_LINK_DEFAULTS.plugInset, ways.margin);
   const out: LevelLink[] = [];
   for (const p of pairs) {
     const s = byId.get(p.source);
@@ -101,7 +112,7 @@ function sideWay(ways: LevelWays, s: Node, t: Node, inset: number): Point[] {
  * The buckets of the obstacles grow with the items, so a long link visits few buckets.
  * The corner graphs use `cones`, so a link goes along the corridors between the groups, not around the outer edge of the board.
  */
-function levelWays(nodes: readonly Node[], options: WayOptions): LevelWays {
+function levelWays(nodes: readonly Node[], options: LevelLinkOptions): LevelWays {
   const margin = options.margin ?? 5;
   const k = options.k ?? 8;
   let size = 0;
@@ -110,7 +121,7 @@ function levelWays(nodes: readonly Node[], options: WayOptions): LevelWays {
   const corners = new CornerGraph(nodes, obstacles, { margin, k, cones: true });
   const out = (p: Plug): Point => ({ x: p.point.x + p.normal.x * margin, y: p.point.y + p.normal.y * margin });
   let tight: CornerGraph | undefined;
-  const tightGraph = (): CornerGraph => (tight ??= new CornerGraph(nodes, obstacles, { margin: Math.min(margin, TIGHT_MARGIN), k, cones: true }));
+  const tightGraph = (): CornerGraph => (tight ??= new CornerGraph(nodes, obstacles, { margin: Math.min(margin, options.tightMargin ?? LEVEL_LINK_DEFAULTS.tightMargin), k, cones: true }));
   return { obstacles, corners, margin, out, tight: tightGraph, free: new Map() };
 }
 

package/src/model.ts

@@ -20,6 +20,8 @@ export interface Node {
   readonly id: string;
   readonly box: Box;
   readonly ports?: readonly Port[];
+  /** This data is free for the grouping rules of the nodes. The rule `keys` reads the string `data.group` by default. */
+  readonly data?: Readonly<Record<string, unknown>>;
 }
 
 /** One end of an edge: a node, and optionally one plug of that node. */

package/src/pick.ts

@@ -0,0 +1,36 @@
+import type { Level } from "./model.ts";
+
+/** This function gives the median width of the shown items of each level, in units of the plane. */
+export function itemSizes(levels: readonly Level[]): number[] {
+  return levels.map((level) => {
+    const sizes = level.items.map((i) => Math.max(i.box.w, i.box.h)).sort((a, b) => a - b);
+    return sizes.length ? sizes[Math.floor(sizes.length / 2)]! : 0;
+  });
+}
+
+/** The far-view thresholds of `pickLevel`, in pixels on the screen. */
+export interface PickOptions {
+  /** When a node is at least this wide on the screen, the view shows each route. */
+  readonly routesAt: number;
+  /** A level is fine enough when its median item is at least this wide on the screen. */
+  readonly itemAt: number;
+}
+
+/** The default thresholds: a node of 22 pixels shows its routes, and a group of 120 pixels shows its parts. */
+export const PICK: PickOptions = Object.freeze({ routesAt: 22, itemAt: 120 });
+
+/**
+ * This function picks the level that a camera shows at a scale, in pixels for each unit of the plane. The sizes come from `itemSizes`.
+ * The value `sizes.length` stands for the routes of each edge. The last level holds the nodes alone.
+ * Each threshold that `options` does not give gets its value from `PICK`.
+ */
+export function pickLevel(sizes: readonly number[], scale: number, options: Partial<PickOptions> = PICK): number {
+  const routesAt = options.routesAt ?? PICK.routesAt;
+  const itemAt = options.itemAt ?? PICK.itemAt;
+  const n = sizes.length;
+  if (n === 0) return 0;
+  if (sizes[n - 1]! * scale >= routesAt) return n;
+  let pick = 0;
+  for (let d = 0; d < n - 1; d++) if (sizes[d]! * scale >= itemAt) pick = d;
+  return pick;
+}

package/src/routers/sections.ts

@@ -1,14 +1,19 @@
 import { BACKTRACK_MIN, goesOutAndBack } from "../bench/links.ts";
 import { center, dist, pointSegmentDistance, polylineLength, type Box, type Point } from "../geom.ts";
-import { levelLinks, type ItemPair } from "../levels.ts";
+import { LEVEL_LINK_DEFAULTS, levelLinks, type ItemPair, type LevelLinkOptions } from "../levels.ts";
 import { nodeIndex, type Graph, type Level, type LevelItem, type Node, type Result, type Route, type Router, type SharedRun } from "../model.ts";
 import { placePlug } from "../plugs.ts";
-import { allSections, buildSections, treeDepth, type Section, type SectionOptions } from "../sections.ts";
+import { allSections, buildSections, checkSections, SECTION_DEFAULTS, treeDepth, type Section, type SectionOptions } from "../sections.ts";
 import { orderLanes } from "../segments.ts";
-import { WayFinder, type WayOptions } from "../ways.ts";
+import type { Strategy } from "../strategies/model.ts";
+import { WayFinder } from "../ways.ts";
 
-/** The options of the router with sections. */
-export interface SectionsOptions extends WayOptions, SectionOptions {
+/**
+ * The options of the router with sections. Each option has a default, and the defaults give the output of version 0.1.5.
+ * The options `cap`, `maxDepth` and `collapse` are the limits of the default grouping rule, the quadtree of `buildSections`.
+ * The options `tightMargin` and `plugInset` are the limits of the level links (`levelLinks`).
+ */
+export interface SectionsOptions extends LevelLinkOptions, SectionOptions {
   /** The name in the benchmark. */
   readonly name: string;
   /**
@@ -16,19 +21,49 @@ export interface SectionsOptions extends WayOptions, SectionOptions {
    * and fewer shared ways. Without it, a way passes each hub from its node up.
    */
   readonly hubs?: number;
-  /** A way through the hubs can be at most this many times as long as the line between its plugs. Else the edge goes directly. The default is 2. */
+  /**
+   * The hub limit. A way through the hubs can be at most this many times as long as the line between its plugs, plus `stretchPad` margins.
+   * Else the edge goes directly. The default is 2. The value `Infinity` keeps each way through the hubs.
+   */
   readonly stretch?: number;
+  /** A way through the hubs can be this many margins longer than `stretch` times the line between its plugs. The default is 4. */
+  readonly stretchPad?: number;
+  /**
+   * A way skips a hub that is more than this many units farther from the target than the nearest approach of the way before it.
+   * The default is 80, two times `BACKTRACK_MIN`. The value `Infinity` keeps each hub.
+   */
+  readonly hubSlack?: number;
+  /**
+   * The grouping rule: a strategy of the step `group` that makes the tree of sections. The hubs and the zoom levels come from this tree.
+   * Without it, the router uses the quadtree of `buildSections` with the options `cap`, `maxDepth` and `collapse`.
+   */
+  readonly group?: Strategy<"group">;
+  /** The options of the strategy `group`. The strategy gets its `defaults` for each option that this object does not give. */
+  readonly groupOptions?: object;
+  /**
+   * The depths of the tree that get a zoom level with groups. The last level, with each node alone, always comes after them.
+   * The default is each depth, from 0 to the depth of the deepest section.
+   */
+  readonly levels?: readonly number[];
   /** The benchmark skips a fixture with more nodes. */
   readonly maxNodes?: number;
 }
 
-const dedupe = (p: readonly Point[]): Point[] => p.filter((q, i) => i === 0 || dist(q, p[i - 1]!) > 1e-9);
+/** The default values of the numbers of `SectionsOptions`: the limits of the hubs, of the tree and of the level links. */
+export const SECTIONS_DEFAULTS: Readonly<Required<Pick<SectionsOptions, "cap" | "maxDepth" | "collapse" | "tightMargin" | "plugInset" | "hubs" | "stretch" | "stretchPad" | "hubSlack">>> =
+  Object.freeze({
+    cap: SECTION_DEFAULTS.cap,
+    maxDepth: SECTION_DEFAULTS.maxDepth,
+    collapse: SECTION_DEFAULTS.collapse,
+    tightMargin: LEVEL_LINK_DEFAULTS.tightMargin,
+    plugInset: LEVEL_LINK_DEFAULTS.plugInset,
+    hubs: Infinity,
+    stretch: 2,
+    stretchPad: 4,
+    hubSlack: 2 * BACKTRACK_MIN,
+  });
 
-/**
- * A hub can be this many units farther from the target than the nearest approach of the way before it.
- * A hub farther away goes out and back, so the way skips it.
- */
-const HUB_SLACK = 2 * BACKTRACK_MIN;
+const dedupe = (p: readonly Point[]): Point[] => p.filter((q, i) => i === 0 || dist(q, p[i - 1]!) > 1e-9);
 
 /**
  * This function makes a router with a tree of sections. Each section has a hub: the free corner nearest to the center of its nodes.
@@ -45,12 +80,14 @@ export function sectionsRouter(options: SectionsOptions): Router {
   const router: Router = {
     name: options.name,
     route(graph: Graph): Result {
-      const stretch = options.stretch ?? 2;
+      const stretch = options.stretch ?? SECTIONS_DEFAULTS.stretch;
+      const stretchPad = options.stretchPad ?? SECTIONS_DEFAULTS.stretchPad;
+      const hubSlack = options.hubSlack ?? SECTIONS_DEFAULTS.hubSlack;
       const byId = nodeIndex(graph);
       const indexOfNode = new Map(graph.nodes.map((n, i) => [n.id, i]));
       const ways = new WayFinder(graph.nodes, options);
       const corners = ways.corners;
-      const root = buildSections(graph.nodes, options);
+      const root = groupNodes(graph, options);
       const parent = new Map<Section, Section>();
       const leafOf: Section[] = [];
       for (const s of allSections(root)) {
@@ -82,7 +119,7 @@ export function sectionsRouter(options: SectionsOptions): Router {
         let last = from;
         for (const c of list) {
           const h = hub(c);
-          if (dist(h, to) > near + HUB_SLACK) continue;
+          if (dist(h, to) > near + hubSlack) continue;
           near = Math.min(near, pointSegmentDistance(to, last, h));
           last = h;
           kept.push(c);
@@ -132,7 +169,7 @@ export function sectionsRouter(options: SectionsOptions): Router {
         const b = up(lv);
         const common = new Set(b);
         const lca = a.find((x) => common.has(x))!;
-        const keep = options.hubs ?? Infinity;
+        const keep = options.hubs ?? SECTIONS_DEFAULTS.hubs;
         const side = (list: Section[]): Section[] => list.slice(Math.max(0, list.indexOf(lca) - keep), list.indexOf(lca));
         const end = ways.out(pt);
         const start = ways.out(ps);
@@ -151,7 +188,7 @@ export function sectionsRouter(options: SectionsOptions): Router {
         append(piece(chain[chain.length - 1]!.id, hub(chain[chain.length - 1]!), at(end), end, used));
         append([pt.point]);
         // A way through the hubs that is too long, or that goes out and back, gives way to the direct way.
-        if (polylineLength(out) > stretch * dist(ps.point, pt.point) + 4 * ways.margin || goesOutAndBack(out)) {
+        if (polylineLength(out) > stretch * dist(ps.point, pt.point) + stretchPad * ways.margin || goesOutAndBack(out)) {
           routes.push({ edge: e.id, points: ways.between(ps, pt, new Set<Node>([s, t])) });
           continue;
         }
@@ -176,17 +213,28 @@ export function sectionsRouter(options: SectionsOptions): Router {
   return options.maxNodes === undefined ? router : { ...router, maxNodes: options.maxNodes };
 }
 
+/** This function gives the tree of sections of the grouping rule. It examines the tree of a strategy (`checkSections`). */
+function groupNodes(graph: Graph, options: SectionsOptions): Section {
+  if (!options.group) return buildSections(graph.nodes, options);
+  const root = options.group.run(graph, options.groupOptions);
+  checkSections(root, graph.nodes.length);
+  return root;
+}
+
 /**
  * This function gives one zoom level for each depth of the tree, and a last level with each node alone.
+ * With the option `levels`, only those depths get a level with groups.
  * At depth d, a section of depth d is one item. A link joins two items and counts the edges between them.
  * In a level with groups, a link goes around the boxes of the other items (`levelLinks`).
  * In the last level, the points of a link are the route of its first edge.
  */
-function makeLevels(graph: Graph, root: Section, routeOf: ReadonlyMap<string, Route>, options: WayOptions): Level[] {
+function makeLevels(graph: Graph, root: Section, routeOf: ReadonlyMap<string, Route>, options: SectionsOptions): Level[] {
   const indexOfNode = new Map(graph.nodes.map((n, i) => [n.id, i]));
   const levels: Level[] = [];
   const deepest = treeDepth(root);
+  const shown = options.levels && new Set(options.levels);
   for (let d = 0; d <= deepest + 1; d++) {
+    if (shown && d <= deepest && !shown.has(d)) continue;
     const items: LevelItem[] = [];
     const itemOf: (Section | number)[] = [];
     const boxOf = (list: readonly number[]): Box => {

package/src/sections.ts

@@ -18,15 +18,21 @@ export interface SectionOptions {
   readonly cap?: number;
   /** The tree stops at this depth. The default is 16. */
   readonly maxDepth?: number;
+  /** A cell shrinks to one quarter at most this many times without a split. Then it stops. The default is 32. */
+  readonly collapse?: number;
 }
 
+/** The default values of `SectionOptions`. */
+export const SECTION_DEFAULTS: Readonly<Required<SectionOptions>> = Object.freeze({ cap: 8, maxDepth: 16, collapse: 32 });
+
 /**
  * This function makes the tree of sections of the nodes. A cell with more than `cap` nodes splits in four.
  * When the nodes of a cell are all in one quarter, the cell becomes that quarter and does not make a level.
  */
 export function buildSections(nodes: readonly Node[], options: SectionOptions = {}): Section {
-  const cap = Math.max(1, options.cap ?? 8);
-  const maxDepth = options.maxDepth ?? 16;
+  const cap = Math.max(1, options.cap ?? SECTION_DEFAULTS.cap);
+  const maxDepth = options.maxDepth ?? SECTION_DEFAULTS.maxDepth;
+  const collapse = options.collapse ?? SECTION_DEFAULTS.collapse;
   const centers = nodes.map((n) => center(n.box));
   let x0 = Infinity;
   let y0 = Infinity;
@@ -41,7 +47,7 @@ export function buildSections(nodes: readonly Node[], options: SectionOptions =
   const root: Box = nodes.length ? { x: x0, y: y0, w: x1 - x0, h: y1 - y0 } : { x: 0, y: 0, w: 0, h: 0 };
   const make = (id: string, depth: number, cell: Box, list: readonly number[]): Section => {
     let box = cell;
-    for (let guard = 0; list.length > cap && depth < maxDepth && guard < 32; guard++) {
+    for (let guard = 0; list.length > cap && depth < maxDepth && guard < collapse; guard++) {
       const mx = box.x + box.w / 2;
       const my = box.y + box.h / 2;
       const parts: number[][] = [[], [], [], []];
@@ -80,3 +86,40 @@ export function allSections(root: Section): Section[] {
 export function treeDepth(root: Section): number {
   return root.children.reduce((d, c) => Math.max(d, treeDepth(c)), root.depth);
 }
+
+/**
+ * This function examines a tree of sections from a grouping rule. It throws an error when the tree is not valid for `count` nodes.
+ * In a valid tree, each node is in exactly one leaf. The children of a section split its nodes, and a child is one level deeper than its parent.
+ */
+export function checkSections(root: Section, count: number): void {
+  const seen = new Array<number>(count).fill(0);
+  const ids = new Set<string>();
+  const fail = (s: Section, what: string): never => {
+    throw new Error(`The tree of sections is not valid at the section "${s.id}": ${what}.`);
+  };
+  if (root.depth !== 0) fail(root, "the root has a depth that is not 0");
+  if (root.nodes.length !== count) fail(root, `the root has ${root.nodes.length} nodes, and the graph has ${count}`);
+  const walk = (s: Section): void => {
+    if (ids.has(s.id)) fail(s, "two sections have this id");
+    ids.add(s.id);
+    if (s.children.length === 0) {
+      for (const i of s.nodes) {
+        if (!Number.isInteger(i) || i < 0 || i >= count) fail(s, `the node index ${i} is not in the graph`);
+        seen[i]!++;
+      }
+      return;
+    }
+    let total = 0;
+    const own = new Set(s.nodes);
+    for (const c of s.children) {
+      if (c.depth !== s.depth + 1) fail(c, "a child is not one level deeper than its parent");
+      for (const i of c.nodes) if (!own.has(i)) fail(c, `the node index ${i} is not in the parent`);
+      total += c.nodes.length;
+      walk(c);
+    }
+    if (total !== s.nodes.length) fail(s, "the children do not split the nodes of the section");
+  };
+  walk(root);
+  const lost = seen.findIndex((n) => n !== 1);
+  if (lost >= 0) fail(root, `the node index ${lost} is in ${seen[lost]} leaves, not in one`);
+}

package/src/strategies/builtins.ts

@@ -2,6 +2,8 @@ import { arcCurve, type ArcOptions } from "../curves/arc/index.ts";
 import { roundedCurve, type RoundedOptions } from "../curves/rounded/index.ts";
 import { splineCurve, type SplineOptions } from "../curves/spline/index.ts";
 import { straightCurve } from "../curves/straight/index.ts";
+import { byDataGroup, keyGroups, type KeyOptions } from "../groups/keys/index.ts";
+import { quadtreeGroups } from "../groups/quadtree/index.ts";
 import type { Graph, Result, Router } from "../model.ts";
 import { roomDemand, type RoomMethod, type RoomOptions } from "../room/index.ts";
 import { cornersRouter, type CornersOptions } from "../routers/corners.ts";
@@ -10,6 +12,7 @@ import { sectionsRouter, type SectionsOptions } from "../routers/sections.ts";
 import { sharedRouter, type SharedOptions } from "../routers/shared.ts";
 import { straightRouter } from "../routers/straight.ts";
 import { byCollection, trunksRouter, type TrunksOptions } from "../routers/trunks.ts";
+import { SECTION_DEFAULTS, type SectionOptions } from "../sections.ts";
 import { createRegistry, defineStrategy, type AnyStrategy, type CurveInput, type Registry, type Strategy } from "./model.ts";
 
 /** The options of a router strategy: the options of its router, without the name and the limit of the benchmark. */
@@ -158,8 +161,30 @@ export const roomStrategies: {
   lines: roomStrategy("lines", "The lanes of a gap are the straight lines between the centers of the boxes that cross the gap."),
 });
 
+/** The built-in grouping rules: the strategies of the step `group`. The router `sections` makes its hubs and its zoom levels from their tree. */
+export const groupStrategies: {
+  readonly quadtree: Strategy<"group", Required<SectionOptions>>;
+  readonly keys: Strategy<"group", KeyOptions>;
+} = Object.freeze({
+  quadtree: defineStrategy({
+    step: "group",
+    name: "quadtree",
+    describe: "The cells of a quadtree of the plane. A cell with more than `cap` nodes splits in four. It is the default rule of the router `sections`.",
+    defaults: { ...SECTION_DEFAULTS },
+    run: (graph: Graph, o: Readonly<Required<SectionOptions>>) => quadtreeGroups(graph, o),
+  }),
+  keys: defineStrategy({
+    step: "group",
+    name: "keys",
+    describe: "One group for each key of the nodes. The default key is the string `data.group` of the node. A node without a key is a group alone.",
+    defaults: { key: byDataGroup } as KeyOptions,
+    run: (graph: Graph, o: Readonly<KeyOptions>) => keyGroups(graph, o),
+  }),
+});
+
 /** The built-in strategies of each step, in order. A consumer adds its own: `createRegistry([...BUILT_IN_STRATEGIES, mine])`. */
 export const BUILT_IN_STRATEGIES: readonly AnyStrategy[] = Object.freeze([
+  ...Object.values(groupStrategies),
   ...Object.values(routerStrategies),
   ...Object.values(curveStrategies),
   ...Object.values(roomStrategies),