@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,436 @@
+import { BitSet } from "../../../../binary/BitSet.js";
+import { Uint32Heap } from "../../../../collection/heap/Uint32Heap.js";
+
+/**
+ * Travelling along a line of constant y.
+ * @type {number}
+ */
+export const ROUTE_AXIS_H = 0;
+
+/**
+ * Travelling along a line of constant x.
+ * @type {number}
+ */
+export const ROUTE_AXIS_V = 1;
+
+/**
+ * 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 {
+
+    /**
+     * @type {RouteGrid}
+     */
+    grid = null;
+
+    /**
+     * @type {Uint32Heap}
+     */
+    open = new Uint32Heap(1024);
+
+    /**
+     * @type {BitSet}
+     */
+    closed = new BitSet();
+
+    /**
+     * Cost to reach each state, meaningful only where `stamp` matches the current search.
+     * @type {Float64Array}
+     */
+    score;
+
+    /**
+     * @type {Int32Array}
+     */
+    stamp;
+
+    /**
+     * @type {Int32Array}
+     */
+    came_from;
+
+    /**
+     * @type {number}
+     */
+    generation = 0;
+
+    /**
+     * Vertices of the route just found, from start to goal.
+     * @type {Int32Array}
+     */
+    path;
+
+    /**
+     * @type {number}
+     */
+    path_length = 0;
+
+    /**
+     * 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 = 0;
+
+    /**
+     * 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 = 0;
+
+    /**
+     * @param {RouteGrid} grid
+     */
+    constructor(grid) {
+        this.grid = grid;
+
+        const state_count = grid.vertex_count * 2;
+
+        this.score = new Float64Array(state_count);
+        this.stamp = new Int32Array(state_count);
+        this.came_from = new Int32Array(state_count);
+
+        this.closed.preventShrink();
+        this.closed.setCapacity(state_count);
+
+        // Enough for a route that goes straight there. One that has to go around something grows
+        // this when it is unwound, which happens rarely and once.
+        this.path = new Int32Array(grid.nx + grid.ny);
+    }
+
+    /**
+     * 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, start_axis, goal, goal_axis, options, through_goal = true, net = -1) {
+        const grid = this.grid;
+
+        const nx = grid.nx;
+        const ny = grid.ny;
+
+        const xs = grid.xs;
+        const ys = grid.ys;
+
+        this.path_length = 0;
+        this.cost = 0;
+
+        if (start === goal) {
+            this.path[0] = start;
+            this.path_length = 1;
+
+            return true;
+        }
+
+        const generation = ++this.generation;
+
+        this.closed.reset();
+        this.open.clear();
+
+        const goal_x = xs[goal % nx];
+        const goal_y = ys[(goal / nx) | 0];
+
+        const bend = options.bend_penalty;
+
+        const start_state = start * 2 + start_axis;
+
+        this.score[start_state] = 0;
+        this.stamp[start_state] = generation;
+        this.came_from[start_state] = -1;
+
+        this.open.insert(start_state, Math.abs(xs[start % nx] - goal_x) + Math.abs(ys[(start / nx) | 0] - goal_y));
+
+        this.expansions = 0;
+
+        while (!this.open.is_empty()) {
+            const state = this.open.pop_min();
+
+            if (this.closed.get(state)) {
+                // a cheaper way here was found after this entry was queued
+                continue;
+            }
+
+            const vertex = state >> 1;
+
+            if (vertex === goal) {
+                return this.__unwind(state);
+            }
+
+            this.closed.set(state, true);
+
+            if (++this.expansions > options.max_route_expansions) {
+                break;
+            }
+
+            const axis = state & 1;
+
+            const i = vertex % nx;
+            const j = (vertex / nx) | 0;
+
+            const cost = this.score[state];
+
+            // A wire never doubles back along the line it arrived by. The axis alone would allow
+            // it — out along a line and straight back is two moves on one axis, with no turn to
+            // pay for — and a wire could then dodge the charge for crossing another at a vertex by
+            // arriving at it along a different axis, having made a spike out of the side and
+            // back. The spike is no less a crossing; it is merely one the count cannot see.
+            const previous = this.came_from[state] === -1 ? -1 : this.came_from[state] >> 1;
+
+            if (i + 1 < nx && vertex + 1 !== previous && !grid.blocked_h.get(vertex)) {
+                this.__relax(
+                    state, cost, axis, vertex + 1, ROUTE_AXIS_H, goal, goal_axis, through_goal, bend, options,
+                    xs[i + 1] - xs[i] + grid.foreign_h(vertex, net) * options.present_cost + grid.history_h[vertex],
+                    Math.abs(xs[i + 1] - goal_x) + Math.abs(ys[j] - goal_y),
+                    generation
+                );
+            }
+
+            if (i > 0 && vertex - 1 !== previous && !grid.blocked_h.get(vertex - 1)) {
+                this.__relax(
+                    state, cost, axis, vertex - 1, ROUTE_AXIS_H, goal, goal_axis, through_goal, bend, options,
+                    xs[i] - xs[i - 1] + grid.foreign_h(vertex - 1, net) * options.present_cost + grid.history_h[vertex - 1],
+                    Math.abs(xs[i - 1] - goal_x) + Math.abs(ys[j] - goal_y),
+                    generation
+                );
+            }
+
+            if (j + 1 < ny && vertex + nx !== previous && !grid.blocked_v.get(vertex)) {
+                this.__relax(
+                    state, cost, axis, vertex + nx, ROUTE_AXIS_V, goal, goal_axis, through_goal, bend, options,
+                    ys[j + 1] - ys[j] + grid.foreign_v(vertex, net) * options.present_cost + grid.history_v[vertex],
+                    Math.abs(xs[i] - goal_x) + Math.abs(ys[j + 1] - goal_y),
+                    generation
+                );
+            }
+
+            if (j > 0 && vertex - nx !== previous && !grid.blocked_v.get(vertex - nx)) {
+                this.__relax(
+                    state, cost, axis, vertex - nx, ROUTE_AXIS_V, goal, goal_axis, through_goal, bend, options,
+                    ys[j] - ys[j - 1] + grid.foreign_v(vertex - nx, net) * options.present_cost + grid.history_v[vertex - nx],
+                    Math.abs(xs[i] - goal_x) + Math.abs(ys[j - 1] - goal_y),
+                    generation
+                );
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * @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
+     */
+    __relax(from, from_cost, from_axis, vertex, axis, goal, goal_axis, through_goal, bend, options, step, remaining, generation) {
+        const state = vertex * 2 + axis;
+
+        if (this.closed.get(state)) {
+            return;
+        }
+
+        let cost = from_cost + step;
+
+        const grid = this.grid;
+
+        if (axis !== from_axis) {
+            cost += bend;
+        } else {
+            // carrying straight on through the vertex being left crosses every wire going straight
+            // through it the other way
+            const through = axis === ROUTE_AXIS_H ? grid.through_v[from >> 1] : grid.through_h[from >> 1];
+
+            if (through > 0) {
+                cost += through * options.crossing_penalty;
+            }
+        }
+
+        if (vertex === goal) {
+            if (axis !== goal_axis) {
+                // meeting a port along the wrong axis means one more turn than the route shows,
+                // made in the stub between the grid and the port itself
+                cost += bend;
+            } else if (through_goal) {
+                // and meeting it along the right one means going straight through the goal vertex
+                // into that stub
+                const through = axis === ROUTE_AXIS_H ? grid.through_v[goal] : grid.through_h[goal];
+
+                if (through > 0) {
+                    cost += through * options.crossing_penalty;
+                }
+            }
+        }
+
+        if (this.stamp[state] === generation && this.score[state] <= cost) {
+            return;
+        }
+
+        this.score[state] = cost;
+        this.stamp[state] = generation;
+        this.came_from[state] = from;
+
+        // Queued rather than updated in place: finding an existing entry costs a scan of the heap,
+        // and a superseded entry is recognised and dropped for nothing when it surfaces.
+        this.open.insert(state, cost + remaining);
+    }
+
+    /**
+     * 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, length, start_axis, goal_axis, options, through_goal = true, net = -1) {
+        if (length < 2) {
+            // a route that is one vertex is the two stubs meeting, which find() prices at nothing
+            return 0;
+        }
+
+        const grid = this.grid;
+
+        const nx = grid.nx;
+
+        const xs = grid.xs;
+        const ys = grid.ys;
+
+        const bend = options.bend_penalty;
+        const crossing = options.crossing_penalty;
+        const present = options.present_cost;
+
+        let cost = 0;
+        let axis = start_axis;
+
+        for (let k = 0; k + 1 < length; k++) {
+            const a = path[k];
+            const b = path[k + 1];
+
+            let step_axis;
+
+            if (b === a + 1) {
+                step_axis = ROUTE_AXIS_H;
+                cost += xs[b % nx] - xs[a % nx] + grid.foreign_h(a, net) * present + grid.history_h[a];
+            } else if (a === b + 1) {
+                step_axis = ROUTE_AXIS_H;
+                cost += xs[a % nx] - xs[b % nx] + grid.foreign_h(b, net) * present + grid.history_h[b];
+            } else if (b === a + nx) {
+                step_axis = ROUTE_AXIS_V;
+                cost += ys[(b / nx) | 0] - ys[(a / nx) | 0] + grid.foreign_v(a, net) * present + grid.history_v[a];
+            } else {
+                step_axis = ROUTE_AXIS_V;
+                cost += ys[(a / nx) | 0] - ys[(b / nx) | 0] + grid.foreign_v(b, net) * present + grid.history_v[b];
+            }
+
+            if (step_axis !== axis) {
+                cost += bend;
+            } else {
+                cost += (step_axis === ROUTE_AXIS_H ? grid.through_v[a] : grid.through_h[a]) * crossing;
+            }
+
+            axis = step_axis;
+        }
+
+        const goal = path[length - 1];
+
+        if (axis !== goal_axis) {
+            cost += bend;
+        } else if (through_goal) {
+            cost += (axis === ROUTE_AXIS_H ? grid.through_v[goal] : grid.through_h[goal]) * crossing;
+        }
+
+        return cost;
+    }
+
+    /**
+     * @param {number} state the goal, reached
+     * @returns {boolean}
+     * @private
+     */
+    __unwind(state) {
+        this.cost = this.score[state];
+
+        let length = 0;
+
+        for (let at = state; at !== -1; at = this.came_from[at]) {
+            length++;
+        }
+
+        if (length > this.path.length) {
+            this.path = new Int32Array(length);
+        }
+
+        const path = this.path;
+
+        let at = state;
+
+        // written back to front, so what comes out reads from the start of the wire to its end
+        for (let i = length - 1; i >= 0; i--, at = this.came_from[at]) {
+            path[i] = at >> 1;
+        }
+
+        this.path_length = length;
+
+        return true;
+    }
+}

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

