@mark1russell7/highways 0.2.0 → 0.3.0

package/src/strategies/schemas.ts

@@ -0,0 +1,221 @@
+import type { CutOptions } from "../groups/cut/index.ts";
+import type { KdOptions } from "../groups/kd/index.ts";
+import type { KeyOptions } from "../groups/keys/index.ts";
+import type { CornersOptions } from "../routers/corners.ts";
+import type { SectionsOptions } from "../routers/sections.ts";
+import type { SharedOptions } from "../routers/shared.ts";
+import type { TrunksOptions } from "../routers/trunks.ts";
+import type { SectionOptions } from "../sections.ts";
+import type { RunOrder } from "../segments.ts";
+import type { ClothoidStrategyOptions, HighwayStrategyOptions, LevelRoomPreset, RadiusOptions, RoomPreset, RouterPreset, SmoothStrategyOptions, TensionOptions } from "./builtins.ts";
+import type { EnumOption, OptionSchema } from "./options.ts";
+
+// The declarations of the options of the built-in strategies. Each `default` is the value that the function uses without the option.
+// The test of the defaults runs each strategy with `optionDefaults` and with no option, and compares the output.
+
+/** The options of the way finder (`WayOptions`), for each router that goes around the nodes. */
+const WAY_SCHEMA: OptionSchema<RouterPreset<CornersOptions>> = {
+  margin: { type: "number", min: 1, max: 20, step: 1, default: 5, describe: "The distance from a box to the corners of the graph." },
+  k: { type: "integer", min: 2, max: 16, step: 1, default: 8, describe: "The number of visible neighbours of each corner." },
+  smooth: { type: "boolean", default: false, describe: "With `true`, a way in clear view uses the inflection rule, and the other ways get round corners." },
+};
+
+/** The declaration of the lane order of the shared ways of the routers `trunks` and `shared`. */
+const LANE_ORDER: EnumOption<RunOrder> = {
+  type: "enum",
+  values: ["bundle", "run"],
+  default: "bundle",
+  describe: "With `bundle`, two edges keep one lane order on each shared way of their common stretch. With `run`, each shared way gets its order alone.",
+};
+
+/** The declaration of the lane order of the runs of the router `sections`. The default keeps the lane order of version 0.2.0. */
+const RUN_LANE_ORDER: EnumOption<RunOrder> = { ...LANE_ORDER, default: "run" };
+
+/** The declarations of the options of the routers `corners` and `corners-smooth`. */
+export const CORNERS_SCHEMA: OptionSchema<RouterPreset<CornersOptions>> = WAY_SCHEMA;
+
+/** The declarations of the options of the router `trunks`. */
+export const TRUNKS_SCHEMA: OptionSchema<RouterPreset<TrunksOptions>> = {
+  ...WAY_SCHEMA,
+  rule: { type: "function", describe: "The grouping rule. The edges from one plug with one key share a trunk." },
+  split: { type: "number", min: 0.1, max: 0.9, step: 0.05, default: 0.5, describe: "The split point is at this share of the way to the center of the targets." },
+  minSize: { type: "integer", min: 1, max: 8, step: 1, default: 2, describe: "A group with fewer edges stays unbundled." },
+  laneOrder: LANE_ORDER,
+  leave: {
+    type: "enum",
+    values: ["part", "split"],
+    default: "part",
+    describe: "With `part`, a lane leaves the trunk where its way parts from the other ways. With `split`, each lane leaves at the split point.",
+  },
+};
+
+/** The declarations of the options of the routers `shared` and `shared-all`. */
+export const SHARED_SCHEMA: OptionSchema<RouterPreset<SharedOptions>> = {
+  ...WAY_SCHEMA,
+  rule: { type: "function", describe: "The edges with one key share their ways. Without a rule, all edges share." },
+  discount: {
+    type: "number",
+    min: 0.05,
+    max: 1,
+    step: 0.05,
+    default: 0.5,
+    describe: "The cost of a link that an edge with the same key uses already, as a share of its length.",
+  },
+  laneOrder: LANE_ORDER,
+};
+
+/** The declarations of the limits of the tree of sections (`SectionOptions`). */
+export const SECTION_SCHEMA: OptionSchema<Required<SectionOptions>> = {
+  cap: { type: "integer", min: 1, max: 32, step: 1, scale: "log", marks: [4, 6, 8, 12, 16], default: 8, describe: "The section limit. A section with more nodes splits in four." },
+  maxDepth: { type: "integer", min: 1, max: 32, step: 1, default: 16, describe: "The depth limit of the tree." },
+  collapse: { type: "integer", min: 1, max: 64, step: 1, default: 32, describe: "A cell shrinks to one quarter at most this many times without a split." },
+};
+
+/** The declarations of the options of the routers `sections` and `sections-tree`. */
+export const SECTIONS_SCHEMA: OptionSchema<RouterPreset<SectionsOptions>> = {
+  ...WAY_SCHEMA,
+  ...SECTION_SCHEMA,
+  hubs: {
+    type: "integer",
+    min: 0,
+    max: 8,
+    step: 1,
+    special: [Infinity],
+    default: Infinity,
+    describe: "The number of hubs on each side of the lowest common section that a way passes. `Infinity` passes each hub.",
+  },
+  stretch: {
+    type: "number",
+    min: 1,
+    max: 4,
+    step: 0.25,
+    special: [Infinity],
+    marks: [1.25, 1.5, 2, 3, Infinity],
+    default: 2,
+    describe: "The hub limit. A way through the hubs is at most this many times the straight line. `Infinity` keeps each such way.",
+  },
+  stretchPad: { type: "number", min: 0, max: 16, step: 1, default: 4, describe: "A way through the hubs can be this many margins longer than the hub limit." },
+  hubSlack: {
+    type: "number",
+    min: 0,
+    max: 320,
+    step: 10,
+    special: [Infinity],
+    marks: [0, 40, 80, 160, Infinity],
+    default: 80,
+    describe: "A way skips a hub that is this many units farther from the target than the way was before.",
+  },
+  tightMargin: { type: "number", min: 0, max: 5, step: 0.5, default: 1, describe: "The margin of the second corner graph of the level links." },
+  plugInset: { type: "number", min: 0, max: 12, step: 1, default: 6, describe: "A plug of a level link stays this far from the corners of its side." },
+  throughCost: {
+    type: "number",
+    min: 0,
+    max: 16,
+    step: 1,
+    marks: [0, 2, 4, 8, 16],
+    default: 8,
+    describe: "The cost of a level link through a far box, in mean box sizes. The value 0 gives the links of version 0.1.5.",
+  },
+  group: { type: "strategy", step: "group", describe: "The grouping rule: a strategy of the step `group`. Without it, the router uses the quadtree." },
+  groupOptions: { type: "object", describe: "The options of the strategy `group`." },
+  levels: { type: "list", describe: "The depths of the tree that get a level with groups. Without it, each depth gets a level." },
+  laneOrder: RUN_LANE_ORDER,
+};
+
+/** The declarations of the option of the curves `rounded` and `arc`. */
+export const RADIUS_SCHEMA: OptionSchema<RadiusOptions> = {
+  radius: { type: "number", min: 0, max: 48, step: 1, describe: "The radius of the corners." },
+};
+
+/** The declarations of the options of the curve `highway`. */
+export const HIGHWAY_SCHEMA: OptionSchema<HighwayStrategyOptions> = {
+  ...RADIUS_SCHEMA,
+  minRadius: { type: "number", min: 0, max: 24, step: 1, describe: "The smallest radius of a lane at a bend of a bundle." },
+  jog: {
+    type: "enum",
+    values: ["biarc", "cubic", "quintic"],
+    default: "biarc",
+    describe: "The shape of the S curve where a lane changes its offset. A `quintic` S curve has no jump of the curvature.",
+  },
+  jogPieces: { type: "integer", min: 1, max: 8, step: 1, default: 4, describe: "The number of cubic pieces of a `quintic` S curve." },
+};
+
+/** The declarations of the options of the curve `smooth`. */
+export const SMOOTH_SCHEMA: OptionSchema<SmoothStrategyOptions> = {
+  ...RADIUS_SCHEMA,
+  smoothing: { type: "number", min: 0, max: 1, step: 0.05, describe: "The share of the turn of a corner in its two spirals. The value 0 gives the curve `arc`." },
+};
+
+/** The declarations of the options of the curve `clothoid`. */
+export const CLOTHOID_SCHEMA: OptionSchema<ClothoidStrategyOptions> = {
+  ...RADIUS_SCHEMA,
+  spiral: { type: "number", min: 0, max: 1, step: 0.05, describe: "The share of the turn of a corner in its two clothoids. The value 0 gives the curve `arc`." },
+  tolerance: { type: "number", min: 0.05, max: 1, step: 0.05, describe: "The largest distance from the cubic pieces to the true clothoid." },
+};
+
+/** The declarations of the option of the curve `spline`. */
+export const TENSION_SCHEMA: OptionSchema<TensionOptions> = {
+  tension: { type: "number", min: 0, max: 1, step: 0.05, describe: "The tension of the spline, from 0 (the spline) to 1 (the polyline)." },
+};
+
+/** The declarations of the options of the room strategies: the options of `roomDemand`, without the method. */
+export const ROOM_SCHEMA: OptionSchema<RoomPreset> = {
+  gutter: { type: "number", min: 0, max: 32, step: 1, marks: [4, 8, 12, 16], default: 8, describe: "The smallest width of each gap." },
+  spacing: { type: "number", min: 1, max: 12, step: 1, marks: [2, 4, 6, 8], default: 4, describe: "The width of one lane: the distance between two lines that run side by side." },
+  maxGrowth: {
+    type: "number",
+    min: 0,
+    max: 1,
+    step: 0.01,
+    special: [Infinity],
+    marks: [0, 0.06, 0.09, 0.12, 0.15, 0.18, 0.21, 0.25, 0.3, 0.35, 0.5, Infinity],
+    default: Infinity,
+    describe: "The largest growth of the board on each axis, as a share of its size. `Infinity` sets no limit.",
+  },
+  router: { type: "object", describe: "The router of the method `routes`. Without it, the links go as the links of a zoom level." },
+  lanes: { type: "enum", values: ["link", "count"], default: "link", describe: "With `count`, a link takes one lane for each of its edges. With `link`, a link takes one lane." },
+  snap: { type: "number", min: 0, max: 4, step: 0.25, default: 0.5, describe: "Two box edges nearer than this distance make one boundary of the sweep." },
+  passes: { type: "integer", min: 1, max: 4, step: 1, marks: [1, 2], default: 1, describe: "The number of passes of the demand. Each pass after the first finds the lanes on the open board." },
+  bends: {
+    type: "object",
+    describe: "The room for the bends of the bundles: a router that bundles, and the lane options of `highwayCurves`. Without it, the bends get no room.",
+  },
+};
+
+/** The declarations of the options of the room strategy `levels`. They are the options of the room, the levels with room and the limits of the quadtree. */
+export const LEVEL_ROOM_SCHEMA: OptionSchema<LevelRoomPreset> = {
+  ...ROOM_SCHEMA,
+  depths: { type: "list", describe: "The depths of the tree that get room. Without it, each depth with groups gets room." },
+  nodes: { type: "boolean", default: false, describe: "With `true`, the last level, with each node alone, also gets room." },
+  board: { type: "enum", values: ["shared", "each"], default: "shared", describe: "With `shared`, each level uses the board of the nearest level. With `each`, each level has its own board." },
+  ...SECTION_SCHEMA,
+};
+
+/** The declarations of the options of the grouping rule `keys`. */
+export const KEY_SCHEMA: OptionSchema<KeyOptions> = {
+  key: { type: "function", describe: "This function gives the key of the group of each node." },
+  split: { type: "object", describe: "With these limits of the quadtree, a large group splits into cells. Without them, each group is one leaf." },
+};
+
+/** The declarations of the limits of the tree of the grouping rules `kd` and `cut`. */
+const SPLIT_TREE_SCHEMA: OptionSchema<Required<Pick<KdOptions, "cap" | "maxDepth" | "fanout">>> = {
+  cap: { ...SECTION_SCHEMA.cap, describe: "The section limit. A section with more nodes splits." },
+  maxDepth: SECTION_SCHEMA.maxDepth,
+  fanout: { type: "integer", min: 2, max: 4, step: 2, default: 4, describe: "The number of children of a section. With 4, a section splits two times on one level." },
+};
+
+/** The declarations of the options of the grouping rule `kd`. */
+export const KD_SCHEMA: OptionSchema<KdOptions> = {
+  ...SPLIT_TREE_SCHEMA,
+  line: { type: "enum", values: ["median", "middle", "slide"], default: "slide", describe: "The place of the line in the cell: the median node, the middle, or the middle that slides to the nearest node." },
+  axis: { type: "enum", values: ["longer", "alternate"], default: "longer", describe: "The axis of each split: across the longer side of the cell, or x and y in turn." },
+};
+
+/** The declarations of the options of the grouping rule `cut`. */
+export const CUT_SCHEMA: OptionSchema<CutOptions> = {
+  ...SPLIT_TREE_SCHEMA,
+  balance: { type: "number", min: 0.05, max: 0.5, step: 0.05, marks: [0.1, 0.25, 0.4], default: 0.25, describe: "The smallest share of the nodes in each part of a split." },
+  objective: { type: "enum", values: ["ratio", "normalized", "sparsest"], default: "ratio", describe: "The cost of a line: the ratio cut, the normalized cut or the sparsest cut." },
+  pull: { type: "number", min: 0, max: 4, step: 0.25, marks: [0, 0.5, 1, 2, 4], default: 0.5, describe: "The cost of a line grows with its distance from the middle of the cell, by this factor." },
+  guard: { type: "boolean", default: true, describe: "With `true`, each section also tests the quadtree split, and keeps the split that cuts fewer edges." },
+};

