@mark1russell7/highways 0.9.0 → 0.9.2

package/package.json

@@ -9,7 +9,7 @@
     "directory": "packages/core"
   },
   "homepage": "https://mark1russell7.github.io/highways/",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "type": "module",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mark1russell7/layout-contract": "^0.2.14"
+    "@mark1russell7/layout-contract": "^0.2.15"
   },
   "devDependencies": {
     "@mark1russell7/cue": "github:mark1russell7/cue",

package/src/bench/compare.ts

@@ -235,7 +235,19 @@ export function stepRouterStrategy(strategy: Strategy<RoutedStep>): Strategy<"ro
     });
   if (strategy.step === "plugs") return own(strategy.maxNodes ?? 10_000, (graph, o) => cornersRouter({ name, plug: strategy as Strategy<"plugs">, plugOptions: o }).route(graph));
   if (strategy.step === "levels") return own(strategy.maxNodes ?? 100_000, (graph, o) => sectionsRouter({ name, level: strategy as Strategy<"levels">, levelOptions: o }).route(graph));
-  return own(strategy.maxNodes, (graph, o) => (strategy as Strategy<"whole">).run(graph, o).result);
+  return own(strategy.maxNodes, (graph, o) => {
+    const out = (strategy as Strategy<"whole">).run(graph, o);
+    WHOLE_BOARDS.set(out.result, out.graph);
+    return out.result;
+  });
+}
+
+/** The board of the output of each whole strategy that `stepRouterStrategy` runs, by its result. The screen reads it for the measures of the moved boxes. */
+const WHOLE_BOARDS = new WeakMap<Result, Graph>();
+
+/** This function gives the board of the output of a whole strategy that `stepRouterStrategy` ran, or `undefined` for another result. A room strategy can move the boxes of this board. */
+export function wholeBoard(result: Result): Graph | undefined {
+  return WHOLE_BOARDS.get(result);
 }
 
 /** This function gives a router for each strategy of one step of `RoutedStep` in a registry, in the order of the registry (`stepRouterStrategy`). */

package/src/bench/measures/curves.ts

@@ -1,6 +1,6 @@
 import type { CurveSegment } from "../../curves/model.ts";
 import type { CurveSpace } from "../../curves/space.ts";
-import { dist, polylineLength, segmentsCross, turns, type Point } from "../../geom.ts";
+import { dist, frechet, polylineLength, segmentsCross, turns, type Point } from "../../geom.ts";
 import { Grid } from "../../grid.ts";
 import { TOLERANCE } from "../properties.ts";
 
@@ -109,6 +109,60 @@ export function bendingEnergy(points: readonly Point[], tolerance = 0.25): numbe
   return polylineLength(q) * sum;
 }
 
