@mark1russell7/highways 0.1.4 → 0.2.0

package/package.json

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

package/src/bench/curves.ts

@@ -1,17 +1,22 @@
-import { curveOf, CURVE_TYPES, curveSpace, sampleCurve, type CurveType } from "../curves/index.ts";
+import { CURVE_TYPES, curveSpace, sampleCurve, type CurveType } from "../curves/index.ts";
 import { polylineLength } from "../geom.ts";
 import { nodeIndex, type Graph, type Router } from "../model.ts";
 import { nearestSide, SIDE_NORMAL } from "../plugs.ts";
+import { curveStrategies } from "../strategies/builtins.ts";
+import type { Strategy } from "../strategies/model.ts";
 import { measureLinks, type MeasuredLink } 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();
 
-/** One row of the benchmark of the curves: one curve type on the routes of one router on one fixture. */
-export interface CurveBenchRow {
+/**
+ * One row of the benchmark of the curves: one curve type on the routes of one router on one fixture.
+ * The type `T` of the name of the curve is `CurveType` for `benchCurves`, and `string` for `benchCurveStrategies`.
+ */
+export interface CurveBenchRow<T extends string = CurveType> {
   readonly router: string;
   readonly fixture: string;
-  readonly type: CurveType;
+  readonly type: T;
   /** The number of routes. */
   readonly links: number;
   /** The number of polylines that go through a box that is not one of their ends (`measureLinks`). */
@@ -40,6 +45,27 @@ export interface CurveBenchOptions {
  * The type `spline` leaves each plug along the normal of the nearest side of its node.
  */
 export function benchCurves(router: Router, fixture: string, graph: Graph, options: CurveBenchOptions = {}): CurveBenchRow[] {
+  // Each built-in curve strategy has the name of its curve type, so each row has a `CurveType`.
+  return benchCurveStrategies(
+    router,
+    fixture,
+    graph,
+    CURVE_TYPES.map((t) => curveStrategies[t]),
+    options,
+  ) as CurveBenchRow[];
+}
+
+/**
+ * This function does the work of `benchCurves` with a list of curve strategies, in place of the curve types.
+ * The option `radius` goes to each strategy. A strategy without such an option does not read it.
+ */
+export function benchCurveStrategies(
+  router: Router,
+  fixture: string,
+  graph: Graph,
+  curves: readonly Strategy<"curve">[],
+  options: CurveBenchOptions = {},
+): CurveBenchRow<string>[] {
   const tolerance = options.tolerance ?? 0.25;
   const result = router.route(graph);
   const byId = nodeIndex(graph);
@@ -60,13 +86,14 @@ export function benchCurves(router: Router, fixture: string, graph: Graph, optio
   });
   const base = measureLinks(boxes, routes);
   const ink = routes.reduce((sum, r) => sum + polylineLength(r.points), 0);
-  return CURVE_TYPES.map((type): CurveBenchRow => {
+  const radius = { radius: options.radius ?? 12 };
+  return curves.map((curve): CurveBenchRow<string> => {
     const make = (withSpace: boolean): MeasuredLink[] =>
       routes.map((r) => ({
         source: r.source,
         target: r.target,
         points: sampleCurve(
-          curveOf(r.points, { type, radius: options.radius ?? 12, startNormal: r.startNormal, endNormal: r.endNormal, ...(withSpace ? { space } : {}) }),
+          curve.run({ points: r.points, startNormal: r.startNormal, endNormal: r.endNormal, ...(withSpace ? { space } : {}) }, radius),
           tolerance,
         ),
       }));
@@ -78,7 +105,7 @@ export function benchCurves(router: Router, fixture: string, graph: Graph, optio
     return {
       router: router.name,
       fixture,
-      type,
+      type: curve.name,
       links: routes.length,
       through: base.through,
       free: free.through,
@@ -90,7 +117,7 @@ export function benchCurves(router: Router, fixture: string, graph: Graph, optio
 }
 
 /** This function writes the rows of `benchCurves` as a Markdown table. */
-export function formatCurves(rows: readonly CurveBenchRow[]): string {
+export function formatCurves(rows: readonly CurveBenchRow<string>[]): string {
   const head = "| router | fixture | curve | routes | through, polyline | through, free | through, clamped | length | ms |";
   const line = "|---|---|---|---:|---:|---:|---:|---:|---:|";
   const body = rows.map((r) => `| ${r.router} | ${r.fixture} | ${r.type} | ${r.links} | ${r.through} | ${r.free} | ${r.clamped} | ${r.length.toFixed(3)} | ${r.ms.toFixed(1)} |`);

package/src/bench/room.ts

@@ -1,8 +1,11 @@
 import { levelLinks } from "../levels.ts";
 import type { Graph, Node, Result } from "../model.ts";
-import { makeRoom, roomLinks, type RoomOptions } from "../room/index.ts";
+import { makeRoom, openGaps, roomLinks, type RoomOptions } from "../room/index.ts";
+import { gapLanes, LANE_ORDERS, type LaneOrder } from "../room/lanes.ts";
 import { sectionsRouter } from "../routers/sections.ts";
 import { laneRoutes, runKey, segmentsOf } from "../segments.ts";
+import { roomStrategies } from "../strategies/builtins.ts";
+import type { Strategy } from "../strategies/model.ts";
 import { measureLinks, measureRouteFaults, type LinkFaults } from "./links.ts";
 import { measureQuality } from "./quality.ts";
 
@@ -50,15 +53,18 @@ function areaOf(nodes: readonly Node[]): number {
 
 /**
  * This function measures the links of one board. It measures the links of the far view, with each node of the graph as one item of a level.
- * It also measures the lane routes of the router `sections` at the lane width `spacing`.
+ * With a lane order, each link of the far view gets its own lane in each gap (`gapLanes` at the lane width `spacing`).
+ * Without it, the links of a gap share the lines of the level links.
+ * The function also measures the lane routes of the router `sections` at the lane width `spacing`.
  */
-export function measureBoard(graph: Graph, spacing: number): Omit<RoomBenchRow, "fixture" | "board" | "area" | "ms"> {
+export function measureBoard(graph: Graph, spacing: number, order?: LaneOrder): Omit<RoomBenchRow, "fixture" | "board" | "area" | "ms"> {
   const links = roomLinks(graph);
   const items = graph.nodes.map((n) => ({ id: n.id, box: n.box, nodes: [n.id] }));
-  const drawn = levelLinks(
+  const level = levelLinks(
     items,
     links.map((l) => ({ source: l.source, target: l.target, count: l.count ?? 1 })),
   );
+  const drawn = order ? gapLanes(graph.nodes, level, { spacing, order }) : level;
   const boxes = new Map(graph.nodes.map((n) => [n.id, n.box]));
   // `measureQuality` reads routes of edges, so each link of the far view stands for the first edge of its pair.
   const edgeOf = new Map<string, string>();
@@ -82,10 +88,15 @@ export function measureBoard(graph: Graph, spacing: number): Omit<RoomBenchRow,
 }
 
 /**
- * This function measures a packed board, the board with each gap open to the gutter only, and the board that `makeRoom` opens with each method.
- * The options of `makeRoom` are the same for each method, except `method`.
+ * This function measures a packed board, the board with each gap open to the gutter only, and the board that each room strategy opens.
+ * The options are the same for each strategy, except `method`. The default strategies are the methods `routes` and `lines` of `roomDemand`.
  */
-export function benchRoom(fixture: string, graph: Graph, options: RoomOptions = {}): RoomBenchRow[] {
+export function benchRoom(
+  fixture: string,
+  graph: Graph,
+  options: RoomOptions = {},
+  methods: readonly Strategy<"room">[] = [roomStrategies.routes, roomStrategies.lines],
+): RoomBenchRow[] {
   const spacing = options.spacing ?? 4;
   const area0 = areaOf(graph.nodes);
   const links = roomLinks(graph);
@@ -97,19 +108,76 @@ export function benchRoom(fixture: string, graph: Graph, options: RoomOptions =
     ...measureBoard({ nodes, edges: graph.edges }, spacing),
   });
   const rows = [row("packed", graph.nodes, 0)];
-  const states: [string, RoomOptions][] = [
-    ["gutter", { ...options, spacing: 0, method: "routes" }],
-    ["routes", { ...options, method: "routes" }],
-    ["lines", { ...options, method: "lines" }],
-  ];
-  for (const [board, o] of states) {
+  const t0 = now();
+  const gutter = makeRoom(graph.nodes, links, { ...options, spacing: 0, method: "routes" });
+  rows.push(row("gutter", gutter.items, now() - t0));
+  const { method: _method, ...preset } = options;
+  for (const s of methods) {
+    const t1 = now();
+    const gaps = s.run({ items: graph.nodes, links }, preset);
+    const nodes = openGaps(graph.nodes, gaps, options.snap);
+    rows.push(row(s.name, nodes, now() - t1));
+  }
+  return rows;
+}
+
+/** One setting of a sweep of the room: the options of `makeRoom` and the lane order of the far view. */
+export interface RoomSetting {
+  /** The name of the setting in the column `board`. */
+  readonly name: string;
+  readonly options: RoomOptions;
+  /** The lane order of the far view. Without it, the links of a gap share the lines of the level links. */
+  readonly lanes?: LaneOrder;
+}
+
+/**
+ * This function measures the board that `makeRoom` opens with each setting, with the method `routes`.
+ * The first row is the fair baseline: the board with each gap open to the gutter of `baseline` only, measured at the spacing of `baseline`.
+ */
+export function sweepRoom(fixture: string, graph: Graph, settings: readonly RoomSetting[], baseline: RoomOptions = { gutter: 8, spacing: 4 }): RoomBenchRow[] {
+  const area0 = areaOf(graph.nodes);
+  const links = roomLinks(graph);
+  const row = (board: string, nodes: readonly Node[], ms: number, spacing: number, lanes?: LaneOrder): RoomBenchRow => ({
+    fixture,
+    board,
+    area: area0 > 0 ? areaOf(nodes) / area0 : 1,
+    ms,
+    ...measureBoard({ nodes, edges: graph.edges }, spacing, lanes),
+  });
+  const fair = makeRoom(graph.nodes, links, { ...baseline, spacing: 0, method: "routes", maxGrowth: Infinity, passes: 1 });
+  const rows = [row("gutter", fair.items, 0, baseline.spacing ?? 4)];
+  for (const s of settings) {
     const t0 = now();
-    const room = makeRoom(graph.nodes, links, o);
-    rows.push(row(board, room.items, now() - t0));
+    const open = makeRoom(graph.nodes, links, { ...s.options, method: "routes" });
+    rows.push(row(s.name, open.items, now() - t0, s.options.spacing ?? 4, s.lanes));
   }
   return rows;
 }
 
+/** The values of `maxGrowth` of the sweep of ROOM-A. */
+export const GROWTH_SWEEP: readonly number[] = [0, 0.06, 0.09, 0.12, 0.15, 0.18, 0.21, 0.25, 0.3, 0.35, 0.5, Infinity];
+
+/** This function gives the settings of ROOM-A: the area and the faults for each `maxGrowth`, at gutter 8 and spacing 4. */
+export function growthSettings(values: readonly number[] = GROWTH_SWEEP): RoomSetting[] {
+  return values.map((m) => ({ name: `maxGrowth ${m}`, options: { gutter: 8, spacing: 4, maxGrowth: m } }));
+}
+
+/**
+ * This function gives the settings of ROOM-C: each lane order of the far view at each spacing, at gutter 8.
+ * The order `shared` is the far view without lanes, as before ROOM-C.
+ */
+export function laneSettings(spacings: readonly number[] = [2, 4, 6, 8], orders: readonly LaneOrder[] = LANE_ORDERS): RoomSetting[] {
+  return spacings.flatMap((spacing) => [
+    { name: `shared spacing ${spacing}`, options: { gutter: 8, spacing } },
+    ...orders.map((lanes) => ({ name: `${lanes} spacing ${spacing}`, options: { gutter: 8, spacing }, lanes })),
+  ]);
+}
+
+/** This function gives the settings of ROOM-D: each gutter with each number of passes, at spacing 4. */
+export function passSettings(gutters: readonly number[] = [4, 8, 12, 16], passes: readonly number[] = [1, 2]): RoomSetting[] {
+  return gutters.flatMap((gutter) => passes.map((p) => ({ name: `gutter ${gutter} passes ${p}`, options: { gutter, spacing: 4, passes: p } })));
+}
+
 /** This function writes the rows of `benchRoom` as a Markdown table. */
 export function formatRoom(rows: readonly RoomBenchRow[]): string {
   const head = "| fixture | board | area | links | through | outside | out and back | worst detour | crossings | ink | detour | lane through | ms |";

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,11 +10,16 @@ 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";
 export * from "./bench/properties.ts";
 export * from "./bench/quality.ts";
 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/room/index.ts

@@ -64,6 +64,12 @@ export interface RoomOptions {
   readonly lanes?: "link" | "count";
   /** Two box edges nearer than this distance make one boundary of the sweep. The default is 0.5. */
   readonly snap?: number;
+  /**
+   * The number of passes of the demand. The default is 1.
+   * Each pass after the first finds the lanes again on the board that the passes before it opened, and adds the growth that it needs.
+   * The limit `maxGrowth` applies to the sum of the passes.
+   */
+  readonly passes?: number;
 }
 
 /** The demand of a board and the board with its gaps open. */
@@ -147,14 +153,28 @@ export function openGaps<T extends Boxed>(items: readonly T[], gaps: readonly Ga
  * The lanes of a gap come from the `method` of the options. The need of a gap is `gutter + lanes × spacing`, and not less than its current width.
  */
 export function roomDemand(items: readonly Boxed[], links: readonly RoomLink[], options: RoomOptions = {}): Gap[] {
+  const gutter = options.gutter ?? DEFAULT_GUTTER;
+  const snap = options.snap ?? DEFAULT_SNAP;
+  const passes = Math.max(1, Math.floor(options.passes ?? 1));
+  let total = demandOnce(items, links, options);
+  for (let p = 1; p < passes; p++) {
+    // The next pass measures the board that the passes before it opened. Its gaps are the same gaps, in the same order.
+    const next = demandOnce(openGaps(items, total, snap), links, options);
+    if (next.length !== total.length || next.some((g, i) => g.axis !== total[i]!.axis)) break;
+    total = total.map((g, i) => ({ ...g, lanes: Math.max(g.lanes, next[i]!.lanes), need: g.need + Math.max(0, next[i]!.need - next[i]!.width) }));
+  }
+  return capGrowth(items, total, gutter, options.maxGrowth ?? Infinity);
+}
+
+/** This function gives the demand of one pass, without the limit `maxGrowth`. */
+function demandOnce(items: readonly Boxed[], links: readonly RoomLink[], options: RoomOptions): Gap[] {
   const gutter = options.gutter ?? DEFAULT_GUTTER;
   const spacing = options.spacing ?? DEFAULT_SPACING;
   const snap = options.snap ?? DEFAULT_SNAP;
   const weight = (l: RoomLink): number => (options.lanes === "count" ? Math.max(1, l.count ?? 1) : 1);
   const gaps = boardGaps(items, snap);
   const lanes = (options.method ?? "routes") === "lines" ? lineLanes(items, links, gaps, weight) : routeLanes(items, links, gaps, gutter, snap, weight, options.router);
-  const raw = gaps.map((g, i) => ({ ...g, lanes: lanes[i]!, need: Math.max(g.width, gutter + lanes[i]! * spacing) }));
-  return capGrowth(items, raw, gutter, options.maxGrowth ?? Infinity);
+  return gaps.map((g, i) => ({ ...g, lanes: lanes[i]!, need: Math.max(g.width, gutter + lanes[i]! * spacing) }));
 }
 
 /** This function gives the demand of the board and the board with each gap open to its need. */