@mark1russell7/highways 0.9.0 → 0.9.2

package/src/bench/screen/screen.ts

@@ -1,17 +1,20 @@
-import type { Graph, Result, Route } from "../../model.ts";
+import type { Graph, Level, Result, Route } from "../../model.ts";
 import { stableOrderStrategy } from "../../order/index.ts";
 import { repairStrategy } from "../../repair/index.ts";
 import { STRATEGIES } from "../../strategies/builtins.ts";
 import { asRouter, createRegistry, getStrategy, listStrategies, register, STEPS, type AnyStrategy, type Registry, type Strategy } from "../../strategies/model.ts";
-import { compareStep, highwayRouters, isRoutedStep, stepRouters, type CompareRow, type CompareStep, type RoutedStep, type StepComparison } from "../compare.ts";
+import { compareStep, highwayRouters, isRoutedStep, stepRouters, wholeBoard, type CompareRow, type CompareStep, type RoutedStep, type StepComparison } from "../compare.ts";
 import { bundledShare, bundleStretch, mergeAngle } from "../measures/bundles.ts";
 import { highwayEdits } from "../measures/highways.ts";
 import { laneArea, laneCrossings, laneFidelity, lanesThrough, occupiedArea, openLanes, orthogonality, routeSeparation, runProfile } from "../measures/lanes.ts";
-import { linkAgreement } from "../measures/levels.ts";
+import { farLevel, groupFill, itemOverlaps, silhouette } from "../measures/groups.ts";
+import { levelRatio, linkAgreement } from "../measures/levels.ts";
 import { orderFragility } from "../measures/order.ts";
 import { paretoFront, type Objective } from "../measures/pareto.ts";
 import { boardUnit } from "../measures/routes.ts";
+import { boxDisplacement, distanceDistortion, roomOrderFaults } from "../measures/room.ts";
 import { routeStability } from "../measures/stability.ts";
+import { routeSymmetry } from "../measures/symmetry.ts";
 import { quantile } from "../measures/stats.ts";
 import { checkLevels, checkProperties, TOLERANCE } from "../properties.ts";
 import { measureQuality } from "../quality.ts";
