@mark1russell7/highways 0.1.1 → 0.1.3

package/package.json

@@ -9,7 +9,7 @@
     "directory": "packages/core"
   },
   "homepage": "https://mark1russell7.github.io/highways/",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -39,6 +39,7 @@
     "test": "vitest run",
     "bench": "node scripts/bench.ts",
     "profile": "node scripts/profile.ts",
+    "levels": "node scripts/levels.ts",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json"
   }

package/src/bench/links.ts

@@ -0,0 +1,191 @@
+import { dist, inflate, pointSegmentDistance, polylineLength, segmentHitsBox, type Box, type Point } from "../geom.ts";
+import { Grid } from "../grid.ts";
+import type { Graph, Level, Result } from "../model.ts";
+import { TOLERANCE } from "./properties.ts";
+
+/**
+ * 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 const BACKTRACK_SHARE = 0.25;
+/** A link goes out and back only when its distance to its target grows by more than this number of units. */
+export const BACKTRACK_MIN = 40;
+/** The default `slack` of `LinkFaultOptions`. */
+export 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 function backtrackOf(p: readonly Point[]): number {
+  if (p.length < 3) return 0;
+  const end = p[p.length - 1]!;
+  let near = dist(p[0]!, end);
+  let worst = 0;
+  for (let i = 1; i < p.length; i++) {
+    worst = Math.max(worst, dist(p[i]!, end) - near);
+    near = Math.min(near, pointSegmentDistance(end, p[i - 1]!, p[i]!));
+  }
+  return worst;
+}
+
+/** 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 function goesOutAndBack(p: readonly Point[]): boolean {
+  if (p.length < 3) return false;
+  const span = dist(p[0]!, p[p.length - 1]!);
+  return backtrackOf(p) > Math.max(BACKTRACK_MIN, BACKTRACK_SHARE * span);
+}
+
+/**
+ * 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 function measureLinks(boxes: ReadonlyMap<string, Box>, links: readonly MeasuredLink[], options: LinkFaultOptions = {}): LinkFaults {
+  const slack = options.slack ?? OUTSIDE_SLACK;
+  let size = 0;
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const b of boxes.values()) {
+    size += Math.max(b.w, b.h);
+    x0 = Math.min(x0, b.x);
+    y0 = Math.min(y0, b.y);
+    x1 = Math.max(x1, b.x + b.w);
+    y1 = Math.max(y1, b.y + b.h);
+  }
+  // Large items cover many buckets of a small grid, so the buckets grow with the items.
+  const grid = new Grid<string>(Math.max(180, (2 * size) / Math.max(1, boxes.size)));
+  for (const [id, b] of boxes) grid.add(id, b);
+  let through = 0;
+  let backtrack = 0;
+  let worstDetour = 0;
+  let outside = 0;
+  for (const l of links) {
+    const p = l.points;
+    if (p.length === 0) continue;
+    let hit = false;
+    for (let i = 1; i < p.length && !hit; i++) {
+      const a = p[i - 1]!;
+      const b = p[i]!;
+      grid.querySegment(a, b, 0, (id) => {
+        if (!hit && id !== l.source && id !== l.target && segmentHitsBox(a, b, inflate(boxes.get(id)!, -TOLERANCE), TOLERANCE)) hit = true;
+      });
+    }
+    if (hit) through++;
+    if (goesOutAndBack(p)) backtrack++;
+    const span = dist(p[0]!, p[p.length - 1]!);
+    if (span > 1) worstDetour = Math.max(worstDetour, polylineLength(p) / span);
+    if (p.some((q) => q.x < x0 - slack || q.x > x1 + slack || q.y < y0 - slack || q.y > y1 + slack)) outside++;
+  }
+  return { links: links.length, through, backtrack, worstDetour, outside };
+}
+
+/** This function measures the faults of the routes of a result. The ends of a route are the nodes of its edge. */
+export function measureRouteFaults(graph: Graph, result: Result, options: LinkFaultOptions = {}): LinkFaults {
+  const boxes = new Map(graph.nodes.map((n) => [n.id, n.box]));
+  const edges = new Map(graph.edges.map((e) => [e.id, e]));
+  const links: MeasuredLink[] = [];
+  for (const r of result.routes) {
+    const e = edges.get(r.edge);
+    if (e) links.push({ source: e.source.node, target: e.target.node, points: r.points });
+  }
+  return measureLinks(boxes, links, options);
+}
+
+/** This function counts the pairs of boxes that overlap by more than `TOLERANCE` on each axis. */
+export function countOverlaps(boxes: readonly Box[]): number {
+  let size = 0;
+  for (const b of boxes) size += Math.max(b.w, b.h);
+  const grid = new Grid<number>(Math.max(180, (2 * size) / Math.max(1, boxes.length)));
+  boxes.forEach((b, i) => grid.add(i, b));
+  let n = 0;
+  boxes.forEach((a, i) => {
+    grid.query(a, (j) => {
+      const b = boxes[j]!;
+      if (j > i && Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x) > TOLERANCE && Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y) > TOLERANCE) n++;
+    });
+  });
+  return n;
+}
+
+/** This function measures the faults of the links of one zoom level. The items of the level are the boxes. */
+export function measureLevel(level: Level, options: LinkFaultOptions = {}): LevelFaults {
+  const boxes = new Map(level.items.map((i) => [i.id, i.box]));
+  return {
+    depth: level.depth,
+    items: level.items.length,
+    groups: level.items.filter((i) => i.nodes.length > 1).length,
+    overlaps: countOverlaps(level.items.map((i) => i.box)),
+    ...measureLinks(boxes, level.links, options),
+  };
+}
+
+/**
+ * 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 function measureLevelFaults(result: Result, options: LinkFaultOptions = {}): LevelFaults[] {
+  return (result.levels ?? []).filter((l) => l.items.some((i) => i.nodes.length > 1)).map((l) => measureLevel(l, options));
+}
+
+/** This function adds the faults of several levels: it sums the counts and keeps the largest `worstDetour`. */
+export function sumFaults(list: readonly LinkFaults[]): LinkFaults {
+  return list.reduce<LinkFaults>(
+    (s, f) => ({
+      links: s.links + f.links,
+      through: s.through + f.through,
+      backtrack: s.backtrack + f.backtrack,
+      worstDetour: Math.max(s.worstDetour, f.worstDetour),
+      outside: s.outside + f.outside,
+    }),
+    { links: 0, through: 0, backtrack: 0, worstDetour: 0, outside: 0 },
+  );
+}

