@woosh/meep-engine 2.87.3 → 2.87.5

package/src/core/geom/2d/quad-tree-binary/QuadTree.js

@@ -0,0 +1,715 @@
+import { assert } from "../../../assert.js";
+import { UINT32_MAX } from "../../../binary/UINT32_MAX.js";
+import { max2 } from "../../../math/max2.js";
+import { min2 } from "../../../math/min2.js";
+import { BinaryElementPool } from "../../3d/topology/struct/binary/BinaryElementPool.js";
+
+export const QT_NULL_POINTER = UINT32_MAX;
+
+/**
+ * Numeric data supplied by the user
+ * @type {number}
+ */
+const COLUMN_ELEMENT_USER_DATA = 0;
+
+/**
+ * Singly-linked list, nest element
+ * can be NULL_POINTER to represent end of the list
+ * @type {number}
+ */
+const COLUMN_ELEMENT_NEXT = 1;
+
+/**
+ * Tree node that contains this element
+ * @type {number}
+ */
+const COLUMN_ELEMENT_PARENT_NODE = 2;
+
+const COLUMN_ELEMENT_X0 = 3;
+const COLUMN_ELEMENT_Y0 = 4;
+const COLUMN_ELEMENT_X1 = 5;
+const COLUMN_ELEMENT_Y1 = 6;
+
+
+const COLUMN_TREE_NODE_FIRST_ELEMENT_NODE_POINTER = 0;
+/**
+ * Number of elements stored in the node's element list
+ * @type {number}
+ */
+const COLUMN_TREE_NODE_ELEMENT_COUNT = 1
+const COLUMN_TREE_NODE_PARENT = 2;
+const COLUMN_TREE_NODE_CHILDREN_POINTER_TL = 3;
+const COLUMN_TREE_NODE_CHILDREN_POINTER_TR = 4;
+const COLUMN_TREE_NODE_CHILDREN_POINTER_BL = 5;
+const COLUMN_TREE_NODE_CHILDREN_POINTER_BR = 6;
+
+const THRESHOLD_SPLIT = 16;
+const THRESHOLD_MERGE = 8;
+
+const temp_array_element = new Uint32Array(4096);
+
+/**
+ *
+ *  NOTE: THIS CODE IS UNFINISHED, IT IS ONLY A SKETCH
+ *  TODO finish implementation
+ */
+export class QuadTree {
+
+    #node_pool = new BinaryElementPool(28);
+    #element_pool = new BinaryElementPool(28);
+
+    #root = QT_NULL_POINTER
+
+    /**
+     * AABB of the entire tree
+     * @type {Float32Array}
+     */
+    #dimensions = new Float32Array([0, 0, 0, 0]);
+
+    /**
+     * Parameters allow us to set initial bounds to prevent early resizing
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} x1
+     * @param {number} y1
+     */
+    constructor(x0 = 0, y0 = 0, x1 = 0, y1 = 0) {
+        this.#setDimensions(x0, y0, x1, y1);
+    }
+
+    get root() {
+        return this.#root;
+    }
+
+    /**
+     * This method is unsafe as it does not re-build the tree
+     * Make sure to rebuild the tree as necessary after calling this
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} x1
+     * @param {number} y1
+     */
+    #setDimensions(x0, y0, x1, y1) {
+
+        assert.isFiniteNumber(x0, 'x0');
+        assert.notNaN(x0, 'x0');
+
+        assert.isFiniteNumber(y0, 'y0');
+        assert.notNaN(y0, 'y0');
+
+        assert.isFiniteNumber(x1, 'x1');
+        assert.notNaN(x1, 'x1');
+
+        assert.isFiniteNumber(y1, 'y1');
+        assert.notNaN(y1, 'y1');
+
+        const dimensions = this.#dimensions;
+
+        dimensions[0] = x0;
+        dimensions[1] = y0;
+        dimensions[2] = x1;
+        dimensions[3] = y1;
+
+    }
+
+    /**
+     * Resize dimensions of the tree to tightly fit all inserted elements
+     */
+    shrink() {
+        if (this.#root === QT_NULL_POINTER) {
+            // tree is empty
+            this.#setDimensions(0, 0, 0, 0);
+        }
+
+        const bounds = [0, 0, 0, 0];
+
+        this.compute_tight_bounds(bounds);
+
+        this.#setDimensions(...bounds);
+
+        this.rebuild();
+    }
+
+    /**
+     *
+     * @param {number[]|Float32Array} output
+     */
+    compute_tight_bounds(output) {
+        const pool = this.#element_pool;
+        const data_pool_size = pool.size;
+        const float32 = pool.data_float32;
+
+        let bounds_x0 = Infinity;
+        let bounds_y0 = Infinity;
+        let bounds_x1 = -Infinity;
+        let bounds_y1 = -Infinity;
+
+        for (let id = 0; id < data_pool_size; id++) {
+            if (pool.is_allocated(id)) {
+
+                const word = pool.element_word(id);
+
+                const x0 = float32[word + COLUMN_ELEMENT_X0];
+                const y0 = float32[word + COLUMN_ELEMENT_Y0];
+
+                const x1 = float32[word + COLUMN_ELEMENT_X1];
+                const y1 = float32[word + COLUMN_ELEMENT_Y1];
+
+                bounds_x0 = min2(x0, bounds_x0);
+                bounds_y0 = min2(y0, bounds_y0);
+
+                bounds_x1 = max2(x1, bounds_x1);
+                bounds_y1 = max2(y1, bounds_y1);
+            }
+        }
+
+        output[0] = bounds_x0;
+        output[1] = bounds_y0;
+        output[2] = bounds_x1;
+        output[3] = bounds_y1;
+    }
+
+    /**
+     * Rebuild tree but keep all the data
+     */
+    rebuild() {
+        // drop existing structure
+        this.#root = QT_NULL_POINTER;
+
+        this.#node_pool.clear();
+
+        // re-insert data elements
+        const pool = this.#element_pool;
+        const data_pool_size = pool.size;
+        for (let i = 0; i < data_pool_size; i++) {
+            if (pool.is_allocated(i)) {
+                this.element_insert(i);
+            }
+        }
+    }
+
+    /**
+     *
+     * @returns {number} ID of data in the tree
+     */
+    element_allocate() {
+        return this.#element_pool.allocate();
+    }
+
+    /**
+     *
+     * @param {number} element
+     * @param {number}  user_data
+     */
+    element_set_user_data(element, user_data) {
+        assert.isNonNegativeInteger(user_data, 'user_data');
+
+        const pool = this.#element_pool;
+
+        const word = pool.element_word(element);
+
+        pool.data_uint32[word + COLUMN_ELEMENT_USER_DATA] = user_data;
+    }
+
+    /**
+     *
+     * @param {number} element
+     * @return {number}
+     */
+    element_get_user_data(element) {
+        const pool = this.#element_pool;
+        const word = pool.element_word(element);
+
+        return pool.data_uint32[word + COLUMN_ELEMENT_USER_DATA];
+    }
+
+    /**
+     *
+     * @param {number} element
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} x1
+     * @param {number} y1
+     */
+    element_set_bounds_primitive(
+        element,
+        x0, y0,
+        x1, y1
+    ) {
+
+        assert.isFiniteNumber(x0, 'x0');
+        assert.notNaN(x0, 'x0');
+
+        assert.isFiniteNumber(y0, 'y0');
+        assert.notNaN(y0, 'y0');
+
+        assert.isFiniteNumber(x1, 'x1');
+        assert.notNaN(x1, 'x1');
+
+        assert.isFiniteNumber(y1, 'y1');
+        assert.notNaN(y1, 'y1');
+
+        const pool = this.#element_pool;
+
+        const word = pool.element_word(element);
+
+        const float32 = pool.data_float32;
+
+        float32[word + COLUMN_ELEMENT_X0] = x0;
+        float32[word + COLUMN_ELEMENT_Y0] = y0;
+        float32[word + COLUMN_ELEMENT_X1] = x1;
+        float32[word + COLUMN_ELEMENT_Y1] = y1;
+
+    }
+
+    /**
+     *
+     * @param {number} element
+     * @return {number} next element in the node
+     */
+    element_get_next(element) {
+        const pool = this.#element_pool;
+        const word = pool.element_word(element);
+
+        return pool.data_uint32[word + COLUMN_ELEMENT_NEXT];
+    }
+
+    /**
+     *
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} x1
+     * @param {number} y1
+     * @return {number}
+     */
+    #find_parent_for_box(x0, y0, x1, y1) {
+
+        if (this.#root === QT_NULL_POINTER) {
+            // special case
+            return QT_NULL_POINTER;
+        }
+
+        let node = this.#root;
+
+        let bounds_x0 = this.#dimensions[0];
+        let bounds_y0 = this.#dimensions[1];
+        let bounds_x1 = this.#dimensions[2];
+        let bounds_y1 = this.#dimensions[3];
+
+        const node_pool = this.#node_pool;
+        const node_uint32 = node_pool.data_uint32;
+
+        for (; ;) {
+            const node_address = node_pool.element_word(node);
+
+            const bounds_mid_x = (bounds_x0 + bounds_x1) * 0.5;
+            const bounds_mid_y = (bounds_y0 + bounds_y1) * 0.5;
+
+            if (y1 < bounds_mid_y) {
+                //top
+                bounds_y1 = bounds_mid_y;
+                if (x1 < bounds_mid_x) {
+                    //left
+                    const child_tl = node_uint32[node_address + COLUMN_TREE_NODE_CHILDREN_POINTER_TL];
+                    if (child_tl === QT_NULL_POINTER) {
+                        break;
+                    }
+                    node = child_tl;
+                    bounds_x1 = bounds_mid_x;
+                } else if (x0 >= bounds_mid_x) {
+                    //right
+                    const child_tr = node_uint32[node_address + COLUMN_TREE_NODE_CHILDREN_POINTER_TR];
+                    if (child_tr === QT_NULL_POINTER) {
+                        break;
+                    }
+                    node = child_tr;
+                    bounds_x0 = bounds_mid_x;
+                } else {
+                    break;
+                }
+            } else if (y0 >= bounds_mid_y) {
+                //bottom
+                bounds_y0 = bounds_mid_y;
+                if (x1 < bounds_mid_x) {
+                    //left
+                    const child_bl = node_uint32[node_address + COLUMN_TREE_NODE_CHILDREN_POINTER_BL];
+                    if (child_bl === QT_NULL_POINTER) {
+                        break;
+                    }
+                    node = child_bl;
+                    bounds_x1 = bounds_mid_x;
+                } else if (x0 >= bounds_mid_x) {
+                    //right
+                    const child_br = node_uint32[node_address + COLUMN_TREE_NODE_CHILDREN_POINTER_BR];
+                    if (child_br === QT_NULL_POINTER) {
+                        break;
+                    }
+                    node = child_br;
+                    bounds_x0 = bounds_mid_x;
+                } else {
+                    break;
+                }
+            } else {
+                // violates child bounds
+                break;
+            }
+        }
+
+        return node;
+    }
+
+    /**
+     *
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} x1
+     * @param {number} y1
+     */
+    ensure_bounds(x0, y0, x1, y1) {
+
+        const dimensions = this.#dimensions;
+
+        const bounds_x0 = dimensions[0];
+        const bounds_y0 = dimensions[1];
+        const bounds_x1 = dimensions[2];
+        const bounds_y1 = dimensions[3];
+
+        if (
+            x0 >= bounds_x0
+            && y0 >= bounds_y0
+            && x1 < bounds_x1
+            && y1 < bounds_y1
+        ) {
+            // bounds are satisfied
+            return;
+        }
+
+        // dimensions violated
+        this.#setDimensions(
+            min2(x0, bounds_x0),
+            min2(y0, bounds_y0),
+            max2(x1, bounds_x1),
+            max2(y1, bounds_y1),
+        );
+
+    }
+
+    /**
+     * Assumes element is allocated and is not present in the tree yet
+     * @param {number} element
+     */
+    element_insert(element) {
+        const element_pool = this.#element_pool;
+        const element_word = element_pool.element_word(element);
+
+        // clear out element pointers
+        element_pool.data_uint32[element_word + COLUMN_ELEMENT_NEXT] = QT_NULL_POINTER;
+
+        const x0 = element_pool.data_float32[element_word + COLUMN_ELEMENT_X0];
+        const y0 = element_pool.data_float32[element_word + COLUMN_ELEMENT_Y0];
+        const x1 = element_pool.data_float32[element_word + COLUMN_ELEMENT_X1];
+        const y1 = element_pool.data_float32[element_word + COLUMN_ELEMENT_Y1];
+
+        this.ensure_bounds(x0, y0, x1, y1);
+
+        let parent_node = this.#find_parent_for_box(x0, y0, x1, y1);
+
+        if (parent_node === QT_NULL_POINTER) {
+            this.#root = this.#node_allocate();
+
+            parent_node = this.#root;
+        }
+
+
+        this.#insert_element_into(parent_node, element);
+
+        this.#node_balance(parent_node);
+    }
+
+    #node_allocate() {
+        const pool = this.#node_pool;
+
+        const node = pool.allocate();
+
+        const address = pool.element_word(node);
+
+        const uint32 = pool.data_uint32;
+
+        // initialize pointers
+        uint32[address + COLUMN_TREE_NODE_PARENT] = QT_NULL_POINTER;
+        uint32[address + COLUMN_TREE_NODE_FIRST_ELEMENT_NODE_POINTER] = QT_NULL_POINTER;
+        uint32[address + COLUMN_TREE_NODE_CHILDREN_POINTER_TL] = QT_NULL_POINTER;
+        uint32[address + COLUMN_TREE_NODE_CHILDREN_POINTER_TR] = QT_NULL_POINTER;
+        uint32[address + COLUMN_TREE_NODE_CHILDREN_POINTER_BL] = QT_NULL_POINTER;
+        uint32[address + COLUMN_TREE_NODE_CHILDREN_POINTER_BR] = QT_NULL_POINTER;
+
+        return node;
+    }
+
+    /**
+     * This operation may create new nodes
+     * @param {number} node
+     */
+    #node_balance(node) {
+        // count owned elements
+        const address = this.#node_pool.element_word(node);
+
+        const element_count = this.#node_pool.data_uint32[address + COLUMN_TREE_NODE_ELEMENT_COUNT];
+
+        if (element_count > THRESHOLD_SPLIT) {
+
+            this.#node_push_data_down(node);
+        } else if (element_count < THRESHOLD_MERGE) {
+            this.#node_pull_data();
+        }
+    }
+
+    /**
+     *
+     * @param {number} node
+     * @param {number[]|Uint32Array} destination
+     * @param {number} destination_offset
+     * @return {number} number of elements read
+     */
+    node_read_elements(node, destination, destination_offset) {
+        const node_address = this.#node_pool.element_word(node);
+
+        let element = this.#node_pool.data_uint32[node_address + COLUMN_TREE_NODE_FIRST_ELEMENT_NODE_POINTER];
+
+        let count = 0;
+
+        while (element !== QT_NULL_POINTER) {
+            destination[destination_offset + count] = element;
+
+            count++;
+
+            const element_address = this.#element_pool.element_word(element);
+            element = this.#element_pool.data_uint32[element_address + COLUMN_ELEMENT_NEXT];
+        }
+
+        return count;
+    }
+
+    /**
+     * Take elements owned by the element and attempt to push them as deep as possible
+     * This operation may create new nodes
+     * @param {number} node
+     */
+    #node_push_data_down(node) {
+
+    }
+
+    #node_pull_data() {
+
+    }
+
+    /**
+     *
+     * @param {number} node
+     * @param {number} element
+     */
+    #insert_element_into(node, element) {
+
+        const node_pool = this.#node_pool;
+        const node_address = node_pool.element_word(node);
+
+        // increment node count
+        node_pool[node_address + COLUMN_TREE_NODE_ELEMENT_COUNT]++;
+
+        let _element = node_pool.data_uint32[node_address + COLUMN_TREE_NODE_FIRST_ELEMENT_NODE_POINTER];
+
+        const element_pool = this.#element_pool;
+
+        if (_element === QT_NULL_POINTER) {
+            // first element
+            node_pool.data_uint32[node_address + COLUMN_TREE_NODE_FIRST_ELEMENT_NODE_POINTER] = element;
+        } else {
+            // scan to the last element
+            let _link = _element;
+
+            for (; ;) {
+                const address = element_pool.element_word(_link);
+                const next = element_pool.data_uint32[address + COLUMN_ELEMENT_NEXT];
+                if (next === QT_NULL_POINTER) {
+                    // end of the list is found
+                    element_pool.data_uint32[address + COLUMN_ELEMENT_NEXT] = element;
+                    break;
+                }
+                _link = next;
+            }
+
+        }
+
+
+        // patch links on the element
+        const element_address = element_pool.element_word(element);
+        element_pool.data_uint32[element_address + COLUMN_ELEMENT_PARENT_NODE] = node;
+    }
+
+    /**
+     *
+     * @param {number} datum_id ID of data in tree
+     */
+    element_remove(datum_id) {
+
+        const element_pool = this.#element_pool;
+        const element_word = element_pool.element_word(datum_id);
+
+        const tree_node_id = element_pool.data_uint32[element_word + COLUMN_ELEMENT_PARENT_NODE];
+
+        this.#tree_node_remove_element(tree_node_id, datum_id);
+    }
+
+    /**
+     *
+     * @param {number} node
+     * @return {boolean}
+     */
+    #is_node_empty(node) {
+        const pool = this.#node_pool;
+        const word = pool.element_word(node);
+
+        const uint32 = pool.data_uint32;
+
+        const first_element_node = uint32[word + COLUMN_TREE_NODE_FIRST_ELEMENT_NODE_POINTER]
+
+        if (first_element_node !== QT_NULL_POINTER) {
+            return false;
+        }
+
+        const has_allocated_children = uint32[word + COLUMN_TREE_NODE_CHILDREN_POINTER_TL] !== QT_NULL_POINTER
+            || uint32[word + COLUMN_TREE_NODE_CHILDREN_POINTER_TR] !== QT_NULL_POINTER
+            || uint32[word + COLUMN_TREE_NODE_CHILDREN_POINTER_BL] !== QT_NULL_POINTER
+            || uint32[word + COLUMN_TREE_NODE_CHILDREN_POINTER_BR] !== QT_NULL_POINTER;
+
+        return !has_allocated_children;
+    }
+
+    /**
+     * Assumes the node is empty
+     * Does not perform any checks
+     * Only updates parent node
+     * @param {number} node
+     * @returns {number} parent of this node
+     */
+    #remove_node(node) {
+
+        const pool = this.#node_pool;
+        const word = pool.element_word(node);
+
+        const uint32 = pool.data_uint32;
+
+        // let's remove reference from the parent to this node
+        const parent = uint32[word + COLUMN_TREE_NODE_PARENT];
+
+        if (parent !== QT_NULL_POINTER) {
+            // not root
+            const parent_word = pool.element_word(parent);
+
+            if (uint32[parent_word + COLUMN_TREE_NODE_CHILDREN_POINTER_TL] === node) {
+                uint32[parent_word + COLUMN_TREE_NODE_CHILDREN_POINTER_TL] = QT_NULL_POINTER;
+            } else if (uint32[parent_word + COLUMN_TREE_NODE_CHILDREN_POINTER_TR] === node) {
+                uint32[parent_word + COLUMN_TREE_NODE_CHILDREN_POINTER_TR] = QT_NULL_POINTER;
+            } else if (uint32[parent_word + COLUMN_TREE_NODE_CHILDREN_POINTER_BL] === node) {
+                uint32[parent_word + COLUMN_TREE_NODE_CHILDREN_POINTER_BL] = QT_NULL_POINTER;
+            } else if (uint32[parent_word + COLUMN_TREE_NODE_CHILDREN_POINTER_BR] === node) {
+                uint32[parent_word + COLUMN_TREE_NODE_CHILDREN_POINTER_BR] = QT_NULL_POINTER;
+            } else {
+                throw new Error(`specified 'parent' node(${parent}) does not point to this node(${node})`);
+            }
+
+        } else {
+            // we are root
+            this.#root = QT_NULL_POINTER;
+        }
+
+        // de-allocate self
+        pool.release(node);
+
+        return parent;
+    }
+
+    /**
+     * Remove node if it's empty, propagates up the parent chain if possible
+     * @param {number} node
+     * @returns {boolean} true if collapsed
+     */
+    #try_remove_node(node) {
+
+        let n = node;
+
+        while (n !== QT_NULL_POINTER && this.#is_node_empty(n)) {
+            // at this point we store no data and have no children, node is useless and can be reclaimed
+            n = this.#remove_node(n);
+        }
+
+        return true;
+    }
+
+    /**
+     * NOTE: This method does NOT do de-allocation
+     * @param {number} node ID of tree node
+     * @param {number} element ID of inserted element
+     * @returns {boolean} if element was found and cut
+     */
+    #tree_node_remove_element(
+        node,
+        element
+    ) {
+
+        assert.isNonNegativeInteger(node, 'tree_node_id');
+        assert.isNonNegativeInteger(element, 'element_id');
+
+        const node_pool = this.#node_pool;
+
+        const node_address = node_pool.element_word(node);
+
+        let element_node_pointer = node_pool.data_uint32[node_address + COLUMN_TREE_NODE_FIRST_ELEMENT_NODE_POINTER];
+        let previous_node_pointer = QT_NULL_POINTER;
+
+        const element_pool = this.#element_pool;
+
+        while (element_node_pointer !== QT_NULL_POINTER) {
+            const element_node_word = element_pool.element_word(element_node_pointer);
+
+            const next_element_pointer = element_pool.data_uint32[element_node_word + COLUMN_ELEMENT_NEXT];
+
+            if (element_node_pointer === element) {
+                // found the right element
+
+                node_pool.data_uint32[node_address + COLUMN_TREE_NODE_ELEMENT_COUNT]--;
+
+                if (previous_node_pointer === QT_NULL_POINTER) {
+                    // this was the first element in the list
+                    node_pool.data_uint32[node_address + COLUMN_TREE_NODE_FIRST_ELEMENT_NODE_POINTER] = next_element_pointer;
+                    // this might be the last element in the list, try to clean-up node if possible
+                    this.#try_remove_node(node);
+                } else {
+                    // patch previous element to point to the next element
+                    const previous_node_word = element_pool.element_word(previous_node_pointer);
+
+                    element_pool.data_uint32[previous_node_word + COLUMN_ELEMENT_NEXT] = next_element_pointer;
+                }
+
+
+                return true;
+            }
+
+            previous_node_pointer = element_node_pointer;
+
+            element_node_pointer = next_element_pointer;
+        }
+
+        // element not found
+        return false;
+    }
+
+    /**
+     * Remove all data
+     */
+    release_all() {
+        this.#root = QT_NULL_POINTER;
+        this.#element_pool.clear();
+        this.#node_pool.clear();
+    }
+}

package/src/core/geom/2d/quad-tree-binary/QuadTree.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=QuadTree.spec.d.ts.map

package/src/core/geom/2d/quad-tree-binary/QuadTree.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuadTree.spec.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/quad-tree-binary/QuadTree.spec.js"],"names":[],"mappings":""}