+/**
+ * This function gives the curvature variation of a sampled curve (C4 of MEAS0, Moreton 1993): `V = L^3 · ∫ (dκ/ds)^2 ds`.
+ * Each inner sample gets the curvature `κ = φ / l` of `bendingEnergy`, with its sign. `L` is the length of the curve.
+ * The sum is `L^3 · Σ (κ_(i+1) - κ_i)^2 / d_i`, with `d_i` the distance of two inner samples in sequence.
+ *
+ * The value has no unit, and lower is better. A straight line and an arc of a circle give 0. Fewer than 4 points give 0. The cost is linear.
+ */
+export function curvatureVariation(points: readonly Point[], tolerance = 0.25): number {
+  const q: Point[] = [];
+  for (const v of points) if (q.length === 0 || dist(q[q.length - 1]!, v) > EPS) q.push(v);
+  if (q.length < 4) return 0;
+  const phi = turns(q);
+  const kappa: number[] = [];
+  for (let i = 1; i + 1 < q.length; i++) {
+    const t = phi[i - 1]!;
+    const l = Math.min((dist(q[i - 1]!, q[i]!) + dist(q[i]!, q[i + 1]!)) / 2, (8 * tolerance) / Math.max(EPS, Math.abs(t)));
+    kappa.push(Math.abs(t) < EPS ? 0 : t / l);
+  }
+  let sum = 0;
+  for (let i = 0; i + 1 < kappa.length; i++) sum += (kappa[i + 1]! - kappa[i]!) ** 2 / dist(q[i + 1]!, q[i + 2]!);
+  return polylineLength(q) ** 3 * sum;
+}
+
+/** This function gives the points of a polyline with no leg longer than `step`. It keeps each vertex. */
+function densify(points: readonly Point[], step: number): Point[] {
+  const out: Point[] = [];
+  for (let i = 0; i < points.length; i++) {
+    const b = points[i]!;
+    if (i > 0) {
+      const a = points[i - 1]!;
+      const n = Math.ceil(dist(a, b) / step);
+      for (let k = 1; k < n; k++) out.push({ x: a.x + ((b.x - a.x) * k) / n, y: a.y + ((b.y - a.y) * k) / n });
+    }
+    out.push(b);
+  }
+  return out;
+}
+
+/** The most points of each of the two lists of `curveDeviation`. More points give a longer step. */
+const DEVIATION_POINTS = 400;
+
+/**
+ * This function gives the deviation of a curve from its route (C8 of MEAS0).
+ * The value is the Fréchet distance of the samples of the curve and the polyline of the route.
+ * Each list gets points with no leg longer than `step`, or longer when a list has more than 400 points. Then the discrete Fréchet distance is near the true distance.
+ *
+ * The value is in units of the board, and lower is better. The caller divides it by the unit of the board. The cost is quadratic for each route.
+ */
+export function curveDeviation(samples: readonly Point[], polyline: readonly Point[], step: number): number {
+  const long = Math.max(polylineLength(samples), polylineLength(polyline));
+  const h = Math.max(step, long / DEVIATION_POINTS, EPS);
+  return frechet(densify(samples, h), densify(polyline, h));
+}
+
 /** This function tells if a polyline crosses itself. Two legs next to each other do not count. The cost is `n log n`. */
 export function crossesItself(p: readonly Point[]): boolean {
   if (p.length < 4) return false;

package/src/bench/measures/groups.ts

@@ -1,4 +1,7 @@
+import { rng } from "../../fixtures.ts";
+import { center, dist, type Point } from "../../geom.ts";
 import type { Graph, Level } from "../../model.ts";
+import { countOverlaps } from "../links.ts";
 import type { Section } from "../../sections.ts";
 import { adjustedRandIndex } from "./stats.ts";
 
@@ -120,3 +123,71 @@ export function leafGroups(root: Section, count: number): string[] {
 export function groupStability(before: Section, after: Section, count: number): number {
   return adjustedRandIndex(leafGroups(before, count), leafGroups(after, count));
 }
+
+/**
+ * This function gives the fill of the groups of one level (G4 of MEAS0): the mean of `fill(c) = Σ_(v in c) area(box(v)) / area(box(c))`.
+ * `box(c)` is the box of the item. Only an item with 2 or more nodes counts, and a fill above 1 counts as 1.
+ * The scale is 0 to 1, and higher is better. A level without such an item gives `undefined`. The cost is linear.
+ */
+export function groupFill(graph: Graph, level: Level): number | undefined {
+  const area = new Map(graph.nodes.map((n) => [n.id, n.box.w * n.box.h] as const));
+  const fills: number[] = [];
+  for (const item of level.items) {
+    if (item.nodes.length < 2) continue;
+    const own = item.box.w * item.box.h;
+    const inside = item.nodes.reduce((s, v) => s + (area.get(v) ?? 0), 0);
+    fills.push(own > 0 ? Math.min(1, inside / own) : 1);
+  }
+  return fills.length === 0 ? undefined : fills.reduce((s, f) => s + f, 0) / fills.length;
+}
+
+/**
+ * This function counts the overlaps of the items of the levels (G5 of MEAS0).
+ * An overlap is a pair of items of one level whose boxes overlap by more than `TOLERANCE`.
+ * It is the sum over the levels of `countOverlaps`. Lower is better. The cost is `n log n` for each level.
+ */
+export function itemOverlaps(levels: readonly Level[]): number {
+  return levels.reduce((n, level) => n + countOverlaps(level.items.map((i) => i.box)), 0);
+}
+
+/** Up to this number of nodes, `silhouette` examines each node. Above it, two seeded samples of this size give an estimate. */
+const SILHOUETTE_NODES = 2000;
+
+/**
+ * This function gives the silhouette of the groups of one level (G7 of MEAS0, Rousseeuw 1987): the mean of `s(v) = (b_v - a_v) / max(a_v, b_v)`.
+ * `a_v` is the mean distance from the center of `v` to the centers of the other nodes of its item. `b_v` is the smallest mean distance to the nodes of another item.
+ * A node alone in its item gets `s(v) = 0`. The scale is -1 to 1, and higher is better.
+ * A level with fewer than 2 items gives `undefined`. The cost is quadratic up to 2000 nodes.
+ * Above 2000 nodes, a seeded sample of 2000 nodes gets `s(v)`, against a second seeded sample of 2000 nodes. Thus the value is an estimate.
+ */
+export function silhouette(graph: Graph, level: Level): number | undefined {
+  const at = new Map(graph.nodes.map((n) => [n.id, center(n.box)] as const));
+  const all = level.items.flatMap((item, k) => item.nodes.flatMap((v) => (at.has(v) ? [{ p: at.get(v)!, k }] : [])));
+  if (new Set(all.map((x) => x.k)).size < 2) return undefined;
+  const R = rng(all.length);
+  const sample = (): typeof all => (all.length <= SILHOUETTE_NODES ? all : Array.from({ length: SILHOUETTE_NODES }, () => all[Math.floor(R() * all.length)]!));
+  const chosen = sample();
+  const ref = sample();
+  const groups = new Map<number, Point[]>();
+  for (const { p, k } of ref) {
+    const g = groups.get(k);
+    if (g) g.push(p);
+    else groups.set(k, [p]);
+  }
+  let sum = 0;
+  for (const { p, k } of chosen) {
+    const own = groups.get(k);
+    if (!own || own.length < 2) continue;
+    let a = 0;
+    let b = Number.POSITIVE_INFINITY;
+    for (const [j, g] of groups) {
+      const d = g.reduce((s, q) => s + dist(p, q), 0);
+      if (j === k) a = d / (g.length - 1);
+      else b = Math.min(b, d / g.length);
+    }
+    if (!Number.isFinite(b)) continue;
+    const m = Math.max(a, b);
+    sum += m > 0 ? (b - a) / m : 0;
+  }
+  return sum / chosen.length;
+}

package/src/bench/measures/index.ts

@@ -10,3 +10,4 @@ export * from "./pareto.ts";
 export * from "./order.ts";
 export * from "./highways.ts";
 export * from "./lanes.ts";
+export * from "./symmetry.ts";

package/src/bench/measures/levels.ts

@@ -185,3 +185,27 @@ export function linkAgreement(graph: Graph, levels: readonly Level[], routes: re
   }
   return n > 0 ? sum / n : undefined;
 }
+
+/** The level ratio of a result (Z5 of MEAS0): the largest step and the spread of the steps from level to level. */
+export interface LevelRatio {
+  /** The largest `lr_d = items_(d+1) / items_d`. */
+  readonly max: number;
+  /** The standard deviation of `log(lr_d)` over the steps. A value of 0 is steps of equal ratio. */
+  readonly spread: number;
+}
+
+/**
+ * This function gives the level ratio of the levels (Z5 of MEAS0, Mondal 2018): `lr_d = items_(d+1) / items_d`, in the order of depth.
+ * A level without items does not count. Fewer than 2 levels give `undefined`. Lower is better for both values. The cost is linear.
+ */
+export function levelRatio(levels: readonly Level[]): LevelRatio | undefined {
+  const counts = byDepth(levels)
+    .map((l) => l.items.length)
+    .filter((n) => n > 0);
+  if (counts.length < 2) return undefined;
+  const ratios = counts.slice(1).map((n, d) => n / counts[d]!);
+  const logs = ratios.map((r) => Math.log(r));
+  const mean = logs.reduce((s, x) => s + x, 0) / logs.length;
+  const spread = Math.sqrt(logs.reduce((s, x) => s + (x - mean) ** 2, 0) / logs.length);
+  return { max: Math.max(...ratios), spread };
+}

package/src/bench/measures/room.ts

@@ -1,5 +1,5 @@
 import { rng } from "../../fixtures.ts";
-import type { Box } from "../../geom.ts";
+import { center, dist, type Box, type Point } from "../../geom.ts";
 import type { Boxed } from "../../room/index.ts";
 
 /** Up to this number of boxes, `roomOrderFaults` examines each pair. */
@@ -41,3 +41,108 @@ export function roomOrderFaults(before: readonly Boxed[], after: readonly Boxed[
   }
   return Math.round((faults * (n * (n - 1)) / 2) / Math.max(1, seen));
 }
+
+/**
+ * This function gives the displacement of the boxes (M3 of MEAS0, Bridgeman 2000): `mean_v dist(box_open(v), box_packed(v)) / u`.
+ * The distance is between the centers of the two boxes of a node, and `u` is the unit of the packed board.
+ * The value has no unit, and lower is better. A board where no box moves gives 0. The cost is linear.
+ */
+export function boxDisplacement(before: readonly Boxed[], after: readonly Boxed[], unit: number): number {
+  const next = new Map(after.map((b) => [b.id, b.box] as const));
+  let sum = 0;
+  let n = 0;
+  for (const b of before) {
+    const a = next.get(b.id);
+    if (!a) continue;
+    sum += dist(center(b.box), center(a));
+    n++;
+  }
+  return n === 0 ? 0 : sum / n / (unit > 0 ? unit : 1);
+}
+
+/** The number of nearest boxes of each box that make the neighbour pairs of `distanceDistortion`. */
+export const DISTORTION_NEIGHBOURS = 4;
+
+/**
+ * This function gives the distance distortion of the boxes (M5 of MEAS0): the Kruskal stress of the centers.
+ * `σ = sqrt(Σ (α d'_ij - d_ij)^2 / Σ d_ij^2)`, with `d` the distance on the packed board, `d'` the distance on the open board, and `α = Σ d d' / Σ d'^2` the best scale.
+ * The pairs are each box and its 4 nearest boxes on the packed board. The scale is 0 to 1, and lower is better.
+ * A board that only changes its scale gives 0. The cost is `n log n` for an even density.
+ */
+export function distanceDistortion(before: readonly Boxed[], after: readonly Boxed[]): number {
+  const next = new Map(after.map((b) => [b.id, center(b.box)] as const));
+  const list = before.flatMap((b) => (next.has(b.id) ? [{ p: center(b.box), q: next.get(b.id)! }] : []));
+  const pairs = neighbourPairs(
+    list.map((x) => x.p),
+    DISTORTION_NEIGHBOURS,
+  );
+  let dd = 0;
+  let qq = 0;
+  let pp = 0;
+  const ds: [number, number][] = [];
+  for (const [i, j] of pairs) {
+    const d = dist(list[i]!.p, list[j]!.p);
+    const e = dist(list[i]!.q, list[j]!.q);
+    ds.push([d, e]);
+    dd += d * e;
+    qq += e * e;
+    pp += d * d;
+  }
+  if (pp === 0) return 0;
+  const alpha = qq > 0 ? dd / qq : 0;
+  const res = ds.reduce((s, [d, e]) => s + (alpha * e - d) ** 2, 0);
+  return Math.sqrt(res / pp);
+}
+
+/** This function gives each pair of a point and one of its `k` nearest points one time, as `[i, j]` with `i < j`. A grid of buckets finds the points. */
+function neighbourPairs(points: readonly Point[], k: number): [number, number][] {
+  const n = points.length;
+  if (n < 2) return [];
+  let x0 = Number.POSITIVE_INFINITY;
+  let y0 = Number.POSITIVE_INFINITY;
+  let x1 = Number.NEGATIVE_INFINITY;
+  let y1 = Number.NEGATIVE_INFINITY;
+  for (const p of points) {
+    x0 = Math.min(x0, p.x);
+    y0 = Math.min(y0, p.y);
+    x1 = Math.max(x1, p.x);
+    y1 = Math.max(y1, p.y);
+  }
+  const cell = Math.max(1e-9, Math.sqrt(((x1 - x0) * (y1 - y0) || 1) / n) * 2);
+  const key = (cx: number, cy: number): string => `${cx},${cy}`;
+  const buckets = new Map<string, number[]>();
+  points.forEach((p, i) => {
+    const kk = key(Math.floor((p.x - x0) / cell), Math.floor((p.y - y0) / cell));
+    const list = buckets.get(kk);
+    if (list) list.push(i);
+    else buckets.set(kk, [i]);
+  });
+  const span = Math.ceil(Math.max(x1 - x0, y1 - y0) / cell) + 1;
+  const seen = new Set<string>();
+  const out: [number, number][] = [];
+  points.forEach((p, i) => {
+    const cx = Math.floor((p.x - x0) / cell);
+    const cy = Math.floor((p.y - y0) / cell);
+    let near: { j: number; d: number }[] = [];
+    for (let ring = 0; ring <= span; ring++) {
+      for (let gx = cx - ring; gx <= cx + ring; gx++)
+        for (let gy = cy - ring; gy <= cy + ring; gy++) {
+          if (Math.max(Math.abs(gx - cx), Math.abs(gy - cy)) !== ring) continue;
+          for (const j of buckets.get(key(gx, gy)) ?? []) if (j !== i) near.push({ j, d: dist(p, points[j]!) });
+        }
+      // A point outside the rings is at least `ring · cell` away, so the k nearest points are known.
+      if (near.length >= Math.min(k, n - 1)) {
+        near.sort((a, b) => a.d - b.d || a.j - b.j);
+        if (near[Math.min(k, n - 1) - 1]!.d <= ring * cell) break;
+      }
+    }
+    near = near.sort((a, b) => a.d - b.d || a.j - b.j).slice(0, k);
+    for (const { j } of near) {
+      const pk = i < j ? `${i},${j}` : `${j},${i}`;
+      if (seen.has(pk)) continue;
+      seen.add(pk);
+      out.push(i < j ? [i, j] : [j, i]);
+    }
+  });
+  return out;
+}

package/src/bench/measures/symmetry.ts

@@ -0,0 +1,114 @@
+import { center, dist, type Point } from "../../geom.ts";
+import type { Graph, Route } from "../../model.ts";
+import { boardUnit } from "./routes.ts";
+
+const EPS = 1e-9;
+
+/** One map of the board onto itself: a mirror on an axis through the center of the board, or the half turn about the center. */
+type Map2 = (p: Point) => Point;
+
+/** This function gives the corners of a polyline: the points without repeats and without inner points on a straight line. */
+function cornersOf(points: readonly Point[]): Point[] {
+  const q: Point[] = [];
+  for (const v of points) if (q.length === 0 || dist(q[q.length - 1]!, v) > EPS) q.push(v);
+  const out: Point[] = [];
+  for (let i = 0; i < q.length; i++) {
+    const v = q[i]!;
+    if (i > 0 && i + 1 < q.length) {
+      const a = out[out.length - 1]!;
+      const c = q[i + 1]!;
+      const cr = (v.x - a.x) * (c.y - v.y) - (v.y - a.y) * (c.x - v.x);
+      const dt = (v.x - a.x) * (c.x - v.x) + (v.y - a.y) * (c.y - v.y);
+      if (Math.abs(cr) <= EPS * Math.max(1, dist(a, v) * dist(v, c)) && dt > 0) continue;
+    }
+    out.push(v);
+  }
+  return out;
+}
+
+/** This function tells if two lists of corners are the same, point by point, within `tol`. */
+const sameCorners = (a: readonly Point[], b: readonly Point[], tol: number): boolean => a.length === b.length && a.every((p, i) => dist(p, b[i]!) <= tol);
+
+/**
+ * This function gives the symmetry of the drawing (H3 of MEAS0). The value is the share of the routes that the best map of the board sends onto a route.
+ * The maps are the two mirrors on the axes and the half turn. Each one goes through the center of the boxes.
+ *
+ * A route of the edge `(s, t)` maps when two things are true. The map sends the centers of `s` and `t` to the centers of the nodes `s'` and `t'`, within `u / 4`.
+ * A route of an edge between `s'` and `t'` has the same corners as the mapped route, within `u / 4`. `u` is the unit of the board.
+ *
+ * The scale is 0 to 1, and higher is better. A router keeps the symmetry that the boxes have, or loses it. Routes without points give `undefined`.
+ * The cost is linear in the points of the routes.
+ */
+export function routeSymmetry(graph: Graph, routes: readonly Route[]): number | undefined {
+  const drawn = routes.filter((r) => r.points.length >= 2);
+  if (drawn.length === 0 || graph.nodes.length === 0) return undefined;
+  const u = boardUnit(graph);
+  const tol = u / 4;
+  let x0 = Number.POSITIVE_INFINITY;
+  let y0 = Number.POSITIVE_INFINITY;
+  let x1 = Number.NEGATIVE_INFINITY;
+  let y1 = Number.NEGATIVE_INFINITY;
+  for (const n of graph.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);
+  }
+  const cx = (x0 + x1) / 2;
+  const cy = (y0 + y1) / 2;
+  const maps: readonly Map2[] = [(p) => ({ x: 2 * cx - p.x, y: p.y }), (p) => ({ x: p.x, y: 2 * cy - p.y }), (p) => ({ x: 2 * cx - p.x, y: 2 * cy - p.y })];
+  // The nodes by a cell of the size `tol`, so the node at a mapped center is a lookup of 9 cells.
+  const cellOf = (p: Point): [number, number] => [Math.floor(p.x / tol), Math.floor(p.y / tol)];
+  const cells = new Map<string, { id: string; at: Point }[]>();
+  const at = new Map<string, Point>();
+  for (const n of graph.nodes) {
+    const c = center(n.box);
+    at.set(n.id, c);
+    const [i, j] = cellOf(c);
+    const k = `${i},${j}`;
+    const list = cells.get(k);
+    if (list) list.push({ id: n.id, at: c });
+    else cells.set(k, [{ id: n.id, at: c }]);
+  }
+  const nodeAt = (p: Point): string | undefined => {
+    const [i, j] = cellOf(p);
+    let best: { id: string; d: number } | undefined;
+    for (let a = i - 1; a <= i + 1; a++)
+      for (let b = j - 1; b <= j + 1; b++)
+        for (const n of cells.get(`${a},${b}`) ?? []) {
+          const d = dist(n.at, p);
+          if (d <= tol && (best === undefined || d < best.d || (d === best.d && n.id < best.id))) best = { id: n.id, d };
+        }
+    return best?.id;
+  };
+  const ends = new Map(graph.edges.map((e) => [e.id, [e.source.node, e.target.node] as const]));
+  const byPair = new Map<string, Point[][]>();
+  const corners = drawn.map((r) => cornersOf(r.points));
+  drawn.forEach((r, i) => {
+    const e = ends.get(r.edge);
+    if (!e) return;
+    const k = `${e[0]}\u0000${e[1]}`;
+    const list = byPair.get(k);
+    if (list) list.push(corners[i]!);
+    else byPair.set(k, [corners[i]!]);
+  });
+  let best = 0;
+  for (const m of maps) {
+    let hits = 0;
+    drawn.forEach((r, i) => {
+      const e = ends.get(r.edge);
+      if (!e) return;
+      const a = at.get(e[0]);
+      const b = at.get(e[1]);
+      const s = a && nodeAt(m(a));
+      const t = b && nodeAt(m(b));
+      if (s === undefined || t === undefined) return;
+      const mapped = corners[i]!.map(m);
+      const back = [...mapped].reverse();
+      const hit = (byPair.get(`${s}\u0000${t}`) ?? []).some((c) => sameCorners(mapped, c, tol)) || (byPair.get(`${t}\u0000${s}`) ?? []).some((c) => sameCorners(back, c, tol));
+      if (hit) hits++;
+    });
+    best = Math.max(best, hits / drawn.length);
+  }
+  return best;
+}

