@mark1russell7/highways 0.1.4 → 0.2.0

package/README.md

@@ -80,7 +80,10 @@ A host layout can pack the boxes of a far view in a grid, with no gap between th
 - 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.
+- With `passes: 2`, `roomDemand` finds the lanes again on the open board and adds the growth that they need. `maxGrowth` limits the sum of the passes.
 - `roomLinks(graph)` gives the links of a graph, with the count of the edges of each pair.
+- `gapLanes(items, links, options)` gives each link of a far view its own lane in each gap. The lanes are `spacing` apart, around the middle of the gap.
+- The option `order` of `gapLanes` sets the lane order in a gap: `links` (the order of the list), `ends` (by the sides of the turns) or `crossings` (the default).
 
 The host layout still packs the boxes. These functions do not place a box. They only open the gaps between the boxes.
 
@@ -104,6 +107,121 @@ The benchmark measures the board `packedGridBoard`: 96 touching boxes and 132 li
 
 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.
 
+`sweepRoom` changes one knob at a time on the same board. `growthSettings`, `laneSettings` and `passSettings` give the settings of the benchmark.
+
+| Knob | Setting | Area | Crossings | Mean detour | Worst detour | Lane routes through a box |
+|---|---|---:|---:|---:|---:|---:|
+| `maxGrowth` | 0.12 | 1.25 | 288 | 1.34 | 2.33 | 6 |
+| `maxGrowth` | 0.25 | 1.46 | 284 | 1.32 | 2.14 | 2 |
+| `maxGrowth` | 0.30 and more | 1.50 | 276 | 1.32 | 2.09 | 2 |
+| Lane order | `links` | 1.50 | 585 | 1.34 | 2.30 | 2 |
+| Lane order | `ends` | 1.50 | 551 | 1.33 | 2.19 | 2 |
+| Lane order | `crossings` | 1.50 | 467 | 1.33 | 2.23 | 2 |
+| Passes | 2 | 1.57 | 281 | 1.32 | 2.03 | 2 |
+| Gutter | 12 | 1.58 | 282 | 1.32 | 2.03 | 2 |
+
+The links of a gap without lanes share one line. Thus the crossings on that line do not count. With a lane for each link, the crossings show, and the order `crossings` removes 20% of them. The spacing changes the crossings less than 5%. The mean detour stays near 1.32 for each knob, because a link with legs parallel to the axes goes around the boxes.
+
+## Options of the zoom levels
+
+The router `sections` makes its hubs and its zoom levels from a tree of groups. Each rule and each limit of that tree is an option. The defaults give the output of version 0.1.5.
+
+| Option | Default | Where | What it sets |
+|---|---|---|---|
+| `group` | the quadtree | `sectionsRouter` | The grouping rule: a strategy of the step `group`. `groupOptions` gives its options. |
+| `levels` | each depth | `sectionsRouter` | The depths of the tree that get a level with groups. The level of single nodes always comes last. |
+| `stretch` | 2 | `sectionsRouter` | The hub limit. A way through the hubs is at most this many times the straight line. `Infinity` keeps each such way. |
+| `stretchPad` | 4 | `sectionsRouter` | A way through the hubs can be this many margins longer than the hub limit. |
+| `hubSlack` | 80 | `sectionsRouter` | A way skips a hub that is this many units farther from the target than the way was before. |
+| `hubs` | `Infinity` | `sectionsRouter` | The number of hubs on each side of the lowest common section that a way passes. |
+| `cap` | 8 | `buildSections` | The section limit. A section with more nodes splits in four. |
+| `maxDepth` | 16 | `buildSections` | The depth limit of the tree. |
+| `collapse` | 32 | `buildSections` | A cell shrinks to one quarter at most this many times without a split. |
+| `tightMargin` | 1 | `levelLinks` | The margin of the second corner graph of the level links. |
+| `plugInset` | 6 | `levelLinks` | A plug of a level link stays this far from the corners of its side. |
+| `routesAt`, `itemAt` | 22, 120 | `pickLevel` | The far-view thresholds, in pixels on the screen. `PICK` holds them. |
+
+`SECTIONS_DEFAULTS`, `SECTION_DEFAULTS`, `LEVEL_LINK_DEFAULTS` and `PICK` give the default numbers. `itemSizes(levels)` gives the sizes that `pickLevel(sizes, scale, options)` reads.
+
+The built-in grouping rules are in `groupStrategies`. The rule `quadtree` splits the plane, as `buildSections` does. The rule `keys` makes one group for each key of the nodes. Its default key is the string `data.group` of a node, and a node without a key is a group alone. With the option `split`, a large group splits into a quadtree.
+
+A consumer rule groups the nodes by its own field. Then the far view shows one item for each group:
+
+```ts
+import { defineStrategy, keyedSections, sectionsRouter } from "@mark1russell7/highways";
+
+const byTeam = defineStrategy({
+  step: "group",
+  name: "team",
+  describe: "One group for each team.",
+  defaults: {},
+  run: (graph) => keyedSections(graph.nodes, { key: (node) => String(node.data?.["team"]) }),
+});
+const result = sectionsRouter({ name: "teams", group: byTeam }).route(graph);
+// result.levels[1] has one item for each team. The id of an item is "s:" and the team.
+```
+
+The router examines the tree of a consumer rule with `checkSections`. Each node must be in exactly one leaf. The children of a section split its nodes, and a child is one level deeper than its parent.
+
+The benchmark sweeps the hub limit, `hubSlack`, `cap` and the grouping rules on the case boards. Each table starts with the defaults. On `case-hub-chain`:
+
+| `stretch` | Worst detour | Routes through hubs | Shared runs | Out and back |
+|---|---:|---:|---:|---:|
+| 1.25 | 1.19 | 14 | 4 | 0 |
+| 1.5 | 1.39 | 20 | 8 | 0 |
+| 2 (default) | 1.78 | 24 | 10 | 0 |
+| 3 | 2.05 | 25 | 11 | 0 |
+
+A smaller hub limit gives shorter routes and fewer shared runs. No route goes through a box or out and back at any value. On `case-many-groups`, the rule `keys` has one key for each group of cards. It gives 32 items at the far view, and no level link goes out and back.
+
+## Strategies
+
+The steps of the pipeline that vary have strategies. Each step has one interface, so a consumer chooses a strategy by its name or adds its own.
+
+| Step | Input | Output | Built-in strategies |
+|---|---|---|---|
+| `group` | `Graph` | `Section`: the tree of groups of the router `sections` | `quadtree`, `keys` |
+| `router` | `Graph` | `Result` | `straight`, `plugs`, `corners`, `corners-smooth`, `trunks`, `shared`, `shared-all`, `sections`, `sections-tree` |
+| `curve` | `CurveInput`: the points, the normals of the plugs and the free space | `CurveSegment[]` | `straight`, `rounded`, `spline`, `arc` |
+| `room` | `RoomInput`: the boxes and the links of a board | `Gap[]` | `routes`, `lines` |
+
+A strategy has a `step`, a `name`, a `describe` text, its `defaults` and the method `run(input, options?)`. The type of the options comes from `defaults`. Each option that a call does not give gets its default value.
+
+- `defineStrategy({ step, name, describe, defaults, run, maxNodes? })` makes a strategy. The function `run` gets each option.
+- `createRegistry(strategies)` makes a registry. Two strategies with one step and one name are an error.
+- `register(registry, ...strategies)` gives a new registry. It does not change the registry before it.
+- `listStrategies(registry, step)` gives the strategies of a step, in order. `findStrategy` and `getStrategy` give one strategy by its name.
+- `asRouter(strategy, options?)` gives a `Router`, and `routersOf(registry)` gives the routers of a registry.
+- `STRATEGIES` is the registry of `BUILT_IN_STRATEGIES`. The records `groupStrategies`, `routerStrategies`, `curveStrategies` and `roomStrategies` give each built-in strategy with its typed options.
+
+A registry is data. No import changes it. The benchmark and the site take their lists from `STRATEGIES`, so a new built-in strategy gets its rows and its button with no other edit. A consumer makes its own registry:
+
+```ts
+import { BUILT_IN_STRATEGIES, center, createRegistry, defineStrategy, FIXTURES, routersOf, runBenchmark } from "@mark1russell7/highways";
+
+const elbow = defineStrategy({
+  step: "router",
+  name: "elbow",
+  describe: "Each edge goes along one axis, then along the other, from center to center.",
+  defaults: { turn: "x" as "x" | "y" },
+  run(graph, o) {
+    const box = new Map(graph.nodes.map((n) => [n.id, n.box]));
+    const routes = graph.edges.map((e) => {
+      const a = center(box.get(e.source.node)!);
+      const b = center(box.get(e.target.node)!);
+      return { edge: e.id, points: [a, o.turn === "x" ? { x: b.x, y: a.y } : { x: a.x, y: b.y }, b] };
+    });
+    return { routes };
+  },
+});
+const registry = createRegistry([...BUILT_IN_STRATEGIES, elbow]);
+const rows = runBenchmark(routersOf(registry), FIXTURES.slice(0, 1)); // The rows include the router `elbow`.
+```
+
+The built-in strategies give the same output as their functions. `curveStrategies.rounded.run({ points, space }, { radius: 8 })` gives the segments of `curveOf(points, { type: "rounded", space, radius: 8 })`. `benchCurveStrategies` and the fourth argument of `benchRoom` take a list of strategies.
+
+The plugs have one strategy, so they have no step yet. The step `group` gives the grouping rule of the zoom levels.
+
 ## License
 
 MIT