@mark1russell7/highways 0.4.2 → 0.5.1

package/src/highways/territories/index.ts

@@ -0,0 +1,150 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { firstRoutes } from "../base.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { snapPlan, type SnapLine, type SnapMember } from "../snap.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The characteristic points of the territories: the plugs, the bends of the first routes, or both. */
+export type TerritoryPoints = "plugs" | "bends" | "both";
+
+/** The values of `TerritoryPoints`. */
+export const TERRITORY_POINTS: readonly TerritoryPoints[] = Object.freeze(["plugs", "bends", "both"]);
+
+/** The options of the highway strategy `territories` (HWY-033 of the note on highways). */
+export interface TerritoryOptions {
+  /** The radius of a group of points, in units of the board. The default is 4. */
+  readonly radius: number;
+  /** A flow between two cells becomes a highway when this number of edges or more cross it. The default is 2. */
+  readonly minSize: number;
+  /** The characteristic points. The default is `both`. */
+  readonly points: TerritoryPoints;
+}
+
+/** The default options of the strategy `territories`. */
+export const TERRITORY_DEFAULTS: Readonly<TerritoryOptions> = Object.freeze({ radius: 4, minSize: 2, points: "both" });
+
+/**
+ * This function puts points into groups of the radius `r` (Andrienko and Andrienko 2011). Each point joins the group with the nearest centre within `r`.
+ * Else it starts a new group. The centre of a group is the mean of its points. A second pass puts each point into the group of its nearest centre.
+ * The result is the centres of the groups that keep points.
+ */
+export function pointGroups(points: readonly Point[], r: number): Point[] {
+  const sums: { x: number; y: number; n: number }[] = [];
+  const centre = (g: { x: number; y: number; n: number }): Point => ({ x: g.x / g.n, y: g.y / g.n });
+  for (const p of points) {
+    let best = -1;
+    let bestD = Infinity;
+    sums.forEach((g, i) => {
+      const d = dist(p, centre(g));
+      if (d < bestD) [best, bestD] = [i, d];
+    });
+    if (best >= 0 && bestD <= r) {
+      const g = sums[best]!;
+      g.x += p.x;
+      g.y += p.y;
+      g.n++;
+    } else sums.push({ x: p.x, y: p.y, n: 1 });
+  }
+  const first = sums.map(centre);
+  const again = first.map(() => ({ x: 0, y: 0, n: 0 }));
+  for (const p of points) {
+    const i = nearestCentre(first, p);
+    again[i]!.x += p.x;
+    again[i]!.y += p.y;
+    again[i]!.n++;
+  }
+  return again.filter((g) => g.n > 0).map(centre);
+}
+
+/** This function gives the index of the centre nearest to `p`. The first of two equal centres wins. */
+export function nearestCentre(centres: readonly Point[], p: Point): number {
+  let best = -1;
+  let bestD = Infinity;
+  centres.forEach((c, i) => {
+    const d = dist(p, c);
+    if (d < bestD) [best, bestD] = [i, d];
+  });
+  return best;
+}
+
+/** One crossing of a route from the cell `from` into the cell `to`, at the share `at` of the length of the route. */
+export interface CellStep {
+  readonly from: number;
+  readonly to: number;
+  readonly at: number;
+}
+
+/**
+ * This function gives the crossings of the cells of a polyline. The cells are the Voronoi cells of the centres.
+ * It samples the polyline at the spacing `step`, and gives each change of the nearest centre.
+ */
+export function cellSteps(line: readonly Point[], centres: readonly Point[], step: number): CellStep[] {
+  const total = polylineLength(line);
+  if (line.length < 2 || centres.length === 0 || total <= 0) return [];
+  const out: CellStep[] = [];
+  let cell = nearestCentre(centres, line[0]!);
+  let walked = 0;
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!;
+    const b = line[i]!;
+    const len = dist(a, b);
+    const n = Math.max(1, Math.ceil(len / Math.max(1e-6, step)));
+    for (let k = 1; k <= n; k++) {
+      const t = k / n;
+      const c = nearestCentre(centres, { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t });
+      if (c !== cell) {
+        out.push({ from: cell, to: c, at: (walked + len * t) / total });
+        cell = c;
+      }
+    }
+    walked += len;
+  }
+  return out;
+}
+
+/**
+ * This function gives the highways of the territories of the flows (HWY-033, Andrienko and Andrienko 2011).
+ * The characteristic points form groups of the radius `radius`. The centres of the groups make Voronoi cells.
+ * Each first route becomes a list of crossings between neighbour cells.
+ *
+ * A pair of cells with `minSize` crossings or more is a line from centre to centre. The edges that cross it snap to it. The centres of the cells are the interchanges.
+ */
+export function territoryPlan(input: HighwayInput, o: Readonly<TerritoryOptions>): HighwayPlan {
+  const graph = input.graph;
+  const unit = boardUnit(graph);
+  const r = Math.max(0.5, o.radius) * unit;
+  const routes = firstRoutes(input);
+  const plugs = edgePlugs(graph);
+  const points: Point[] = [];
+  for (const { edge, ps, pt } of plugs) {
+    if (o.points !== "bends") points.push(ps.point, pt.point);
+    if (o.points !== "plugs") {
+      const route = routes.get(edge.id) ?? [];
+      for (let i = 1; i < route.length - 1; i++) points.push(route[i]!);
+    }
+  }
+  if (points.length === 0) return { highways: [] };
+  const centres = pointGroups(points, r);
+  // The crossings of each pair of cells, in the order of the edges.
+  const flows = new Map<string, { a: number; b: number; members: SnapMember[] }>();
+  for (const { edge, ps, pt } of plugs) {
+    const route = routes.get(edge.id) ?? [ps.point, pt.point];
+    const seen = new Set<string>();
+    for (const s of cellSteps(route, centres, r / 4)) {
+      const [a, b] = s.from < s.to ? [s.from, s.to] : [s.to, s.from];
+      const key = `${a}:${b}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const flow = flows.get(key) ?? { a, b, members: [] };
+      flow.members.push({ edge: edge.id, from: centres[s.from]!, to: centres[s.to]!, at: s.at });
+      flows.set(key, flow);
+    }
+  }
+  const min = Math.max(2, Math.round(o.minSize));
+  const lines: SnapLine[] = [...flows.values()]
+    .filter((f) => f.members.length >= min)
+    .sort((p, q) => p.a - q.a || p.b - q.b)
+    .map((f) => ({ key: `t${f.a}-${f.b}`, a: centres[f.a]!, b: centres[f.b]!, members: f.members }));
+  return snapPlan(input, lines, { minSize: min });
+}

package/src/highways/trace.ts

@@ -0,0 +1,153 @@
+import { dist, type Point } from "../geom.ts";
+import type { Obstacles } from "../visibility.ts";
+import type { WayFinder } from "../ways.ts";
+import type { HighwayInput, HighwayPlan } from "./model.ts";
+import { edgePlugs, sharedStretches, type KeyedWay } from "./stretches.ts";
+
+/** The options of `tracePlan`. */
+export interface TraceOptions {
+  /** The side of the grid that the waypoints snap to, in units of the board. The value 0 keeps each waypoint where it is. */
+  readonly snap: number;
+  /** A highway has this number of edges or more. The value is 2 or more. */
+  readonly minSize: number;
+  /** The key of the ways. Only the ways with one key share a highway. */
+  readonly key: string;
+}
+
+/**
+ * This function moves a point out of each box, made larger by `pad`. A point in a box moves to the nearest side of that box.
+ * The function tries four times, so a point between two near boxes can stay in a box.
+ */
+export function outOfBoxes(obstacles: Obstacles, p: Point, pad: number): Point {
+  let q = p;
+  for (let k = 0; k < 4; k++) {
+    let hit: { x: number; y: number; w: number; h: number } | undefined;
+    obstacles.query({ x: q.x - pad, y: q.y - pad, w: 2 * pad, h: 2 * pad }, (n) => {
+      const b = n.box;
+      if (!hit && q.x > b.x - pad && q.x < b.x + b.w + pad && q.y > b.y - pad && q.y < b.y + b.h + pad) hit = b;
+    });
+    if (!hit) return q;
+    const b = hit;
+    const eps = 1e-3;
+    const moves = [
+      { d: q.x - (b.x - pad), p: { x: b.x - pad - eps, y: q.y } },
+      { d: b.x + b.w + pad - q.x, p: { x: b.x + b.w + pad + eps, y: q.y } },
+      { d: q.y - (b.y - pad), p: { x: q.x, y: b.y - pad - eps } },
+      { d: b.y + b.h + pad - q.y, p: { x: q.x, y: b.y + b.h + pad + eps } },
+    ];
+    moves.sort((u, v) => u.d - v.d);
+    q = moves[0]!.p;
+  }
+  return q;
+}
+
+/**
+ * This function gives the push of the boxes on a point. Each box nearer than `reach` adds a unit vector away from it, times `(reach - d) / reach`.
+ * The value `d` is the distance from the point to the box. It is the gradient of a field that is 0 at the distance `reach` from each box.
+ */
+export function boxPush(obstacles: Obstacles, p: Point, reach: number): Point {
+  let x = 0;
+  let y = 0;
+  if (reach <= 0) return { x, y };
+  obstacles.query({ x: p.x - reach, y: p.y - reach, w: 2 * reach, h: 2 * reach }, (n) => {
+    const b = n.box;
+    const qx = Math.max(b.x, Math.min(b.x + b.w, p.x));
+    const qy = Math.max(b.y, Math.min(b.y + b.h, p.y));
+    let dx = p.x - qx;
+    let dy = p.y - qy;
+    let d = Math.hypot(dx, dy);
+    if (d >= reach) return;
+    if (d < 1e-9) {
+      // The point is in the box: it goes out through the nearest side.
+      const sides = [
+        { d: p.x - b.x, v: [-1, 0] },
+        { d: b.x + b.w - p.x, v: [1, 0] },
+        { d: p.y - b.y, v: [0, -1] },
+        { d: b.y + b.h - p.y, v: [0, 1] },
+      ].sort((u, v) => u.d - v.d);
+      [dx, dy] = sides[0]!.v as [number, number];
+      d = 0;
+    } else {
+      dx /= d;
+      dy /= d;
+    }
+    const f = (reach - d) / reach;
+    x += dx * f;
+    y += dy * f;
+  });
+  return { x, y };
+}
+
+/** This function gives points at equal steps of `step` or a little less along a polyline, without its two ends. A polyline without length gives no point. */
+export function innerPoints(line: readonly Point[], step: number): Point[] {
+  const at: number[] = [0];
+  for (let i = 1; i < line.length; i++) at.push(at[i - 1]! + dist(line[i - 1]!, line[i]!));
+  const total = at[at.length - 1] ?? 0;
+  if (total <= 1e-9 || step <= 0) return [];
+  const count = Math.floor(total / step);
+  const out: Point[] = [];
+  let j = 1;
+  for (let k = 1; k <= count; k++) {
+    const s = (total * k) / (count + 1);
+    while (j < line.length - 1 && at[j]! < s) j++;
+    const a = line[j - 1]!;
+    const b = line[j]!;
+    const len = at[j]! - at[j - 1]!;
+    const u = len > 0 ? Math.max(0, Math.min(1, (s - at[j - 1]!) / len)) : 0;
+    out.push({ x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+  }
+  return out;
+}
+
+/**
+ * This function gives the way of one edge through its waypoints. The way starts at `a` and ends at `b`.
+ * Each waypoint snaps to the grid of side `snap`. A waypoint in a box moves to the nearest corner of the corner graph.
+ * From each waypoint to the next one, the way is a straight line when that line is clear. Otherwise it goes through the corner graph.
+ * A waypoint that the graph does not reach is not on the way. When the way cannot reach `b`, the function gives the way of the corner graph from `a` to `b`.
+ */
+export function waypointWay(finder: WayFinder, a: Point, b: Point, waypoints: readonly Point[], snap: number): Point[] | undefined {
+  const corners = finder.corners;
+  const pad = finder.margin / 2;
+  const fixed: Point[] = [];
+  for (const w of waypoints) {
+    let q = snap > 0 ? { x: Math.round(w.x / snap) * snap, y: Math.round(w.y / snap) * snap } : w;
+    if (finder.obstacles.inside(q, pad)) {
+      const i = corners.nearest(q);
+      if (i < 0) continue;
+      q = corners.points[i]!;
+    }
+    const last = fixed[fixed.length - 1];
+    if (last && dist(last, q) <= 1e-9) continue;
+    fixed.push(q);
+  }
+  const out: Point[] = [a];
+  let at = a;
+  for (const q of fixed) {
+    if (dist(at, q) <= 1e-9) continue;
+    const piece = corners.path(at, q);
+    if (!piece) continue;
+    out.push(...piece.slice(1));
+    at = q;
+  }
+  const tail = dist(at, b) <= 1e-9 ? [b] : corners.path(at, b);
+  if (!tail) return corners.path(a, b);
+  out.push(...tail.slice(1));
+  return out;
+}
+
+/**
+ * This function gives the highways of the waypoints of each edge. The ways go through the corner graph, so they stay out of the boxes.
+ * Each edge goes from the point at `margin` from its source plug, through its waypoints, to the point at `margin` from its target plug.
+ * Each stretch that `minSize` ways or more share is one highway, with the needless corners removed.
+ * An edge without waypoints takes its way of the corner graph.
+ */
+export function tracePlan(input: HighwayInput, finder: WayFinder, waypoints: ReadonlyMap<string, readonly Point[]>, o: Readonly<TraceOptions>): HighwayPlan {
+  const ways: KeyedWay[] = [];
+  for (const { edge, ps, pt } of edgePlugs(input.graph)) {
+    const a = finder.out(ps);
+    const b = finder.out(pt);
+    const way = waypointWay(finder, a, b, waypoints.get(edge.id) ?? [], o.snap);
+    if (way) ways.push({ edge: edge.id, key: o.key, points: way });
+  }
+  return sharedStretches(ways, { minSize: o.minSize, pull: (p) => finder.corners.pull(p) });
+}

package/src/highways/traclus/index.ts

@@ -0,0 +1,296 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, pointSegmentDistance, polylineLength, type Point } from "../../geom.ts";
+import { orderLanes } from "../../segments.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import { firstRoutes, nearestPlace, orderAlongRoutes, tidyPlan } from "../base.ts";
+import { lengthBetween, memberAt, type Highway, type HighwayInput, type HighwayMember, type HighwayPlan } from "../model.ts";
+
+/** The options of the highway strategy `traclus` (HWY-025 of the note on highways). */
+export interface TraclusOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** Two segments are neighbours when their distance is this value or less, in units of the board. The default is 2. */
+  readonly eps: number;
+  /** A cluster has segments of this number of edges or more, and a core segment has this number of neighbours or more. The default is 3. */
+  readonly minLns: number;
+  /** The weight of the perpendicular distance. The default is 1. */
+  readonly wPerp: number;
+  /** The weight of the parallel distance. The default is 1. */
+  readonly wPar: number;
+  /** The weight of the angle distance. The default is 1. */
+  readonly wTheta: number;
+  /** A route keeps a corner when the cost of the line without it is more than this value times the cost with it. The default is 1. */
+  readonly mdl: number;
+}
+
+/** The default options of the strategy `traclus`. */
+export const TRACLUS_DEFAULTS: Readonly<Required<Omit<TraclusOptions, "margin" | "k">>> = Object.freeze({ eps: 2, minLns: 3, wPerp: 1, wPar: 1, wTheta: 1, mdl: 1 });
+
+/** One segment of a partitioned route: the edge, the index of the segment in the route, and its two ends. */
+export interface RouteSegment {
+  readonly edge: string;
+  readonly index: number;
+  readonly a: Point;
+  readonly b: Point;
+}
+
+/** This function gives the distance of the point `p` to the line through `a` and `b`. It also gives the place of its projection as a share of `ab`. */
+function project(p: Point, a: Point, b: Point): { perp: number; u: number } {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const len2 = dx * dx + dy * dy;
+  if (len2 < 1e-12) return { perp: dist(p, a), u: 0 };
+  const u = ((p.x - a.x) * dx + (p.y - a.y) * dy) / len2;
+  return { perp: Math.abs((p.x - a.x) * dy - (p.y - a.y) * dx) / Math.sqrt(len2), u };
+}
+
+/**
+ * This function gives the TRACLUS distance of two segments (Lee, Han and Whang 2007): `w_perp d_perp + w_par d_par + w_theta d_theta`.
+ * `d_perp` is `(l1² + l2²) / (l1 + l2)` with the distances of the ends of the shorter segment to the line of the longer segment.
+ * `d_par` is the gap along the longer segment between the two segments, 0 when they overlap. `d_theta` is `|shorter| sin(theta)`.
+ * The segments have no direction, so the angle is 90 degrees or less.
+ */
+export function segmentDistance(p: { a: Point; b: Point }, q: { a: Point; b: Point }, w: { perp: number; par: number; theta: number }): number {
+  const [long, short] = dist(p.a, p.b) >= dist(q.a, q.b) ? [p, q] : [q, p];
+  const len = dist(long.a, long.b);
+  const s = project(short.a, long.a, long.b);
+  const e = project(short.b, long.a, long.b);
+  const perp = s.perp + e.perp > 1e-12 ? (s.perp * s.perp + e.perp * e.perp) / (s.perp + e.perp) : 0;
+  const lo = Math.min(s.u, e.u);
+  const hi = Math.max(s.u, e.u);
+  const par = (hi < 0 ? -hi : lo > 1 ? lo - 1 : 0) * len;
+  const shortLen = dist(short.a, short.b);
+  let theta = 0;
+  if (len > 1e-12 && shortLen > 1e-12) {
+    const cos = Math.abs(((long.b.x - long.a.x) * (short.b.x - short.a.x) + (long.b.y - long.a.y) * (short.b.y - short.a.y)) / (len * shortLen));
+    theta = shortLen * Math.sqrt(Math.max(0, 1 - cos * cos));
+  }
+  return w.perp * perp + w.par * par + w.theta * theta;
+}
+
+/**
+ * This function gives the characteristic points of a route by the rule of the minimum description length (MDL) of TRACLUS.
+ * A partition from point `i` to point `j` costs `L(H) + L(D|H)`. `L(H)` is the log of its length, and `L(D|H)` the logs of the perpendicular and angle distances of the route parts.
+ * The route keeps the point before `j` when that cost is more than `ratio` times the cost of the route parts. The lengths are in units of the board.
+ */
+export function characteristicPoints(route: readonly Point[], unit: number, ratio: number): Point[] {
+  const n = route.length;
+  if (n <= 2) return [...route];
+  const lg = (x: number): number => Math.log2(1 + x / unit);
+  const costs = (i: number, j: number): { par: number; nopar: number } => {
+    const a = route[i]!;
+    const b = route[j]!;
+    let perp = 0;
+    let theta = 0;
+    let nopar = 0;
+    for (let k = i; k < j; k++) {
+      const part = { a: route[k]!, b: route[k + 1]! };
+      perp += segmentDistance({ a, b }, part, { perp: 1, par: 0, theta: 0 });
+      theta += segmentDistance({ a, b }, part, { perp: 0, par: 0, theta: 1 });
+      nopar += lg(dist(part.a, part.b));
+    }
+    return { par: lg(dist(a, b)) + lg(perp) + lg(theta), nopar };
+  };
+  const out: Point[] = [route[0]!];
+  let start = 0;
+  let length = 1;
+  while (start + length < n) {
+    const curr = start + length;
+    const c = costs(start, curr);
+    if (c.par > ratio * c.nopar && curr - 1 > start) {
+      out.push(route[curr - 1]!);
+      start = curr - 1;
+      length = 1;
+    } else length++;
+  }
+  out.push(route[n - 1]!);
+  return out;
+}
+
+/**
+ * This function gives the clusters of segments of DBSCAN. A segment with `minLns` neighbours or more within `eps` (itself included) is a core segment.
+ * A cluster grows from each core segment through its neighbours. A cluster with segments of fewer than `minLns` edges is dropped.
+ */
+export function segmentClusters(segments: readonly RouteSegment[], eps: number, minLns: number, w: { perp: number; par: number; theta: number }): RouteSegment[][] {
+  const n = segments.length;
+  // A grid of cells of side `eps` prunes the pairs. Two segments within `eps` have boxes within `eps` of each other in each axis.
+  const near: number[][] = segments.map(() => []);
+  const box = segments.map((s) => ({ x0: Math.min(s.a.x, s.b.x), y0: Math.min(s.a.y, s.b.y), x1: Math.max(s.a.x, s.b.x), y1: Math.max(s.a.y, s.b.y) }));
+  for (let i = 0; i < n; i++) {
+    near[i]!.push(i);
+    for (let j = i + 1; j < n; j++) {
+      const a = box[i]!;
+      const b = box[j]!;
+      if (a.x0 > b.x1 + eps || b.x0 > a.x1 + eps || a.y0 > b.y1 + eps || b.y0 > a.y1 + eps) continue;
+      if (segmentDistance(segments[i]!, segments[j]!, w) <= eps) {
+        near[i]!.push(j);
+        near[j]!.push(i);
+      }
+    }
+  }
+  const label = new Int32Array(n).fill(-1);
+  const out: RouteSegment[][] = [];
+  for (let i = 0; i < n; i++) {
+    if (label[i] !== -1 || near[i]!.length < minLns) continue;
+    const id = out.length;
+    const members: number[] = [];
+    const queue = [i];
+    label[i] = id;
+    while (queue.length > 0) {
+      const k = queue.shift()!;
+      members.push(k);
+      if (near[k]!.length < minLns) continue;
+      for (const j of near[k]!) {
+        if (label[j] !== -1) continue;
+        label[j] = id;
+        queue.push(j);
+      }
+    }
+    out.push(members.sort((a, b) => a - b).map((k) => segments[k]!));
+  }
+  return out.filter((c) => new Set(c.map((s) => s.edge)).size >= minLns);
+}
+
+/**
+ * This function gives the representative line of a cluster of segments. The line goes along the mean direction of the segments.
+ * A sweep along that direction stops at each end of a segment. Where `minLns` segments or more cover the stop, the point is the mean of their points there.
+ * Two points of the line are at least `gap` apart.
+ */
+export function representative(cluster: readonly RouteSegment[], minLns: number, gap: number): Point[] {
+  const first = cluster[0]!;
+  const fx = first.b.x - first.a.x;
+  const fy = first.b.y - first.a.y;
+  let vx = 0;
+  let vy = 0;
+  for (const s of cluster) {
+    let dx = s.b.x - s.a.x;
+    let dy = s.b.y - s.a.y;
+    const len = Math.hypot(dx, dy);
+    if (len < 1e-9) continue;
+    if (dx * fx + dy * fy < 0) [dx, dy] = [-dx, -dy];
+    vx += dx / len;
+    vy += dy / len;
+  }
+  const vl = Math.hypot(vx, vy);
+  if (vl < 1e-9) return [];
+  const ux = vx / vl;
+  const uy = vy / vl;
+  const along = (p: Point): number => p.x * ux + p.y * uy;
+  const across = (p: Point): number => -p.x * uy + p.y * ux;
+  const spans = cluster.map((s) => {
+    const [p, q] = along(s.a) <= along(s.b) ? [s.a, s.b] : [s.b, s.a];
+    return { x0: along(p), y0: across(p), x1: along(q), y1: across(q) };
+  });
+  const stops = [...new Set(spans.flatMap((s) => [s.x0, s.x1]))].sort((a, b) => a - b);
+  const out: Point[] = [];
+  let lastX = -Infinity;
+  for (const x of stops) {
+    const cover = spans.filter((s) => s.x0 <= x + 1e-9 && s.x1 >= x - 1e-9);
+    if (cover.length < minLns) continue;
+    if (x - lastX < gap) continue;
+    let y = 0;
+    for (const s of cover) y += s.x1 - s.x0 > 1e-9 ? s.y0 + ((s.y1 - s.y0) * (x - s.x0)) / (s.x1 - s.x0) : (s.y0 + s.y1) / 2;
+    y /= cover.length;
+    out.push({ x: x * ux - y * uy, y: x * uy + y * ux });
+    lastX = x;
+  }
+  return out;
+}
+
+/** This function gives the distance of the point `p` to the polyline `line`. */
+function lineDistance(line: readonly Point[], p: Point): number {
+  let best = Infinity;
+  for (let i = 1; i < line.length; i++) best = Math.min(best, pointSegmentDistance(p, line[i - 1]!, line[i]!));
+  return best;
+}
+
+/** The largest ratio of the length along the spine of a member to the length of its own route between the same ends. */
+const DETOUR = 1.25;
+
+/**
+ * This function gives the highways of TRACLUS (HWY-025). Each first route breaks into a few long segments by the rule of MDL.
+ * DBSCAN puts the segments that are near in distance and angle into clusters. Each cluster with segments of `minLns` edges or more is one highway.
+ * The spine is the representative line of the cluster, or a way through the corner graph between its ends when the line hits a box.
+ * Each edge of the cluster joins the spine nearest to the first end of its segments. It leaves the spine nearest to the last end.
+ * An edge rides only when both ends of its part are within `eps` of the spine.
+ * Its length on the spine is also at most 1.25 times the length of its own route there.
+ * Each edge rides one highway at most: the highway where it rides the longest length.
+ */
+export function traclusPlan(input: HighwayInput, o: Readonly<TraclusOptions>): HighwayPlan {
+  const graph = input.graph;
+  const unit = boardUnit(graph);
+  const finder = new WayFinder(graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const pad = finder.margin / 2;
+  const routes = firstRoutes(input);
+  const segments: RouteSegment[] = [];
+  const corners = new Map<string, Point[]>();
+  for (const e of graph.edges) {
+    const route = routes.get(e.id);
+    if (!route || route.length < 2) continue;
+    const cps = characteristicPoints(route, unit, o.mdl);
+    corners.set(e.id, cps);
+    for (let i = 1; i < cps.length; i++) if (dist(cps[i - 1]!, cps[i]!) > 1e-9) segments.push({ edge: e.id, index: i - 1, a: cps[i - 1]!, b: cps[i]! });
+  }
+  const minLns = Math.max(2, Math.round(o.minLns));
+  const w = { perp: o.wPerp, par: o.wPar, theta: o.wTheta };
+  const eps = o.eps * unit;
+  const clusters = segmentClusters(segments, eps, minLns, w);
+  type Placed = { edge: string; on: number; off: number; ride: number };
+  const found: { spine: Point[]; placed: Placed[] }[] = [];
+  for (const cluster of clusters) {
+    const line = representative(cluster, minLns, finder.margin);
+    if (line.length < 2 || polylineLength(line) <= finder.margin) continue;
+    let spine: Point[] | undefined = line;
+    if (!finder.obstacles.clearPath(line, pad) || line.some((p) => finder.obstacles.inside(p, pad))) {
+      const a = line[0]!;
+      const b = line[line.length - 1]!;
+      const way = finder.obstacles.inside(a, pad) || finder.obstacles.inside(b, pad) ? undefined : finder.corners.path(a, b);
+      spine = way ? finder.corners.pull(way) : undefined;
+    }
+    if (!spine || spine.length < 2 || polylineLength(spine) <= finder.margin) continue;
+    // The part of each edge in the cluster: its first and its last segment in the order of its route.
+    const parts = new Map<string, { first: RouteSegment; last: RouteSegment }>();
+    for (const s of cluster) {
+      const p = parts.get(s.edge);
+      if (!p) parts.set(s.edge, { first: s, last: s });
+      else {
+        if (s.index < p.first.index) p.first = s;
+        if (s.index > p.last.index) p.last = s;
+      }
+    }
+    const placed: Placed[] = [];
+    for (const [edge, p] of parts) {
+      if (lineDistance(spine, p.first.a) > eps || lineDistance(spine, p.last.b) > eps) continue;
+      const on = nearestPlace(spine, p.first.a);
+      const off = nearestPlace(spine, p.last.b);
+      const ride = lengthBetween(spine, Math.min(on, off), Math.max(on, off));
+      const own = polylineLength(corners.get(edge)!.slice(p.first.index, p.last.index + 2));
+      if (ride > finder.margin && ride <= DETOUR * own + finder.margin) placed.push({ edge, on, off, ride });
+    }
+    if (placed.length >= 2) found.push({ spine, placed });
+  }
+  // Each edge keeps the highway where it rides the longest length. The first highway wins a tie.
+  const best = new Map<string, { at: number; ride: number }>();
+  found.forEach((f, at) => {
+    for (const x of f.placed) if ((best.get(x.edge)?.ride ?? -1) < x.ride) best.set(x.edge, { at, ride: x.ride });
+  });
+  const highways: Highway[] = [];
+  found.forEach((f, at) => {
+    const placed = f.placed.filter((x) => best.get(x.edge)!.at === at);
+    if (placed.length < 2) return;
+    const route = f.spine;
+    // The lane order reads the plugs of each edge on each side of the spine.
+    const trip = (x: Placed): Point[] => {
+      const own = routes.get(x.edge)!;
+      const [from, to] = [own[0]!, own[own.length - 1]!];
+      return x.on <= x.off ? [from, ...route, to] : [to, ...route, from];
+    };
+    const lanes = orderLanes(
+      route,
+      placed.map((x) => ({ edge: x.edge, points: trip(x) })),
+      "bundle",
+    );
+    const byEdge = new Map(placed.map((x) => [x.edge, x]));
+    const members: HighwayMember[] = lanes.map((edge) => memberAt(route, edge, byEdge.get(edge)!.on, byEdge.get(edge)!.off));
+    highways.push({ id: `h${highways.length}`, key: `t${highways.length}`, spine: route, lanes, members });
+  });
+  return tidyPlan(orderAlongRoutes({ highways }, routes));
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./plugs.ts";
 export * from "./curves.ts";
 export * from "./curves/index.ts";
 export * from "./visibility.ts";
+export * from "./channels.ts";
 export * from "./ways.ts";
 export * from "./segments.ts";
 export * from "./sections.ts";
@@ -31,3 +32,4 @@ export * from "./bench/screen/index.ts";
 export * from "./highways/index.ts";
 export * from "./order/index.ts";
 export * from "./repair/index.ts";
+export * from "./portfolio/index.ts";

package/src/portfolio/bands.ts

@@ -0,0 +1,33 @@
+/** The rule of the caller. Under `collection`, a shared segment holds edges of one collection only. Under `all`, collections can mix. */
+export type PortfolioRule = "collection" | "all";
+
+/** The stretch caps of the portfolio router: the caps of the gap closed (B10). */
+export type PortfolioCap = 1.1 | 1.25 | 1.5;
+
+/** The rules of the portfolio router. */
+export const PORTFOLIO_RULES: readonly PortfolioRule[] = ["collection", "all"];
+
+/** The caps of the portfolio router. */
+export const PORTFOLIO_CAPS: readonly PortfolioCap[] = [1.1, 1.25, 1.5];
+
+/** The sizes of the sets of the portfolio router, without the base. */
+export const PORTFOLIO_KS_API: readonly (3 | 5 | 8)[] = [3, 5, 8];
+
+/** One size band of the inputs. Each band has its own greedy sets. */
+export interface PortfolioBand {
+  readonly id: string;
+  /** The largest node count of the band. An input with more nodes than the last band uses the last band. */
+  readonly maxNodes: number;
+}
+
+/** The size bands: up to 12 nodes, 13 to 24 nodes, and 25 to 40 nodes. An input above 40 nodes uses the band `n25-40`. */
+export const PORTFOLIO_BANDS: readonly PortfolioBand[] = [
+  { id: "n1-12", maxNodes: 12 },
+  { id: "n13-24", maxNodes: 24 },
+  { id: "n25-40", maxNodes: 40 },
+];
+
+/** This function gives the band of a node count: the first band whose `maxNodes` is the count or more, else the last band. */
+export function portfolioBand(nodes: number, bands: readonly PortfolioBand[] = PORTFOLIO_BANDS): PortfolioBand {
+  return bands.find((b) => nodes <= b.maxNodes) ?? bands[bands.length - 1]!;
+}