package/src/bench/properties.ts

@@ -1,10 +1,18 @@
-import { dist, inflate, pointBoxDistance, segmentHitsBox, type Point } from "../geom.ts";
+import { dist, inflate, pointBoxDistance, segmentHitsBox, type Box, type Point } from "../geom.ts";
 import { Grid } from "../grid.ts";
 import { fixedPortPoint, nodeIndex, type Graph, type Node, type Result } from "../model.ts";
 
 /** 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" | "bundle-trunk" | "run-shared";
+  readonly rule:
+    | "complete"
+    | "ends-at-plugs"
+    | "fixed-plugs"
+    | "no-pass-through"
+    | "counts-sum"
+    | "link-ends"
+    | "bundle-trunk"
+    | "run-shared";
   readonly edge?: string;
   readonly detail: string;
 }
@@ -15,6 +23,7 @@ export const TOLERANCE = 0.5;
 /**
  * This function checks the hard rules of a result. Each edge has one route, and each route starts and ends at its nodes.
  * Fixed plugs stay in place. No route goes through a node that is not one of its ends. The counts of each level add up.
+ * Each link of a level starts on the box of its source and ends on the box of its target.
  *
  * Each route of a bundle starts with its trunk, and an edge is in one bundle at most.
  * Each run has two edges or more, and the route of each edge holds the points of the run in a row.
@@ -91,10 +100,26 @@ export function checkProperties(graph: Graph, result: Result, limit = 100): Viol
     const sum = level.links.reduce((s, l) => s + l.count, 0);
     if (sum !== between)
       if (add({ rule: "counts-sum", detail: `level ${level.depth}: the links count ${sum} edges, not ${between}` })) return out;
+    const boxOf = new Map(level.items.map((it) => [it.id, it.box]));
+    for (const l of level.links) {
+      const s = boxOf.get(l.source);
+      const t = boxOf.get(l.target);
+      const p = l.points;
+      if (!s || !t || p.length < 2 || !onBoundary(p[0]!, s) || !onBoundary(p[p.length - 1]!, t))
+        if (add({ rule: "link-ends", detail: `level ${level.depth}: the link ${l.source} to ${l.target} does not start and end on the boundaries of its items` }))
+          return out;
+    }
   }
   return out;
 }
 
+/** This function tells if the point is on the boundary of the box, within `TOLERANCE`. */
+function onBoundary(p: Point, b: Box): boolean {
+  const inner = inflate(b, -TOLERANCE);
+  const deep = p.x > inner.x && p.x < inner.x + inner.w && p.y > inner.y && p.y < inner.y + inner.h;
+  return !deep && pointBoxDistance(p, b) <= TOLERANCE;
+}
+
 /** This function tells if the polyline `p` holds the points of `part` in a row. */
 function holds(p: readonly Point[], part: readonly Point[]): boolean {
   if (part.length === 0) return true;

package/src/bench/run.ts

@@ -1,5 +1,6 @@
 import { makeFixture, type FixtureSpec } from "../fixtures.ts";
 import type { Graph, Result, Router } from "../model.ts";
+import { measureLevelFaults, measureRouteFaults, sumFaults, type LevelFaults, type LinkFaults } from "./links.ts";
 import { checkProperties, type Violation } from "./properties.ts";
 import { measureQuality, type Quality } from "./quality.ts";
 
@@ -20,6 +21,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. */
@@ -87,6 +92,8 @@ export function benchOne(router: Router, fixture: string, graph: Graph, repeat =
     violations: all.length,
     sample: all.slice(0, 5),
     quality: measureQuality(graph, result),
+    faults: measureRouteFaults(graph, result),
+    levelFaults: measureLevelFaults(result),
   };
 }
 
