@woosh/meep-engine 3.15.0 → 3.17.0

package/src/core/model/node-graph/visual/layout/RouteGrid.js

@@ -0,0 +1,405 @@
+import { BitSet } from "../../../../binary/BitSet.js";
+import { binarySearchLowIndex } from "../../../../collection/array/binarySearchLowIndex.js";
+import { isValueBetween } from "../../../../math/interval/isValueBetween.js";
+import { overlap1D } from "../../../../math/interval/overlap1D.js";
+import { number_compare_ascending } from "../../../../primitives/numbers/number_compare_ascending.js";
+
+/**
+ * Coordinates nearer than this to one another are the same coordinate.
+ *
+ * Two lines a fraction of a unit apart are one line to anybody looking at the drawing, and keeping
+ * both of them costs a whole row or column of the grid. It is also how far inside a box a line has
+ * to be before it counts as inside: a lane placed exactly a clearance from a box lands a rounding
+ * error either side of the box's own clearance line, and a line that is inside by less than this
+ * is on the edge.
+ *
+ * @type {number}
+ */
+export const ROUTE_GRID_EPSILON = 0.5;
+
+/**
+ * Add a wire of `net` to one line, or remove it, keeping the line's holder straight.
+ *
+ * The holder is the net that had the line first; a line vacated by its holder is up for grabs, and
+ * a line that never had a holder — its wires all arrived while some other net held it — gets one
+ * the next time a wire arrives on it empty of holder. Nothing is lost for it: those wires are of
+ * other nets than the one asking, and are charged as such, which they should be.
+ *
+ * @param {Int32Array} use
+ * @param {Int32Array} owner
+ * @param {Int32Array} owned
+ * @param {number} v
+ * @param {number} net
+ * @param {number} delta
+ * @returns {void}
+ */
+function claim(use, owner, owned, v, net, delta) {
+    use[v] += delta;
+
+    if (delta > 0) {
+        if (owner[v] === -1) {
+            owner[v] = net;
+            owned[v] = 1;
+        } else if (owner[v] === net) {
+            owned[v]++;
+        }
+    } else if (owner[v] === net && --owned[v] === 0) {
+        owner[v] = -1;
+    }
+}
+
+/**
+ * The space wires are allowed to occupy.
+ *
+ * A **sparse grid**: not a fine mesh over the drawing, but the few horizontal and vertical lines
+ * that are actually worth travelling along — the edges of the boxes and a margin around them, the
+ * heights the ports sit at, the lanes the layout reserved for wires passing through a column, and a
+ * handful of tracks across each channel. Every route that is worth having runs along some of these
+ * and turns where two of them meet, so a grid made of only these has every good route in it and is
+ * a hundredth the size of a mesh fine enough to hold them.
+ *
+ * This is the Hanan grid of the obstacles, which is the standard construction: for a set of
+ * rectangles, an optimal rectilinear route between any two points on it exists on the grid their
+ * own edges induce, so nothing is lost by refusing to leave it.
+ *
+ * **Obstacles block edges, not vertices.** A wire crosses a box by travelling along a line that
+ * passes through it, and whether that is possible is a property of the line between two grid
+ * points rather than of the points themselves — both ends of a line straddling a box are outside
+ * it. Marking the crossing itself is what makes a box solid, and it is also what lets the grid stay
+ * sparse: a grid that had to make every crossing land on a blocked vertex would need a line at
+ * every box edge, and there are four of those per box.
+ *
+ * **Occupancy is per edge as well**, for the same reason: two wires sharing a length of line
+ * overlap and are drawn on top of each other, and two wires meeting at a point merely cross, which
+ * is legal and costs the reader nothing. Counting points would make the router pay to avoid a
+ * crossing and then take a detour to do it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RouteGrid {
+
+    /**
+     * Ascending, distinct.
+     * @type {Float64Array}
+     */
+    xs;
+
+    /**
+     * @type {Float64Array}
+     */
+    ys;
+
+    /**
+     * @type {number}
+     */
+    nx = 0;
+
+    /**
+     * @type {number}
+     */
+    ny = 0;
+
+    /**
+     * @type {number}
+     */
+    vertex_count = 0;
+
+    /**
+     * Whether the line from vertex `v` to the vertex right of it passes through a box.
+     * @type {BitSet}
+     */
+    blocked_h = new BitSet();
+
+    /**
+     * Whether the line from vertex `v` to the vertex below it passes through a box.
+     * @type {BitSet}
+     */
+    blocked_v = new BitSet();
+
+    /**
+     * Wires currently occupying each rightward line.
+     * @type {Int32Array}
+     */
+    use_h;
+
+    /**
+     * @type {Int32Array}
+     */
+    use_v;
+
+    /**
+     * What each rightward line remembers about having been fought over. See
+     * {@link NodeGraphLayoutOptions#history_rate}.
+     * @type {Float32Array}
+     */
+    history_h;
+
+    /**
+     * @type {Float32Array}
+     */
+    history_v;
+
+    /**
+     * Wires passing straight through each vertex horizontally — in along one rightward line and
+     * out along the next, without turning.
+     *
+     * This is what a crossing is made of. Wires are confined to the grid lines, so two of them can
+     * only cross at a vertex, and they cross there exactly when one goes straight through it one
+     * way and the other goes straight through it the other way. Every other way two wires can meet
+     * at a vertex is either a shared line, which {@link use_h} already counts, or two corners
+     * touching, which the curves they become pull apart.
+     *
+     * A wire's stub counts as the direction it arrives from: a wire leaving a port on the right of
+     * a box and carrying straight on has gone straight through the vertex where it met the grid.
+     *
+     * @type {Int32Array}
+     */
+    through_h;
+
+    /**
+     * @type {Int32Array}
+     */
+    through_v;
+
+    /**
+     * The net every wire on each rightward line belongs to, when they all belong to one — the
+     * wires that leave one port together are a net — and -1 otherwise.
+     *
+     * Wires of one net are one signal, and where they run along the same line they are one line
+     * that forks, not two wires drawn on top of each other. So a wire is charged for sharing a
+     * line only with wires of other nets, and this is what says how many of those there are: the
+     * wires on the line, less the ones of the net that holds it. A line with wires of several nets
+     * on it is held by whichever claimed it first; the others count as sharing, which they are.
+     *
+     * @type {Int32Array}
+     */
+    owner_h;
+
+    /**
+     * @type {Int32Array}
+     */
+    owner_v;
+
+    /**
+     * How many of the wires on each rightward line belong to the net that holds it.
+     * @type {Int32Array}
+     */
+    owned_h;
+
+    /**
+     * @type {Int32Array}
+     */
+    owned_v;
+
+    /**
+     * @param {Float64Array} xs ascending, distinct
+     * @param {Float64Array} ys ascending, distinct
+     */
+    constructor(xs, ys) {
+        this.xs = xs;
+        this.ys = ys;
+
+        this.nx = xs.length;
+        this.ny = ys.length;
+
+        this.vertex_count = this.nx * this.ny;
+
+        this.blocked_h.preventShrink();
+        this.blocked_v.preventShrink();
+
+        this.blocked_h.setCapacity(this.vertex_count);
+        this.blocked_v.setCapacity(this.vertex_count);
+
+        this.use_h = new Int32Array(this.vertex_count);
+        this.use_v = new Int32Array(this.vertex_count);
+
+        this.history_h = new Float32Array(this.vertex_count);
+        this.history_v = new Float32Array(this.vertex_count);
+
+        this.through_h = new Int32Array(this.vertex_count);
+        this.through_v = new Int32Array(this.vertex_count);
+
+        this.owner_h = new Int32Array(this.vertex_count).fill(-1);
+        this.owner_v = new Int32Array(this.vertex_count).fill(-1);
+
+        this.owned_h = new Int32Array(this.vertex_count);
+        this.owned_v = new Int32Array(this.vertex_count);
+    }
+
+    /**
+     * Forget every route, keeping the obstacles and everything the grid has learned about
+     * congestion. This is what a round of rip-up and reroute starts with.
+     * @returns {void}
+     */
+    clear_use() {
+        this.use_h.fill(0);
+        this.use_v.fill(0);
+
+        this.through_h.fill(0);
+        this.through_v.fill(0);
+
+        this.owner_h.fill(-1);
+        this.owner_v.fill(-1);
+
+        this.owned_h.fill(0);
+        this.owned_v.fill(0);
+    }
+
+    /**
+     * Wires of other nets on the rightward line from vertex `v`: what a wire of `net` shares it
+     * with. See {@link owner_h}.
+     *
+     * @param {number} v
+     * @param {number} net
+     * @returns {number}
+     */
+    foreign_h(v, net) {
+        return this.use_h[v] - (this.owner_h[v] === net ? this.owned_h[v] : 0);
+    }
+
+    /**
+     * @param {number} v
+     * @param {number} net
+     * @returns {number}
+     */
+    foreign_v(v, net) {
+        return this.use_v[v] - (this.owner_v[v] === net ? this.owned_v[v] : 0);
+    }
+
+    /**
+     * Put a wire of `net` on the rightward line from vertex `v`, or take it off.
+     *
+     * @param {number} v
+     * @param {number} net
+     * @param {number} delta 1 or -1
+     * @returns {void}
+     */
+    claim_h(v, net, delta) {
+        claim(this.use_h, this.owner_h, this.owned_h, v, net, delta);
+    }
+
+    /**
+     * @param {number} v
+     * @param {number} net
+     * @param {number} delta 1 or -1
+     * @returns {void}
+     */
+    claim_v(v, net, delta) {
+        claim(this.use_v, this.owner_v, this.owned_v, v, net, delta);
+    }
+
+    /**
+     * Index of the grid line at or immediately below `value`.
+     *
+     * Clamped rather than reported as absent: a point off the end of the grid belongs to the line at
+     * that end, which is what every caller here wants and what a bare lower bound does not say.
+     *
+     * @param {Float64Array} axis
+     * @param {number} value
+     * @returns {number}
+     */
+    static floor_index(axis, value) {
+        const found = binarySearchLowIndex(axis, value, number_compare_ascending);
+
+        // below every line
+        return found === -1 ? 0 : found;
+    }
+
+    /**
+     * Index of the grid line nearest `value`.
+     *
+     * @param {Float64Array} axis
+     * @param {number} value
+     * @returns {number}
+     */
+    static nearest_index(axis, value) {
+        const low = RouteGrid.floor_index(axis, value);
+
+        if (low + 1 >= axis.length) {
+            return low;
+        }
+
+        return value - axis[low] <= axis[low + 1] - value ? low : low + 1;
+    }
+
+    /**
+     * @param {number} x
+     * @returns {number}
+     */
+    nearest_x(x) {
+        return RouteGrid.nearest_index(this.xs, x);
+    }
+
+    /**
+     * @param {number} y
+     * @returns {number}
+     */
+    nearest_y(y) {
+        return RouteGrid.nearest_index(this.ys, y);
+    }
+
+    /**
+     * Mark every line crossing the given rectangle as impassable.
+     *
+     * A line is impassable when it enters the rectangle's interior. Lines running along an edge of
+     * it — to within {@link ROUTE_GRID_EPSILON} — are left alone: the rectangle handed here is
+     * already the box grown by its clearance, so its edges are where a wire is meant to run.
+     *
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} x1
+     * @param {number} y1
+     * @returns {void}
+     */
+    block_rectangle(x0, y0, x1, y1) {
+        const xs = this.xs;
+        const ys = this.ys;
+
+        const nx = this.nx;
+
+        // rightward lines: the line from column i covers [xs[i], xs[i+1]], and enters the rectangle
+        // when that overlaps (x0, x1) while its own height is strictly inside (y0, y1)
+        const column_first = RouteGrid.floor_index(xs, x0);
+        const row_first = RouteGrid.floor_index(ys, y0);
+        const column_last = RouteGrid.floor_index(xs, x1);
+        const row_last = RouteGrid.floor_index(ys, y1);
+
+        // what "inside" means, once lines on the edge are allowed to be a rounding error off it
+        const inner_x0 = x0 + ROUTE_GRID_EPSILON;
+        const inner_x1 = x1 - ROUTE_GRID_EPSILON;
+        const inner_y0 = y0 + ROUTE_GRID_EPSILON;
+        const inner_y1 = y1 - ROUTE_GRID_EPSILON;
+
+        for (let j = row_first; j <= row_last && j < this.ny; j++) {
+            if (!isValueBetween(ys[j], inner_y0, inner_y1)) {
+                // the line runs along or outside an edge, which is where a wire is meant to be
+                continue;
+            }
+
+            const row = j * nx;
+
+            for (let i = column_first; i <= column_last && i + 1 < nx; i++) {
+                if (!overlap1D(xs[i], xs[i + 1], x0, x1)) {
+                    continue;
+                }
+
+                this.blocked_h.set(row + i, true);
+            }
+        }
+
+        for (let i = column_first; i <= column_last && i < nx; i++) {
+            if (!isValueBetween(xs[i], inner_x0, inner_x1)) {
+                continue;
+            }
+
+            for (let j = row_first; j <= row_last && j + 1 < this.ny; j++) {
+                if (!overlap1D(ys[j], ys[j + 1], y0, y1)) {
+                    continue;
+                }
+
+                this.blocked_v.set(j * nx + i, true);
+            }
+        }
+    }
+}