@@ -0,0 +1,93 @@
+/**
+ * The routes of every wire, as corner points, flat.
+ *
+ * A route is the point it leaves its port at, every corner it turns, and the point it meets the
+ * other port at. Points in the middle of a straight run are not kept: they say nothing, and the
+ * stage that nudges routes apart works on runs, which it would otherwise have to reconstruct.
+ *
+ * All of them share two coordinate arrays, indexed by `offset`, because there are a few hundred of
+ * them and they are read together — once to nudge, once to turn into curves — and a few hundred
+ * small arrays is a few hundred allocations and no locality.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RouteSet {
+    /**
+     * @param {number} count routes
+     * @param {number} capacity points to start with
+     */
+    constructor(count: number, capacity?: number);
+    /**
+     * @type {number}
+     */
+    count: number;
+    /**
+     * Where each route starts in {@link x}. Length `count + 1`.
+     * @type {Int32Array}
+     */
+    offset: Int32Array;
+    /**
+     * @type {Float64Array}
+     */
+    x: Float64Array;
+    /**
+     * @type {Float64Array}
+     */
+    y: Float64Array;
+    /**
+     * Net of each route: routes leaving one port together share a number here, and a stage that
+     * pulls overlapping routes apart leaves those together — they are one line that forks. Null
+     * when nobody has said; every route is then its own net.
+     * @type {Int32Array|null}
+     */
+    net: Int32Array | null;
+    /**
+     * @type {number}
+     * @private
+     */
+    private __length;
+    /**
+     * Where the route currently being written began.
+     * @type {number}
+     * @private
+     */
+    private __start;
+    /**
+     * Discard every route, keeping the room they occupied.
+     * @returns {void}
+     */
+    clear(): void;
+    /**
+     * Begin the route of the given wire. Routes must be written in order.
+     * @param {number} index
+     * @returns {void}
+     */
+    begin(index: number): void;
+    /**
+     * Add a corner to the route being written, unless it is on the straight the last two were on.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @returns {void}
+     */
+    push(x: number, y: number): void;
+    /**
+     * Finish the route being written.
+     * @param {number} index
+     * @returns {void}
+     */
+    end(index: number): void;
+    /**
+     * @param {number} needed
+     * @returns {void}
+     * @private
+     */
+    private __ensure;
+    /**
+     * @param {number} index
+     * @returns {number} corners in this route
+     */
+    length_of(index: number): number;
+}
+//# sourceMappingURL=RouteSet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RouteSet.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/RouteSet.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH;IA4CI;;;OAGG;IACH,mBAHW,MAAM,aACN,MAAM,EAShB;IArDD;;OAEG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,UAAU,CAEb;IAEP;;OAEG;IACH,GAFU,YAAY,CAEpB;IAEF;;OAEG;IACH,GAFU,YAAY,CAEpB;IAEF;;;;;OAKG;IACH,KAFU,UAAU,GAAC,IAAI,CAEd;IAEX;;;OAGG;IACH,iBAAa;IAEb;;;;OAIG;IACH,gBAAY;IAeZ;;;OAGG;IACH,SAFa,IAAI,CAOhB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;;;;;OAMG;IACH,QAJW,MAAM,KACN,MAAM,GACJ,IAAI,CAiChB;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,iBAmBC;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}

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

