@mark1russell7/highways 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,109 @@
+# @mark1russell7/highways
+
+`@mark1russell7/highways` routes the edges of large graphs. It knows no renderer. It takes boxes and edges, and it gives polylines and zoom levels.
+
+The [repository README](https://github.com/mark1russell7/highways#readme) tells the idea, the routers and the benchmark. The [site](https://mark1russell7.github.io/highways/) shows a live map.
+
+## Install
+
+```sh
+pnpm add @mark1russell7/highways
+```
+
+## Route a graph
+
+```ts
+import { cornersRouter, type Graph } from "@mark1russell7/highways";
+
+const graph: Graph = {
+  nodes: [
+    { id: "a", box: { x: 0, y: 0, w: 80, h: 40 } },
+    { id: "b", box: { x: 240, y: 120, w: 80, h: 40 } },
+  ],
+  edges: [{ id: "ab", source: { node: "a" }, target: { node: "b" } }],
+};
+const result = cornersRouter({ name: "corners" }).route(graph);
+// Each route is a polyline: result.routes[0].points
+```
+
+## Curve types
+
+A router gives polylines. The curve layer turns a polyline into a curve of a type. The polyline can come from any router, from a lane of `laneRoutes` or from a link of a zoom level.
+
+| Type | Curve | Ends |
+|---|---|---|
+| `straight` | The polyline as it is. | As the polyline. |
+| `rounded` | A quadratic Bezier curve at each corner, as `roundCorners` draws it. The `radius` sets the size of the corners. | The first and the last legs stay. |
+| `spline` | A centripetal Catmull-Rom spline through each point. It does not overshoot or make loops in a piece. The `tension` goes from 0 (the spline) to 1 (the polyline). | With `startNormal` and `endNormal`, the curve leaves and enters each plug along its normal. |
+| `arc` | A circular arc at each corner, tangent to the two legs. On horizontal and vertical legs, each arc is a quarter circle. | The first and the last legs stay. |
+
+The output is a list of segments: `move`, `line`, `cubic` and `arc`. A renderer maps them to SVG path data, to canvas calls or to the vertices of a mesh.
+
+- `curveOf(points, options)` gives the segments of a curve. The `type` of `options` selects the curve type.
+- `toSvgPath(segments, digits = 2)` writes the segments as SVG path data.
+- `sampleCurve(segments, tolerance = 0.5)` gives a polyline within `tolerance` of the curve, for hit tests and measures.
+- `curveSpace(boxes)` makes the free space of a board one time. With `space`, a curve goes through no box that its polyline avoids.
+
+Where the full curve goes through a box, the free space makes the curve smaller. It shrinks the radius of a corner, or the tangents of a piece of a spline. A corner with no clear radius stays sharp. A piece of a spline with no clear tangent is its straight leg.
+
+```ts
+import { curveOf, curveSpace, nearestSide, SIDE_NORMAL, toSvgPath } from "@mark1russell7/highways";
+
+const space = curveSpace(graph.nodes.map((n) => n.box));
+const box = new Map(graph.nodes.map((n) => [n.id, n.box]));
+for (const route of result.routes) {
+  const edge = graph.edges.find((e) => e.id === route.edge)!;
+  const p = route.points;
+  const curve = curveOf(p, {
+    type: "spline",
+    startNormal: SIDE_NORMAL[nearestSide(box.get(edge.source.node)!, p[0]!)],
+    endNormal: SIDE_NORMAL[nearestSide(box.get(edge.target.node)!, p[p.length - 1]!)],
+    space,
+  });
+  const d = toSvgPath(curve); // The data of an SVG path element: "M 80 20 C ..."
+}
+```
+
+A canvas draws an `arc` segment with `ctx.arc(center.x, center.y, radius, start, start + sweep, sweep < 0)`.
+
+Each type has its own function too: `straightCurve`, `roundedCurve`, `splineCurve` and `arcCurve`.
+
+The benchmark compares each curve type to the polylines of each router, on the fixtures of 100 nodes or fewer. It counts the curves that go through a box, with and without the free space. It also gives the ratio of the lengths.
+
+## Room for the links
+
+A host layout can pack the boxes of a far view in a grid, with no gap between them. Then the links have no channel, and they go through the boxes. The router knows the room that the links need. The room functions give that room, and they can open the gaps.
+
+- `roomDemand(items, links, options)` gives the gaps of the board. A gap is a boundary between two columns (`axis: "x"`) or two rows (`axis: "y"`). Each gap has its current `width`, its `lanes` and its `need`.
+- The need of a gap is `gutter + lanes × spacing`, and not less than its current width. The default gutter is 8, and the default spacing is 4.
+- With the method `routes`, the default, the function opens each gap to the gutter and routes the links one time. The lanes of a gap are the most routes that go along it side by side.
+- With the method `lines`, the lanes of a gap are the straight lines between the centers of the boxes that cross the gap.
+- `openGaps(items, gaps)` moves each box by the growth of each gap before it. The boxes keep their size, their order and their alignment, so a grid stays a grid.
+- `makeRoom(items, links, options)` gives the gaps and the open board. `maxGrowth` limits the growth of the board on each axis, as a share of its size.
+- `roomLinks(graph)` gives the links of a graph, with the count of the edges of each pair.
+
+The host layout still packs the boxes. These functions do not place a box. They only open the gaps between the boxes.
+
+```ts
+import { cornersRouter, makeRoom, roomLinks } from "@mark1russell7/highways";
+
+const room = makeRoom(graph.nodes, roomLinks(graph), { gutter: 8, spacing: 4 });
+// Each gap tells its axis, its place `at`, its `width`, its `lanes` and its `need`.
+const open = { nodes: room.items, edges: graph.edges };
+const result = cornersRouter({ name: "corners" }).route(open);
+```
+
+The benchmark measures the board `packedGridBoard`: 96 touching boxes and 132 links, at gutter 8 and spacing 4. The links are the links of the far view. A lane route of the router `sections` gets a lane of 4 units for each edge of a shared segment.
+
+| Board | Area | Through | Crossings | Mean detour | Worst detour | Lane routes through a box |
+|---|---:|---:|---:|---:|---:|---:|
+| Packed | 1.00 | 62 | 162 | 1.12 | 1.48 | 94 |
+| Gutter only | 1.13 | 0 | 345 | 1.34 | 2.38 | 10 |
+| Method `routes` | 1.50 | 0 | 276 | 1.32 | 2.09 | 2 |
+| Method `lines` | 3.80 | 0 | 382 | 1.20 | 1.47 | 5 |
+
+On the packed board, the links are short only because they go through the boxes. The method `routes` is the default, because it gives the fewest crossings for its area.
+
+## License
+
+MIT

package/build/index.d.ts

@@ -70,6 +70,11 @@ export declare class Grid<T> {
   query(b: Box, visit: (item: T) => void): void;
   /** This method gives each item whose buckets come within `margin` of the segment `ab` to `visit`, one time each. */
   querySegment(a: Point, b: Point, margin: number, visit: (item: T) => void): void;
+  /**
+   * This method tells if `test` gives true for an item whose buckets come within `margin` of the segment `ab`.
+   * It gives the items in the order of `querySegment`, and it stops at the first item that passes the test.
+   */
+  someSegment(a: Point, b: Point, margin: number, test: (item: T) => boolean): boolean;
 }
 /** This function gives the bounding box of the segment `ab`. */
 export declare function segmentBounds(a: Point, b: Point): Box;
@@ -211,6 +216,45 @@ export declare const FIXTURES: readonly FixtureSpec[];
  * Node boxes do not overlap, and a gap of 12 units stays between them.
  */
 export declare function makeFixture(spec: FixtureSpec): Graph;
+/**
+ * A board of made-up data that shows one known defect of the routes or of the zoom levels.
+ * The benchmark races the routers on each case, and the measures of `measureLinks` give a number for the defect.
+ */
+export interface CaseBoard {
+  readonly name: string;
+  /** The defect that the board shows, in a few words. */
+  readonly defect: string;
+  /** This function makes the graph. The same function always gives the same graph. */
+  readonly make: () => Graph;
+}
+/**
+ * This function makes a dense board: 150 nodes in tight clusters. At the far view, the boxes of the groups overlap.
+ * Then a level link starts or ends in a group that another group covers.
+ */
+export declare function denseGroupsBoard(): Graph;
+/**
+ * This function makes a board of three rows of 32 cards. Each card links to the next card of its row.
+ * Forty long links join cards far apart. The hub of a section is near the middle of its cards.
+ * So a long link climbs to hubs behind its source or past its target, and comes back.
+ */
+export declare function hubChainBoard(): Graph;
+/**
+ * This function makes a board of 32 groups in 8 columns and 4 rows. Each group has 4 cards in a square.
+ * The cards of a group link in a chain, and 96 random links join cards of two groups.
+ * On a level with many groups, some level links go around the outer edge of the board.
+ */
+export declare function manyGroupsBoard(): Graph;
+/**
+ * This function makes the far view of a board after a host layout packs it.
+ * The board has 96 boxes of one size in a grid of 12 columns and 8 rows.
+ * The boxes touch, with no gap between them. Each box links to a box near it, and 48 long links join boxes far apart.
+ * The links have no channel between the boxes. The roadmap item ROOM measures this board before and after `makeRoom`.
+ *
+ * The board is not in `CASES`, because the digests of the router fix the output on each board of `CASES`.
+ */
+export declare function packedGridBoard(): Graph;
+/** The case boards of the benchmark. Each board has a few hundred nodes at most, so the benchmark races them on each run. */
+export declare const CASES: readonly CaseBoard[];
 /** A plug: the point where a route leaves or enters a node, and the outward normal of its side. */
 export interface Plug {
   readonly point: Point;
@@ -261,6 +305,160 @@ export declare function inflectionCurve(p0: Point, normal: Point, target: Point,
  * The curve starts and ends at most `radius` from the vertex, and at most half of each segment. The ends of the polyline stay.
  */
 export declare function roundCorners(p: readonly Point[], radius: number, steps?: number): Point[];
+/**
+ * A type of curve for a route.
+ *
+ * - `straight`: the polyline as it is.
+ * - `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.
+ */
+export type CurveType = "straight" | "rounded" | "spline" | "arc";
+/** The curve types, in the order of the benchmark. */
+export declare const CURVE_TYPES: readonly CurveType[];
+/** The start of a curve: the pen goes to `to` and draws nothing. */
+export interface MoveSegment {
+  readonly kind: "move";
+  readonly to: Point;
+}
+/** A straight line from the end of the segment before to `to`. */
+export interface LineSegment {
+  readonly kind: "line";
+  readonly to: Point;
+}
+/** A cubic Bezier curve from the end of the segment before to `to`, with the control points `c1` and `c2`. */
+export interface CubicSegment {
+  readonly kind: "cubic";
+  readonly c1: Point;
+  readonly c2: Point;
+  readonly to: Point;
+}
+/**
+ * A circular arc from the end of the segment before to `to`. The arc has its center at `center` and the radius `radius`.
+ * It starts at the angle `start` and turns by `sweep` radians. A positive `sweep` turns from the x axis to the y axis.
+ * On a canvas, `ctx.arc(center.x, center.y, radius, start, start + sweep, sweep < 0)` draws it.
+ */
+export interface ArcSegment {
+  readonly kind: "arc";
+  readonly center: Point;
+  readonly radius: number;
+  readonly start: number;
+  readonly sweep: number;
+  readonly to: Point;
+}
+/**
+ * A segment of a curve. A curve is a list of segments: one `move` first, then lines, cubic curves and arcs.
+ * A renderer maps the list to SVG path data, to canvas calls or to the vertices of a mesh.
+ */
+export type CurveSegment = MoveSegment | LineSegment | CubicSegment | ArcSegment;
+/** This function gives the points of a polyline without the points that are nearer than `eps` to the point before them. */
+export declare function distinctPoints(points: readonly Point[], eps?: number): Point[];
+/**
+ * The free space of a board: the boxes that a curve must not go through.
+ * Make it one time for a board with `curveSpace`, and give it to each call of `curveOf`.
+ */
+interface CurveSpace {
+  /** The boxes of the board. */
+  readonly boxes: readonly Box[];
+  /** The tolerance of the samples of a curve, in units of the plane. */
+  readonly tolerance: number;
+  /**
+   * This method tells if the polyline `q` goes through a box that the polyline `p` does not go through.
+   * 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 function makes the free space of a board from its boxes. The boxes are the nodes, or the items of a zoom level.
+ * The curves sample each piece within `tolerance` of the curve for the test.
+ */
+export declare function curveSpace(boxes: readonly Box[], tolerance?: number): CurveSpace;
+/**
+ * This function gives a polyline that follows the curve. The distance from each part of the curve to the polyline is `tolerance` or less.
+ * The polyline starts at the point of the `move` and goes through the end of each segment.
+ * Hit tests, measures and renderers that draw only lines use this polyline.
+ */
+export declare function sampleCurve(segments: readonly CurveSegment[], tolerance?: number): Point[];
+/** This function gives the point at the parameter `t` of the cubic Bezier curve with the control points `p0`, `p1`, `p2` and `p3`. */
+export declare function cubicAt(p0: Point, p1: Point, p2: Point, p3: Point, t: number): Point;
+/**
+ * This function writes the segments as the data of an SVG path: the commands `M`, `L`, `C` and `A`.
+ * Each number has at most `digits` digits after the point.
+ */
+export declare function toSvgPath(segments: readonly CurveSegment[], digits?: number): string;
+/** This function gives the polyline as it is: one `move` to the first point and one `line` to each other point. */
+export declare function straightCurve(points: readonly Point[]): CurveSegment[];
+/** The options of `roundedCurve`. */
+interface RoundedOptions {
+  /** The largest distance from a corner to the start and to the end of its curve. The default is 12. */
+  readonly radius?: number;
+  /** The boxes that the curve must not go through. Without it, each corner gets the full radius. */
+  readonly space?: CurveSpace;
+}
+/**
+ * This function rounds each inner vertex of a polyline with a quadratic Bezier curve, as `roundCorners` does.
+ * The curve of a corner starts and ends at most `radius` from the vertex, and at most half of each leg. The ends of the polyline stay.
+ * The function gives each quadratic curve as the same cubic curve. With `space`, it makes the radius of a corner smaller until the curve
+ * goes through no box that the polyline avoids.
+ */
+export declare function roundedCurve(points: readonly Point[], options?: RoundedOptions): CurveSegment[];
+/** The options of `splineCurve`. */
+interface SplineOptions {
+  /**
+   * The tension of the spline, from 0 to 1. The value 0 gives the centripetal Catmull-Rom spline, and 1 gives the polyline.
+   * The default is 0.
+   */
+  readonly tension?: number;
+  /** The outward normal of the plug at the first point. With it, the curve leaves the first point along this normal. */
+  readonly startNormal?: Point;
+  /** The outward normal of the plug at the last point. With it, the curve comes into the last point against this normal. */
+  readonly endNormal?: Point;
+  /** The boxes that the curve must not go through. Without it, each piece gets the full tangents. */
+  readonly space?: CurveSpace;
+}
+/**
+ * This function draws a centripetal Catmull-Rom spline through the points of a polyline (Yuksel, Schaefer and Keyser, 2011).
+ * Each piece between two points is one cubic Bezier curve. The centripetal knots keep the curve free of cusps and loops in a piece.
+ * The curve goes through each point. Its tangent at a point keeps one direction on the two sides of the point.
+ *
+ * With `space`, the function makes the tangents of a piece shorter until the piece goes through no box that its leg avoids.
+ * A piece with no tangent is the straight leg.
+ */
+export declare function splineCurve(points: readonly Point[], options?: SplineOptions): CurveSegment[];
+/** The options of `arcCurve`. */
+interface ArcOptions {
+  /** The largest radius of the arc at a corner. The default is 12. */
+  readonly radius?: 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;
+}
+/**
+ * This function puts a circular arc at each inner vertex of a polyline. The arc is tangent to the two legs of its corner.
+ * The tangent points stay on the first half of each leg, so the ends of the polyline stay.
+ * With `space`, the function makes the radius of a corner smaller until the arc goes through no box that the polyline avoids.
+ * On a polyline with only horizontal and vertical legs, each arc is a quarter circle.
+ */
+export declare function arcCurve(points: readonly Point[], options?: ArcOptions): CurveSegment[];
+/** The options of `curveOf`. Each type reads only the options that it uses. */
+export interface CurveOptions {
+  readonly type: CurveType;
+  /** The types `rounded` and `arc` read this radius of the corners. The default is 12. */
+  readonly radius?: number;
+  /** The type `spline` reads this tension, from 0 to 1. The default is 0. */
+  readonly tension?: number;
+  /** The type `spline` leaves the first point along this outward normal of its plug. */
+  readonly startNormal?: Point;
+  /** The type `spline` comes into the last point against this outward normal of its plug. */
+  readonly endNormal?: Point;
+  /** The boxes that the curve must not go through, from `curveSpace`. The type `straight` does not read it. */
+  readonly space?: CurveSpace;
+}
+/**
+ * This function gives the curve of a route: a polyline of a router, a lane of `laneRoutes` or a link of a zoom level.
+ * The curve starts at the first point and ends at the last point of the polyline.
+ * The output is a list of segments for any renderer. `toSvgPath` writes it as SVG path data, and `sampleCurve` gives points.
+ */
+export declare function curveOf(points: readonly Point[], options: CurveOptions): CurveSegment[];
 /** The nodes as obstacles, with a grid for fast tests. */
 export declare class Obstacles {
   #private;
@@ -268,11 +466,30 @@ export declare class Obstacles {
   constructor(nodes: readonly Node[], cell: number);
   /** This method tells if the segment `ab` stays out of each box, made larger by `pad`. The nodes in `skip` do not count. */
   clear(a: Point, b: Point, pad: number, skip?: ReadonlySet<Node>): boolean;
+  /**
+   * This method gives a node whose box, made larger by `pad`, the segment `ab` goes into, or `undefined` when the segment is clear.
+   * The nodes in `skip` do not count. The test stops at the first such node.
+   */
+  hit(a: Point, b: Point, pad: number, skip?: ReadonlySet<Node>): Node | undefined;
   /** This method tells if the polyline stays out of each box, made larger by `pad`. The nodes in `skip` do not count. */
   clearPath(p: readonly Point[], pad: number, skip?: ReadonlySet<Node>): boolean;
+  /** This method gives each node whose bucket the box touches to `visit`. A node can be outside the box. */
+  query(box: Box, visit: (n: Node) => void): void;
   /** This method tells if the point is inside a box, made larger by `pad`. The node `skip` does not count. */
   inside(p: Point, pad: number, skip?: Node): boolean;
 }
+/** A free point at an end of a search of `CornerGraph.pathAmong`, and the cost to reach it. */
+export interface Terminal {
+  readonly point: Point;
+  readonly cost: number;
+}
+/** A path of `CornerGraph.pathAmong`: its points, the index of its first point in `from`, the index of its last point in `to`, and its cost. */
+export interface Among {
+  readonly points: Point[];
+  readonly from: number;
+  readonly to: number;
+  readonly cost: number;
+}
 /** The options of the corner graph. */
 export interface CornerGraphOptions {
   /** The distance from a box to its corners. */
@@ -284,6 +501,11 @@ export interface CornerGraphOptions {
    * The lattice links groups of nodes across empty space. Without it, the nearest corners of a group are all in that group.
    */
   readonly lattice?: number;
+  /**
+   * With `cones`, each corner also links to the nearest corner that it can see in each of four cones around the axes.
+   * Then a path can go along a long corridor between rows or columns of boxes. The default is false.
+   */
+  readonly cones?: boolean;
 }
 /**
  * A sparse visibility graph. Its vertices are the corners of the boxes, made larger by `margin`.
@@ -309,6 +531,11 @@ export declare class CornerGraph {
    * It must give at least `floor` × `d`, so that the estimate of A* stays below the true cost.
    */
   path(from: Point, to: Point, cost?: (i: number, j: number, d: number) => number, floor?: number): Point[] | undefined;
+  /**
+   * This method gives the shortest path from a point of `from` to a point of `to`, or `undefined` when the graph has none.
+   * The cost of a path includes the costs of its two points. One search finds the path, so this method is faster than a call of `path` for each pair.
+   */
+  pathAmong(from: readonly Terminal[], to: readonly Terminal[]): Among | undefined;
   /** This method removes the vertices that a later vertex makes needless: from each vertex, it goes to the farthest vertex in view. */
   pull(p: readonly Point[], lookahead?: number): Point[];
 }
@@ -498,6 +725,8 @@ interface SectionsOptions extends WayOptions, SectionOptions {
  * Each way from hub to hub is found one time, so all the edges on it share its points.
  * The edges in one section of the lowest level go straight around the nodes.
  *
+ * An edge skips a hub that takes it away from its target. A way that still goes out and back gives way to the direct way.
+ *
  * The result gives one zoom level for each depth of the tree.
  * A link of a level goes from the boundary of one item to the boundary of the other, around the other items.
  */
@@ -543,6 +772,90 @@ export declare function splitPoint(start: Point, targets: readonly Point[], spli
 export declare function trunksRouter(options: TrunksOptions): Router;
 /** The routers that the benchmark races. */
 export declare const ROUTERS: readonly Router[];
+/** An item with a box: a node of a graph, an item of a level or a box of a host layout. */
+export interface Boxed {
+  readonly id: string;
+  readonly box: Box;
+}
+/** A link between two boxes. For a bundled link, `count` is the number of its edges. The default count is 1. */
+export interface RoomLink {
+  readonly source: string;
+  readonly target: string;
+  readonly count?: number;
+}
+/**
+ * A gap of a board: a boundary of the sweep over the left or top edges of the boxes.
+ * On the axis `x`, the gap is a vertical channel between two columns. On the axis `y`, it is a horizontal channel between two rows.
+ */
+export interface Gap {
+  readonly axis: "x" | "y";
+  /** The place of the gap in the order of the gaps on its axis, from 0. */
+  readonly index: number;
+  /** The coordinate where the boxes after the gap start, on the axis of the gap. */
+  readonly at: number;
+  /** The ids of the boxes that end at the near side of the gap. */
+  readonly before: readonly string[];
+  /** The ids of the boxes that start at the far side of the gap, at `at`. */
+  readonly after: readonly string[];
+  /** The current width of the gap: the distance from the nearest box edge before the gap to `at`. */
+  readonly width: number;
+  /** The number of lanes that the links need in the gap. */
+  readonly lanes: number;
+  /** The width that the gap needs: at least the current width, and at least `gutter + lanes × spacing`. */
+  readonly need: number;
+}
+/** The ways that `roomDemand` finds the lanes of each gap. */
+export type RoomMethod = "routes" | "lines";
+/** The options of `roomDemand` and `makeRoom`. */
+export interface RoomOptions {
+  /** The smallest width of each gap. The default is 8. */
+  readonly gutter?: number;
+  /** The width of one lane: the distance between two lines that run side by side. The default is 4. */
+  readonly spacing?: number;
+  /**
+   * The largest growth of the board on each axis, as a share of its size. The default is `Infinity`.
+   * When the lanes need more, each gap gets its gutter, and the lanes share the rest in proportion.
+   */
+  readonly maxGrowth?: number;
+  /**
+   * The way to find the lanes. The default is `routes`.
+   * With `routes`, the function routes the links one time on the board with each gap open to the gutter.
+   * The lanes of a gap are the most routes that run along the gap side by side.
+   * With `lines`, the lanes of a gap are the straight lines between the centers of the boxes that cross the gap.
+   */
+  readonly method?: RoomMethod;
+  /** The router of the method `routes`. Without it, the links go as the links of a zoom level (`levelLinks`), with the margin `gutter / 2`. */
+  readonly router?: Router;
+  /** With `count`, a link takes one lane for each of its edges. With `link`, the default, a link takes one lane. */
+  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 demand of a board and the board with its gaps open. */
+export interface Room<T extends Boxed> {
+  readonly gaps: readonly Gap[];
+  readonly items: T[];
+}
+/**
+ * This function gives the gaps of a board. A sweep over each axis sorts the left (or top) edges of the boxes.
+ * Each distinct edge after the first is a gap. The `lanes` of each gap are 0, and its `need` is its current width.
+ */
+export declare function boardGaps(items: readonly Boxed[], snap?: number): Gap[];
+/**
+ * This function moves the boxes apart, so that each gap gets the width `need`. The boxes keep their size, their order and their alignment.
+ * A box moves by the sum of the growth of each gap at or before its left (or top) edge. Thus a grid stays a grid.
+ * The function moves no box nearer to another box, so it makes no overlap.
+ */
+export declare function openGaps<T extends Boxed>(items: readonly T[], gaps: readonly Gap[], snap?: number): T[];
+/**
+ * This function gives the room that the links need in each gap of the board.
+ * 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 declare function roomDemand(items: readonly Boxed[], links: readonly RoomLink[], options?: RoomOptions): Gap[];
+/** This function gives the demand of the board and the board with each gap open to its need. */
+export declare function makeRoom<T extends Boxed>(items: readonly T[], links: readonly RoomLink[], options?: RoomOptions): Room<T>;
+/** This function gives the links between the nodes of a graph, with the count of the edges of each pair. A loop does not count. */
+export declare function roomLinks(graph: Graph): RoomLink[];
 /** A broken hard rule. A correct router has none. */
 export interface Violation {
   readonly rule: "complete" | "ends-at-plugs" | "fixed-plugs" | "no-pass-through" | "counts-sum" | "link-ends" | "bundle-trunk" | "run-shared";
@@ -605,6 +918,83 @@ export interface Stability {
 }
 /** This function measures how much the routes changed between two results. */
 export declare function measureStability(before: Result, after: Result): Stability;
+/**
+ * The faults of a set of links: the routes of the edges, or the links of one zoom level.
+ * Each value counts links, except `worstDetour`. Lower is better for each value.
+ */
+export interface LinkFaults {
+  /** The number of links that the measure examined. */
+  readonly links: number;
+  /**
+   * The number of links that go through the inside of a box that is not one of their two ends.
+   * A segment goes through a box when a part of it longer than `TOLERANCE` is inside the box made smaller by `TOLERANCE`.
+   */
+  readonly through: number;
+  /**
+   * The number of links that go out and back. The distance from a point of the link to its last point grows after the nearest approach.
+   * A link goes out and back when this growth is more than `BACKTRACK_SHARE` of the distance between its ends, and more than `BACKTRACK_MIN` units.
+   */
+  readonly backtrack: number;
+  /** The largest ratio of the length of a link to the distance between its ends. Links with ends nearer than 1 unit do not count. */
+  readonly worstDetour: number;
+  /**
+   * The number of links with a point outside the bounding box of all the boxes, made larger by `slack`.
+   * Both ends of a link are always in that bounding box, so such a link goes around the outer edge of the board.
+   */
+  readonly outside: number;
+}
+/** The faults of the links of one zoom level. */
+export interface LevelFaults extends LinkFaults {
+  readonly depth: number;
+  /** The number of items of the level. */
+  readonly items: number;
+  /** The number of items that hold more than one node. */
+  readonly groups: number;
+  /** The number of pairs of items whose boxes overlap by more than `TOLERANCE` on each axis. */
+  readonly overlaps: number;
+}
+/** The options of the link measures. */
+export interface LinkFaultOptions {
+  /** A link that goes farther than this distance outside the bounding box of all the boxes counts in `outside`. The default is 24. */
+  readonly slack?: number;
+}
+/** A link goes out and back when its distance to its target grows by more than this share of the distance between its ends. */
+export declare const BACKTRACK_SHARE = .25;
+/** A link goes out and back only when its distance to its target grows by more than this number of units. */
+export declare const BACKTRACK_MIN = 40;
+/** The default `slack` of `LinkFaultOptions`. */
+export declare const OUTSIDE_SLACK = 24;
+/** A link from one box to another box, as `measureLinks` sees it. */
+export interface MeasuredLink {
+  readonly source: string;
+  readonly target: string;
+  readonly points: readonly Point[];
+}
+/**
+ * This function gives the largest growth of the distance to the last point of a polyline.
+ * The growth at a vertex is its distance to the last point, less the nearest approach of the polyline before that vertex.
+ */
+export declare function backtrackOf(p: readonly Point[]): number;
+/** This function tells if the polyline `p` goes out and back: `backtrackOf(p)` is more than `BACKTRACK_MIN` and more than `BACKTRACK_SHARE` of the span. */
+export declare function goesOutAndBack(p: readonly Point[]): boolean;
+/**
+ * This function measures the faults of links between boxes. The map `boxes` gives the box of each end.
+ * The bounding box of `outside` is the bounding box of all the boxes of the map.
+ */
+export declare function measureLinks(boxes: ReadonlyMap<string, Box>, links: readonly MeasuredLink[], options?: LinkFaultOptions): LinkFaults;
+/** This function measures the faults of the routes of a result. The ends of a route are the nodes of its edge. */
+export declare function measureRouteFaults(graph: Graph, result: Result, options?: LinkFaultOptions): LinkFaults;
+/** This function counts the pairs of boxes that overlap by more than `TOLERANCE` on each axis. */
+export declare function countOverlaps(boxes: readonly Box[]): number;
+/** This function measures the faults of the links of one zoom level. The items of the level are the boxes. */
+export declare function measureLevel(level: Level, options?: LinkFaultOptions): LevelFaults;
+/**
+ * This function measures the faults of each zoom level of a result that has groups: the levels of the far view.
+ * A level of single nodes only is the near view. Its links are routes, and `measureRouteFaults` measures them.
+ */
+export declare function measureLevelFaults(result: Result, options?: LinkFaultOptions): LevelFaults[];
+/** This function adds the faults of several levels: it sums the counts and keeps the largest `worstDetour`. */
+export declare function sumFaults(list: readonly LinkFaults[]): LinkFaults;
 /** One row of the benchmark: one router on one fixture. */
 export interface BenchRow {
   readonly router: string;
@@ -619,6 +1009,10 @@ export interface BenchRow {
   /** The first violations, for the report. */
   readonly sample: readonly Violation[];
   readonly quality: Quality;
+  /** The faults of the routes of the edges (`measureRouteFaults`). */
+  readonly faults: LinkFaults;
+  /** The faults of each zoom level with groups (`measureLevelFaults`). The list is empty for a router without levels. */
+  readonly levelFaults: readonly LevelFaults[];
 }
 /** The options of a benchmark run. */
 export interface BenchOptions {
@@ -636,5 +1030,78 @@ export declare function sameData(a: unknown, b: unknown): boolean;
 export declare function benchOne(router: Router, fixture: string, graph: Graph, repeat?: number): BenchRow;
 /** This function writes the rows as a Markdown table. */
 export declare function formatTable(rows: readonly BenchRow[]): string;
-export type { CornersOptions, SectionsOptions, SharedOptions, TrunksOptions };
+/**
+ * This function writes the faults of the rows as a Markdown table: the routes first, then the sum of the levels with groups.
+ * A router without such levels gets a dash in the columns of the levels.
+ */
+export declare function formatFaults(rows: readonly BenchRow[]): string;
+/** One row of the benchmark of the curves: one curve type on the routes of one router on one fixture. */
+export interface CurveBenchRow {
+  readonly router: string;
+  readonly fixture: string;
+  readonly type: CurveType;
+  /** The number of routes. */
+  readonly links: number;
+  /** The number of polylines that go through a box that is not one of their ends (`measureLinks`). */
+  readonly through: number;
+  /** The number of curves without a free space that go through such a box. */
+  readonly free: number;
+  /** The number of curves with the free space of the nodes (`curveSpace`) that go through such a box. */
+  readonly clamped: number;
+  /** The ratio of the length of all curves with the free space to the length of all polylines. */
+  readonly length: number;
+  /** The time to make all curves with the free space, in milliseconds. */
+  readonly ms: number;
+}
+/** The options of `benchCurves`. */
+export interface CurveBenchOptions {
+  /** The radius of the types `rounded` and `arc`. The default is 12. */
+  readonly radius?: number;
+  /** The tolerance of the samples of the curves. The default is 0.25. */
+  readonly tolerance?: number;
+}
+/**
+ * This function routes a graph with a router and makes each curve type of each route.
+ * It counts the curves that go through a box, with and without the free space, and it compares their length to the polylines.
+ * The type `spline` leaves each plug along the normal of the nearest side of its node.
+ */
+export declare function benchCurves(router: Router, fixture: string, graph: Graph, options?: CurveBenchOptions): CurveBenchRow[];
+/** This function writes the rows of `benchCurves` as a Markdown table. */
+export declare function formatCurves(rows: readonly CurveBenchRow[]): string;
+/** One row of the benchmark of the room: one state of a board, packed or open, and the measures of its links. */
+export interface RoomBenchRow {
+  readonly fixture: string;
+  /** The state of the board: `packed`, `gutter` (each gap open to the gutter only), or a method of `roomDemand`. */
+  readonly board: string;
+  /** The area of the bounding box of the boxes, as a share of the area of the packed board. */
+  readonly area: number;
+  /** The faults of the links of the far view (`levelLinks` with each box as one item). */
+  readonly faults: LinkFaults;
+  /** The crossings of the links of the far view (`measureQuality`). */
+  readonly crossings: number;
+  /** The ink of the links of the far view. */
+  readonly ink: number;
+  /** The mean detour of the links of the far view. */
+  readonly detour: number;
+  /**
+   * The number of lane routes of the router `sections` that go through a box. Each shared segment opens to one lane for each edge,
+   * at the spacing of the options (`laneRoutes`).
+   */
+  readonly laneThrough: number;
+  /** The time of `makeRoom`, in milliseconds. It is 0 for the packed board. */
+  readonly ms: 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`.
+ */
+export declare function measureBoard(graph: Graph, spacing: number): Omit<RoomBenchRow, "fixture" | "board" | "area" | "ms">;
+/**
+ * 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`.
+ */
+export declare function benchRoom(fixture: string, graph: Graph, options?: RoomOptions): RoomBenchRow[];
+/** This function writes the rows of `benchRoom` as a Markdown table. */
+export declare function formatRoom(rows: readonly RoomBenchRow[]): string;
+export type { ArcOptions, CornersOptions, CurveSpace, RoundedOptions, SectionsOptions, SharedOptions, SplineOptions, TrunksOptions };
 //# sourceMappingURL=index.d.ts.map