package/src/core/model/node-graph/visual/layout/RouteSearch.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Travelling along a line of constant y.
+ * @type {number}
+ */
+export const ROUTE_AXIS_H: number;
+/**
+ * Travelling along a line of constant x.
+ * @type {number}
+ */
+export const ROUTE_AXIS_V: number;
+/**
+ * One wire's path through the grid, found by A*.
+ *
+ * **A state is a vertex together with the direction the wire arrived in**, not a vertex alone.
+ * Turning costs something here — it has to, or the shortest route is a staircase and the drawing
+ * is unreadable — and a cost that depends on how you arrived is a cost the search cannot see
+ * unless arriving is part of what it searches over. Two states per vertex is the whole price of
+ * that: the wire cares which axis it is on, not which of the two ways along it.
+ *
+ * **The scratch outlives the search.** A route is found several hundred times over one layout — once
+ * per wire, once per round of rip-up — and the arrays it needs are the size of the grid. Clearing
+ * them each time costs more than the search does, so the scores carry a stamp instead and a score
+ * left over from a previous route reads as absent rather than as a very good one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RouteSearch {
+    /**
+     * @param {RouteGrid} grid
+     */
+    constructor(grid: RouteGrid);
+    /**
+     * @type {RouteGrid}
+     */
+    grid: RouteGrid;
+    /**
+     * @type {Uint32Heap}
+     */
+    open: Uint32Heap;
+    /**
+     * @type {BitSet}
+     */
+    closed: BitSet;
+    /**
+     * Cost to reach each state, meaningful only where `stamp` matches the current search.
+     * @type {Float64Array}
+     */
+    score: Float64Array;
+    /**
+     * @type {Int32Array}
+     */
+    stamp: Int32Array;
+    /**
+     * @type {Int32Array}
+     */
+    came_from: Int32Array;
+    /**
+     * @type {number}
+     */
+    generation: number;
+    /**
+     * Vertices of the route just found, from start to goal.
+     * @type {Int32Array}
+     */
+    path: Int32Array;
+    /**
+     * @type {number}
+     */
+    path_length: number;
+    /**
+     * What the route just found costs, under the grid as it stood when it was found. This is the
+     * same number {@link cost_of} gives for it, and is what a route it replaces is compared with.
+     * @type {number}
+     */
+    cost: number;
+    /**
+     * States the last search took off the queue before it found the goal or gave up. What the
+     * search cost, for anybody tuning it.
+     * @type {number}
+     */
+    expansions: number;
+    /**
+     * Find a wire's way from one vertex to another.
+     *
+     * The cost being minimised is length, plus a fixed price per turn, plus a fixed price for every
+     * wire crossed, plus what the grid charges for lines other wires are already on. The estimate
+     * driving the search is the straight rectilinear distance remaining, which never exceeds what
+     * the route will actually cost — turns, crossings and congestion only ever add — so the first
+     * route found is the cheapest one.
+     *
+     * A crossing is charged where it happens: on going straight through a vertex, for every wire
+     * already going straight through it the other way. See {@link RouteGrid#through_h}.
+     *
+     * @param {number} start vertex
+     * @param {number} start_axis the axis the wire is already travelling on as it arrives here,
+     *        one of {@link ROUTE_AXIS_H}, {@link ROUTE_AXIS_V}
+     * @param {number} goal vertex
+     * @param {number} goal_axis the axis the wire must be on to meet the port it is heading for
+     * @param {NodeGraphLayoutOptions} options
+     * @param {boolean} [through_goal] whether arriving at the goal along its axis is going straight
+     *        through it. True at a port, where the wire carries on into its stub; false at a
+     *        waypoint the wire will leave by another search, which charges for the leaving.
+     * @param {number} [net] the net the wire belongs to, whose other wires it may share a line
+     *        with for nothing — see {@link RouteGrid#owner_h}. -1 for a wire of no net.
+     * @returns {boolean} whether a route was found. The route is left in {@link path}.
+     */
+    find(start: number, start_axis: number, goal: number, goal_axis: number, options: NodeGraphLayoutOptions, through_goal?: boolean, net?: number): boolean;
+    /**
+     * @param {number} from state
+     * @param {number} from_cost
+     * @param {number} from_axis
+     * @param {number} vertex being moved to
+     * @param {number} axis being moved along
+     * @param {number} goal
+     * @param {number} goal_axis
+     * @param {boolean} through_goal
+     * @param {number} bend
+     * @param {NodeGraphLayoutOptions} options
+     * @param {number} step what the move itself costs
+     * @param {number} remaining estimate from `vertex` to the goal
+     * @param {number} generation
+     * @returns {void}
+     * @private
+     */
+    private __relax;
+    /**
+     * What a route costs under the grid as it stands now.
+     *
+     * The same sum {@link find} minimises, added up along a route that already exists: length, a
+     * turn wherever the axis changes — counting the stubs at either end, which fix the axis the
+     * route starts and finishes on — a crossing wherever it goes straight through a vertex some
+     * other wire goes straight through the other way, and the grid's charge for every line it
+     * shares. The route's own occupancy must have been taken off the grid first, or it is charged
+     * for sharing lines with itself.
+     *
+     * Kept exactly in step with {@link find}, because it exists to be compared with it: a route
+     * found now is worth taking over the one it replaces only if this says the old one costs more.
+     *
+     * @param {Int32Array} path grid vertices, start to goal
+     * @param {number} length how many of `path` to read
+     * @param {number} start_axis
+     * @param {number} goal_axis
+     * @param {NodeGraphLayoutOptions} options
+     * @param {boolean} [through_goal] as for {@link find}
+     * @param {number} [net] as for {@link find}
+     * @returns {number}
+     */
+    cost_of(path: Int32Array, length: number, start_axis: number, goal_axis: number, options: NodeGraphLayoutOptions, through_goal?: boolean, net?: number): number;
+    /**
+     * @param {number} state the goal, reached
+     * @returns {boolean}
+     * @private
+     */
+    private __unwind;
+}
+import { Uint32Heap } from "../../../../collection/heap/Uint32Heap.js";
+import { BitSet } from "../../../../binary/BitSet.js";
+//# sourceMappingURL=RouteSearch.d.ts.map

