@mark1russell7/highways 0.1.5 → 0.3.0

package/src/cases.ts

@@ -103,6 +103,18 @@ export function manyGroupsBoard(): Graph {
   return b.graph();
 }
 
+/** The options of `packedGridBoard`. */
+export interface PackedGridOptions {
+  /** The seed of the links. The default is 11. */
+  readonly seed?: number;
+  /** The number of columns. The default is 12. */
+  readonly cols?: number;
+  /** The number of rows. The default is 8. */
+  readonly rows?: number;
+  /** The number of long links between boxes far apart. The default is 48. */
+  readonly long?: number;
+}
+
 /**
  * This function makes the far view of a board after a host layout packs it.
  * The board has 96 boxes of one size in a grid of 12 columns and 8 rows.
@@ -110,12 +122,14 @@ export function manyGroupsBoard(): Graph {
  * The links have no channel between the boxes. The roadmap item ROOM measures this board before and after `makeRoom`.
  *
  * The board is not in `CASES`, because the digests of the router fix the output on each board of `CASES`.
+ * The options make a family of such boards for the measure suite. Without options, the board does not change.
  */
-export function packedGridBoard(): Graph {
-  const R = rng(11);
+export function packedGridBoard(options: PackedGridOptions = {}): Graph {
+  const R = rng(options.seed ?? 11);
   const b = new Board();
-  const cols = 12;
-  const rows = 8;
+  const cols = options.cols ?? 12;
+  const rows = options.rows ?? 8;
+  const long = options.long ?? 48;
   const w = 140;
   const h = 90;
   const id = (r: number, c: number): string => `p${r}-${c}`;
@@ -127,7 +141,29 @@ export function packedGridBoard(): Graph {
       const cc = Math.max(0, Math.min(cols - 1, c + step()));
       b.link(id(r, c), id(rr, cc));
     }
-  for (let n = 0; n < 48; n++) b.link(id(Math.floor(R() * rows), Math.floor(R() * cols)), id(Math.floor(R() * rows), Math.floor(R() * cols)));
+  for (let n = 0; n < long; n++) b.link(id(Math.floor(R() * rows), Math.floor(R() * cols)), id(Math.floor(R() * rows), Math.floor(R() * cols)));
+  return b.graph();
+}
+
+/**
+ * This function makes a packed board with three zoom levels of groups. The board has 256 touching boxes in a grid of 16 columns and 16 rows.
+ * The quadtree of `buildSections` splits it into 4, 16 and 64 groups. Each box links to a box near it, and 64 long links join boxes far apart.
+ * At each level, the boxes of the groups touch, so the level links have no channel. The roadmap item ROOM2 measures this board.
+ *
+ * The board is not in `CASES`, because the digests of the router fix the output on each board of `CASES`.
+ */
+export function nestedGridBoard(): Graph {
+  const R = rng(13);
+  const b = new Board();
+  const side = 16;
+  const w = 120;
+  const h = 80;
+  const id = (r: number, c: number): string => `n${r}-${c}`;
+  for (let r = 0; r < side; r++) for (let c = 0; c < side; c++) b.node(id(r, c), c * w, r * h, w, h);
+  const step = (): number => Math.floor(R() * 5) - 2;
+  const clamp = (v: number): number => Math.max(0, Math.min(side - 1, v));
+  for (let r = 0; r < side; r++) for (let c = 0; c < side; c++) b.link(id(r, c), id(clamp(r + step()), clamp(c + step())));
+  for (let n = 0; n < 64; n++) b.link(id(Math.floor(R() * side), Math.floor(R() * side)), id(Math.floor(R() * side), Math.floor(R() * side)));
   return b.graph();
 }
 

package/src/curves/clothoid/index.ts

@@ -0,0 +1,150 @@
+import type { Point } from "../../geom.ts";
+import { cornerTangent, spiralCorners, type SpiralShape } from "../corner.ts";
+import { fitPieces, type CubicPiece } from "../fit.ts";
+import type { CurveSegment } from "../model.ts";
+import { cubicAt } from "../sample.ts";
+import type { CurveSpace } from "../space.ts";
+
+/** The options of `clothoidCurve`. */
+export interface ClothoidOptions {
+  /** The radius of the arc in the middle of each corner: the smallest radius of the corner. The default is 12. */
+  readonly radius?: number;
+  /** The share of the turn of a corner in its two clothoids, from 0 (a circular arc) to 1 (no arc). The default is 0.5. */
+  readonly spiral?: number;
+  /** The largest distance from the cubic pieces to the true clothoid, in units of the plane. The default is 0.25. */
+  readonly tolerance?: number;
+  /** The boxes that the curve must not go through. Without it, each corner gets the largest radius that fits on its legs. */
+  readonly space?: CurveSpace;
+}
+
+/** The largest number of cubic pieces of one clothoid. */
+export const MAX_CLOTHOID_PIECES = 8;
+
+/**
+ * This function gives the point at the arc length `s` of the clothoid that starts at the origin along the x axis.
+ * The tangent angle is `θ(s) = s² / (2 a2)`, so the curvature `s / a2` grows linearly with the length.
+ * The Fresnel integrals give the point. Their power series converge fast for the turns of a corner.
+ */
+export function clothoidPoint(s: number, a2: number): Point {
+  const theta = (s * s) / (2 * a2);
+  const t2 = theta * theta;
+  let x = 0;
+  let y = 0;
+  // The term of x is (-1)^n θ^(2n) / ((2n)! (4n + 1)). The term of y is (-1)^n θ^(2n+1) / ((2n+1)! (4n + 3)).
+  let px = 1;
+  let py = theta;
+  for (let n = 0; n < 40; n++) {
+    const tx = px / (4 * n + 1);
+    const ty = py / (4 * n + 3);
+    x += tx;
+    y += ty;
+    if (Math.abs(tx) < 1e-17 && Math.abs(ty) < 1e-17) break;
+    px *= -t2 / ((2 * n + 1) * (2 * n + 2));
+    py *= -t2 / ((2 * n + 2) * (2 * n + 3));
+  }
+  return { x: s * x, y: s * y };
+}
+
+/** The cubic pieces of one clothoid at the radius 1, and their largest distance to the clothoid. */
+interface ClothoidFit {
+  readonly pieces: readonly CubicPiece[];
+  readonly error: number;
+}
+
+/** The fits of the clothoids of recent corners, by the turn and the spiral share. Each fit comes when a corner first needs it. The cache empties when it gets large. */
+const fits = new Map<string, (n: number) => ClothoidFit>();
+
+/** The number of points of the dense polyline that measures the error of a fit. */
+const DENSE = 256;
+
+/** This function gives the distance from the point `q` to the part of the polyline `p` from the index `from` to the index `to`. */
+function distanceTo(q: Point, p: readonly Point[], from: number, to: number): number {
+  let best = Infinity;
+  for (let i = Math.max(1, from); i <= Math.min(p.length - 1, to); i++) {
+    const a = p[i - 1]!;
+    const b = p[i]!;
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const l2 = dx * dx + dy * dy;
+    const t = l2 > 0 ? Math.max(0, Math.min(1, ((q.x - a.x) * dx + (q.y - a.y) * dy) / l2)) : 0;
+    best = Math.min(best, Math.hypot(a.x + t * dx - q.x, a.y + t * dy - q.y));
+  }
+  return best;
+}
+
+/**
+ * This function gives the fits of the clothoid that turns by `theta` and ends with the curvature 1, with 1 to `MAX_CLOTHOID_PIECES` pieces.
+ * Each piece is G2 with its neighbours. The error of a fit is the largest distance from 16 samples of each piece to a dense polyline of the clothoid.
+ * A sample looks only at the part of the polyline near its arc length. A smaller part gives a larger distance, so the error does not get smaller.
+ */
+function clothoidFits(theta: number): (n: number) => ClothoidFit {
+  const length = 2 * theta;
+  const a2 = length;
+  const at = (t: number): { p: Point; d: Point; dd: Point } => {
+    const s = t * length;
+    const angle = (s * s) / (2 * a2);
+    const k = s / a2;
+    const d = { x: length * Math.cos(angle), y: length * Math.sin(angle) };
+    return { p: clothoidPoint(s, a2), d, dd: { x: -d.y * length * k, y: d.x * length * k } };
+  };
+  const dense: Point[] = [];
+  for (let i = 0; i <= DENSE; i++) dense.push(clothoidPoint((i / DENSE) * length, a2));
+  const done: ClothoidFit[] = [];
+  return (n) => {
+    const known = done[n];
+    if (known) return known;
+    const pieces = fitPieces(at, n);
+    const window = Math.ceil(DENSE / n / 2) + 8;
+    let error = 0;
+    let from: Point = { x: 0, y: 0 };
+    pieces.forEach((q, k) => {
+      for (let i = 1; i < 16; i++) {
+        const mid = Math.round(((k + i / 16) / n) * DENSE);
+        error = Math.max(error, distanceTo(cubicAt(from, q.c1, q.c2, q.to, i / 16), dense, mid - window, mid + window));
+      }
+      from = q.to;
+    });
+    const fit = { pieces, error };
+    done[n] = fit;
+    return fit;
+  };
+}
+
+/** This function gives the shape of a corner of `clothoidCurve` with the turn `turn` at the radius 1. */
+export function clothoidShape(turn: number, spiral: number, tolerance: number): SpiralShape {
+  const theta = (Math.max(0, Math.min(1, spiral)) * turn) / 2;
+  if (theta < 1e-9) return { tangent: Math.tan(turn / 2), theta: 0, pieces: () => [], end: { x: 0, y: 0 } };
+  const key = `${turn}|${spiral}`;
+  let all = fits.get(key);
+  if (all === undefined) {
+    if (fits.size >= 256) fits.clear();
+    all = clothoidFits(theta);
+    fits.set(key, all);
+  }
+  const fit = all;
+  const end = clothoidPoint(2 * theta, 2 * theta);
+  return {
+    tangent: cornerTangent(turn, theta, end),
+    theta,
+    end,
+    // The error of a fit scales with the radius. The corner takes the fewest pieces that keep the error within the tolerance.
+    pieces: (radius) => {
+      for (let n = 1; n < MAX_CLOTHOID_PIECES; n++) if (fit(n).error * radius <= tolerance) return fit(n).pieces;
+      return fit(MAX_CLOTHOID_PIECES).pieces;
+    },
+  };
+}
+
+/**
+ * This function rounds each inner vertex of a polyline with a clothoid, a circular arc and a second clothoid (F6 of the note CURVES).
+ * The curvature of a clothoid grows linearly with its length, from 0 on the leg to `1 / radius` on the arc. This is the transition curve of roads and railways.
+ * Each clothoid turns by `spiral` times half of the turn. G2 cubic pieces draw it within `tolerance` of the true clothoid.
+ *
+ * The ends of each corner stay on the first half of each leg, so the ends of the polyline stay.
+ * With `space`, the radius of a corner shrinks until its corner triangle overlaps no box that the polyline avoids.
+ */
+export function clothoidCurve(points: readonly Point[], options: ClothoidOptions = {}): CurveSegment[] {
+  const spiral = options.spiral ?? 0.5;
+  const tolerance = Math.max(1e-3, options.tolerance ?? 0.25);
+  return spiralCorners(points, { radius: options.radius ?? 12, ...(options.space ? { space: options.space } : {}) }, (turn) => clothoidShape(turn, spiral, tolerance));
+}

package/src/curves/corner.ts

@@ -0,0 +1,116 @@
+import { dist, type Point } from "../geom.ts";
+import type { CubicPiece } from "./fit.ts";
+import { distinctPoints, type CurveSegment } from "./model.ts";
+import { fitCorner, type CurveSpace } from "./space.ts";
+
+/**
+ * The shape of a symmetric corner with a spiral, an arc and a second spiral, at the smallest radius 1.
+ * The local frame of the first spiral starts at the tangent point on the leg in. Its x axis goes along the leg, and its y axis goes to the side of the turn.
+ */
+export interface SpiralShape {
+  /** The tangent length of the corner at the radius 1: the distance from the vertex to each end of the corner. */
+  readonly tangent: number;
+  /** The turn of each spiral, in radians. The arc turns by the rest of the corner. */
+  readonly theta: number;
+  /** The cubic pieces of the first spiral at the radius 1, from the origin of the local frame to the start of the arc. */
+  readonly pieces: (radius: number) => readonly CubicPiece[];
+  /** The end of the first spiral at the radius 1: the start of the arc. */
+  readonly end: Point;
+}
+
+/** A turn smaller than this angle, in radians, is no corner. A turn nearer to a half turn than this angle stays sharp. */
+const FLAT = 1e-6;
+
+/** The options of `spiralCorners`. */
+export interface SpiralCornerOptions {
+  /** The largest smallest radius of a corner. */
+  readonly radius: number;
+  /** The boxes that the curve must not go through. Without it, each corner gets the largest radius that fits on its legs. */
+  readonly space?: CurveSpace;
+}
+
+/**
+ * This function puts a symmetric corner at each inner vertex of a polyline: a spiral, an arc and a second spiral.
+ * The function `shapeOf` gives the shape of a corner from its turn, at the radius 1. A larger radius scales the shape.
+ * The ends of each corner stay on the first half of each leg, so the ends of the polyline stay.
+ * With `space`, the radius of a corner shrinks until its corner triangle overlaps no box that the polyline avoids.
+ */
+export function spiralCorners(points: readonly Point[], options: SpiralCornerOptions, shapeOf: (turn: number) => SpiralShape): CurveSegment[] {
+  const p = distinctPoints(points);
+  if (p.length === 0) return [];
+  const out: CurveSegment[] = [{ kind: "move", to: p[0]! }];
+  for (let i = 1; i + 1 < p.length; i++) {
+    const a = p[i - 1]!;
+    const v = p[i]!;
+    const b = p[i + 1]!;
+    const la = dist(a, v);
+    const lb = dist(v, b);
+    const u = { x: (v.x - a.x) / la, y: (v.y - a.y) / la };
+    const w = { x: (b.x - v.x) / lb, y: (b.y - v.y) / lb };
+    const turn = Math.atan2(u.x * w.y - u.y * w.x, u.x * w.x + u.y * w.y);
+    if (Math.abs(turn) < FLAT || Math.PI - Math.abs(turn) < FLAT) {
+      out.push({ kind: "line", to: v });
+      continue;
+    }
+    const shape = shapeOf(Math.abs(turn));
+    const side = Math.sign(turn);
+    const ends = (r: number): [Point, Point] => [
+      { x: v.x - u.x * r * shape.tangent, y: v.y - u.y * r * shape.tangent },
+      { x: v.x + w.x * r * shape.tangent, y: v.y + w.y * r * shape.tangent },
+    ];
+    const piece = (r: number): CurveSegment[] => cornerSegments(shape, r, ends(r), u, w, side, Math.abs(turn));
+    const r = fitCorner(
+      options.space,
+      Math.min(Math.max(0, options.radius), Math.min(la, lb) / (2 * shape.tangent)),
+      (s) => [ends(s)[0], v, ends(s)[1]],
+      (s) => [{ kind: "move", to: ends(s)[0] }, ...piece(s)],
+    );
+    if (r <= 0) {
+      out.push({ kind: "line", to: v });
+      continue;
+    }
+    const [p1] = ends(r);
+    if (dist(p1, out[out.length - 1]!.to) > 1e-9) out.push({ kind: "line", to: p1 });
+    out.push(...piece(r));
+  }
+  if (p.length > 1) out.push({ kind: "line", to: p[p.length - 1]! });
+  return out;
+}
+
+/**
+ * This function gives the segments of one corner at the radius `r`, from the tangent point `p1` to the tangent point `p2`.
+ * The first spiral is in the frame of the leg in. The second spiral is the mirror image of the first, in the frame of the leg out, in the reverse order.
+ */
+function cornerSegments(shape: SpiralShape, r: number, [p1, p2]: [Point, Point], u: Point, w: Point, side: number, turn: number): CurveSegment[] {
+  // The y axis of each frame goes to the side of the turn: the left normal of the leg, times the sign of the turn.
+  const n1 = { x: -u.y * side, y: u.x * side };
+  const n2 = { x: -w.y * side, y: w.x * side };
+  const map1 = (q: Point): Point => ({ x: p1.x + (u.x * q.x + n1.x * q.y) * r, y: p1.y + (u.y * q.x + n1.y * q.y) * r });
+  const map2 = (q: Point): Point => ({ x: p2.x + (-w.x * q.x + n2.x * q.y) * r, y: p2.y + (-w.y * q.x + n2.y * q.y) * r });
+  const out: CurveSegment[] = [];
+  const pieces = shape.theta > 0 ? shape.pieces(r) : [];
+  for (const q of pieces) out.push({ kind: "cubic", c1: map1(q.c1), c2: map1(q.c2), to: map1(q.to) });
+  const sweep = turn - 2 * shape.theta;
+  if (sweep > 1e-9) {
+    const from = map1(shape.end);
+    // The center of the arc is at the distance r from the end of the spiral, to the side of the turn.
+    const center = map1({ x: shape.end.x - Math.sin(shape.theta), y: shape.end.y + Math.cos(shape.theta) });
+    out.push({ kind: "arc", center, radius: r, start: Math.atan2(from.y - center.y, from.x - center.x), sweep: side * sweep, to: map2(shape.end) });
+  }
+  for (let k = pieces.length - 1; k >= 0; k--) {
+    const q = pieces[k]!;
+    const start = k === 0 ? { x: 0, y: 0 } : pieces[k - 1]!.to;
+    out.push({ kind: "cubic", c1: map2(q.c2), c2: map2(q.c1), to: k === 0 ? p2 : map2(start) });
+  }
+  return out;
+}
+
+/**
+ * This function gives the tangent length of a symmetric corner at the radius 1. The spiral of the corner turns by `theta` and ends at `end`.
+ * The center of the arc is on the bisector of the corner: `T = k + (1 + p) tan(turn / 2)`, with the shift `p` and the offset `k` of the arc.
+ */
+export function cornerTangent(turn: number, theta: number, end: Point): number {
+  const k = end.x - Math.sin(theta);
+  const p = end.y - (1 - Math.cos(theta));
+  return k + (1 + p) * Math.tan(turn / 2);
+}

package/src/curves/fit.ts

@@ -0,0 +1,79 @@
+import type { Point } from "../geom.ts";
+
+/** One end of a piece of a smooth curve: the point, the unit tangent and the signed curvature. */
+export interface CurveEnd {
+  readonly p: Point;
+  readonly t: Point;
+  readonly k: number;
+}
+
+/** The control points of a cubic Bezier piece after its start point. */
+export interface CubicPiece {
+  readonly c1: Point;
+  readonly c2: Point;
+  readonly to: Point;
+}
+
+const cross = (a: Point, b: Point): number => a.x * b.y - a.y * b.x;
+
+/**
+ * This function fits one cubic Bezier piece to two ends of a curve with G2 Hermite data.
+ * The piece starts at `a.p` along `a.t` with the curvature `a.k`, and it ends at `b.p` along `b.t` with the curvature `b.k`.
+ *
+ * The handles have the lengths `h0` and `h1`. The curvature at the start is `(2/3) (cross(t0, D) - h1 cross(t0, t1)) / h0^2`,
+ * and at the end `(2/3) (cross(D, t1) - h0 cross(t0, t1)) / h1^2`, with `D = b.p - a.p`.
+ * Newton steps solve these two equations, from the handles `guess`.
+ * The function gives `undefined` when the steps do not converge to two positive handles. The caller then uses the C1 handles.
+ */
+export function fitG2(a: CurveEnd, b: CurveEnd, guess: readonly [number, number]): CubicPiece | undefined {
+  const D = { x: b.p.x - a.p.x, y: b.p.y - a.p.y };
+  const s = cross(a.t, b.t);
+  const c0 = cross(a.t, D);
+  const c1 = cross(D, b.t);
+  let [h0, h1] = guess;
+  const scale = Math.max(1e-12, Math.hypot(D.x, D.y));
+  for (let i = 0; i < 30; i++) {
+    const f1 = a.k * h0 * h0 - (2 / 3) * (c0 - h1 * s);
+    const f2 = b.k * h1 * h1 - (2 / 3) * (c1 - h0 * s);
+    if (Math.abs(f1) < 1e-13 * scale && Math.abs(f2) < 1e-13 * scale) break;
+    // The Jacobian of (f1, f2) by (h0, h1).
+    const j11 = 2 * a.k * h0;
+    const j12 = (2 / 3) * s;
+    const j21 = (2 / 3) * s;
+    const j22 = 2 * b.k * h1;
+    const det = j11 * j22 - j12 * j21;
+    if (Math.abs(det) < 1e-18) return undefined;
+    h0 -= (f1 * j22 - f2 * j12) / det;
+    h1 -= (j11 * f2 - j21 * f1) / det;
+    if (!Number.isFinite(h0) || !Number.isFinite(h1)) return undefined;
+  }
+  const f1 = a.k * h0 * h0 - (2 / 3) * (c0 - h1 * s);
+  const f2 = b.k * h1 * h1 - (2 / 3) * (c1 - h0 * s);
+  if (!(h0 > 0 && h1 > 0) || Math.abs(f1) > 1e-9 * scale || Math.abs(f2) > 1e-9 * scale) return undefined;
+  // A handle longer than the chord gives a loop or a bulge. The C1 handles are better then.
+  if (h0 > 1.5 * scale || h1 > 1.5 * scale) return undefined;
+  return { c1: { x: a.p.x + a.t.x * h0, y: a.p.y + a.t.y * h0 }, c2: { x: b.p.x - b.t.x * h1, y: b.p.y - b.t.y * h1 }, to: b.p };
+}
+
+/**
+ * This function gives `n` cubic Bezier pieces of a smooth curve `at(t)`, with `t` from 0 to 1. The pieces have equal steps of `t`.
+ * The function `at` gives the point, the first derivative and the second derivative.
+ * Each piece is G2 with its neighbours where `fitG2` finds handles. Elsewhere it has the C1 handles of the derivatives.
+ */
+export function fitPieces(at: (t: number) => { p: Point; d: Point; dd: Point }, n: number): CubicPiece[] {
+  const end = (t: number): CurveEnd & { speed: number } => {
+    const { p, d, dd } = at(t);
+    const speed = Math.hypot(d.x, d.y);
+    return { p, t: { x: d.x / speed, y: d.y / speed }, k: cross(d, dd) / speed ** 3, speed };
+  };
+  const out: CubicPiece[] = [];
+  let a = end(0);
+  for (let i = 1; i <= n; i++) {
+    const b = end(i / n);
+    const h0 = a.speed / (3 * n);
+    const h1 = b.speed / (3 * n);
+    out.push(fitG2(a, b, [h0, h1]) ?? { c1: { x: a.p.x + a.t.x * h0, y: a.p.y + a.t.y * h0 }, c2: { x: b.p.x - b.t.x * h1, y: b.p.y - b.t.y * h1 }, to: b.p });
+    a = b;
+  }
+  return out;
+}