@mark1russell7/highways 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build/index.d.ts

@@ -0,0 +1,625 @@
+/** A point in the plane. */
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+/** A box with its top-left corner at (`x`, `y`). */
+export interface Box {
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+/** This function gives the distance between two points. */
+export declare function dist(a: Point, b: Point): number;
+/** This function gives the center of a box. */
+export declare function center(b: Box): Point;
+/** This function gives a box that is larger by `m` on each side. A negative `m` makes the box smaller. */
+export declare function inflate(b: Box, m: number): Box;
+/** This function gives the sum of the lengths of the segments of a polyline. */
+export declare function polylineLength(p: readonly Point[]): number;
+/**
+ * This function tells if the segments `ab` and `cd` cross at one point inside both of them.
+ * Segments that only touch at an end, or that are collinear, do not cross.
+ */
+export declare function segmentsCross(a: Point, b: Point, c: Point, d: Point): boolean;
+/**
+ * This function tells if the segment `ab` goes through the inside of the box.
+ * The function clips the segment to the box (Liang-Barsky) and asks for a part longer than `eps`.
+ */
+export declare function segmentHitsBox(a: Point, b: Point, box: Box, eps?: number): boolean;
+/** This function tells if the segment `ab` goes through the inside of the box from (`x0`, `y0`) to (`x1`, `y1`). */
+export declare function segmentHitsRect(a: Point, b: Point, x0: number, y0: number, x1: number, y1: number, eps?: number): boolean;
+/** This function gives the distance from a point to a box. The distance is 0 when the point is in the box. */
+export declare function pointBoxDistance(p: Point, b: Box): number;
+/** This function gives the distance from a point to the segment `ab`. */
+export declare function pointSegmentDistance(p: Point, a: Point, b: Point): number;
+/** This function gives the distance from the segment `ab` to a box. The distance is 0 when they touch. */
+export declare function segmentBoxDistance(a: Point, b: Point, box: Box): number;
+/**
+ * This function gives the turn at each inner vertex of a polyline, in radians, from -π to π.
+ * A positive turn is counterclockwise in a frame with the y axis up. The function skips segments shorter than `eps`.
+ */
+export declare function turns(p: readonly Point[], eps?: number): number[];
+/** This function counts the vertices of a polyline where the direction changes by more than `minTurn` radians. */
+export declare function bendCount(p: readonly Point[], minTurn?: number): number;
+/**
+ * This function counts the inflections of a polyline: the changes of the sign of the turn.
+ * A turn smaller than `minTurn` radians does not count. Thus a straight part between two turns keeps their signs.
+ */
+export declare function inflectionCount(p: readonly Point[], minTurn?: number): number;
+/**
+ * This function gives the discrete Fréchet distance between two polylines (Eiter and Mannila, 1994).
+ * The cost is O(|p|·|q|) in time and O(|q|) in memory.
+ */
+export declare function frechet(p: readonly Point[], q: readonly Point[]): number;
+/**
+ * A uniform grid of buckets over the plane. A box item goes into each bucket that the box touches.
+ * A segment item goes only into the buckets along the segment, so a long diagonal segment stays cheap.
+ * A query gives each item in the buckets that it touches, one time each.
+ */
+export declare class Grid<T> {
+  #private;
+  /** This constructor makes an empty grid with square buckets of side `cell`. */
+  constructor(cell: number);
+  /** This method adds an item with its bounding box. */
+  add(item: T, b: Box): void;
+  /** This method adds the segment `ab` as an item. */
+  addSegment(item: T, a: Point, b: Point): void;
+  /** This method gives each item whose buckets touch the box to `visit`, one time each. */
+  query(b: Box, visit: (item: T) => void): void;
+  /** This method gives each item whose buckets come within `margin` of the segment `ab` to `visit`, one time each. */
+  querySegment(a: Point, b: Point, margin: number, visit: (item: T) => void): void;
+}
+/** This function gives the bounding box of the segment `ab`. */
+export declare function segmentBounds(a: Point, b: Point): Box;
+/** A side of a node box. */
+export type Side = "north" | "east" | "south" | "west";
+/**
+ * A plug of a node: a place where edges go into the node.
+ * A plug with `at` is fixed. The router does not move it. A plug without `at` is free: the router places it.
+ */
+export interface Port {
+  readonly id: string;
+  /** This point is the fixed place of the plug, relative to the top-left corner of the node box. */
+  readonly at?: Point;
+  /** This side is where a free plug goes. Without it, the router picks the side. */
+  readonly side?: Side;
+}
+/** A node: a box that routes must not go through. */
+export interface Node {
+  readonly id: string;
+  readonly box: Box;
+  readonly ports?: readonly Port[];
+}
+/** One end of an edge: a node, and optionally one plug of that node. */
+export interface End {
+  readonly node: string;
+  readonly port?: string;
+}
+/** An edge between two nodes. `data` is free for the grouping rules. */
+export interface Edge {
+  readonly id: string;
+  readonly source: End;
+  readonly target: End;
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+/** The input of a router. */
+export interface Graph {
+  readonly nodes: readonly Node[];
+  readonly edges: readonly Edge[];
+}
+/** The route of one edge: a polyline from the source plug to the target plug, in absolute coordinates. */
+export interface Route {
+  readonly edge: string;
+  readonly points: readonly Point[];
+}
+/**
+ * One zoom level of a result. Each shown item is a node or a group of nodes.
+ * Each link joins two shown items and carries the count of the edges that it stands for.
+ */
+export interface Level {
+  readonly depth: number;
+  readonly items: readonly LevelItem[];
+  readonly links: readonly LevelLink[];
+}
+/** A shown item of a level: one node, or a group that stands for its nodes. */
+export interface LevelItem {
+  readonly id: string;
+  readonly box: Box;
+  readonly nodes: readonly string[];
+}
+/** A link of a level: the edges between two shown items, drawn as one path. */
+export interface LevelLink {
+  readonly source: string;
+  readonly target: string;
+  readonly count: number;
+  readonly points: readonly Point[];
+}
+/** The output of a router. `levels` is present when the router makes zoom levels. */
+export interface Result {
+  readonly routes: readonly Route[];
+  readonly levels?: readonly Level[];
+  readonly bundles?: readonly Bundle[];
+  /** The stretches of way that several routes share, if the router gives them. */
+  readonly runs?: readonly SharedRun[];
+}
+/**
+ * A bundle: edges from one node that share one plug and one trunk. Then the edges fan out to their targets.
+ * A renderer draws a bundle as one fat edge with a count, or as one lane for each edge.
+ */
+export interface Bundle {
+  readonly id: string;
+  /** The key that the grouping rule gave each edge of the bundle. */
+  readonly key: string;
+  /** The node where the edges share their plug. */
+  readonly node: string;
+  /** The edges in lane order. Lane 0 turns most to the left of the trunk, in a frame with the y axis down. */
+  readonly edges: readonly string[];
+  /** The shared start of each route of the bundle, from the plug to the split point. */
+  readonly trunk: readonly Point[];
+}
+/**
+ * A stretch of way that several routes share, with the same points. Each route of `edges` has `points` in it,
+ * in this order or in the reverse order. A renderer draws a run as one fat line, or as one lane for each edge.
+ */
+export interface SharedRun {
+  readonly id: string;
+  /** The key of the grouping rule of the edges. */
+  readonly key: string;
+  readonly points: readonly Point[];
+  /** The edges in lane order. Lane 0 is on the left of the run, from its first point to its last. The y axis points down. */
+  readonly edges: readonly string[];
+}
+/** A grouping rule gives each edge a key. The edges from one plug with one key make a bundle. An edge without a key stays alone. */
+export type GroupRule = (edge: Edge) => string | undefined;
+/** A router: a strategy with a name. The same input must give the same result. */
+export interface Router {
+  readonly name: string;
+  /** The benchmark skips a fixture with more nodes than this. Without it, the router takes each fixture. */
+  readonly maxNodes?: number;
+  route(graph: Graph): Result;
+}
+/** This function gives a map from the id of each node to the node. */
+export declare function nodeIndex(g: Graph): Map<string, Node>;
+/** This function gives the absolute place of a fixed plug, or `undefined` for a free plug or no plug. */
+export declare function fixedPortPoint(node: Node, end: End): Point | undefined;
+/** This function gives a seeded random source with values in [0, 1) (mulberry32). */
+export declare function rng(seed: number): () => number;
+/**
+ * The ways a fixture puts its nodes and picks its edges. In `collections`, each cluster is one collection,
+ * and some nodes link to many nodes of one other collection (a fan-out).
+ */
+export type FixtureKind = "uniform" | "clustered" | "grid" | "hubs" | "collections";
+/** The parameters of a generated graph. */
+export interface FixtureSpec {
+  readonly name: string;
+  readonly kind: FixtureKind;
+  readonly nodes: number;
+  /** The number of edges is about `nodes × edgesPerNode`. */
+  readonly edgesPerNode: number;
+  readonly seed: number;
+  /** This share of the edges, from 0 to 1, joins a node near the source. */
+  readonly locality?: number;
+  /** This share of the nodes, from 0 to 1, has one fixed plug that its outgoing edges use. */
+  readonly fixedPorts?: number;
+}
+/** The fixtures of the benchmark, from 10 to 100 000 nodes. */
+export declare const FIXTURES: readonly FixtureSpec[];
+/**
+ * This function makes the graph of a fixture. The same spec always gives the same graph.
+ * Node boxes do not overlap, and a gap of 12 units stays between them.
+ */
+export declare function makeFixture(spec: FixtureSpec): Graph;
+/** A plug: the point where a route leaves or enters a node, and the outward normal of its side. */
+export interface Plug {
+  readonly point: Point;
+  readonly normal: Point;
+}
+/** The outward normal of each side, in a frame with the y axis down. */
+export declare const SIDE_NORMAL: Readonly<Record<Side, Point>>;
+/** This function gives the side of the box that is nearest to the point. */
+export declare function nearestSide(box: Box, p: Point): Side;
+/**
+ * This function gives the side that faces `toward`: the side of the larger component of the direction from the center.
+ * Thus the angle between the normal of the side and that direction is 45° or less.
+ */
+export declare function sideToward(box: Box, toward: Point): Side;
+/**
+ * This function gives the point on a side of the box that is nearest to the line from the center to `toward`.
+ * The point stays away from the corners by `inset`, or by a quarter of the side when the side is short.
+ */
+export declare function pointOnSide(box: Box, side: Side, toward: Point, inset?: number): Point;
+/**
+ * This function places the plug of one end of an edge. A fixed plug stays at its point. A plug with a side stays on that side.
+ * The router places a free plug on the side that faces `toward`.
+ */
+export declare function placePlug(node: Node, end: End, toward: Point): Plug;
+/** The options of the inflection rule. */
+export interface InflectionOptions {
+  /** The half width of the axis and diagonal bands, in radians. The default is 7°. */
+  readonly tol?: number;
+  /** The number of segments of the curve. The default is 24. */
+  readonly samples?: number;
+  /** The largest angle between the tangent and the chord, in radians. The default is 1.35 (approximately 77°). */
+  readonly maxAngle?: number;
+}
+/**
+ * This function gives the number of inflections that the rule asks for a chord at the angle `angle` (radians).
+ * It gives 0 near an axis, 1 near a diagonal and 2 between them. The bands are `tol` wide on each side.
+ */
+export declare function inflectionSector(angle: number, tol?: number): 0 | 1 | 2;
+/**
+ * This function draws the curve of the inflection rule from the plug `p0` to `target`.
+ * The curve leaves `p0` along `normal`. In the frame of the chord, its side offset f has f(0) = f(L) = 0 and f'(0) = tan θ.
+ * Here θ is the angle from the chord to the normal. A polynomial of degree 2, 3 or 4 gives 0, 1 or 2 inflections,
+ * at 1/2, or at 1/3 and 2/3, of the chord.
+ */
+export declare function inflectionCurve(p0: Point, normal: Point, target: Point, options?: InflectionOptions): Point[];
+/**
+ * This function rounds each inner vertex of a polyline with a quadratic Bézier curve.
+ * The curve starts and ends at most `radius` from the vertex, and at most half of each segment. The ends of the polyline stay.
+ */
+export declare function roundCorners(p: readonly Point[], radius: number, steps?: number): Point[];
+/** The nodes as obstacles, with a grid for fast tests. */
+export declare class Obstacles {
+  #private;
+  /** This constructor indexes the boxes of the nodes. */
+  constructor(nodes: readonly Node[], cell: number);
+  /** This method tells if the segment `ab` stays out of each box, made larger by `pad`. The nodes in `skip` do not count. */
+  clear(a: Point, b: Point, pad: number, skip?: ReadonlySet<Node>): boolean;
+  /** This method tells if the polyline stays out of each box, made larger by `pad`. The nodes in `skip` do not count. */
+  clearPath(p: readonly Point[], pad: number, skip?: ReadonlySet<Node>): boolean;
+  /** This method tells if the point is inside a box, made larger by `pad`. The node `skip` does not count. */
+  inside(p: Point, pad: number, skip?: Node): boolean;
+}
+/** The options of the corner graph. */
+export interface CornerGraphOptions {
+  /** The distance from a box to its corners. */
+  readonly margin: number;
+  /** The number of visible neighbours of each corner. */
+  readonly k: number;
+  /**
+   * The spacing of a lattice of free points over the plane, in units of the mean node size. The default is 3, and 0 turns it off.
+   * The lattice links groups of nodes across empty space. Without it, the nearest corners of a group are all in that group.
+   */
+  readonly lattice?: number;
+}
+/**
+ * A sparse visibility graph. Its vertices are the corners of the boxes, made larger by `margin`.
+ * Each corner links to its `k` nearest corners that it can see. A lattice of free points links the groups of nodes.
+ * A path goes from corner to corner around the boxes.
+ * The obstacle test uses half of the margin, so a path keeps a clearance of at least half of the margin.
+ */
+export declare class CornerGraph {
+  #private;
+  readonly points: Point[];
+  /** This constructor makes the graph of the nodes. */
+  constructor(nodes: readonly Node[], obstacles: Obstacles, options: CornerGraphOptions);
+  /** This method gives the number of links of the graph. */
+  get linkCount(): number;
+  /** This method gives the index of the corner nearest to `p`, seen or not, or -1 when the graph has no corner near it. */
+  nearest(p: Point): number;
+  /** This method gives at most `k` corners that `p` can see, nearest first. The corner `self` does not count. */
+  nearestVisible(p: Point, k: number, self?: number): number[];
+  /**
+   * This method gives a shortest path from `from` to `to` in the graph (A*), with the two points as its ends.
+   * It gives `undefined` when the graph links no corner near `from` to a corner near `to`.
+   * The function `cost` can change the cost of the link from corner `i` to corner `j`, of length `d`.
+   * It must give at least `floor` × `d`, so that the estimate of A* stays below the true cost.
+   */
+  path(from: Point, to: Point, cost?: (i: number, j: number, d: number) => number, floor?: number): Point[] | undefined;
+  /** This method removes the vertices that a later vertex makes needless: from each vertex, it goes to the farthest vertex in view. */
+  pull(p: readonly Point[], lookahead?: number): Point[];
+}
+/** The options of a way finder. */
+export interface WayOptions {
+  /** The distance from a box to the corners of the graph. The default is 5. */
+  readonly margin?: number;
+  /** The number of visible neighbours of each corner. The default is 8. */
+  readonly k?: number;
+  /** With `smooth`, a way in clear view uses the inflection rule, and the other ways get round corners. */
+  readonly smooth?: boolean;
+}
+/**
+ * The ways around the nodes of one graph. A way leaves a plug along its normal.
+ * It goes a shortest way (A*) through the corner graph, without the needless corners. It enters the other plug along its normal.
+ */
+export declare class WayFinder {
+  #private;
+  readonly obstacles: Obstacles;
+  readonly corners: CornerGraph;
+  readonly margin: number;
+  /** This constructor makes the obstacles and the corner graph of the nodes. */
+  constructor(nodes: readonly Node[], options?: WayOptions);
+  /** This method gives the point at `margin` from the plug, along its normal. */
+  out(p: Plug): Point;
+  /** This method gives a way from plug to plug. Without a way in the graph, it gives the straight line. */
+  between(ps: Plug, pt: Plug, ends: ReadonlySet<Node>): Point[];
+  /** This method gives a way from a plug to a free point, or `undefined` when the graph has none. */
+  fromPlug(ps: Plug, to: Point): Point[] | undefined;
+  /** This method gives a way from a free point to a plug, or `undefined` when the graph has none. */
+  toPlug(from: Point, pt: Plug): Point[] | undefined;
+}
+/** A piece of drawn way. A shared segment carries several edges, in lane order. A private segment carries one edge. */
+export interface Segment {
+  readonly id: string;
+  readonly points: readonly Point[];
+  /** The edges in lane order. Lane 0 is on the left of the segment, from its first point to its last. The y axis points down. */
+  readonly edges: readonly string[];
+  /** The number of edges. A renderer shows it on a fat edge. */
+  readonly count: number;
+}
+/** One step of a path: a segment, the way through it, and the lane of the edge in it. */
+export interface SegmentRef {
+  readonly segment: string;
+  /** This value is true when the edge goes from the last point of the segment to its first point. */
+  readonly reverse: boolean;
+  readonly lane: number;
+}
+/** The route of one edge as a list of segments. */
+export interface Path {
+  readonly edge: string;
+  readonly segments: readonly SegmentRef[];
+}
+/** The routes of a result as shared geometry. A renderer can draw each segment one time, with a count. */
+export interface SegmentGraph {
+  readonly segments: readonly Segment[];
+  readonly paths: readonly Path[];
+}
+/**
+ * This function breaks each route into segments. The runs and the trunks of the bundles become shared segments.
+ * The other parts of each route become private segments. The segments of a path, in order, give the points of its route again.
+ */
+export declare function segmentsOf(result: Result): SegmentGraph;
+/** This function gives the points of a path, with the segments in the order and the way of the path. */
+export declare function pathPoints(graph: SegmentGraph, path: Path): Point[];
+/**
+ * This function moves each point of a polyline by `d` to the left, in a frame with the y axis down.
+ * At an inner point, it moves along the bisector, at most 2 × `d` far.
+ */
+export declare function offsetPolyline(p: readonly Point[], d: number): Point[];
+/** The options of `pullApart`. */
+export interface PullApartOptions {
+  /** The distance between two lanes. */
+  readonly spacing: number;
+  /** The largest width of a segment, from its outer lane on the left to its outer lane on the right. */
+  readonly maxWidth: number;
+}
+/**
+ * This function pulls the lanes of each shared segment apart, and gives a route for each edge.
+ * The lanes keep the lane order, so they do not cross in a segment. The two ends of each route stay at their plugs.
+ */
+export declare function pullApart(graph: SegmentGraph, options: PullApartOptions): Route[];
+/**
+ * This function gives the lane order of the edges on a shared way `run` (metro-line order). Two routes go on together
+ * past the last point of the run until they part. The route that turns more to the left there gets the lane more to the left.
+ * Two routes can part only before the first point. Then the route that comes from more to the left gets the lane more to the left.
+ * A route that does not hold the run goes last.
+ */
+export declare function orderLanes(run: readonly Point[], routes: readonly Route[]): string[];
+/** A section of the plane: a cell of a quadtree, with the nodes whose centers are in it. */
+export interface Section {
+  /** The path from the root: "s", then one digit from 0 to 3 for each step down. */
+  readonly id: string;
+  readonly depth: number;
+  readonly cell: Box;
+  /** The indices of the nodes, in the order of the graph. */
+  readonly nodes: readonly number[];
+  readonly children: readonly Section[];
+}
+/** The options of the tree of sections. */
+export interface SectionOptions {
+  /** A section with more nodes splits. The default is 8. */
+  readonly cap?: number;
+  /** The tree stops at this depth. The default is 16. */
+  readonly maxDepth?: number;
+}
+/**
+ * This function makes the tree of sections of the nodes. A cell with more than `cap` nodes splits in four.
+ * When the nodes of a cell are all in one quarter, the cell becomes that quarter and does not make a level.
+ */
+export declare function buildSections(nodes: readonly Node[], options?: SectionOptions): Section;
+/** This function gives the sections of the tree, parents before children. */
+export declare function allSections(root: Section): Section[];
+/** This function gives the depth of the deepest section. */
+export declare function treeDepth(root: Section): number;
+/** This function gives the point where the ray from the center of the box to `toward` leaves the box. */
+export declare function boxExit(box: Box, toward: Point): Point;
+/**
+ * The control of the benchmark: each edge is one straight line between its plugs.
+ * A free plug goes where the line between the two centers leaves the box.
+ */
+export declare const straightRouter: Router;
+/**
+ * Plugs and the inflection rule, with no obstacles. Each edge leaves its source plug at the tangent of the side.
+ * It goes to the target plug on the curve of the rule. This router measures the rule alone.
+ */
+export declare const plugsRouter: Router;
+/** The options of the corner router. */
+interface CornersOptions extends WayOptions {
+  /** The name in the benchmark. */
+  readonly name: string;
+  /** The benchmark skips a fixture with more nodes. */
+  readonly maxNodes?: number;
+}
+/**
+ * This function makes a router that goes around the nodes.
+ * Each edge leaves its plug along the normal of the side. It goes a shortest way (A*) through a sparse visibility graph
+ * of the box corners, without the needless corners. It enters the target plug along its normal.
+ */
+export declare function cornersRouter(options: CornersOptions): Router;
+/** The options of the router with shared ways. */
+interface SharedOptions extends WayOptions {
+  /** The name in the benchmark. */
+  readonly name: string;
+  /** The edges with one key share their ways. Without a rule, all edges share. An edge without a key shares with no edge. */
+  readonly rule?: GroupRule;
+  /** The cost of a link that an edge with the same key uses already, as a share of its length. The default is 0.5. */
+  readonly discount?: number;
+  /** The benchmark skips a fixture with more nodes. */
+  readonly maxNodes?: number;
+}
+/**
+ * This function makes a router where edges share their ways (after Pupyrev, Nachmanson, Bereg and Holroyd, "Edge routing with ordered bundles").
+ * The edges go one by one through the corner graph. A link that an edge with the same key uses already costs less.
+ * Thus the edges of a key come together on common ways. Each stretch that several edges share has the same points in each route.
+ * The result gives each stretch as a run, with the order of its lanes.
+ */
+export declare function sharedRouter(options: SharedOptions): Router;
+/** The options of the router with sections. */
+interface SectionsOptions extends WayOptions, SectionOptions {
+  /** The name in the benchmark. */
+  readonly name: string;
+  /**
+   * The number of hubs on each side of the lowest common section that a way passes. A smaller number gives shorter ways
+   * and fewer shared ways. Without it, a way passes each hub from its node up.
+   */
+  readonly hubs?: number;
+  /** A way through the hubs can be at most this many times as long as the line between its plugs. Else the edge goes directly. The default is 2. */
+  readonly stretch?: number;
+  /** The benchmark skips a fixture with more nodes. */
+  readonly maxNodes?: number;
+}
+/**
+ * This function makes a router with a tree of sections. Each section has a hub: the free corner nearest to the center of its nodes.
+ * An edge goes from its node up the hubs of its sections to the lowest common section, across, and down to the other node.
+ * Each way from hub to hub is found one time, so all the edges on it share its points.
+ * The edges in one section of the lowest level go straight around the nodes. The result gives one zoom level for each depth of the tree.
+ */
+export declare function sectionsRouter(options: SectionsOptions): Router;
+/** The options of the trunk router. */
+interface TrunksOptions extends WayOptions {
+  /** The name in the benchmark. */
+  readonly name: string;
+  /** The grouping rule. The edges from one plug with one key share a trunk. */
+  readonly rule: GroupRule;
+  /** The split point is at this share of the way to the center of the targets. The default is 0.5. */
+  readonly split?: number;
+  /** A group with fewer edges stays unbundled. The default is 2. */
+  readonly minSize?: number;
+  /** The benchmark skips a fixture with more nodes. */
+  readonly maxNodes?: number;
+}
+/** The rule that groups the edges by the collection of their target, in `data.collection`. */
+export declare const byCollection: GroupRule;
+/**
+ * This function groups the edges by their source plug and their key. Each group keeps the order of the edges.
+ * A group with fewer than `minSize` edges does not appear.
+ */
+export declare function groupEdges(edges: readonly Edge[], rule: GroupRule, minSize?: number): Map<string, Edge[]>;
+/**
+ * This function gives the lane order of the branches that leave the split point `from`, with the trunk along `dir`.
+ * Lane 0 turns most to the left, in a frame with the y axis down. Thus two lanes do not cross at the split.
+ */
+export declare function laneOrder(dir: Point, from: Point, branches: readonly {
+  readonly edge: string;
+  readonly next: Point;
+}[]): string[];
+/**
+ * This function gives the split point of a bundle, on the line from `start` to the center of the targets.
+ * The point is at `split` of the way, but at most half of the way to the nearest target. It moves back toward `start` out of the boxes.
+ */
+export declare function splitPoint(start: Point, targets: readonly Point[], split: number, free: (p: Point) => boolean, step: number): Point;
+/**
+ * This function makes a router that bundles the edges by a rule. The edges of a group share one plug and one trunk
+ * to a split point. From there, each edge goes its own way. The router gives the bundles with their lane order.
+ * The edges outside the groups go as in the corner router.
+ */
+export declare function trunksRouter(options: TrunksOptions): Router;
+/** The routers that the benchmark races. */
+export declare const ROUTERS: readonly Router[];
+/** A broken hard rule. A correct router has none. */
+export interface Violation {
+  readonly rule: "complete" | "ends-at-plugs" | "fixed-plugs" | "no-pass-through" | "counts-sum" | "bundle-trunk" | "run-shared";
+  readonly edge?: string;
+  readonly detail: string;
+}
+/** The tolerance of the hard rules, in units of the plane. */
+export declare const TOLERANCE = .5;
+/**
+ * This function checks the hard rules of a result. Each edge has one route, and each route starts and ends at its nodes.
+ * Fixed plugs stay in place. No route goes through a node that is not one of its ends. The counts of each level add up.
+ *
+ * Each route of a bundle starts with its trunk, and an edge is in one bundle at most.
+ * Each run has two edges or more, and the route of each edge holds the points of the run in a row.
+ * The function gives at most `limit` violations.
+ */
+export declare function checkProperties(graph: Graph, result: Result, limit?: number): Violation[];
+/** The quality of a result. Lower is better for each value except `clearance`. */
+export interface Quality {
+  /** The length of all drawn lines. A segment that several routes share counts one time. */
+  readonly ink: number;
+  /** The number of points where two drawn segments cross. */
+  readonly crossings: number;
+  /** This value is true when `crossings` is an estimate from a sample of the segments. */
+  readonly crossingsEstimated: boolean;
+  /** The mean number of bends of a route. */
+  readonly bends: number;
+  /** The mean number of inflections of a route. */
+  readonly inflections: number;
+  /** The mean distance from a route to the nearest node that is not one of its ends, up to `CLEARANCE_CAP`. */
+  readonly clearance: number;
+  /** The share of the routes that come closer than 4 units to a node that is not one of their ends. */
+  readonly tight: number;
+  /** The mean ratio of the length of a route to the distance between its ends. */
+  readonly detour: number;
+  /** The mean angle, in degrees, between the first or last segment of a route and the normal of the side of its node. */
+  readonly plugAngle: number;
+}
+/** The clearance stops at this distance. */
+export declare const CLEARANCE_CAP = 40;
+/** This function measures the quality of a result. */
+export declare function measureQuality(graph: Graph, result: Result): Quality;
+/**
+ * This function gives an angle in degrees: the angle between the segment from `at` to `next` and the outward normal.
+ * The normal is the normal of the side of the box nearest to `at`. A route that starts inside the box (an interior route) gives no angle.
+ */
+export declare function sideAngle(box: Box, at: Point, next: Point): number | undefined;
+/**
+ * This function counts the crossings of a set of segments with a grid of buckets.
+ * Above 20 000 segments, it counts the crossings of a seeded sample of 2 000 segments and scales the count.
+ */
+export declare function countCrossings(segs: readonly (readonly [Point, Point])[]): [number, boolean];
+/** The change between two results of the same graph: the Fréchet distance between the two routes of each edge. */
+export interface Stability {
+  readonly mean: number;
+  readonly max: number;
+  /** The share of the routes that moved more than 1 unit. */
+  readonly moved: number;
+}
+/** This function measures how much the routes changed between two results. */
+export declare function measureStability(before: Result, after: Result): Stability;
+/** One row of the benchmark: one router on one fixture. */
+export interface BenchRow {
+  readonly router: string;
+  readonly fixture: string;
+  readonly nodes: number;
+  readonly edges: number;
+  /** The median time of one run, in milliseconds. */
+  readonly ms: number;
+  /** This value is false when two runs on the same input gave different results. */
+  readonly deterministic: boolean;
+  readonly violations: number;
+  /** The first violations, for the report. */
+  readonly sample: readonly Violation[];
+  readonly quality: Quality;
+}
+/** The options of a benchmark run. */
+export interface BenchOptions {
+  /** The number of timed routes of each fixture by each router. The default is 3. */
+  readonly repeat?: number;
+}
+/** This function routes each fixture with each router, checks the hard rules and measures the quality. */
+export declare function runBenchmark(routers: readonly Router[], fixtures: readonly FixtureSpec[], options?: BenchOptions): BenchRow[];
+/**
+ * This function tells if two values hold the same data, as JSON sees it. It does not make a string,
+ * because the result of a large graph can be longer than the longest string.
+ */
+export declare function sameData(a: unknown, b: unknown): boolean;
+/** This function routes one graph with one router and measures the result. */
+export declare function benchOne(router: Router, fixture: string, graph: Graph, repeat?: number): BenchRow;
+/** This function writes the rows as a Markdown table. */
+export declare function formatTable(rows: readonly BenchRow[]): string;
+export type { CornersOptions, SectionsOptions, SharedOptions, TrunksOptions };
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/geom.ts","../src/grid.ts","../src/model.ts","../src/fixtures.ts","../src/plugs.ts","../src/curves.ts","../src/visibility.ts","../src/ways.ts","../src/segments.ts","../src/sections.ts","../src/routers/straight.ts","../src/routers/plugs.ts","../src/routers/corners.ts","../src/routers/shared.ts","../src/routers/sections.ts","../src/routers/trunks.ts","../src/routers/index.ts","../src/bench/properties.ts","../src/bench/quality.ts","../src/bench/run.ts"],"mappings":";iBACiB;WACN;WACA;;;iBAIM;WACN;WACA;WACA;WACA;;;wBAIK,KAAK,GAAG,OAAO,GAAG;;wBAOlB,OAAO,GAAG,MAAM;;wBAKhB,QAAQ,GAAG,KAAK,YAAY;;wBAK5B,eAAe,YAAY;;;;;wBAY3B,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG;;;;;wBAY/C,eAAe,GAAG,OAAO,GAAG,OAAO,KAAK,KAAK;;wBAK7C,gBAAgB,GAAG,OAAO,GAAG,OAAO,YAAY,YAAY,YAAY,YAAY;;wBA2BpF,iBAAiB,GAAG,OAAO,GAAG;;wBAO9B,qBAAqB,GAAG,OAAO,GAAG,OAAO,GAAG;;wBAS5C,mBAAmB,GAAG,OAAO,GAAG,OAAO,KAAK;;;;;wBAiB5C,MAAM,YAAY,SAAS;;wBAgB3B,UAAU,YAAY,SAAS;;;;;wBAQ/B,gBAAgB,YAAY,SAAS;;;;;wBAgBrC,QAAQ,YAAY,SAAS,YAAY;;;;;;qBC1J5C,KAAK;;;EAUhB,YAAY;;EAuEZ,IAAI,MAAM,GAAG,GAAG;;EAKhB,WAAW,MAAM,GAAG,GAAG,OAAO,GAAG;;EAMjC,MAAM,GAAG,KAAK,QAAQ,MAAM;;EAK5B,aAAa,GAAG,OAAO,GAAG,OAAO,gBAAgB,QAAQ,MAAM;;;wBAOjD,cAAc,GAAG,OAAO,GAAG,QAAQ;;YC5GvC;;;;;iBAMK;WACN;;WAEA,KAAK;;WAEL,OAAO;;;iBAID;WACN;WACA,KAAK;WACL,iBAAiB;;;iBAIX;WACN;WACA;;;iBAIM;WACN;WACA,QAAQ;WACR,QAAQ;WACR,OAAO,SAAS;;;iBAIV;WACN,gBAAgB;WAChB,gBAAgB;;;iBAIV;WACN;WACA,iBAAiB;;;;;;iBAOX;WACN;WACA,gBAAgB;WAChB,gBAAgB;;;iBAIV;WACN;WACA,KAAK;WACL;;;iBAIM;WACN;WACA;WACA;WACA,iBAAiB;;;iBAIX;WACN,iBAAiB;WACjB,kBAAkB;WAClB,mBAAmB;;WAEnB,gBAAgB;;;;;;iBAOV;WACN;;WAEA;;WAEA;;WAEA;;WAEA,gBAAgB;;;;;;iBAOV;WACN;;WAEA;WACA,iBAAiB;;WAEjB;;;YAIC,aAAa,MAAM;;iBAGd;WACN;;WAEA;EACT,MAAM,OAAO,QAAQ;;;wBAIP,UAAU,GAAG,QAAQ,YAAY;;wBAOjC,eAAe,MAAM,MAAM,KAAK,MAAM;;wBC/HtC,IAAI;;;;;YAeR;;iBAGK;WACN;WACA,MAAM;WACN;;WAEA;WACA;;WAEA;;WAEA;;;qBAIE,mBAAmB;;;;;wBAqBhB,YAAY,MAAM,cAAc;;iBCtD/B;WACN,OAAO;WACP,QAAQ;;;qBAIN,aAAa,SAAS,OAAO,MAAM;;wBAQhC,YAAY,KAAK,KAAK,GAAG,QAAQ;;;;;wBAgBjC,WAAW,KAAK,KAAK,QAAQ,QAAQ;;;;;wBAYrC,YAAY,KAAK,KAAK,MAAM,MAAM,QAAQ,OAAO,iBAAY;;;;;wBAsB7D,UAAU,MAAM,MAAM,KAAK,KAAK,QAAQ,QAAQ;;iBCjE/C;;WAEN;;WAEA;;WAEA;;;;;;wBAOK,iBAAiB,eAAe;;;;;;;wBAchC,gBAAgB,IAAI,OAAO,QAAQ,OAAO,QAAQ,OAAO,UAAS,oBAAyB;;;;;wBAkC3F,aAAa,YAAY,SAAS,gBAAgB,iBAAY;;qBC3DjE;;;EAIX,YAAY,gBAAgB,QAAQ;;EAMpC,MAAM,GAAG,OAAO,GAAG,OAAO,aAAa,OAAO,YAAY;;EAY1D,UAAU,YAAY,SAAS,aAAa,OAAO,YAAY;;EAM/D,OAAO,GAAG,OAAO,aAAa,OAAO;;;iBAatB;;WAEN;;WAEA;;;;;WAKA;;;;;;;;qBASE;;WACF,QAAQ;;EAoBjB,YAAY,gBAAgB,QAAQ,WAAW,WAAW,SAAS;;MA0D/D;;EAOJ,QAAQ,GAAG;;EAkBX,eAAe,GAAG,OAAO,WAAW;;;;;;;EA4BpC,KAAK,MAAM,OAAO,IAAI,OAAO,QAAQ,WAAW,WAAW,sBAAsB,iBAAoB;;EAqDrG,KAAK,YAAY,SAAS,qBAAiB;;;iBClP5B;;WAEN;;WAEA;;WAEA;;;;;;qBAOE;;WACF,WAAW;WACX,SAAS;WACT;;EAIT,YAAY,gBAAgB,QAAQ,UAAS;;EAQ7C,IAAI,GAAG,OAAO;;EAKd,QAAQ,IAAI,MAAM,IAAI,MAAM,MAAM,YAAY,QAAQ;;EAgBtD,SAAS,IAAI,MAAM,IAAI,QAAQ;;EAM/B,OAAO,MAAM,OAAO,IAAI,OAAO;;;iBC1DhB;WACN;WACA,iBAAiB;;WAEjB;;WAEA;;;iBAIM;WACN;;WAEA;WACA;;;iBAIM;WACN;WACA,mBAAmB;;;iBAIb;WACN,mBAAmB;WACnB,gBAAgB;;;;;;wBAmBX,WAAW,QAAQ,SAAS;;wBAkD5B,WAAW,OAAO,cAAc,MAAM,OAAO;;;;;wBAgB7C,eAAe,YAAY,SAAS,YAAY;;iBAuB/C;;WAEN;;WAEA;;;;;;wBAOK,UAAU,OAAO,cAAc,SAAS,mBAAmB;;;;;;;wBAsC3D,WAAW,cAAc,SAAS,iBAAiB;;iBCvLlD;;WAEN;WACA;WACA,MAAM;;WAEN;WACA,mBAAmB;;;iBAIb;;WAEN;;WAEA;;;;;;wBAOK,cAAc,gBAAgB,QAAQ,UAAS,iBAAsB;;wBA0CrE,YAAY,MAAM,UAAU;;wBAW5B,UAAU,MAAM;;wBC3EhB,QAAQ,KAAK,KAAK,QAAQ,QAAQ;;;;;qBAerC,gBAAgB;;;;;qBCVhB,aAAa;;UCHT,uBAAuB;;WAE7B;;WAEA;;;;;;;wBAQK,cAAc,SAAS,iBAAiB;;UCZvC,sBAAsB;;WAE5B;;WAEA,OAAO;;WAEP;;WAEA;;;;;;;;wBAyCK,aAAa,SAAS,gBAAgB;;UCpCrC,wBAAwB,YAAY;;WAE1C;;;;;WAKA;;WAEA;;WAEA;;;;;;;;wBAWK,eAAe,SAAS,kBAAkB;;UCnCzC,sBAAsB;;WAE5B;;WAEA,MAAM;;WAEN;;WAEA;;WAEA;;;qBAIE,cAAc;;;;;wBASX,WAAW,gBAAgB,QAAQ,MAAM,WAAW,mBAAc,YAAY;;;;;wBAkB9E,UAAU,KAAK,OAAO,MAAM,OAAO;WAA8B;WAAuB,MAAM;;;;;;wBAgB9F,WAAW,OAAO,OAAO,kBAAkB,SAAS,eAAe,OAAO,GAAG,mBAAmB,eAAe;;;;;;wBAkB/G,aAAa,SAAS,gBAAgB;;qBCjEzC,kBAAkB;;iBCXd;WACN;WACA;WACA;;;qBAIE;;;;;;;;;wBAUG,gBAAgB,OAAO,OAAO,QAAQ,QAAQ,iBAAc;;iBCN3D;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;qBAIE;;wBAQG,eAAe,OAAO,OAAO,QAAQ,SAAS;;;;;wBAqG9C,UAAU,KAAK,KAAK,IAAI,OAAO,MAAM;;;;;wBAoBrC,eAAe,0BAA0B,OAAO;;iBAsB/C;WACN;WACA;;WAEA;;;wBAIK,iBAAiB,QAAQ,QAAQ,OAAO,SAAS;;iBC5LhD;WACN;WACA;WACA;WACA;;WAEA;;WAEA;WACA;;WAEA,iBAAiB;WACjB,SAAS;;;iBAIH;;WAEN;;;wBAIK,aAAa,kBAAkB,UAAU,mBAAmB,eAAe,UAAS,eAAoB;;;;;wBAaxG,SAAS,YAAY;;wBAqBrB,SAAS,QAAQ,QAAQ,iBAAiB,OAAO,OAAO,kBAAa;;wBA4BrE,YAAY,eAAe"}