@mark1russell7/highways 0.9.0 → 0.9.2

package/README.md

@@ -26,6 +26,55 @@ const result = cornersRouter({ name: "corners" }).route(graph);
 // Each route is a polyline: result.routes[0].points
 ```
 
+### Plugs
+
+A node can have `ports`, and an end of an edge can name one of them in `port`. Each plug has one of these forms:
+
+| Form | The place of the plug |
+|---|---|
+| `{ id }` | The router picks the side and the point. |
+| `{ id, side }` | The router picks the point on that side. |
+| `{ id, at }` | The plug is fixed at `at`, relative to the top-left corner of the box. |
+| `{ id, side, along }` | The plug is fixed at the side start plus `along` times the side length. |
+
+- `along` goes from 0 to 1. The start of `north` and `south` is the left end. The start of `east` and `west` is the top end.
+- When the box gets taller or wider, a plug with `along` keeps its fraction of the side.
+- `resolvePorts(graph)` gives each plug with `along` a fixed `at`. Each router calls it at the start of `route`.
+- The arithmetic is the arithmetic of `portPoint` of `@mark1russell7/layout-contract`. `portOffset` calls it.
+- `resolvePorts` throws a `RangeError` for a bad `along`. A bad value is not finite or is outside 0 to 1. A plug with `along` also needs a `side` and has no `at`.
+- In an input file, such a plug has `side` and `along`, with no `x` and no `y`.
+
+```ts
+const node = { id: "a", box: { x: 0, y: 0, w: 80, h: 40 }, ports: [{ id: "out", side: "east", along: 0.25 }] };
+// The plug "out" is at (80, 10). With h = 120, it is at (80, 30).
+```
+
+### 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.
+
+- An inner edge goes from a plug of a frame to a node in the frame. `splitFrames(graph)` finds the inner edges.
+- The router `corners` routes each inner edge inside its frame. The route stays in the box of the frame, smaller by the option `frameInset`.
+- The route goes around the other nodes of the frame. It leaves the plug of the wall into the frame, along the normal of the wall.
+- Each inner route has the id of its frame in `Route.frame`. The inner routes come after the outer routes.
+- Each other router gives no route for an inner edge. To route both, use your outer router, then `corners` for the inner routes.
+- An outer edge to a plug of the frame routes as before. The outer route and the inner route meet at the plug.
+- The default of `frameInset` is the margin of the router.
+- A parent that names no node, or a cycle of parents, makes each router throw a `RangeError`.
+- The option `outside` sets the rule for a node box outside the box of its frame:
+  - `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.
+
+```ts
+const nodes = [
+  { id: "card", box: { x: 0, y: 0, w: 240, h: 200 }, ports: [{ id: "in", side: "west", along: 0.25 }] },
+  { id: "row", parent: "card", box: { x: 20, y: 120, w: 200, h: 24 } },
+];
+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"
+```
+
 ## 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.
@@ -453,6 +502,11 @@ The step `highway` decides which edges share a way. It gives a plan, not routes.
 | `consensus` | The consensus of HWY-035. The finders vote on the pairs of edges, and the pairs that most finders agree on stay. |
 | `p-hub` | The p-hub median of HWY-041. The p-median of the plugs gives the hubs, and the links between two hubs become highways. |
 | `scale-space` | The scale space of HWY-053. Only the clusters that live over a long range of scales get highways. |
+| `steiner` | The Steiner trees of HWY-036. Each group of edges gets one rectilinear tree around the boxes, and the shared parts of the tree become highways. |
+| `gaps` | The gap highways of HWY-057. A free line in a gap between boxes holds a highway when enough edges can ride it. |
+| `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. |
 
 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`.
@@ -518,6 +572,16 @@ const shared = stableOrderStrategy(routerStrategies.shared);
 const result = repairStrategy(shared).run(graph); // The router `shared+stable+repair`.
 ```
 
+### The router `attraction`
+
+The router `attraction` is opt-in. It is not in `STRATEGIES`, so the default outputs do not change.
+
+- `attractionRouter(options)` gives the negotiated attraction of HWY-044, and `attractionStrategy` is its router strategy.
+- Each pass after the first routes each edge again. A link that many edges used in the passes before gets a lower cost.
+- The options are `passes` (1 to 10), `attraction` (0 to 1), `capacityWeight` (0 to 10) and `laneWidth` (1 to 12).
+- 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 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.
@@ -621,10 +685,14 @@ The [note on the measures](https://github.com/mark1russell7/highways/blob/main/d
 | R11 | `plugSpacing`: the gaps between the plugs of each side |
 | B1, B4 | `inkSaved`, `ambiguity` |
 | C1, C2, C3 | `g1Defect`, `g2Defect`, `bendingEnergy` |
+| C4, C8 | `curvatureVariation`, `curveDeviation` |
+| Z5 | `levelRatio`: the largest ratio of the item counts of two levels, and the spread of the ratios |
 | Z6, Z7, Z8 | `nestingFaults`, `positionStability`, `orderStability` |
 | Z10 | `changeGraph` makes a seeded small change, and `routeStability` compares the routes |
 | G1, G2, G8, G9 | `modularity`, `cutShare`, `treeCost`, `groupStability` |
-| M2 | `roomOrderFaults` |
+| G4, G5, G7 | `groupFill`, `itemOverlaps`, `silhouette` |
+| M2, M3, M5 | `roomOrderFaults`, `boxDisplacement`, `distanceDistortion` |
+| H3 | `routeSymmetry`: the share of the routes that a mirror or a half turn of the board keeps |
 
 A quadratic measure examines a seeded sample above its limit, so the values of a large board are estimates.