package/src/bench/screen/exercise.ts

@@ -77,6 +77,11 @@ export const MOVE_NAMES: Readonly<Record<string, string>> = Object.freeze({
   consensus: "cluster",
   "p-hub": "hubLink",
   "scale-space": "cluster",
+  steiner: "tree",
+  gaps: "gap",
+  streets: "street",
+  search: "searched",
+  interchanges: "networkRoad",
 });
 
 /**

package/src/bench/screen/forms.ts

@@ -12,6 +12,8 @@ export interface LayoutPort {
   /** The fixed place of the port, from the top-left corner of the box. The router does not move a port with `x` and `y`. */
   readonly x?: number;
   readonly y?: number;
+  /** The fixed place of the port on its `side`: a fraction from 0 to 1. The start is the top end or the left end of the side. */
+  readonly along?: number;
 }
 
 /** A point of a region: `[x, y]`. The y axis points down. */
@@ -238,18 +240,20 @@ function sideAt(p: { x: number; y: number }, w: number, h: number): LayoutSide {
 const num = round3;
 
 function portToFile(p: Port, n: Node): LayoutPort {
+  if (p.along !== undefined) return { id: p.id, ...(p.side ? { side: TO_FILE[p.side] } : {}), along: p.along };
   const side = p.side ? TO_FILE[p.side] : p.at ? sideAt(p.at, n.box.w, n.box.h) : undefined;
   return { id: p.id, ...(side ? { side } : {}), ...(p.at ? { x: num(p.at.x), y: num(p.at.y) } : {}) };
 }
 
 function portToModel(p: LayoutPort): Port {
+  if (p.along !== undefined) return { id: p.id, ...(p.side ? { side: TO_MODEL[p.side] } : {}), along: p.along };
   if (p.x !== undefined && p.y !== undefined) return { id: p.id, at: { x: p.x, y: p.y } };
   return { id: p.id, ...(p.side ? { side: TO_MODEL[p.side] } : {}) };
 }
 
 /**
  * This function writes a graph as an input file of the form `layout-input/1`, with its hash.
- * A fixed plug gets `x`, `y` and the side that holds it. `inputGraph` reads the file back.
+ * A fixed plug gets `x`, `y` and the side that holds it. A plug with `along` keeps its `side` and `along`. `inputGraph` reads the file back.
  */
 export function graphInput(graph: Graph, head: LayoutInputHead): LayoutInput {
   const boxes = graph.nodes.map(
@@ -259,6 +263,7 @@ export function graphInput(graph: Graph, head: LayoutInputHead): LayoutInput {
       h: num(n.box.h),
       x: num(n.box.x),
       y: num(n.box.y),
+      ...(n.parent !== undefined ? { parent: n.parent } : {}),
       ...(n.ports ? { ports: n.ports.map((p) => portToFile(p, n)) } : {}),
       ...(n.data ? { data: n.data } : {}),
     }),
@@ -312,7 +317,7 @@ export function regionBounds(region: Region): { x: number; y: number; w: number;
 export type RouteInput = Pick<LayoutInput, "id" | "boxes" | "obstacles"> & { readonly edges?: LayoutInput["edges"] };
 
 /**
- * This function reads the graph of the router from an input file. The router reads the positions, the ports, the edges and the data.
+ * This function reads the graph of the router from an input file. The router reads the positions, the ports, the parents, the edges and the data.
  * Each obstacle becomes a node without edges, with the bounding box of its region, after the boxes.
  * The router ignores the other fields of the packer: `container`, `gap`, `locked`, `rank`, the `shape` of a box and the `move` of an obstacle.
  * A box without `x` and `y` is an error.
@@ -320,7 +325,13 @@ export type RouteInput = Pick<LayoutInput, "id" | "boxes" | "obstacles"> & { rea
 export function inputGraph(input: RouteInput): Graph {
   const nodes = input.boxes.map((b): Node => {
     if (b.x === undefined || b.y === undefined) throw new Error(`The box "${b.id}" of the input "${input.id}" has no position. The router needs a placed input.`);
-    return { id: b.id, box: { x: b.x, y: b.y, w: b.w, h: b.h }, ...(b.ports ? { ports: b.ports.map(portToModel) } : {}), ...(b.data ? { data: b.data } : {}) };
+    return {
+      id: b.id,
+      box: { x: b.x, y: b.y, w: b.w, h: b.h },
+      ...(b.ports ? { ports: b.ports.map(portToModel) } : {}),
+      ...(b.data ? { data: b.data } : {}),
+      ...(b.parent !== undefined ? { parent: b.parent } : {}),
+    };
   });
   for (const o of input.obstacles ?? []) nodes.push({ id: o.id, box: regionBounds(o.region) });
   const edges = (input.edges ?? []).map(

package/src/bench/screen/measures.ts

@@ -24,6 +24,8 @@ export interface MeasureInfo {
    * A measure without this field has the threshold `RECORD_EPS`.
    */
   readonly minEffect?: MinEffect;
+  /** The definition of the measure in one or two sentences: what it counts, and when its value is good. The site shows it. */
+  readonly definition?: string;
 }
 
 /** One rule of `MIN_EFFECTS`: the units, the minimum effect of a measure with one of these units, and the reason. */
@@ -69,7 +71,7 @@ export const MIN_EFFECTS: readonly MinEffectRule[] = Object.freeze([
 const MIN_EFFECT_BY_UNIT: ReadonlyMap<string, MinEffectRule> = new Map(MIN_EFFECTS.flatMap((r) => r.units.map((u) => [u, r] as const)));
 
 /** The text of a row of `MEASURES`: the key, the id, the name, the unit, the better side and the placement dependence. */
-type Row = readonly [key: string, id: string, name: string, unit: string, better: "lower" | "higher", placement: boolean];
+type Row = readonly [key: string, id: string, name: string, unit: string, better: "lower" | "higher", placement: boolean, definition?: string];
 
 const ROWS: readonly Row[] = [
   // The routes. A placement makes crossings, plugs on short sides and boxes that touch, so these measures depend on it.
@@ -127,6 +129,12 @@ const ROWS: readonly Row[] = [
   // The step `room` of `runSuite` gives the same keys for the boards that a room strategy opens.
   ["M1.area", "M1", "route.lane.area", "ratio", "lower", false],
   ["M4.laneThrough", "M4", "route.lane.through", "count", "lower", true],
+  // SCREEN-MEASURES: M2, M3 and M5 of the step `whole` compare the board of the output with the input board. A whole strategy without a room strategy gives 0.
+  ["M2.order", "M2", "route.room.order", "count", "lower", false, "The number of pairs of boxes whose order or alignment on an axis changes when the boxes move. 0 is correct."],
+  ["M3.displacement", "M3", "route.room.displacement", "no unit", "lower", false, "The mean distance that the center of a box moves, divided by the unit of the board."],
+  ["M5.stress", "M5", "route.room.distortion", "0 to 1", "lower", false, "The stress of the distances from each box to its 4 nearest boxes, after the best change of scale. 0 is a board that only changes its scale."],
+  // SCREEN-MEASURES: H3 is the symmetry of the routes on a board of fixed boxes.
+  ["H3.share", "H3", "route.symmetry", "0 to 1", "higher", true, "The share of the routes that a mirror or a half turn of the board sends onto a route, for the best of the three maps."],
   // The order fragility (W3 of MEAS3, from WILD-056): the spread of a measure over random orders of the edges. The placement can move it.
   ["W3.crossings", "W3", "route.order.crossings", "IQR over the median", "lower", true],
   ["W3.detour", "W3", "route.order.detour", "IQR over the median", "lower", true],
@@ -156,11 +164,35 @@ const ROWS: readonly Row[] = [
   ["Z4.farItems", "Z4", "route.level.far-items", "count", "lower", true],
   ["Z7.position", "Z7", "route.level.position", "no unit", "lower", true],
   ["Z8.order", "Z8", "route.level.order", "-1 to 1", "higher", true],
+  // SCREEN-MEASURES: Z1 is the count of the hard rule `counts-sum`, as Z2. Z5 is the ratio of the item counts from level to level.
+  ["Z1.countsSum", "Z1", "route.level.counts-sum", "count", "lower", false, "The faults of the hard rule `counts-sum`: a level whose items miss a node, or whose links miss an edge. 0 is correct."],
+  ["Z5.max", "Z5", "route.level.ratio.max", "ratio", "lower", true, "The largest ratio of the item counts of two levels in sequence. A large ratio is a sudden jump of the zoom."],
+  [
+    "Z5.spread",
+    "Z5",
+    "route.level.ratio.spread",
+    "no unit",
+    "lower",
+    true,
+    "The standard deviation of the log of the ratios of the item counts of the levels. 0 is a zoom with steps of equal size.",
+  ],
   ["G1.modularity", "G1", "route.group.modularity", "-0.5 to 1", "higher", true],
   ["G2.cut", "G2", "route.group.cut", "0 to 1", "lower", true],
   ["G6.balance", "G6", "route.group.balance", "0 to 1", "higher", true],
   ["G8.treeCost", "G8", "route.group.tree-cost", "0 to 1", "lower", true],
   ["G9.ari", "G9", "route.group.stability", "-1 to 1", "higher", true],
+  // SCREEN-MEASURES: G4, G5 and G7 read the boxes of the items of the levels.
+  ["G4.fill", "G4", "route.group.fill", "0 to 1", "higher", true, "The mean share of the box of a group of the far view that the boxes of its nodes fill. A full group box is 1."],
+  ["G5.overlaps", "G5", "route.group.overlaps", "count", "lower", true, "The number of pairs of items of one level whose boxes overlap. 0 is correct."],
+  [
+    "G7.silhouette",
+    "G7",
+    "route.group.silhouette",
+    "-1 to 1",
+    "higher",
+    true,
+    "The mean silhouette of the nodes of the far view: how much nearer a node is to its group than to the nearest other group.",
+  ],
   // The curves. A curve draws a fixed polyline, so no measure of a curve depends on the placement.
   ["C1.max", "C1", "route.curve.c1.max", "degrees", "lower", false],
   ["C1.share", "C1", "route.curve.c1.share", "0 to 1", "lower", false],
@@ -168,6 +200,11 @@ const ROWS: readonly Row[] = [
   ["C2.max", "C2", "route.curve.c2.max", "no unit", "lower", false],
   ["C3.median", "C3", "route.curve.c3.median", "no unit", "lower", false],
   ["C3.q95", "C3", "route.curve.c3.q95", "no unit", "lower", false],
+  // SCREEN-MEASURES: C4 is the change of the curvature along a curve. C8 is the distance of a curve from its route.
+  ["C4.median", "C4", "route.curve.c4.median", "no unit", "lower", false, "The median curvature variation of the curves, without a unit. A circle or a straight line is 0. A sudden change of the curvature is large."],
+  ["C4.q95", "C4", "route.curve.c4.q95", "no unit", "lower", false, "The 0.95 quantile of the curvature variation of the curves. It shows the worst curves."],
+  ["C8.median", "C8", "route.curve.c8.median", "no unit", "lower", false, "The median Fréchet distance of a curve from the polyline of its route, divided by the unit of the board."],
+  ["C8.max", "C8", "route.curve.c8.max", "no unit", "lower", false, "The largest Fréchet distance of a curve from the polyline of its route, divided by the unit of the board."],
   ["C5.peak", "C5", "route.curve.c5.peak", "curvature times the unit of the board", "lower", false],
   ["C6.length", "C6", "route.curve.c6.length", "ratio", "lower", false],
   ["curve-clear", "C7", "route.curve.rule.clear", "count", "lower", false],
@@ -182,10 +219,10 @@ const ROWS: readonly Row[] = [
  * It compares a measure with the value `true` only between runs on the same input.
  */
 export const MEASURES: readonly MeasureInfo[] = Object.freeze(
-  ROWS.map(([key, id, name, unit, better, placementDependent]) => {
+  ROWS.map(([key, id, name, unit, better, placementDependent, definition]) => {
     const rule = MIN_EFFECT_BY_UNIT.get(unit);
     if (!rule) throw new Error(`MEASURES: the unit "${unit}" of ${key} has no rule in MIN_EFFECTS`);
-    const info: MeasureInfo = { key, id, name, unit, better, placementDependent };
+    const info: MeasureInfo = { key, id, name, unit, better, placementDependent, ...(definition === undefined ? {} : { definition }) };
     return Object.freeze(rule.minEffect === undefined ? info : { ...info, minEffect: rule.minEffect });
   }),
 );