package/src/visibility.ts

@@ -1,4 +1,5 @@
-import { dist, inflate, segmentHitsRect, type Box, type Point } from "./geom.ts";
+import { TOLERANCE } from "./bench/properties.ts";
+import { dist, inflate, segmentHitsBox, segmentHitsRect, type Box, type Point } from "./geom.ts";
 import { Grid } from "./grid.ts";
 import type { Node } from "./model.ts";
 
@@ -37,6 +38,17 @@ export class Obstacles {
     return true;
   }
 
+  /**
+   * This method gives each node whose box the segment `ab` goes through to `visit`, one time each.
+   * The segment goes through a box when a part of it longer than `TOLERANCE` is inside the box made smaller by `TOLERANCE`.
+   * The link measures (`measureLinks`) use the same test.
+   */
+  through(a: Point, b: Point, visit: (n: Node) => void): void {
+    this.#grid.querySegment(a, b, 0, (n) => {
+      if (segmentHitsBox(a, b, inflate(n.box, -TOLERANCE), TOLERANCE)) visit(n);
+    });
+  }
+
   /** This method gives each node whose bucket the box touches to `visit`. A node can be outside the box. */
   query(box: Box, visit: (n: Node) => void): void {
     this.#grid.query(box, visit);
@@ -493,6 +505,183 @@ export class CornerGraph {
   }
 }
 
