@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -1,242 +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";
-
-/**
- * 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;
-
-    /**
-     * @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);
-    }
-
-    /**
-     * 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);
-    }
-
-    /**
-     * 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 exactly along an
-     * edge of it 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);
-
-        for (let j = row_first; j <= row_last && j < this.ny; j++) {
-            if (!isValueBetween(ys[j], y0, 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], x0, 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);
-            }
-        }
-    }
-}
+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);
+            }
+        }
+    }
+}