@mark1russell7/highways 0.9.2 → 0.9.4

package/README.md

@@ -49,6 +49,40 @@ const node = { id: "a", box: { x: 0, y: 0, w: 80, h: 40 }, ports: [{ id: "out",
 // The plug "out" is at (80, 10). With h = 120, it is at (80, 30).
 ```
 
+### Plug rules and fixed ports
+
+A plug rule is a strategy of the step `plugs`. It places the free plugs of each edge. A fixed plug stays at its point.
+
+| Rule | The place of each free plug |
+|---|---|
+| `facing` | The plug faces the other end of its edge. It is the default of the router `corners`. |
+| `side` | The search of the route starts from the whole free side. The plug goes where the way leaves the side (WILD-001). |
+| `justify` | The plugs of `facing`, then the plugs of each side keep their order and the gap `plugGap` (WILD-002). |
+| `spread` | The plugs of each wall share the room of the wall, with the gap `plugGap`, in the order of their far ends. |
+
+- `side` gives the plugs of `corners` with `plugs: "side"`. `justify` gives the plugs of `corners` with the same `plugGap`.
+- `spread` keeps the room of a wall free of the corner insets (`inset`) and of the fixed plugs on the wall.
+  - When the room is too small for the gap, the gap shrinks evenly. No plug drops.
+  - The order on the wall keeps the order of the far ends, so the straight lines of two plugs do not cross at the wall.
+  - The ends of one port share one plug. The option `rounds` sorts each wall again by the new places of the far ends.
+- The option `plug` of `corners` takes a plug rule. The other routers place the plugs as `facing` does.
+
+`fixPorts(graph, rule, options?)` runs a plug rule, and gives each free port a fixed `at` and a `side` from the plugs of the rule. Then each router keeps those plugs.
+
+- The rule is a plug strategy, or the name of one in `STRATEGIES` (or in the option `registry`). `plugOptions` gives its options.
+- A fixed port keeps its values, and a port of no edge stays free. A port of several ends takes the plug of its first end.
+- An end without a port stays free. With `newPorts: true`, it gets a new fixed port with the id `<edge id>:source` or `<edge id>:target`.
+- The output is a new graph. The function does not change the input.
+- The routes of `corners` on the output are the routes of `corners` with the option `plug` on the input.
+
+```ts
+import { fixPorts, sectionsRouter } from "@mark1russell7/highways";
+
+// The rows of each card get plugs on the walls with at least 8 px between two plugs. Then `sections` routes between them.
+const fixed = fixPorts(graph, "spread", { plugOptions: { plugGap: 8 } });
+const result = sectionsRouter({ name: "sections" }).route(fixed);
+```
+
 ### Frames
 
 A node can name a frame node in `parent`. A frame is a node that holds other nodes, for example a card that holds rows.
@@ -65,6 +99,16 @@ A node can name a frame node in `parent`. A frame is a node that holds other nod
   - `throw` (the default) throws a `RangeError`.
   - `skip` gives no route to the edges of that node.
   - `clamp` cuts the box to the bounds of the frame.
+- The option `inner` sets the mode of the inner routes:
+  - `corners` (the default) finds each route in the corner graph, as above.
+  - `gutter` gives orthogonal routes in the gaps between the nodes and in the strips at the walls.
+- In the mode `gutter`, a route uses the whole box of the frame. The mode does not use `frameInset`.
+- A route of the mode `gutter` goes into its row at the port, or at the left or right end of the row.
+- The plug stub stays perpendicular to the wall. A plug that is level with its row gives only the stub.
+- The option `bendCost` is the cost of one bend in units of length. A larger cost gives fewer bends. The default is 16.
+- Each gap that two or more routes share gets one lane for each route. The lanes are evenly spaced, in an order with few crossings.
+- The space between two lanes is the margin of the router. In a narrow gap, the space becomes smaller.
+- An edge with no way through the free room gets no route, as with `skip`. Rows that touch each other with gap 0 can block a way.
 
 ```ts
 const nodes = [
@@ -73,6 +117,7 @@ const nodes = [
 ];
 const edges = [{ id: "inner", source: { node: "row" }, target: { node: "card", port: "in" } }];
 const inner = cornersRouter({ name: "corners" }).route({ nodes, edges }).routes; // inner[0].frame is "card"
+const gutters = cornersRouter({ name: "corners", inner: "gutter", bendCost: 24 }).route({ nodes, edges }).routes; // only H and V legs
 ```
 
 ## Curve types
@@ -396,7 +441,7 @@ The steps of the pipeline that vary have strategies. Each step has one interface
 | Step | Input | Output | Built-in strategies |
 |---|---|---|---|
 | `group` | `Graph` | `Section`: the tree of groups of the router `sections` | `quadtree`, `keys`, `kd`, `cut` |
-| `plugs` | `PlugInput`: the graph, and optionally the ways of the router | `PlugPair[]`: the two plugs of each edge | `facing` |
+| `plugs` | `PlugInput`: the graph, and optionally the ways of the router | `PlugPair[]`: the two plugs of each edge | `facing`, `side`, `justify`, `spread` |
 | `router` | `Graph` | `Result` | `straight`, `plugs`, `corners`, `corners-smooth`, `trunks`, `shared`, `shared-all`, `sections`, `sections-tree` |
 | `highway` | `HighwayInput`: the graph, optionally the first routes of a router, and optionally the plan before an edit | `HighwayPlan`: the highways as data | `keys`, `shared-ways`, `corridors`, `meet`, `weiszfeld`, `stubs`, `zipper`, `level-links`, `quickbundles`, `road-classes`, `flow-field`, `wspd`, `od-cells`, `select`, `mingle`, `spiral`, `flow-clusters`, `traclus`, `diffusion`, `nested`, `lanes`, `growth`, `edge-paths`, `soft-keys`, `hough`, `ridges`, `hdbscan`, `hub-arcs`, `divided`, `hierarchy`, `fdeb`, `mesh`, `kdeeb`, `cubu`, `mlseb`, `sbeb`, `areas`, `confluent`, `power`, `crossbars`, `frechet`, `spectral`, `resistance`, `link-communities`, `territories`, `consensus`, `p-hub`, `scale-space`, `corridors+breakeven`, `corridors+stretch`, `corridors+ambiguity`, `corridors+hysteresis`, `corridors+ids` |
 | `levels` | `LevelInput`: the graph, the tree of groups and the routes | `Level[]`: the zoom levels of the router `sections` | `depths` |
@@ -429,6 +474,13 @@ Each of these steps has one default strategy. The default gives the output of th
   The option `level` of `sections` takes a level strategy, and `levelOptions` gives its options. The strategy also gets the level options of the router.
 - `pipeline` (the step `whole`) runs a room strategy, then a router or a highway plan, with the rules that the router reads (`runPipeline`).
   Without options, it routes with `corners`. The demo of the site runs it. It does not draw the curves.
+- `venation` (the step `levels`, NAT-016) keeps the levels of `depths`. Its level links take their ways on a closed backbone of the items.
+  The backbone is the relative neighbourhood graph (`rng`) or the Gabriel graph. A backbone link that a level link uses costs less for the next level links.
+  The routes do not change, so only the level links (Z3) change.
+- `board-portfolio` (the step `whole`, WILD-045) runs a short list of settings on the board and keeps the best one.
+  The list `BOARD_PORTFOLIO_SETTINGS` holds 12 routers and highway plans. The option `settings` sets how many of them run.
+  A setting with a break of a hard rule does not count. The score adds the rank shares of the crossings, the median detour and the ink saved.
+  It reads no screen record and has no fit. With `budget: 0`, the default, the pick does not depend on the speed of the machine.
 - `strategyKey(router, step)` gives the option of a router that takes a strategy of the step. `pipeline` uses it for the steps `group`, `plugs` and `levels`.
 - `stepRouterStrategy(strategy)` runs a strategy of a step of `RoutedStep` as a router. `stepRouters(registry, step)` gives one router for each strategy of the step.
 
@@ -507,6 +559,8 @@ The step `highway` decides which edges share a way. It gives a plan, not routes.
 | `streets` | The orthogonal streets of HWY-058. A greedy set cover picks the free horizontal and vertical lines that carry the most edge length. |
 | `search` | The local search of HWY-059. It adds, drops and changes the highways of a start plan, and it keeps the plan with the best score. |
 | `interchanges` | The interchanges of HWY-060. An edge can change from one highway to another at an interchange, where two spines come near. |
+| `knee` | The knee tree of NAT-018. A sweep of the balancing factor gives trees from the least ink to the most direct paths, and the knee of that front is the pick. |
+| `bronchial` | The bronchial tree of NAT-019. The tree grows toward the center of its targets, then splits them in two sectors, again and again. |
 
 The strategy `corridors` joins two ways when they share a long length. The length is `BREAK_EVEN` times the lane width or more, and the share `rho` of the shorter way or more.
 The strategies `meet`, `weiszfeld`, `stubs`, `zipper`, `level-links`, `lanes`, `divided` and `crossbars` change the plan of the option `from`: `shared-ways` (the default), `corridors` or `none`.
@@ -582,6 +636,17 @@ The router `attraction` is opt-in. It is not in `STRATEGIES`, so the default out
 - A capacity term raises the cost of a link when its users are more than its width holds.
 - With 1 pass, `attraction: 0` and `capacityWeight: 0`, the routes are the routes of `shared`.
 
+### The routers `tight` and `annealing`
+
+The routers `tight` and `annealing` are opt-in. They are not in `STRATEGIES`, so the default outputs do not change. Both put a hook on the router `shared`.
+
+- `tightRouter(options)` gives the order of WILD-023: the edges whose second way costs much more than their first way go first.
+  Its options are `penalty` (2 to 10), `first` (`tight` or `loose`) and `ties` (`id` or `length`). `tightStrategy` is its router strategy.
+- `annealingRouter(options)` gives the simulated annealing of RULE-021, with the candidate routes of WILD-028. Each edge picks one of a few ways.
+  The energy adds the ink, the path length and the crossings. The chance to keep a worse state is rational, so it uses no `Math.exp`.
+  Its options are `candidates` (3 to 8), `crossing` (0 to 20), `temperature` (0.1 to 10), `cooling` (0.9 to 0.99), `budget` (20 to 200) and `seed`.
+  The same seed gives the same routes. `annealingStrategy` is its router strategy.
+
 ### The portfolio router
 
 The router `portfolio` is opt-in. It is not in `STRATEGIES`, so the default outputs do not change. [`PORTFOLIO.md`](../../docs/research/PORTFOLIO.md#the-portfolio-router-portfolio-api) gives its tables.
@@ -740,6 +805,24 @@ const { rows, front } = compareStep("curve", graph, { options: { arc: { radius:
 const lanes = compareStep("curve", graph, { curveRouter: "shared", lanes: { width: 5, maxWidth: 30 }, options: { highway: { jog: "quintic" } } });
 ```
 
+## The corpus families
+
+`HIGHWAYS_FAMILIES` lists the 15 generators of the boards of the screen and the site. Each one is a family of `@mark1russell7/layout-contract`, with its dimensions as data. `highwaysRegistry()` makes a registry of them.
+
+- The first 6 families make the boards of `screen-v1` and `screen-v2`.
+- `COVERAGE_FAMILIES` adds 9 families: `frame-rows`, `pipeline`, `fan-out`, `two-hubs`, `uneven-sizes`, `thin-bars`, `sparse-long`, `local-mesh` and `bipartite`.
+- The screen set `screen-v3` has the 15 families, each with 10 seeds.
+- `signTestPower(n)` gives the least count of families out of `n` that passes a two-sided sign test at the level 0.05. For 15 families, the count is 12.
+
+```ts
+import { highwaysRegistry, signTestPower } from "@mark1russell7/highways";
+
+const { graph } = highwaysRegistry().generate("fan-out", 4, { leaves: 40 });
+console.log(graph.nodes.length, signTestPower(15)); // 41 12
+```
+
+[The corpus families](https://github.com/mark1russell7/highways/blob/main/docs/LAYOUT-RECORDS.md#the-corpus-families-corpus-gen) give the dimensions of each family.
+
 ## The same routes on each platform
 
 A transcendental Math function, for example `Math.atan2` or `Math.hypot`, can give a different last bit on another platform or node version. A decision of a router must not depend on that bit.