+/** The options of the soft graph. */
+export interface SoftGraphOptions {
+  /** The distance from a box to its corners. */
+  readonly margin: number;
+  /** The number of nearest neighbours of each vertex. */
+  readonly k: number;
+  /**
+   * The spacing of a lattice of points in the bounding box of the boxes, in units of the mean node size. The default is 3, and 0 turns it off.
+   * The lattice links groups of boxes across empty space.
+   */
+  readonly lattice?: number;
+}
+
+/**
+ * A graph whose links can go through the boxes. Its vertices are the corners of the boxes, made larger by `margin`,
+ * and a lattice of points in the bounding box of the boxes. Each vertex links to its `k` nearest vertices, in view or not.
+ * The graph keeps the boxes that each link goes through (`Obstacles.through`).
+ * A search gives each box a cost, so a path goes through few boxes, and only through boxes of a low cost.
+ */
+export class SoftGraph {
+  readonly points: Point[] = [];
+  readonly #nodes: readonly Node[];
+  readonly #obstacles: Obstacles;
+  readonly #adj: number[][] = [];
+  readonly #len: number[][] = [];
+  // The indices of the nodes that each link goes through, in the order of #adj.
+  readonly #through: (readonly number[])[][] = [];
+  readonly #grid: Grid<number>;
+  readonly #cell: number;
+  readonly #k: number;
+
+  /** This constructor makes the graph of the nodes. */
+  constructor(nodes: readonly Node[], obstacles: Obstacles, options: SoftGraphOptions) {
+    this.#nodes = nodes;
+    this.#obstacles = obstacles;
+    this.#k = options.k;
+    let size = 0;
+    for (const n of nodes) size += (n.box.w + n.box.h) / 2;
+    this.#cell = Math.max(1, size / Math.max(1, nodes.length) + 2 * options.margin);
+    this.#grid = new Grid<number>(this.#cell);
+    let x0 = Infinity;
+    let y0 = Infinity;
+    let x1 = -Infinity;
+    let y1 = -Infinity;
+    for (const n of nodes) {
+      const b = inflate(n.box, options.margin);
+      for (const c of [
+        { x: b.x, y: b.y },
+        { x: b.x + b.w, y: b.y },
+        { x: b.x + b.w, y: b.y + b.h },
+        { x: b.x, y: b.y + b.h },
+      ])
+        this.#add(c);
+      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);
+    }
+    // The lattice stays in the bounding box of the boxes, so a path does not go around the outer edge of the board.
+    const spacing = (options.lattice ?? 3) * this.#cell;
+    if (spacing > 0) for (let x = x0 + spacing / 2; x < x1; x += spacing) for (let y = y0 + spacing / 2; y < y1; y += spacing) this.#add({ x, y });
+    const links: Set<number>[] = this.points.map(() => new Set<number>());
+    for (let i = 0; i < this.points.length; i++)
+      for (const j of this.#nearest(this.points[i]!, this.#k, i)) {
+        links[i]!.add(j);
+        links[j]!.add(i);
+      }
+    const index = new Map(nodes.map((n, i) => [n, i]));
+    // The boxes of each link, found one time for the two directions of the link.
+    const known = new Map<number, readonly number[]>();
+    const count = this.points.length;
+    links.forEach((set, i) => {
+      const adj = [...set].sort((a, b) => a - b);
+      this.#adj.push(adj);
+      this.#len.push(adj.map((j) => dist(this.points[i]!, this.points[j]!)));
+      this.#through.push(
+        adj.map((j) => {
+          const key = Math.min(i, j) * count + Math.max(i, j);
+          let list = known.get(key);
+          if (list === undefined) {
+            const found: number[] = [];
+            obstacles.through(this.points[i]!, this.points[j]!, (n) => found.push(index.get(n)!));
+            list = found;
+            known.set(key, list);
+          }
+          return list;
+        }),
+      );
+    });
+  }
+
+  #add(c: Point): void {
+    this.#grid.add(this.points.length, { x: c.x, y: c.y, w: 0, h: 0 });
+    this.points.push(c);
+  }
+
+  /** This method gives at most `k` vertices nearest to `p`, in view or not, nearest first, and equal distances by index. The vertex `self` does not count. */
+  #nearest(p: Point, k: number, self = -1): number[] {
+    const all = this.points.length - (self >= 0 ? 1 : 0);
+    const want = Math.min(k, all);
+    if (want <= 0) return [];
+    for (let r = this.#cell; ; r *= 2) {
+      const found: number[] = [];
+      this.#grid.query({ x: p.x - r, y: p.y - r, w: 2 * r, h: 2 * r }, (j) => {
+        if (j !== self && dist(p, this.points[j]!) <= r) found.push(j);
+      });
+      if (found.length >= want) {
+        const d = (j: number): number => dist(p, this.points[j]!);
+        return found.sort((a, b) => d(a) - d(b) || a - b).slice(0, want);
+      }
+    }
+  }
+
+  /**
+   * This method gives a path of least cost from `from` to `to` (A*), with the two points as its ends.
+   * The cost of a path is its length, plus `cost(n)` for each link of the path and each box `n` of that link.
+   * Each cost must be 0 or more. The straight line from `from` to `to` is a path too, so the method always gives a path.
+   */
+  path(from: Point, to: Point, cost: (n: Node) => number): Point[] {
+    const points = this.points;
+    const nodes = this.#nodes;
+    const extra = (a: Point, b: Point): number => {
+      let c = 0;
+      this.#obstacles.through(a, b, (m) => {
+        c += cost(m);
+      });
+      return c;
+    };
+    let best = dist(from, to) + extra(from, to);
+    let bestEnd = -1;
+    const goal = new Map<number, number>();
+    for (const j of this.#nearest(to, 2 * this.#k)) goal.set(j, dist(points[j]!, to) + extra(points[j]!, to));
+    const n = points.length;
+    const g = new Float64Array(n).fill(Infinity);
+    const parent = new Int32Array(n).fill(-1);
+    const closed = new Uint8Array(n);
+    const heap = new MinHeap();
+    for (const j of this.#nearest(from, 2 * this.#k)) {
+      const c = dist(from, points[j]!) + extra(from, points[j]!);
+      if (c < g[j]!) {
+        g[j] = c;
+        heap.push(c + dist(points[j]!, to), j);
+      }
+    }
+    while (heap.size > 0) {
+      if (heap.topKey >= best) break;
+      const i = heap.pop();
+      if (closed[i] === 1) continue;
+      closed[i] = 1;
+      const gi = g[i]!;
+      const tail = goal.get(i);
+      if (tail !== undefined && gi + tail < best) {
+        best = gi + tail;
+        bestEnd = i;
+      }
+      const adj = this.#adj[i]!;
+      const len = this.#len[i]!;
+      const through = this.#through[i]!;
+      for (let m = 0; m < adj.length; m++) {
+        const j = adj[m]!;
+        if (closed[j] === 1) continue;
+        let c = gi + len[m]!;
+        for (const b of through[m]!) c += cost(nodes[b]!);
+        if (c < g[j]!) {
+          g[j] = c;
+          parent[j] = i;
+          heap.push(c + dist(points[j]!, to), j);
+        }
+      }
+    }
+    const out: Point[] = [to];
+    for (let i = bestEnd; i >= 0; i = parent[i]!) out.push(points[i]!);
+    out.push(from);
+    return out.reverse();
+  }
+}
+
 /** A link of a cone is at most this number of cells long. A longer search costs time on a dense level and finds few new links. */
 const CONE_CELLS = 3;