package/src/core/model/node-graph/visual/layout/RouteSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteSearch.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/RouteSearch.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,2BAFU,MAAM,CAEc;AAE9B;;;GAGG;AACH,2BAFU,MAAM,CAEc;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH;IA+DI;;OAEG;IACH,6BAeC;IA/ED;;OAEG;IACH,gBAAY;IAEZ;;OAEG;IACH,MAFU,UAAU,CAEQ;IAE5B;;OAEG;IACH,QAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,OAFU,YAAY,CAEhB;IAEN;;OAEG;IACH,OAFU,UAAU,CAEd;IAEN;;OAEG;IACH,WAFU,UAAU,CAEV;IAEV;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,MAFU,UAAU,CAEf;IAEL;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAsBf;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,YAbW,MAAM,cACN,MAAM,QAEN,MAAM,aACN,MAAM,kDAEN,OAAO,QAGP,MAAM,GAEJ,OAAO,CAiHnB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,gBAkDC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cATW,UAAU,UACV,MAAM,cACN,MAAM,aACN,MAAM,kDAEN,OAAO,QACP,MAAM,GACJ,MAAM,CA4DlB;IAED;;;;OAIG;IACH,iBAyBC;CACJ;2BAlb0B,2CAA2C;uBAD/C,8BAA8B"}