@@ -227,11 +230,30 @@ function screenRegistry(step: ScreenStep, strategies: readonly (Strategy<ScreenS
 /** This function tells if a step of the screen gives routes. The step `router` gives routes, and each step of `RoutedStep` gives routes as a router. */
 const givesRoutes = (step: ScreenStep): step is "router" | RoutedStep => step === "router" || isRoutedStep(step);
 
+/** This function gives the measures of the shape of the groups and of the levels: G4, G5, G7 and Z5. A value without its data is not in the result. */
+function groupShapeValues(graph: Graph, levels: readonly Level[]): Record<string, number> {
+  const values: Record<string, number> = {};
+  if (levels.length === 0) return values;
+  values["G5.overlaps"] = itemOverlaps(levels);
+  const far = farLevel(levels);
+  const fill = far && groupFill(graph, far);
+  if (fill !== undefined) values["G4.fill"] = fill;
+  const sil = far && silhouette(graph, far);
+  if (sil !== undefined) values["G7.silhouette"] = sil;
+  const ratio = levelRatio(levels);
+  if (ratio) {
+    values["Z5.max"] = ratio.max;
+    values["Z5.spread"] = ratio.spread;
+  }
+  return values;
+}
+
 /**
  * This function gives the values of a row of `compareStep`, with the measures of `measureQuality` for a router.
  * A router also gets the bundled share (B2), the merge angle (B6) and the bundle stretch (B3) against the routes `base` of `corners`.
  * It also gets the measures of MEAS3A: R12, R14, B5, B7, B8, B9, M1 and M4. The lane measures open each shared segment at `MEASURE_LANE_WIDTH`.
- * A result with zoom levels also gets the link agreement (Z9), for a router and for a grouping rule.
+ * A result with zoom levels also gets the link agreement (Z9) and `groupShapeValues`, for a router and for a grouping rule.
+ * A router also gets the symmetry of its routes (H3). A whole strategy also gets M2, M3 and M5 of the board of its output.
  */
 function rowValues(step: ScreenStep, graph: Graph, row: CompareRow, base: () => readonly Route[]): Record<string, number> {
   const values: Record<string, number> = { ...row.values };
@@ -265,10 +287,21 @@ function rowValues(step: ScreenStep, graph: Graph, row: CompareRow, base: () =>
     }
     values["M1.area"] = laneArea(graph, open);
     values["M4.laneThrough"] = lanesThrough(graph, open);
+    const h3 = routeSymmetry(graph, routes);
+    if (h3 !== undefined) values["H3.share"] = h3;
   }
   if ((givesRoutes(step) || step === "group") && row.result?.levels) {
-    const la = linkAgreement(graph, row.result.levels, row.result.routes, boardUnit(graph));
+    const levels = row.result.levels;
+    const la = linkAgreement(graph, levels, row.result.routes, boardUnit(graph));
     if (la !== undefined) values["Z9.mean"] = la;
+    Object.assign(values, groupShapeValues(graph, levels));
+  }
+  // The step `whole` can move the boxes with a room strategy. M2, M3 and M5 compare the board of the output with the input board.
+  if (step === "whole" && row.result) {
+    const board = wholeBoard(row.result) ?? graph;
+    values["M2.order"] = roomOrderFaults(graph.nodes, board.nodes);
+    values["M3.displacement"] = boxDisplacement(graph.nodes, board.nodes, boardUnit(graph));
+    values["M5.stress"] = distanceDistortion(graph.nodes, board.nodes);
   }
   return values;
 }
@@ -426,6 +459,8 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
       const values = rowValues(step, graph, row, cornersBase);
       // Z2 is the count of the hard rule `link-ends`, as a measure. The steps `router`, `highway` and `group` check the rule.
       if (hard["link-ends"] !== undefined) values["Z2.linkEnds"] = hard["link-ends"];
+      // Z1 is the count of the hard rule `counts-sum`, as a measure, the same way.
+      if (hard["counts-sum"] !== undefined) values["Z1.countsSum"] = hard["counts-sum"];
       if (optima && withOptima.has(input.id) && row.result) Object.assign(values, gapValues(input, graph, row.result, cornersBase(), gapBase(), optima));
       if (shuffles > 0 && row.result) {
         const router = asRouter(strategy as Strategy<"router">, own[row.strategy]);

package/src/bench/suite.ts

@@ -15,7 +15,7 @@ import { asRouter, listStrategies, STEPS, type LaneBoard, type Registry, type St
 import { measureLevelFaults, sumFaults } from "./links.ts";
 import { checkLevels } from "./properties.ts";
 import { ambiguity, inkSaved } from "./measures/bundles.ts";
-import { bendingEnergy, curveFaults, g1Defect, g2Defect } from "./measures/curves.ts";
+import { bendingEnergy, curvatureVariation, curveDeviation, curveFaults, g1Defect, g2Defect } from "./measures/curves.ts";
 import { balance, cutShare, farLevel, groupStability, levelGrouping, modularity, treeCost } from "./measures/groups.ts";
 import { nestingFaults, orderStability, positionStability } from "./measures/levels.ts";
 import { paretoFront, type Objective } from "./measures/pareto.ts";
@@ -328,7 +328,7 @@ export interface CurveRun {
   readonly edges: readonly string[];
 }
 
-/** This function draws the routes of a result with each curve strategy and measures the curves (C1, C2, C3, C6 and the curve rules). */
+/** This function draws the routes of a result with each curve strategy and measures the curves (C1, C2, C3, C4, C6, C8 and the curve rules). */
 export function curveRuns(graph: Graph, result: Result, curves: readonly Strategy<"curve">[], options: CurveRunOptions): CurveRun[] {
   const byId = nodeIndex(graph);
   const edges = new Map(graph.edges.map((e) => [e.id, e]));
@@ -363,6 +363,8 @@ export function curveRuns(graph: Graph, result: Result, curves: readonly Strateg
     const g1: number[] = [];
     const g2: number[] = [];
     const energy: number[] = [];
+    const variation: number[] = [];
+    const deviation: number[] = [];
     const rules = { "curve-clear": 0, "curve-ends": 0, "curve-g1": 0, "curve-simple": 0 };
     let length = 0;
     drawn.forEach((segments, i) => {
@@ -371,6 +373,8 @@ export function curveRuns(graph: Graph, result: Result, curves: readonly Strateg
       g1.push(g1Defect(segments));
       g2.push(g2Defect(segments, u));
       energy.push(bendingEnergy(s, 0.25));
+      variation.push(curvatureVariation(s, 0.25));
+      deviation.push(curveDeviation(s, r.points, u / 4) / u);
       length += polylineLength(s);
       const normals = options.normals.has(curve.name);
       const f = curveFaults({
@@ -394,6 +398,10 @@ export function curveRuns(graph: Graph, result: Result, curves: readonly Strateg
       "C2.max": g2.reduce((m, x) => Math.max(m, x), 0),
       "C3.median": quantile(energy, 0.5) || 0,
       "C3.q95": quantile(energy, 0.95) || 0,
+      "C4.median": quantile(variation, 0.5) || 0,
+      "C4.q95": quantile(variation, 0.95) || 0,
+      "C8.median": quantile(deviation, 0.5) || 0,
+      "C8.max": deviation.reduce((m, x) => Math.max(m, x), 0),
       "C6.length": ink > 0 ? length / ink : 1,
       ...rules,
     };

package/src/highways/fixtures.test-util.ts

@@ -49,6 +49,19 @@ export const parallel: Graph = {
   edges: [0, 1, 2].map((i) => ({ id: `e${i}`, source: { node: `l${i}` }, target: { node: `r${i}` } })),
 };
 
+/** Three rows of nodes on the left and on the right, with three edges between the rows. The gaps between the rows are 40 wide. */
+export const rows: Graph = {
+  nodes: [0, 1, 2].flatMap((i) => [
+    { id: `l${i}`, box: box(0, 60 * i) },
+    { id: `r${i}`, box: box(600, 60 * i) },
+  ]),
+  edges: [
+    { id: "a", source: { node: "l0" }, target: { node: "r2" } },
+    { id: "b", source: { node: "l1" }, target: { node: "r1" } },
+    { id: "c", source: { node: "l2" }, target: { node: "r0" } },
+  ],
+};
+
 /**
  * This function adds the common tests of a highway strategy. The strategy is in the registry, and it gives a correct plan the same each time.
  * Its routes break no hard rule after `follow`.

package/src/highways/follow.ts

@@ -1,5 +1,5 @@
 import { center, dist, pointBoxDistance, type Point } from "../geom.ts";
-import { fixedPortPoint, nodeIndex, type End, type Graph, type Node, type Result, type Route, type SharedRun } from "../model.ts";
+import { fixedPortPoint, nodeIndex, outerGraph, type End, type Graph, type Node, type Result, type Route, type SharedRun } from "../model.ts";
 import { placePlug } from "../plugs.ts";
 import { orderLanes, type RunOrder } from "../segments.ts";
 import { WayFinder, type WayOptions } from "../ways.ts";
@@ -68,7 +68,8 @@ function slice(stops: Stops, on: number, off: number): Point[] {
  * The result has a shared run for each stretch of a spine where the same two edges or more go. Each run holds the points of its routes in a row.
  * The same graph, plan and options give the same result.
  */
-export function follow(graph: Graph, plan: HighwayPlan, options: FollowOptions = {}): Result {
+export function follow(input: Graph, plan: HighwayPlan, options: FollowOptions = {}): Result {
+  const graph = outerGraph(input);
   const byId = nodeIndex(graph);
   const ways = new WayFinder(graph.nodes, options);
   const base = new Map((options.routes?.routes ?? []).map((r) => [r.edge, r.points]));

package/src/highways/free-lines.ts

@@ -0,0 +1,141 @@
+import { dist, polylineLength, type Point } from "../geom.ts";
+import type { Graph } from "../model.ts";
+import { boardGaps } from "../room/index.ts";
+import type { WayFinder } from "../ways.ts";
+import { firstRoutes } from "./base.ts";
+import type { HighwayInput } from "./model.ts";
+import { edgePlugs } from "./stretches.ts";
+
+/** The source of the candidate streets: the middle lines of the gaps of the room step, or the lines through the corners. */
+export type StreetSource = "room" | "corners";
+
+/** The values of `StreetSource`. */
+export const STREET_SOURCES: readonly StreetSource[] = Object.freeze(["room", "corners"]);
+
+/** One axis-parallel street in the free space, from `a` to `b`. */
+export interface FreeLine {
+  readonly a: Point;
+  readonly b: Point;
+}
+
+/** One edge for the streets: its two points out of its plugs, and the length of its first route. */
+export interface StreetEdge {
+  readonly edge: string;
+  readonly s: Point;
+  readonly t: Point;
+  readonly base: number;
+}
+
+/** The ride of one edge on one street. It has the points where the edge joins and leaves the street, and two lengths. */
+export interface StreetRide {
+  readonly on: Point;
+  readonly off: Point;
+  /** The length on the street. */
+  readonly ride: number;
+  /** The length of the two ramps, to the street and from it. */
+  readonly ramps: number;
+}
+
+const round = (v: number): number => Math.round(v * 2) / 2;
+
+/**
+ * This function gives the free pieces of the line `x = c` (axis `x`) or `y = c` (axis `y`). A box closer than `pad` to the line blocks it.
+ * A piece shorter than `min` is not in the list. The pieces run over the board and `2 pad` past it.
+ */
+function freePieces(finder: WayFinder, axis: "x" | "y", c: number, pad: number, min: number, lo: number, hi: number): FreeLine[] {
+  const blocks: [number, number][] = [];
+  const strip = axis === "x" ? { x: c - pad, y: lo, w: 2 * pad, h: hi - lo } : { x: lo, y: c - pad, w: hi - lo, h: 2 * pad };
+  finder.obstacles.query(strip, (n) => {
+    const a = axis === "x" ? n.box.x : n.box.y;
+    const w = axis === "x" ? n.box.w : n.box.h;
+    if (c <= a - pad || c >= a + w + pad) return;
+    const b = axis === "x" ? n.box.y : n.box.x;
+    const h = axis === "x" ? n.box.h : n.box.w;
+    blocks.push([b - pad, b + h + pad]);
+  });
+  blocks.sort((p, q) => p[0] - q[0] || p[1] - q[1]);
+  const out: FreeLine[] = [];
+  const at = (u: number): Point => (axis === "x" ? { x: c, y: u } : { x: u, y: c });
+  let from = lo;
+  for (const [s, e] of blocks) {
+    if (s - from >= min) out.push({ a: at(from), b: at(s) });
+    from = Math.max(from, e);
+  }
+  if (hi - from >= min) out.push({ a: at(from), b: at(hi) });
+  return out;
+}
+
+/**
+ * This function gives the candidate streets of a board. Each street is an axis-parallel piece of free space.
+ * The source `room` takes the middle line of each gap of `boardGaps` that is two margins wide or more.
+ * The source `corners` takes the lines one margin out from each side of each box.
+ * A street is two margins long or more. The list has no copies, and its order is the same each time.
+ */
+export function freeLines(graph: Graph, finder: WayFinder, source: StreetSource): FreeLine[] {
+  const nodes = graph.nodes;
+  if (nodes.length === 0) return [];
+  const m = finder.margin;
+  const pad = m / 2;
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const n of 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 lines: { axis: "x" | "y"; c: number }[] = [];
+  if (source === "room") {
+    for (const g of boardGaps(nodes)) if (g.width >= 2 * m) lines.push({ axis: g.axis, c: round(g.at - g.width / 2) });
+  } else {
+    for (const n of nodes) {
+      lines.push({ axis: "x", c: round(n.box.x - m) }, { axis: "x", c: round(n.box.x + n.box.w + m) });
+      lines.push({ axis: "y", c: round(n.box.y - m) }, { axis: "y", c: round(n.box.y + n.box.h + m) });
+    }
+  }
+  const seen = new Set<string>();
+  const out: FreeLine[] = [];
+  const sorted = [...lines].sort((p, q) => (p.axis === q.axis ? p.c - q.c : p.axis < q.axis ? -1 : 1));
+  for (const l of sorted) {
+    const k = `${l.axis}${l.c}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    const [lo, hi] = l.axis === "x" ? [y0 - 2 * m, y1 + 2 * m] : [x0 - 2 * m, x1 + 2 * m];
+    out.push(...freePieces(finder, l.axis, l.c, pad, 2 * m, lo, hi));
+  }
+  return out;
+}
+
+/** This function gives the edges of the input for the streets, with the points out of their plugs and the lengths of their first routes. */
+export function streetEdges(input: HighwayInput, finder: WayFinder): StreetEdge[] {
+  const first = firstRoutes(input);
+  const out: StreetEdge[] = [];
+  for (const p of edgePlugs(input.graph)) {
+    const route = first.get(p.edge.id);
+    const s = finder.out(p.ps);
+    const t = finder.out(p.pt);
+    out.push({ edge: p.edge.id, s, t, base: route ? polylineLength(route) : dist(s, t) });
+  }
+  return out;
+}
+
+/** This function gives the point of the street nearest to `p`. */
+export function streetPoint(line: FreeLine, p: Point): Point {
+  if (line.a.x === line.b.x) {
+    const lo = Math.min(line.a.y, line.b.y);
+    const hi = Math.max(line.a.y, line.b.y);
+    return { x: line.a.x, y: Math.min(hi, Math.max(lo, p.y)) };
+  }
+  const lo = Math.min(line.a.x, line.b.x);
+  const hi = Math.max(line.a.x, line.b.x);
+  return { x: Math.min(hi, Math.max(lo, p.x)), y: line.a.y };
+}
+
+/** This function gives the ride of an edge on a street. The edge joins the street at the point nearest to `s`, and leaves it at the point nearest to `t`. */
+export function streetRide(line: FreeLine, e: StreetEdge): StreetRide {
+  const on = streetPoint(line, e.s);
+  const off = streetPoint(line, e.t);
+  return { on, off, ride: dist(on, off), ramps: dist(e.s, on) + dist(off, e.t) };
+}

package/src/highways/gaps/index.ts

@@ -0,0 +1,85 @@
+import { WayFinder } from "../../ways.ts";
+import { freeLines, streetEdges, streetRide, type FreeLine, type StreetEdge, type StreetSource } from "../free-lines.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { snapPlan, type SnapLine } from "../snap.ts";
+
+/** The options of the highway strategy `gaps` (HWY-057 of the note on highways). */
+export interface GapOptions {
+  /** A street with fewer edges than this number (the demand `k`) is not a highway. The default is 3. */
+  readonly minSize: number;
+  /** The cost of a length on a street against a length off the streets, from 0.1 to 0.8. The default is 0.5. */
+  readonly discount: number;
+  /** An edge rides a street only when its way along the street is this many times its first route or less. The default is 1.3. */
+  readonly detour: number;
+  /** The source of the streets: the gaps of the room step, or the lines through the corners. The default is `room`. */
+  readonly source: StreetSource;
+}
+
+/** The default options of the strategy `gaps`. */
+export const GAP_DEFAULTS: Readonly<GapOptions> = Object.freeze({ minSize: 3, discount: 0.5, detour: 1.3, source: "room" });
+
+/** The best street of an edge, from the streets in `open`. The ride costs `discount` times its length. The way is at most `detour` times the first route. */
+function bestStreet(lines: readonly FreeLine[], open: ReadonlySet<number>, e: StreetEdge, o: Readonly<GapOptions>, min: number): number {
+  let best = -1;
+  let bestSaving = 1e-9;
+  for (const i of open) {
+    const r = streetRide(lines[i]!, e);
+    if (r.ride < min) continue;
+    if (r.ramps + r.ride > o.detour * e.base) continue;
+    const saving = e.base - (r.ramps + o.discount * r.ride);
+    if (saving > bestSaving || (saving === bestSaving && i < best)) [best, bestSaving] = [i, saving];
+  }
+  return best;
+}
+
+/**
+ * This function gives the highways on the gaps of the board (HWY-057). The streets are the free middle lines of the gaps.
+ * Each edge takes the street that saves it the most cost, when a length on a street costs `discount` times its length.
+ * A street with `minSize` edges or more becomes a highway. The edges of the other streets then choose again among the highways, two times.
+ */
+export function gapPlan(input: HighwayInput, o: Readonly<GapOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes);
+  const lines = freeLines(input.graph, finder, o.source);
+  const edges = streetEdges(input, finder);
+  const min = 2 * finder.margin;
+  const size = Math.max(2, Math.round(o.minSize));
+  let open = new Set(lines.map((_, i) => i));
+  let choice = new Map<string, number>();
+  for (let round = 0; round < 3; round++) {
+    choice = new Map();
+    const count = new Map<number, number>();
+    for (const e of edges) {
+      const i = bestStreet(lines, open, e, o, min);
+      if (i < 0) continue;
+      choice.set(e.edge, i);
+      count.set(i, (count.get(i) ?? 0) + 1);
+    }
+    const kept = new Set([...open].filter((i) => (count.get(i) ?? 0) >= size));
+    if (kept.size === open.size) break;
+    open = kept;
+  }
+  const byLine = new Map<number, SnapLine["members"][number][]>();
+  for (const e of edges) {
+    const i = choice.get(e.edge);
+    if (i === undefined || !open.has(i)) continue;
+    const r = streetRide(lines[i]!, e);
+    const list = byLine.get(i) ?? [];
+    list.push({ edge: e.edge, from: r.on, to: r.off, at: 0 });
+    byLine.set(i, list);
+  }
+  const snaps: SnapLine[] = [...byLine.keys()]
+    .sort((p, q) => p - q)
+    .map((i) => {
+      const members = byLine.get(i)!;
+      // The spine runs only over the part of the street that its members ride.
+      const line = lines[i]!;
+      const vertical = line.a.x === line.b.x;
+      const us = members.flatMap((m) => (vertical ? [m.from.y, m.to.y] : [m.from.x, m.to.x]));
+      const lo = Math.min(...us);
+      const hi = Math.max(...us);
+      const a = vertical ? { x: line.a.x, y: lo } : { x: lo, y: line.a.y };
+      const b = vertical ? { x: line.a.x, y: hi } : { x: hi, y: line.a.y };
+      return { key: `gap${i}`, a, b, members };
+    });
+  return snapPlan(input, snaps, { minSize: size, direct: true });
+}

package/src/highways/index.ts

@@ -97,5 +97,11 @@ export { LINK_COMMUNITY_DEFAULTS, linkCommunities, linkCommunityGroups, linkComm
 export { cellSteps, nearestCentre, pointGroups, TERRITORY_DEFAULTS, TERRITORY_POINTS, territoryPlan, type CellStep, type TerritoryOptions, type TerritoryPoints } from "./territories/index.ts";
 export { coAssociation, CONSENSUS_DEFAULTS, CONSENSUS_LINKAGES, consensusGroups, consensusLabels, consensusPlan, type ConsensusLinkage, type ConsensusOptions } from "./consensus/index.ts";
 export { HUB_ALLOCATIONS, HUB_CANDIDATES, hubCandidates, P_HUB_DEFAULTS, pHubPlan, pMedian, type HubAllocation, type HubCandidates, type PHubOptions } from "./p-hub/index.ts";
+export { freeLines, STREET_SOURCES, streetEdges, streetPoint, streetRide, type FreeLine, type StreetEdge, type StreetRide, type StreetSource } from "./free-lines.ts";
+export { oneSteiner, spanningTree, STEINER_DEFAULTS, STEINER_GROUPS, STEINER_METHODS, STEINER_METRICS, steinerPlan, type SteinerGroup, type SteinerMethod, type SteinerMetric, type SteinerOptions } from "./steiner/index.ts";
+export { GAP_DEFAULTS, gapPlan, type GapOptions } from "./gaps/index.ts";
+export { STREET_DEFAULTS, streetPlan, type StreetOptions } from "./streets/index.ts";
+export { SEARCH_DEFAULTS, SEARCH_MOVES, searchPlan, searchScore, type SearchMove, type SearchOptions } from "./search/index.ts";
+export { INTERCHANGE_BASES, INTERCHANGE_DEFAULTS, interchangeCandidates, interchangePlan, type Interchange, type InterchangeBase, type InterchangeOptions } from "./interchanges/index.ts";
 export { SCALE_SPACE_DEFAULTS, scaleClusters, scaleSpaceGroups, scaleSpacePlan, type ScaleCluster, type ScaleSpaceOptions } from "./scale-space/index.ts";
 export * from "./gates/index.ts";

package/src/highways/interchanges/index.ts

@@ -0,0 +1,231 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { orderLanes } from "../../segments.ts";
+import { WayFinder } from "../../ways.ts";
+import { basePlan, firstRoutes, nearestPlace, tidyPlan } from "../base.ts";
+import { lengthBetween, memberAt, pointAt, type Highway, type HighwayInput, type HighwayMember, type HighwayPlan } from "../model.ts";
+import { spinePart } from "../snap.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The plan that gives the highways of the network: the plan of `corridors` or of `shared-ways`, with their defaults. */
+export type InterchangeBase = "corridors" | "shared-ways";
+
+/** The values of `InterchangeBase`. */
+export const INTERCHANGE_BASES: readonly InterchangeBase[] = Object.freeze(["corridors", "shared-ways"]);
+
+/** The options of the highway strategy `interchanges` (HWY-060 of the note on highways). */
+export interface InterchangeOptions {
+  /** The plan that gives the highways. The default is `corridors`. */
+  readonly from: InterchangeBase;
+  /** The cost of a change between two highways, in units of the board, from 0 to 8. The default is 2. */
+  readonly changeCost: number;
+  /** The largest number of interchanges, from 1 to 32. The default is 16. */
+  readonly interchanges: number;
+  /** The largest number of highways on the way of one edge, from 1 to 3. The default is 2. */
+  readonly perEdge: number;
+  /** Two highways get an interchange where they come this near, in units of the board. The default is 2. */
+  readonly radius: number;
+  /** The cost of a length on a highway against a length off the highways, from 0.1 to 1. The default is 0.5. */
+  readonly discount: number;
+  /** An edge rides the network only when its way is this many times its first route or less. The default is 1.5. */
+  readonly detour: number;
+}
+
+/** The default options of the strategy `interchanges`. */
+export const INTERCHANGE_DEFAULTS: Readonly<InterchangeOptions> = Object.freeze({ from: "corridors", changeCost: 2, interchanges: 16, perEdge: 2, radius: 2, discount: 0.5, detour: 1.5 });
+
+/** The largest number of candidate interchanges of the first pass. */
+const MAX_CANDIDATES = 64;
+
+/** One interchange: a place on the highway `h`, a place on the highway `g`, and the length of the link between the two places. */
+export interface Interchange {
+  readonly h: number;
+  readonly hAt: number;
+  readonly g: number;
+  readonly gAt: number;
+  readonly gap: number;
+}
+
+/** The nearest points of the segments `a b` and `c d`, as the parameters `s` and `t` from 0 to 1, with their distance. */
+function nearestOfSegments(a: Point, b: Point, c: Point, d: Point): { s: number; t: number; d: number } {
+  const ux = b.x - a.x;
+  const uy = b.y - a.y;
+  const vx = d.x - c.x;
+  const vy = d.y - c.y;
+  const at = (s: number, t: number): number => {
+    const dx = a.x + s * ux - (c.x + t * vx);
+    const dy = a.y + s * uy - (c.y + t * vy);
+    // `Math.sqrt` is exact on each platform. `Math.hypot` is not.
+    return Math.sqrt(dx * dx + dy * dy);
+  };
+  const clamp = (v: number): number => Math.min(1, Math.max(0, v));
+  const uu = ux * ux + uy * uy;
+  const vv = vx * vx + vy * vy;
+  const project = (p: Point, q: Point, x: number, y: number, len: number): number => (len > 0 ? clamp(((p.x - q.x) * x + (p.y - q.y) * y) / len) : 0);
+  // The four ends against the other segment, and the crossing point, give the nearest pair.
+  const tries: [number, number][] = [
+    [0, project(a, c, vx, vy, vv)],
+    [1, project(b, c, vx, vy, vv)],
+    [project(c, a, ux, uy, uu), 0],
+    [project(d, a, ux, uy, uu), 1],
+  ];
+  const den = ux * vy - uy * vx;
+  if (Math.abs(den) > 1e-12) {
+    const s = ((c.x - a.x) * vy - (c.y - a.y) * vx) / den;
+    const t = ((c.x - a.x) * uy - (c.y - a.y) * ux) / den;
+    if (s >= 0 && s <= 1 && t >= 0 && t <= 1) tries.push([s, t]);
+  }
+  let best = { s: 0, t: 0, d: Infinity };
+  for (const [s, t] of tries) {
+    const v = at(s, t);
+    if (v < best.d - 1e-12) best = { s, t, d: v };
+  }
+  return best;
+}
+
+/** This function gives the candidate interchanges: the nearest places of each pair of spines that come within `radius`, with a link in clear view. */
+export function interchangeCandidates(spines: readonly (readonly Point[])[], radius: number, clear: (a: Point, b: Point) => boolean): Interchange[] {
+  const out: Interchange[] = [];
+  for (let h = 0; h < spines.length; h++) {
+    for (let g = h + 1; g < spines.length; g++) {
+      const p = spines[h]!;
+      const q = spines[g]!;
+      let best: Interchange | undefined;
+      for (let i = 0; i + 1 < p.length; i++) {
+        for (let j = 0; j + 1 < q.length; j++) {
+          const n = nearestOfSegments(p[i]!, p[i + 1]!, q[j]!, q[j + 1]!);
+          if (n.d <= radius && (!best || n.d < best.gap - 1e-12)) best = { h, hAt: i + n.s, g, gAt: j + n.t, gap: n.d };
+        }
+      }
+      if (best && (best.gap <= 1e-9 || clear(pointAt(p, best.hAt), pointAt(q, best.gAt)))) out.push(best);
+    }
+  }
+  return out.sort((x, y) => x.gap - y.gap || x.h - y.h || x.g - y.g).slice(0, MAX_CANDIDATES);
+}
+
+/** One leg of the way of an edge: the highway and its two places. */
+interface Leg {
+  readonly h: number;
+  readonly on: number;
+  readonly off: number;
+}
+
+/** The best way of one edge over the network, with the interchanges that it uses. */
+interface Trip {
+  readonly legs: readonly Leg[];
+  readonly used: readonly number[];
+}
+
+/**
+ * This function gives the highways of a network with interchanges (HWY-060). The highways come from a plan. Two highways that come near get an interchange.
+ * Each edge takes its cheapest way: a ride on one highway, or on up to `perEdge` highways with a change at an interchange.
+ * A change costs `changeCost` units. The interchanges that the most edges use stay, up to `interchanges`.
+ */
+export function interchangePlan(input: HighwayInput, o: Readonly<InterchangeOptions>): HighwayPlan {
+  const graph = input.graph;
+  const base = basePlan(input, o.from);
+  const spines = base.highways.map((h) => h.spine);
+  if (spines.length === 0) return { highways: [] };
+  const finder = new WayFinder(graph.nodes);
+  const pad = finder.margin / 2;
+  const unit = boardUnit(graph);
+  const first = firstRoutes(input);
+  const change = Math.max(0, o.changeCost) * unit;
+  const perEdge = Math.min(3, Math.max(1, Math.round(o.perEdge)));
+  const disc = Math.min(1, Math.max(0.05, o.discount));
+  const ride = (h: number, a: number, b: number): number => lengthBetween(spines[h]!, Math.min(a, b), Math.max(a, b));
+  const edges = edgePlugs(graph).map((p) => {
+    const s = finder.out(p.ps);
+    const t = finder.out(p.pt);
+    const route = first.get(p.edge.id);
+    const ends = spines.map((spine) => {
+      const on = nearestPlace(spine, s);
+      const off = nearestPlace(spine, t);
+      return { on, off, rampIn: dist(s, pointAt(spine, on)), rampOut: dist(pointAt(spine, off), t) };
+    });
+    return { edge: p.edge.id, s, t, base: route ? polylineLength(route) : dist(s, t), ends };
+  });
+
+  // The cheapest way of one edge over the interchanges `list`. The cost counts a ride at `disc` times its length. Each leg is one margin long or more.
+  const tripOf = (e: (typeof edges)[number], list: readonly Interchange[]): Trip | undefined => {
+    const found: { cost: number; trip: Trip | undefined } = { cost: Infinity, trip: undefined };
+    const offer = (cost: number, length: number, trip: Trip): void => {
+      if (trip.legs.some((l) => ride(l.h, l.on, l.off) < finder.margin)) return;
+      if (cost >= e.base || length > o.detour * e.base) return;
+      if (cost < found.cost - 1e-9) [found.cost, found.trip] = [cost, trip];
+    };
+    spines.forEach((_, h) => {
+      const x = e.ends[h]!;
+      const r = ride(h, x.on, x.off);
+      offer(x.rampIn + disc * r + x.rampOut, x.rampIn + r + x.rampOut, { legs: [{ h, on: x.on, off: x.off }], used: [] });
+    });
+    if (perEdge < 2) return found.trip;
+    // Each interchange, in both directions: on `p` at its place `pAt`, then off at the place `qAt` of `q`.
+    const sides = list.flatMap((c, i) => [
+      { i, p: c.h, pAt: c.hAt, q: c.g, qAt: c.gAt, gap: c.gap },
+      { i, p: c.g, pAt: c.gAt, q: c.h, qAt: c.hAt, gap: c.gap },
+    ]);
+    for (const a of sides) {
+      const x = e.ends[a.p]!;
+      const y = e.ends[a.q]!;
+      const r1 = ride(a.p, x.on, a.pAt);
+      const r2 = ride(a.q, a.qAt, y.off);
+      offer(x.rampIn + disc * (r1 + r2) + a.gap + change + y.rampOut, x.rampIn + r1 + r2 + a.gap + y.rampOut, {
+        legs: [
+          { h: a.p, on: x.on, off: a.pAt },
+          { h: a.q, on: a.qAt, off: y.off },
+        ],
+        used: [a.i],
+      });
+      if (perEdge < 3) continue;
+      for (const b of sides) {
+        if (b.p !== a.q || b.q === a.p || b.i === a.i) continue;
+        const z = e.ends[b.q]!;
+        const r3 = ride(a.q, a.qAt, b.pAt);
+        const r4 = ride(b.q, b.qAt, z.off);
+        offer(x.rampIn + disc * (r1 + r3 + r4) + a.gap + b.gap + 2 * change + z.rampOut, x.rampIn + r1 + r3 + r4 + a.gap + b.gap + z.rampOut, {
+          legs: [
+            { h: a.p, on: x.on, off: a.pAt },
+            { h: a.q, on: a.qAt, off: b.pAt },
+            { h: b.q, on: b.qAt, off: z.off },
+          ],
+          used: [a.i, b.i],
+        });
+      }
+    }
+    return found.trip;
+  };
+
+  const clear = (a: Point, b: Point): boolean => finder.obstacles.clear(a, b, pad);
+  const candidates = interchangeCandidates(spines, Math.max(0, o.radius) * unit, clear);
+  // The first pass counts the edges at each candidate. The busiest candidates stay for the second pass.
+  const use = new Array<number>(candidates.length).fill(0);
+  for (const e of edges) for (const i of tripOf(e, candidates)?.used ?? []) use[i] = use[i]! + 1;
+  const kept = candidates
+    .map((c, i) => ({ c, i, n: use[i]! }))
+    .filter((x) => x.n > 0)
+    .sort((x, y) => y.n - x.n || x.i - y.i)
+    .slice(0, Math.max(1, Math.round(o.interchanges)))
+    .sort((x, y) => x.i - y.i)
+    .map((x) => x.c);
+
+  const riders = spines.map(() => [] as { edge: string; on: number; off: number; seq: number; points: Point[] }[]);
+  for (const e of edges) {
+    const trip = tripOf(e, kept);
+    if (!trip) continue;
+    trip.legs.forEach((l, seq) => riders[l.h]!.push({ edge: e.edge, on: l.on, off: l.off, seq, points: [e.s, ...spinePart(spines[l.h]!, l.on, l.off), e.t] }));
+  }
+  const highways: Highway[] = [];
+  spines.forEach((spine, h) => {
+    const list = riders[h]!;
+    if (list.length < 2) return;
+    const lanes = orderLanes(spine, list.map((r) => ({ edge: r.edge, points: r.points })), "bundle");
+    const byEdge = new Map(list.map((r) => [r.edge, r]));
+    const members: HighwayMember[] = lanes.map((edge) => {
+      const r = byEdge.get(edge)!;
+      return memberAt(spine, edge, r.on, r.off, r.seq);
+    });
+    highways.push({ id: `h${h}`, key: base.highways[h]!.key, spine, lanes, members });
+  });
+  return tidyPlan({ highways });
+}