@@ -0,0 +1,176 @@
+/**
+ * The routes of every wire, as corner points, flat.
+ *
+ * A route is the point it leaves its port at, every corner it turns, and the point it meets the
+ * other port at. Points in the middle of a straight run are not kept: they say nothing, and the
+ * stage that nudges routes apart works on runs, which it would otherwise have to reconstruct.
+ *
+ * All of them share two coordinate arrays, indexed by `offset`, because there are a few hundred of
+ * them and they are read together — once to nudge, once to turn into curves — and a few hundred
+ * small arrays is a few hundred allocations and no locality.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RouteSet {
+
+    /**
+     * @type {number}
+     */
+    count = 0;
+
+    /**
+     * Where each route starts in {@link x}. Length `count + 1`.
+     * @type {Int32Array}
+     */
+    offset;
+
+    /**
+     * @type {Float64Array}
+     */
+    x;
+
+    /**
+     * @type {Float64Array}
+     */
+    y;
+
+    /**
+     * Net of each route: routes leaving one port together share a number here, and a stage that
+     * pulls overlapping routes apart leaves those together — they are one line that forks. Null
+     * when nobody has said; every route is then its own net.
+     * @type {Int32Array|null}
+     */
+    net = null;
+
+    /**
+     * @type {number}
+     * @private
+     */
+    __length = 0;
+
+    /**
+     * Where the route currently being written began.
+     * @type {number}
+     * @private
+     */
+    __start = 0;
+
+    /**
+     * @param {number} count routes
+     * @param {number} capacity points to start with
+     */
+    constructor(count, capacity = count * 4) {
+        this.count = count;
+
+        this.offset = new Int32Array(count + 1);
+
+        this.x = new Float64Array(capacity);
+        this.y = new Float64Array(capacity);
+    }
+
+    /**
+     * Discard every route, keeping the room they occupied.
+     * @returns {void}
+     */
+    clear() {
+        this.__length = 0;
+        this.__start = 0;
+
+        this.offset.fill(0);
+    }
+
+    /**
+     * Begin the route of the given wire. Routes must be written in order.
+     * @param {number} index
+     * @returns {void}
+     */
+    begin(index) {
+        this.__start = this.__length;
+
+        this.offset[index] = this.__length;
+    }
+
+    /**
+     * Add a corner to the route being written, unless it is on the straight the last two were on.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @returns {void}
+     */
+    push(x, y) {
+        const start = this.__start;
+
+        if (this.__length > start) {
+            const last = this.__length - 1;
+
+            if (this.x[last] === x && this.y[last] === y) {
+                return;
+            }
+
+            if (this.__length - start >= 2) {
+                const before = last - 1;
+
+                const straight_x = this.x[before] === x && this.x[last] === x;
+                const straight_y = this.y[before] === y && this.y[last] === y;
+
+                if (straight_x || straight_y) {
+                    this.x[last] = x;
+                    this.y[last] = y;
+
+                    return;
+                }
+            }
+        }
+
+        this.__ensure(this.__length + 1);
+
+        this.x[this.__length] = x;
+        this.y[this.__length] = y;
+
+        this.__length++;
+    }
+
+    /**
+     * Finish the route being written.
+     * @param {number} index
+     * @returns {void}
+     */
+    end(index) {
+        this.offset[index + 1] = this.__length;
+    }
+
+    /**
+     * @param {number} needed
+     * @returns {void}
+     * @private
+     */
+    __ensure(needed) {
+        if (needed <= this.x.length) {
+            return;
+        }
+
+        let capacity = this.x.length === 0 ? 64 : this.x.length;
+
+        while (capacity < needed) {
+            capacity *= 2;
+        }
+
+        const x = new Float64Array(capacity);
+        const y = new Float64Array(capacity);
+
+        x.set(this.x);
+        y.set(this.y);
+
+        this.x = x;
+        this.y = y;
+    }
+
+    /**
+     * @param {number} index
+     * @returns {number} corners in this route
+     */
+    length_of(index) {
+        return this.offset[index + 1] - this.offset[index];
+    }
+}