@@ -101,3 +108,24 @@ export function formatTable(rows: readonly BenchRow[]): string {
   });
   return [head, line, ...body].join("\n");
 }
+
+/**
+ * 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 function formatFaults(rows: readonly BenchRow[]): string {
+  const head =
+    "| router | fixture | through | out and back | worst detour | outside | level links | level overlaps | level through | level out and back | level worst detour | level outside |";
+  const line = "|---|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|";
+  const body = rows.map((r) => {
+    const f = r.faults;
+    const cells = [r.router, r.fixture, f.through, f.backtrack, f.worstDetour.toFixed(2), f.outside];
+    if (r.levelFaults.length === 0) cells.push("-", "-", "-", "-", "-", "-");
+    else {
+      const l = sumFaults(r.levelFaults);
+      cells.push(l.links, r.levelFaults.reduce((s, x) => s + x.overlaps, 0), l.through, l.backtrack, l.worstDetour.toFixed(2), l.outside);
+    }
+    return `| ${cells.join(" | ")} |`;
+  });
+  return [head, line, ...body].join("\n");
+}

package/src/cases.ts

@@ -0,0 +1,111 @@
+import { makeFixture, rng } from "./fixtures.ts";
+import type { Edge, Graph, Node } from "./model.ts";
+
+/**
+ * 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;
+}
+
+/** A board while it grows: the functions add nodes and edges in order. */
+class Board {
+  readonly nodes: Node[] = [];
+  readonly edges: Edge[] = [];
+  readonly #pairs = new Set<string>();
+
+  node(id: string, x: number, y: number, w: number, h: number): string {
+    this.nodes.push({ id, box: { x, y, w, h } });
+    return id;
+  }
+
+  /** This method adds an edge. It adds nothing for a loop or for a second edge between the same two nodes. */
+  link(source: string, target: string): void {
+    const key = source < target ? `${source}|${target}` : `${target}|${source}`;
+    if (source === target || this.#pairs.has(key)) return;
+    this.#pairs.add(key);
+    this.edges.push({ id: `e${this.edges.length}`, source: { node: source }, target: { node: target } });
+  }
+
+  graph(): Graph {
+    return { nodes: this.nodes, edges: this.edges };
+  }
+}
+
+/**
+ * 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 function denseGroupsBoard(): Graph {
+  return makeFixture({ name: "dense-groups", kind: "clustered", nodes: 150, edgesPerNode: 2, seed: 3 });
+}
+
+/**
+ * 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 function hubChainBoard(): Graph {
+  const R = rng(3);
+  const b = new Board();
+  const rows = 3;
+  const cols = 32;
+  const gap = 48;
+  const id = (r: number, c: number): string => `c${r}-${c}`;
+  for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) b.node(id(r, c), c * (80 + gap), r * (36 + gap), 80, 36);
+  for (let r = 0; r < rows; r++) for (let c = 0; c + 1 < cols; c++) b.link(id(r, c), id(r, c + 1));
+  for (let n = 0; n < 40; n++) {
+    const r = Math.floor(R() * rows);
+    const c = Math.floor(R() * cols);
+    const span = Math.floor(cols / 8 + (R() * cols) / 2);
+    if (c + span < cols) b.link(id(r, c), id((r + 1) % rows, c + span));
+  }
+  return b.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 function manyGroupsBoard(): Graph {
+  const R = rng(7);
+  const b = new Board();
+  const cols = 8;
+  const rows = 4;
+  const per = 4;
+  const w = 60;
+  const h = 30;
+  const cardGap = 12;
+  const groupGap = 60;
+  const side = Math.ceil(Math.sqrt(per));
+  const gw = side * w + (side - 1) * cardGap;
+  const gh = Math.ceil(per / side) * h + (Math.ceil(per / side) - 1) * cardGap;
+  const groups: string[][] = [];
+  for (let r = 0; r < rows; r++)
+    for (let c = 0; c < cols; c++) {
+      const list: string[] = [];
+      for (let i = 0; i < per; i++) {
+        const x = c * (gw + groupGap) + (i % side) * (w + cardGap);
+        const y = r * (gh + groupGap) + Math.floor(i / side) * (h + cardGap);
+        list.push(b.node(`g${r}-${c}-${i}`, x, y, w, h));
+      }
+      groups.push(list);
+    }
+  for (const list of groups) for (let i = 1; i < list.length; i++) b.link(list[i - 1]!, list[i]!);
+  const pick = (list: readonly string[]): string => list[Math.floor(R() * list.length)]!;
+  for (let n = 0; n < groups.length * 3; n++) b.link(pick(groups[Math.floor(R() * groups.length)]!), pick(groups[Math.floor(R() * groups.length)]!));
+  return b.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 const CASES: readonly CaseBoard[] = [
+  { name: "case-dense-groups", defect: "Groups overlap at the far view, and level links go through other groups.", make: denseGroupsBoard },
+  { name: "case-hub-chain", defect: "A route climbs a chain of hubs away from its target and comes back.", make: hubChainBoard },
+  { name: "case-many-groups", defect: "On a level with many groups, links go around the outer edge of the board.", make: manyGroupsBoard },
+];

package/src/grid.ts

@@ -71,6 +71,56 @@ export class Grid<T> {
     }
   }
 
+  /**
+   * This method gives each item in the buckets along the segment `ab`, widened by `margin`, to `visit`, one time each.
+   * The buckets are those of `#segment`, in the same order, so the items come in the same order.
+   * A bucket in the range of the step before has no new item, so the walk skips it.
+   * The walk stops when `visit` gives true, and then the method gives true.
+   */
+  #walk(a: Point, b: Point, margin: number, visit: (item: T) => boolean | void): boolean {
+    const stamp = ++this.#stamp;
+    const c = this.#cell;
+    const items = this.#items;
+    const n = Math.max(1, Math.ceil(Math.hypot(b.x - a.x, b.y - a.y) / (c / 2)));
+    let px = a.x;
+    let py = a.y;
+    // The bucket range of the step before. The first step has none.
+    let pi0 = 1;
+    let pi1 = 0;
+    let pj0 = 1;
+    let pj1 = 0;
+    for (let k = 1; k <= n; k++) {
+      const qx = k === n ? b.x : a.x + ((b.x - a.x) * k) / n;
+      const qy = k === n ? b.y : a.y + ((b.y - a.y) * k) / n;
+      const i0 = Math.floor((Math.min(px, qx) - margin) / c);
+      const j0 = Math.floor((Math.min(py, qy) - margin) / c);
+      const i1 = Math.floor((Math.max(px, qx) + margin) / c);
+      const j1 = Math.floor((Math.max(py, qy) + margin) / c);
+      // A visit can add an item and so replace the array of stamps. Each step reads it again, as `#take` does.
+      const seen = this.#seen;
+      for (let i = i0; i <= i1; i++) {
+        const before = i >= pi0 && i <= pi1;
+        for (let j = j0; j <= j1; j++) {
+          if (before && j >= pj0 && j <= pj1) continue;
+          const list = this.#buckets.get(this.#key(i, j));
+          if (list === undefined) continue;
+          for (const id of list) {
+            if (seen[id] === stamp) continue;
+            seen[id] = stamp;
+            if (visit(items[id]!) === true) return true;
+          }
+        }
+      }
+      pi0 = i0;
+      pi1 = i1;
+      pj0 = j0;
+      pj1 = j1;
+      px = qx;
+      py = qy;
+    }
+    return false;
+  }
+
   // The buckets along a segment, widened by `margin`: the boxes of steps of at most half a bucket.
   #segment(a: Point, b: Point, margin: number, each: (x0: number, y0: number, x1: number, y1: number) => void): void {
     const n = Math.max(1, Math.ceil(Math.hypot(b.x - a.x, b.y - a.y) / (this.#cell / 2)));
@@ -103,8 +153,17 @@ export class Grid<T> {
 
   /** 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 {
-    const stamp = ++this.#stamp;
-    this.#segment(a, b, margin, (x0, y0, x1, y1) => this.#take(stamp, x0, y0, x1, y1, visit));
+    this.#walk(a, b, margin, (item) => {
+      visit(item);
+    });
+  }
+
+  /**
+   * 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 {
+    return this.#walk(a, b, margin, test);
   }
 }
 

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./geom.ts";
 export { Grid, segmentBounds } from "./grid.ts";
 export * from "./model.ts";
 export * from "./fixtures.ts";
+export * from "./cases.ts";
 export * from "./plugs.ts";
 export * from "./curves.ts";
 export * from "./visibility.ts";
@@ -11,4 +12,5 @@ export * from "./sections.ts";
 export * from "./routers/index.ts";
 export * from "./bench/properties.ts";
 export * from "./bench/quality.ts";
+export * from "./bench/links.ts";
 export * from "./bench/run.ts";