@mark1russell7/highways 0.1.5 → 0.3.0

package/src/curves/model.ts

@@ -7,11 +7,13 @@ import type { Point } from "../geom.ts";
  * - `rounded`: a quadratic Bezier curve at each corner, as `roundCorners` draws it.
  * - `spline`: a centripetal Catmull-Rom spline through the points. It does not overshoot or make loops.
  * - `arc`: a circular arc at each corner, tangent to the two legs.
+ * - `smooth`: a cubic spiral, an arc and a second cubic spiral at each corner, as the corner smoothing of Figma.
+ * - `clothoid`: a clothoid, an arc and a second clothoid at each corner, as a transition curve of a road.
  */
-export type CurveType = "straight" | "rounded" | "spline" | "arc";
+export type CurveType = "straight" | "rounded" | "spline" | "arc" | "smooth" | "clothoid";
 
 /** The curve types, in the order of the benchmark. */
-export const CURVE_TYPES: readonly CurveType[] = ["straight", "rounded", "spline", "arc"];
+export const CURVE_TYPES: readonly CurveType[] = ["straight", "rounded", "spline", "arc", "smooth", "clothoid"];
 
 /** The start of a curve: the pen goes to `to` and draws nothing. */
 export interface MoveSegment {

package/src/curves/smooth/index.ts

@@ -0,0 +1,50 @@
+import type { Point } from "../../geom.ts";
+import { cornerTangent, spiralCorners, type SpiralShape } from "../corner.ts";
+import type { CurveSegment } from "../model.ts";
+import type { CurveSpace } from "../space.ts";
+
+/** The options of `smoothCurve`. */
+export interface SmoothOptions {
+  /** The radius of the arc in the middle of each corner: the smallest radius of the corner. The default is 12. */
+  readonly radius?: number;
+  /** The share of the turn of a corner in its two spirals, from 0 (a circular arc) to 1 (no arc). The default is 0.6. */
+  readonly smoothing?: number;
+  /** The boxes that the curve must not go through. Without it, each corner gets the largest radius that fits on its legs. */
+  readonly space?: CurveSpace;
+}
+
+/** The largest turn of one spiral, in radians. A cubic spiral with a larger turn has a curvature that is not monotone. */
+export const MAX_SPIRAL_TURN = 1;
+
+/**
+ * This function gives the cubic Bezier spiral at the radius 1 with the turn `theta` (F7 of the note CURVES).
+ * The first three control points are on the x axis, so the curvature is 0 at the start. The end has the curvature 1 and the tangent angle `theta`.
+ * The handles are `a = (2/3) θ (1 - θ²/2)` and `b = (2/3) θ (1 + θ²/5)`, and the middle leg is `g = 1.5 b² / sin θ`.
+ * With these handles, the curvature rises monotonically from 0 to 1 for each turn up to `MAX_SPIRAL_TURN`.
+ */
+export function bezierSpiral(theta: number): { readonly c1: Point; readonly c2: Point; readonly to: Point } {
+  const a = (2 / 3) * theta * (1 - (theta * theta) / 2);
+  const b = (2 / 3) * theta * (1 + (theta * theta) / 5);
+  const g = (1.5 * b * b) / Math.sin(theta);
+  return { c1: { x: a, y: 0 }, c2: { x: a + g, y: 0 }, to: { x: a + g + b * Math.cos(theta), y: b * Math.sin(theta) } };
+}
+
+/** This function gives the shape of a corner of `smoothCurve` with the turn `turn` at the radius 1. */
+export function smoothShape(turn: number, smoothing: number): SpiralShape {
+  const theta = Math.min((Math.max(0, Math.min(1, smoothing)) * turn) / 2, MAX_SPIRAL_TURN);
+  if (theta < 1e-9) return { tangent: Math.tan(turn / 2), theta: 0, pieces: () => [], end: { x: 0, y: 0 } };
+  const spiral = bezierSpiral(theta);
+  return { tangent: cornerTangent(turn, theta, spiral.to), theta, pieces: () => [spiral], end: spiral.to };
+}
+
+/**
+ * This function rounds each inner vertex of a polyline with a cubic spiral, a circular arc and a second cubic spiral.
+ * It is the shape of the corner smoothing of Figma (F7 of the note CURVES). The curvature rises from 0 on the leg to `1 / radius` on the arc,
+ * so the curve is G2: it has no jump of the curvature. Each spiral turns by `smoothing` times half of the turn, up to `MAX_SPIRAL_TURN`.
+ * The ends of each corner stay on the first half of each leg, so the ends of the polyline stay.
+ * With `space`, the radius of a corner shrinks until its corner triangle overlaps no box that the polyline avoids.
+ */
+export function smoothCurve(points: readonly Point[], options: SmoothOptions = {}): CurveSegment[] {
+  const smoothing = options.smoothing ?? 0.6;
+  return spiralCorners(points, { radius: options.radius ?? 12, ...(options.space ? { space: options.space } : {}) }, (turn) => smoothShape(turn, smoothing));
+}

package/src/curves/space.ts

@@ -18,6 +18,12 @@ export interface CurveSpace {
    * A polyline goes through a box when a part of it longer than `TOLERANCE` is inside the box made smaller by `TOLERANCE`.
    */
   addsHit(q: readonly Point[], p: readonly Point[]): boolean;
+  /**
+   * This method tells if the triangle `(a, v, b)` overlaps a box that the polyline `(a, v, b)` does not go through.
+   * A convex corner from `a` to `b` stays in this triangle, so a clear triangle proves a clear corner with no samples.
+   * The method is optional. Without it, a corner samples its curve.
+   */
+  addsHitTriangle?(a: Point, v: Point, b: Point): boolean;
 }
 
 /**
@@ -59,9 +65,79 @@ export function curveSpace(boxes: readonly Box[], tolerance = 0.25): CurveSpace
       }
       return false;
     },
+    addsHitTriangle(a: Point, v: Point, b: Point): boolean {
+      const x0 = Math.min(a.x, v.x, b.x);
+      const y0 = Math.min(a.y, v.y, b.y);
+      let before: Set<number> | undefined;
+      let hit = false;
+      grid.query({ x: x0, y: y0, w: Math.max(a.x, v.x, b.x) - x0, h: Math.max(a.y, v.y, b.y) - y0 }, (id) => {
+        if (hit || !triangleOverlapsBox(a, v, b, inner[id]!)) return;
+        before ??= hits([a, v, b]);
+        if (!before.has(id)) hit = true;
+      });
+      return hit;
+    },
   };
 }
 
+/**
+ * This function tells if the triangle `(a, b, c)` and the box overlap by more than `eps`. It is the test of the separating axes:
+ * the two axes of the box and the normal of each side of the triangle.
+ */
+export function triangleOverlapsBox(a: Point, b: Point, c: Point, box: Box, eps = 1e-9): boolean {
+  if (Math.max(a.x, b.x, c.x) <= box.x + eps || Math.min(a.x, b.x, c.x) >= box.x + box.w - eps) return false;
+  if (Math.max(a.y, b.y, c.y) <= box.y + eps || Math.min(a.y, b.y, c.y) >= box.y + box.h - eps) return false;
+  const corners: readonly Point[] = [
+    { x: box.x, y: box.y },
+    { x: box.x + box.w, y: box.y },
+    { x: box.x, y: box.y + box.h },
+    { x: box.x + box.w, y: box.y + box.h },
+  ];
+  const tri = [a, b, c];
+  for (let i = 0; i < 3; i++) {
+    const p = tri[i]!;
+    const q = tri[(i + 1) % 3]!;
+    const n = { x: q.y - p.y, y: p.x - q.x };
+    const len = Math.hypot(n.x, n.y);
+    if (len < 1e-12) continue;
+    const proj = (r: Point): number => ((r.x - p.x) * n.x + (r.y - p.y) * n.y) / len;
+    // The triangle is on one side of its side pq: the side of the third vertex.
+    const side = proj(tri[(i + 2) % 3]!);
+    if (Math.abs(side) < 1e-12) continue;
+    const toward = corners.map(proj).map((x) => (side > 0 ? x : -x));
+    if (Math.max(...toward) <= eps) return false;
+  }
+  return true;
+}
+
+/**
+ * This function finds the largest size from `max` down to 0 that keeps a convex corner clear, with the test of its triangle.
+ * The function `triangle` gives the start of the corner, the vertex and the end of the corner at a size.
+ * Without `addsHitTriangle` in the space, the function samples the segments of `piece`, as `fitSize` does.
+ * The function tries `max` first, then it halves the interval `steps` times.
+ */
+export function fitCorner(
+  space: CurveSpace | undefined,
+  max: number,
+  triangle: (size: number) => readonly [Point, Point, Point],
+  piece: (size: number) => readonly CurveSegment[],
+  steps = 8,
+): number {
+  if (space === undefined || max <= 0) return Math.max(0, max);
+  const test = space.addsHitTriangle?.bind(space);
+  if (!test) return fitSize(space, max, triangle, piece, steps);
+  const clear = (size: number): boolean => !test(...triangle(size));
+  if (clear(max)) return max;
+  let lo = 0;
+  let hi = max;
+  for (let i = 0; i < steps; i++) {
+    const mid = (lo + hi) / 2;
+    if (clear(mid)) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
+
 /**
  * This function finds the largest size from `max` down to 0 that keeps a piece of a curve clear.
  * A clear piece goes through no box that its polyline avoids.

package/src/groups/cut/index.ts

@@ -0,0 +1,292 @@
+import { center, type Box, type Point } from "../../geom.ts";
+import type { Graph } from "../../model.ts";
+import type { Section } from "../../sections.ts";
+import { coord, growSections, halves, sides, sortOn, type SplitPart } from "../kd/index.ts";
+
+/** The cost of a line of the rule `cut`, from the cut `c` and the parts `A` and `B` of the split. */
+export type CutObjective = "ratio" | "normalized" | "sparsest";
+
+/** The options of the grouping rule `cut` (M1 of GRP-R, the guillotine cut). */
+export interface CutOptions {
+  /** A section with more nodes splits. The default is 8, as for the quadtree. */
+  readonly cap?: number;
+  /** The tree stops at this depth. The default is 16. */
+  readonly maxDepth?: number;
+  /** The number of children of a section: 2 or 4. With 4, a section splits two times on one level. The default is 4. */
+  readonly fanout?: number;
+  /** The smallest share of the nodes in each part of a split (`β`), from 0.05 to 0.5. The default is 0.25. */
+  readonly balance?: number;
+  /**
+   * The cost of a line. The value `ratio` is `c / min(|A|, |B|)`. The value `normalized` is `c / vol(A) + c / vol(B)`, with `vol` the sum of the degrees
+   * inside the section. The value `sparsest` is `c / (|A| · |B|)`. The default is `ratio`.
+   */
+  readonly objective?: CutObjective;
+  /**
+   * The cost of a line grows by the factor `1 + pull · d`. The value `d` is the distance of the line from the middle of the cell, as a share of the side.
+   * A large value prefers the middle line, as the quadtree does. The default is 0.5.
+   */
+  readonly pull?: number;
+  /**
+   * With `true`, each section also tests the split of the quadtree, and keeps the split that cuts fewer edges.
+   * Thus no section cuts more edges than the quadtree split of its cell. With the fan-out 2, the test uses each midline of the cell. The default is `true`.
+   */
+  readonly guard?: boolean;
+}
+
+/** The default values of `CutOptions`. */
+export const CUT_DEFAULTS: Readonly<Required<CutOptions>> = Object.freeze({ cap: 8, maxDepth: 16, fanout: 4, balance: 0.25, objective: "ratio", pull: 0.5, guard: true });
+
+/** A split with the number of edges between its parts. */
+interface CutSplit {
+  readonly parts: readonly SplitPart[];
+  readonly cut: number;
+}
+
+/** The most times that the guard shrinks a cell to one quarter without a split, as `buildSections` does. */
+const SHRINK = 32;
+
+/**
+ * This function gives the tree of sections of the grouping rule `cut`: a guillotine cut that reads the edges (M1 of GRP-R).
+ * A section with more than `cap` nodes splits in two along the line with the lowest cost, on either axis. A line goes between two centers.
+ * Each part of a split holds at least the share `balance` of the nodes. With the fan-out 4, each half splits again on the same level.
+ *
+ * The cells nest and do not overlap. The option `guard` keeps the split of the quadtree when that split cuts fewer edges.
+ */
+export function cutGroups(graph: Graph, options: CutOptions = {}): Section {
+  const o: Required<CutOptions> = { ...CUT_DEFAULTS, ...options };
+  const fanout = o.fanout >= 4 ? 4 : 2;
+  const balance = Math.min(0.5, Math.max(0, o.balance));
+  const pull = Math.max(0, o.pull);
+  const nodes = graph.nodes;
+  const n = nodes.length;
+  const centers: Point[] = nodes.map((v) => center(v.box));
+  const cx = Float64Array.from(centers, (c) => c.x);
+  const cy = Float64Array.from(centers, (c) => c.y);
+  const index = new Map(nodes.map((v, i) => [v.id, i]));
+  const adj: number[][] = nodes.map(() => []);
+  for (const e of graph.edges) {
+    const a = index.get(e.source.node);
+    const b = index.get(e.target.node);
+    if (a === undefined || b === undefined || a === b) continue;
+    adj[a]!.push(b);
+    adj[b]!.push(a);
+  }
+  const mark = new Int32Array(n);
+  const rank = new Int32Array(n);
+  const degree = new Float64Array(n);
+  const owner = new Int32Array(n);
+  let token = 0;
+  // The orders of the nodes of a part on each axis, by the list of the part. A split hands the orders of a section down to its parts, so only the root sorts.
+  const orders = new WeakMap<readonly number[], readonly [number[], number[]]>();
+  const ordersOf = (list: readonly number[]): readonly [number[], number[]] => {
+    let both = orders.get(list);
+    if (!both) {
+      both = [sortOn(list, centers, 0), sortOn(list, centers, 1)];
+      orders.set(list, both);
+    }
+    return both;
+  };
+  const handDown = (list: readonly number[], parts: readonly SplitPart[]): void => {
+    parts.forEach((p, k) => {
+      for (const i of p.list) owner[i] = k;
+    });
+    const [ox, oy] = ordersOf(list);
+    const xs: number[][] = parts.map(() => []);
+    const ys: number[][] = parts.map(() => []);
+    for (const i of ox) xs[owner[i]!]!.push(i);
+    for (const i of oy) ys[owner[i]!]!.push(i);
+    parts.forEach((p, k) => orders.set(p.list, [xs[k]!, ys[k]!]));
+  };
+
+  /** This function gives the edges with both ends in the list, as a flat list of index pairs. It keeps the pairs of the last list for the guard. */
+  let lastList: readonly number[] | undefined;
+  let lastPairs: number[] = [];
+  const insideEdges = (list: readonly number[]): number[] => {
+    if (list === lastList) return lastPairs;
+    token++;
+    for (const i of list) mark[i] = token;
+    const out: number[] = [];
+    for (const i of list) for (const j of adj[i]!) if (j > i && mark[j] === token) out.push(i, j);
+    lastList = list;
+    lastPairs = out;
+    return out;
+  };
+
+  /** This function gives the number of edges of the list between two parts: `part` gives the part of a node. */
+  const cutOf = (list: readonly number[], part: (i: number) => number): number => {
+    const pairs = insideEdges(list);
+    let cut = 0;
+    for (let p = 0; p < pairs.length; p += 2) if (part(pairs[p]!) !== part(pairs[p + 1]!)) cut++;
+    return cut;
+  };
+
+  /** This function gives the cost of a line. Its inputs are the cut `c`, and the sizes `a`, `b` and the volumes `va`, `vb` of the parts. */
+  const objective = (c: number, a: number, b: number, va: number, vb: number): number => {
+    if (o.objective === "sparsest") return c / (a * b);
+    if (o.objective === "normalized") return (va > 0 ? c / va : 0) + (vb > 0 ? c / vb : 0);
+    return c / Math.min(a, b);
+  };
+
+  /**
+   * This function splits the list in two along the line with the lowest cost. It tests each line between two centers on each axis.
+   * When no line keeps the share `balance` in each part, it takes the line with the largest smaller part.
+   */
+  const guillotine = (list: readonly number[], cell: Box): CutSplit | undefined => {
+    const len = list.length;
+    if (len < 2) return undefined;
+    const pairs = insideEdges(list);
+    for (const i of list) degree[i] = 0;
+    for (const i of pairs) degree[i]!++;
+    let total = 0;
+    for (const i of list) total += degree[i]!;
+    const minPart = Math.max(1, Math.ceil(balance * len - 1e-9));
+    // The best line, and the most even line for a list where no line keeps the balance. An axis of -1 is no line.
+    let bestAxis = -1;
+    let bestT = 0;
+    let bestAt = 0;
+    let bestCut = 0;
+    let bestCost = Infinity;
+    let bestShare = Infinity;
+    let fbAxis = -1;
+    let fbT = 0;
+    let fbAt = 0;
+    let fbCut = 0;
+    let fbSmall = 0;
+    let fbShare = Infinity;
+    const both = ordersOf(list);
+    for (const axis of [0, 1] as const) {
+      const order = both[axis];
+      const at0 = axis === 0 ? cx : cy;
+      for (let r = 0; r < len; r++) rank[order[r]!] = r;
+      const diff = new Int32Array(len + 1);
+      for (let p = 0; p < pairs.length; p += 2) {
+        const ra = rank[pairs[p]!]!;
+        const rb = rank[pairs[p + 1]!]!;
+        if (ra < rb) {
+          diff[ra + 1]!++;
+          diff[rb + 1]!--;
+        } else {
+          diff[rb + 1]!++;
+          diff[ra + 1]!--;
+        }
+      }
+      const side = axis === 0 ? cell.w : cell.h;
+      const mid = (axis === 0 ? cell.x : cell.y) + side / 2;
+      let cut = 0;
+      let va = 0;
+      let before = at0[order[0]!]!;
+      for (let t = 1; t < len; t++) {
+        cut += diff[t]!;
+        va += degree[order[t - 1]!]!;
+        const after = at0[order[t]!]!;
+        const prev = before;
+        before = after;
+        // A line goes between two centers, so two nodes at one coordinate stay in one part.
+        if (!(after > prev)) continue;
+        const at = (prev + after) / 2;
+        const share = side > 0 ? Math.abs(at - mid) / side : 0;
+        const small = t < len - t ? t : len - t;
+        if (small < minPart) {
+          if (small > fbSmall || (small === fbSmall && share < fbShare)) {
+            fbAxis = axis;
+            fbT = t;
+            fbAt = at;
+            fbCut = cut;
+            fbSmall = small;
+            fbShare = share;
+          }
+          continue;
+        }
+        const cost = objective(cut, t, len - t, va, total - va) * (1 + pull * share);
+        if (cost < bestCost - 1e-12 || (Math.abs(cost - bestCost) <= 1e-12 && share < bestShare)) {
+          bestAxis = axis;
+          bestT = t;
+          bestAt = at;
+          bestCut = cut;
+          bestCost = cost;
+          bestShare = share;
+        }
+      }
+    }
+    const found = bestAxis >= 0;
+    const axis = (found ? bestAxis : fbAxis) as 0 | 1 | -1;
+    if (axis < 0) return undefined;
+    const t = found ? bestT : fbT;
+    const order = both[axis as 0 | 1];
+    token++;
+    for (let r = 0; r < t; r++) mark[order[r]!] = token;
+    const [a, b] = sides(list, (i) => mark[i] === token);
+    const cells = halves(cell, axis as 0 | 1, found ? bestAt : fbAt);
+    const parts: SplitPart[] = [
+      { digit: 0, cell: cells[0], list: a },
+      { digit: 1, cell: cells[1], list: b },
+    ];
+    handDown(list, parts);
+    return { parts, cut: found ? bestCut : fbCut };
+  };
+
+  /** This function gives the guillotine split of a section. With the fan-out 2, it is one cut. With the fan-out 4, it also cuts each half. */
+  const split = (list: readonly number[], cell: Box): CutSplit | undefined => {
+    const first = guillotine(list, cell);
+    if (!first || fanout < 4) return first;
+    let cut = first.cut;
+    const parts = first.parts.flatMap((half) => {
+      const second = guillotine(half.list, half.cell);
+      if (!second) return [{ ...half, digit: 2 * half.digit }];
+      cut += second.cut;
+      return second.parts.map((q) => ({ ...q, digit: 2 * half.digit + q.digit }));
+    });
+    return { parts, cut };
+  };
+
+  /**
+   * This function gives the split of the quadtree at the cell, as `buildSections` makes it: four quarters at the middle of the cell.
+   * When the nodes are all in one quarter, the cell shrinks to that quarter. With the fan-out 2, it gives the midline of the cell with the lower cut.
+   */
+  const quadSplit = (list: readonly number[], cell: Box): CutSplit | undefined => {
+    if (fanout < 4) {
+      let out: CutSplit | undefined;
+      for (const axis of [0, 1] as const) {
+        const lo = axis === 0 ? cell.x : cell.y;
+        const mid = lo + (axis === 0 ? cell.w : cell.h) / 2;
+        const [a, b] = sides(list, (i) => coord(centers[i]!, axis) < mid);
+        if (a.length === 0 || b.length === 0) continue;
+        const cut = cutOf(list, (i) => (coord(centers[i]!, axis) < mid ? 0 : 1));
+        const cells = halves(cell, axis, mid);
+        if (!out || cut < out.cut)
+          out = {
+            parts: [
+              { digit: 0, cell: cells[0], list: a },
+              { digit: 1, cell: cells[1], list: b },
+            ],
+            cut,
+          };
+      }
+      if (out) handDown(list, out.parts);
+      return out;
+    }
+    let box = cell;
+    for (let s = 0; s < SHRINK; s++) {
+      const mx = box.x + box.w / 2;
+      const my = box.y + box.h / 2;
+      const quarterOf = (i: number): number => (centers[i]!.x < mx ? 0 : 1) + (centers[i]!.y < my ? 0 : 2);
+      const lists: number[][] = [[], [], [], []];
+      for (const i of list) lists[quarterOf(i)]!.push(i);
+      const quarter = (q: number): Box => ({ x: q % 2 === 0 ? box.x : mx, y: q < 2 ? box.y : my, w: box.w / 2, h: box.h / 2 });
+      const full = lists.map((l, q) => ({ digit: q, cell: quarter(q), list: l })).filter((p) => p.list.length > 0);
+      if (full.length > 1) {
+        handDown(list, full);
+        return { parts: full, cut: cutOf(list, quarterOf) };
+      }
+      box = full[0]?.cell ?? box;
+    }
+    return undefined;
+  };
+
+  return growSections(nodes, o.cap, o.maxDepth, (list, cell) => {
+    const cut = split(list, cell);
+    if (!o.guard) return cut?.parts;
+    const quad = quadSplit(list, cell);
+    return quad && (!cut || quad.cut < cut.cut) ? quad.parts : cut?.parts;
+  });
+}

package/src/groups/index.ts

@@ -0,0 +1,4 @@
+export { quadtreeGroups } from "./quadtree/index.ts";
+export { byDataGroup, keyedSections, keyGroups, type KeyOptions, type NodeKey } from "./keys/index.ts";
+export { CUT_DEFAULTS, cutGroups, type CutObjective, type CutOptions } from "./cut/index.ts";
+export { KD_DEFAULTS, kdGroups, type KdAxis, type KdLine, type KdOptions } from "./kd/index.ts";

package/src/groups/kd/index.ts

@@ -0,0 +1,207 @@
+import { center, type Box, type Point } from "../../geom.ts";
+import type { Graph, Node } from "../../model.ts";
+import type { Section } from "../../sections.ts";
+
+/** The place of the line of a split of the rule `kd`. */
+export type KdLine = "median" | "middle" | "slide";
+
+/** The axis of each split of the rule `kd`. */
+export type KdAxis = "longer" | "alternate";
+
+/** The options of the grouping rule `kd` (S3 of GRP-R). */
+export interface KdOptions {
+  /** A section with more nodes splits. The default is 8, as for the quadtree. */
+  readonly cap?: number;
+  /** The tree stops at this depth. The default is 16. */
+  readonly maxDepth?: number;
+  /**
+   * This value sets the place of the line in the cell. The value `median` puts half of the nodes on each side. The value `middle` cuts the cell in half,
+   * and an empty half makes the cell shrink to the other half. The value `slide` cuts the cell in half, and a line with an empty side slides to the nearest node.
+   * The default is `slide`.
+   */
+  readonly line?: KdLine;
+  /** The number of children of a section: 2 or 4. With 4, a section splits two times on one level. The default is 4. */
+  readonly fanout?: number;
+  /** The value `longer` cuts across the longer side of the cell. The value `alternate` cuts across x, then y, then x again. The default is `longer`. */
+  readonly axis?: KdAxis;
+}
+
+/** The default values of `KdOptions`. */
+export const KD_DEFAULTS: Readonly<Required<KdOptions>> = Object.freeze({ cap: 8, maxDepth: 16, line: "slide", fanout: 4, axis: "longer" });
+
+/** One child of a split: the digit of its id, its cell and the indices of its nodes, in the order of the graph. */
+export interface SplitPart {
+  readonly digit: number;
+  readonly cell: Box;
+  readonly list: readonly number[];
+}
+
+/** A split rule gives the children of a section, or `undefined` when the section cannot split. */
+export type SplitRule = (list: readonly number[], cell: Box, depth: number) => readonly SplitPart[] | undefined;
+
+/** This function gives the bounding box of the boxes of the nodes. */
+export function nodeBounds(nodes: readonly Node[]): Box {
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const n of nodes) {
+    x0 = Math.min(x0, n.box.x);
+    y0 = Math.min(y0, n.box.y);
+    x1 = Math.max(x1, n.box.x + n.box.w);
+    y1 = Math.max(y1, n.box.y + n.box.h);
+  }
+  return nodes.length ? { x: x0, y: y0, w: x1 - x0, h: y1 - y0 } : { x: 0, y: 0, w: 0, h: 0 };
+}
+
+/**
+ * This function makes a tree of sections with a split rule. The root cell is the bounding box of the nodes.
+ * A section with more than `cap` nodes, above `maxDepth`, gets the children of the rule. A child without nodes does not become a section.
+ * The id of a child is the id of its parent and the digit of the child.
+ */
+export function growSections(nodes: readonly Node[], cap: number, maxDepth: number, rule: SplitRule): Section {
+  const limit = Math.max(1, cap);
+  const make = (id: string, depth: number, cell: Box, list: readonly number[]): Section => {
+    if (list.length > limit && depth < maxDepth) {
+      const parts = (rule(list, cell, depth) ?? []).filter((p) => p.list.length > 0);
+      if (parts.length > 1) return { id, depth, cell, nodes: list, children: parts.map((p) => make(`${id}${p.digit}`, depth + 1, p.cell, p.list)) };
+    }
+    return { id, depth, cell, nodes: list, children: [] };
+  };
+  return make(
+    "s",
+    0,
+    nodeBounds(nodes),
+    nodes.map((_, i) => i),
+  );
+}
+
+/** This function gives the coordinate of a point on an axis: 0 is x, and 1 is y. */
+export const coord = (p: Point, axis: 0 | 1): number => (axis === 0 ? p.x : p.y);
+
+/** This function gives the two halves of a cell, cut across the axis at the coordinate `at`. */
+export function halves(cell: Box, axis: 0 | 1, at: number): [Box, Box] {
+  if (axis === 0) {
+    const w = Math.min(cell.w, Math.max(0, at - cell.x));
+    return [
+      { x: cell.x, y: cell.y, w, h: cell.h },
+      { x: cell.x + w, y: cell.y, w: cell.w - w, h: cell.h },
+    ];
+  }
+  const h = Math.min(cell.h, Math.max(0, at - cell.y));
+  return [
+    { x: cell.x, y: cell.y, w: cell.w, h },
+    { x: cell.x, y: cell.y + h, w: cell.w, h: cell.h - h },
+  ];
+}
+
+/** This function puts each node of the list on its side of a split: `low` tells if a node goes to the first part. Each part keeps the order of the graph. */
+export function sides(list: readonly number[], low: (i: number) => boolean): [number[], number[]] {
+  const a: number[] = [];
+  const b: number[] = [];
+  for (const i of list) (low(i) ? a : b).push(i);
+  return [a, b];
+}
+
+/** This function gives the nodes of the list in the order of their centers on the axis. Two nodes at one coordinate keep the order of the graph. */
+export function sortOn(list: readonly number[], centers: readonly Point[], axis: 0 | 1): number[] {
+  return [...list].sort((i, j) => coord(centers[i]!, axis) - coord(centers[j]!, axis) || i - j);
+}
+
+/** The most times that the rule `middle` shrinks a cell to one half without a split. The quadtree has the same limit (`collapse`). */
+const SHRINK = 32;
+
+/** This function splits the list in two on one axis with the line rule. It gives `undefined` when no line of the rule has a node on each side. */
+function lineSplit(list: readonly number[], cell: Box, centers: readonly Point[], axis: 0 | 1, line: KdLine): [SplitPart, SplitPart] | undefined {
+  const c = (i: number): number => coord(centers[i]!, axis);
+  const part = (cells: [Box, Box], [a, b]: [number[], number[]]): [SplitPart, SplitPart] | undefined =>
+    a.length > 0 && b.length > 0
+      ? [
+          { digit: 0, cell: cells[0], list: a },
+          { digit: 1, cell: cells[1], list: b },
+        ]
+      : undefined;
+  const lo = axis === 0 ? cell.x : cell.y;
+  const size = axis === 0 ? cell.w : cell.h;
+  if (line === "median") {
+    const order = sortOn(list, centers, axis);
+    const k = Math.floor(order.length / 2);
+    const rank = new Map(order.map((i, r) => [i, r]));
+    const at = (c(order[k - 1]!) + c(order[k]!)) / 2;
+    return part(
+      halves(cell, axis, at),
+      sides(list, (i) => rank.get(i)! < k),
+    );
+  }
+  if (line === "slide") {
+    const mid = lo + size / 2;
+    let [a, b] = sides(list, (i) => c(i) < mid);
+    let at = mid;
+    if (a.length === 0) {
+      // Each center is at the middle or past it. The line slides to the nearest center, and the nodes at that coordinate go to the first part.
+      at = list.reduce((m, i) => Math.min(m, c(i)), Infinity);
+      [a, b] = sides(list, (i) => c(i) <= at);
+    } else if (b.length === 0) {
+      at = list.reduce((m, i) => Math.max(m, c(i)), -Infinity);
+      [a, b] = sides(list, (i) => c(i) < at);
+    }
+    return part(halves(cell, axis, at), [a, b]);
+  }
+  // The rule `middle`: an empty half makes the cell shrink to the other half, up to `SHRINK` times.
+  let box = cell;
+  for (let n = 0; n < SHRINK; n++) {
+    const blo = axis === 0 ? box.x : box.y;
+    const bsize = axis === 0 ? box.w : box.h;
+    if (!(bsize > 0)) return undefined;
+    const mid = blo + bsize / 2;
+    const split = sides(list, (i) => c(i) < mid);
+    const cells = halves(box, axis, mid);
+    if (split[0].length > 0 && split[1].length > 0) return part(cells, split);
+    box = split[0].length > 0 ? cells[0] : cells[1];
+  }
+  return undefined;
+}
+
+/** This function gives the axes of one binary split, in the order to try: the axis of the rule first, then the other axis. */
+function axesOf(cell: Box, axis: KdAxis, step: number): [0 | 1, 0 | 1] {
+  const first: 0 | 1 = axis === "longer" ? (cell.w >= cell.h ? 0 : 1) : step % 2 === 0 ? 0 : 1;
+  return first === 0 ? [0, 1] : [1, 0];
+}
+
+/** This function splits the list in two with the line rule. When no line on the first axis has a node on each side, it tries the other axis. */
+function binarySplit(list: readonly number[], cell: Box, centers: readonly Point[], o: Readonly<Required<KdOptions>>, step: number): [SplitPart, SplitPart] | undefined {
+  for (const axis of axesOf(cell, o.axis, step)) {
+    const split = lineSplit(list, cell, centers, axis, o.line);
+    if (split) return split;
+  }
+  return undefined;
+}
+
+/**
+ * This function makes a split rule of fan-out 4 from a binary split. The binary split cuts the section in two. Then it cuts each half with 2 nodes or more.
+ * The digit of a quarter is 2 times the digit of its half plus its own digit. A half that does not split keeps the digit of its first quarter.
+ */
+export function twoSteps(binary: (list: readonly number[], cell: Box, step: number) => readonly SplitPart[] | undefined, fanout: number): SplitRule {
+  return (list, cell, depth) => {
+    if (fanout < 4) return binary(list, cell, depth);
+    const first = binary(list, cell, 2 * depth);
+    if (!first) return undefined;
+    return first.flatMap((half) => {
+      const second = half.list.length >= 2 ? binary(half.list, half.cell, 2 * depth + 1) : undefined;
+      return second ? second.map((q) => ({ ...q, digit: 2 * half.digit + q.digit })) : [{ ...half, digit: 2 * half.digit }];
+    });
+  };
+}
+
+/**
+ * This function gives the tree of sections of the grouping rule `kd`: a k-d tree of the plane (S3 of GRP-R).
+ * A section with more than `cap` nodes splits in two with a line across one axis. With the fan-out 4, each half splits again on the same level.
+ * The cells nest and do not overlap. The line `median` gives halves of equal size.
+ */
+export function kdGroups(graph: Graph, options: KdOptions = {}): Section {
+  const o: Required<KdOptions> = { ...KD_DEFAULTS, ...options };
+  const centers = graph.nodes.map((n) => center(n.box));
+  const fanout = o.fanout >= 4 ? 4 : 2;
+  const binary = (list: readonly number[], cell: Box, step: number): readonly SplitPart[] | undefined => binarySplit(list, cell, centers, o, step);
+  return growSections(graph.nodes, o.cap, o.maxDepth, twoSteps(binary, fanout));
+}