@woosh/meep-engine 2.34.31 → 2.34.35

package/core/assert.js

@@ -316,6 +316,17 @@ assert.defined = function (value, name = "value") {
 
 };
 
+/**
+ *
+ * @param {*} value
+ * @param {String} [name]
+ */
+assert.isNull = function (value, name){
+    if (value !== null) {
+        throw new Error(`${name} is NOT null`);
+    }
+}
+
 /**
  *
  * @param {*} value

package/core/bvh2/BinaryNode.js

@@ -8,7 +8,7 @@ import { arrayQuickSort } from "../collection/array/arrayQuickSort.js";
 import { max2 } from "../math/max2.js";
 import { min2 } from "../math/min2.js";
 import { computeSampleStandardDeviation } from "../math/statistics/computeSampleStandardDeviation.js";
-import { aabb3_intersect_aabb3, boxSurfaceArea2 } from "./aabb3/AABB3Math.js";
+import { _boxSurfaceArea2, aabb3_intersect_aabb3, boxSurfaceArea2 } from "./aabb3/AABB3Math.js";
 import { isLeaf, LeafNode } from "./LeafNode.js";
 import { Node } from "./Node.js";
 import { surfaceAreaHeuristic } from "./sah/surfaceAreaHeuristic.js";
@@ -139,13 +139,135 @@ BinaryNode.prototype.setChildren = function (left, right) {
     right.parentNode = this;
 };
 
+/**
+ *
+ * @param {Node} child
+ */
+BinaryNode.prototype.setChildLeft = function (child) {
+    assert.isNull(this.left, 'left');
+
+    this.left = child;
+
+    this.updateLeafNodeCount();
+
+    this.refit();
+
+    child.parentNode = this;
+}
+
+/**
+ *
+ * @param {Node} child
+ */
+BinaryNode.prototype.setChildRight = function (child) {
+    assert.isNull(this.right, 'right');
+
+    this.right = child;
+
+    this.updateLeafNodeCount();
+
+    this.refit();
+
+    child.parentNode = this;
+}
+
+/**
+ * @see "Dynamic BVH" by Erin Catto / Blizzard
+ * @param {AABB3} node
+ * @param {AABB3} addition
+ * @returns {number}
+ */
+function inclusion_surface_area_heuristic(node, addition) {
+    const x0 = min2(node.x0, addition.x0);
+    const y0 = min2(node.y0, addition.y0);
+    const z0 = min2(node.z0, addition.z0);
+
+    const x1 = max2(node.x1, addition.x1);
+    const y1 = max2(node.y1, addition.y1);
+    const z1 = max2(node.z1, addition.z1);
+
+    return _boxSurfaceArea2(x0, y0, z0, x1, y1, z1) - boxSurfaceArea2(node);
+}
+
+/**
+ *
+ * @param {BinaryNode|LeafNode} node
+ * @param {AABB3} addition
+ */
+function inclusion_cost_lower_bound(node, addition) {
+    let n = node;
+    let r = boxSurfaceArea2(addition);
+
+    while (n !== null) {
+
+        r += n.costForInclusion(addition);
+
+        n = n.parentNode;
+    }
+
+    return r;
+}
+
+/**
+ * For incremental insertion, a sibling needs to be found, newly inserted node will be parented together with this sibling
+ * @param {AABB3} box
+ * @returns {BinaryNode|LeafNode}
+ */
+BinaryNode.prototype.__insertion_findSiblingFor = function (box) {
+
+    const open_set = [this];
+    let cursor = 1;
+
+    let best_cost = Infinity;
+    let best_node = this;
+
+    while (cursor > 0) {
+        const node = open_set[--cursor];
+
+        const cost = inclusion_surface_area_heuristic(node, box);
+
+        if (cost < best_cost) {
+            best_cost = cost;
+            best_node = node;
+        }
+
+        if (node.isBinaryNode) {
+
+            if (node.isProtected()) {
+                continue;
+            }
+
+            // consider pushing children into the queue
+
+            // compute lower bound for cost
+            const c_low = inclusion_cost_lower_bound(node, box);
+
+            if (c_low < best_cost) {
+                // worth-while to explore children
+                if (node.left !== null) {
+                    open_set[cursor++] = node.left;
+                }
+                if (node.right !== null) {
+                    open_set[cursor++] = node.right
+                }
+            }
+        }
+
+
+    }
+
+    return best_node;
+}
+
 /**
  *
  * @param {AABB3} box
- * @returns {Node}
+ * @returns {Node|BinaryNode|LeafNode}
  */
 BinaryNode.prototype.findParentFor = function (box) {
     let n = this;
+    let aCost = 0;
+    let bCost = 0;
 
     for (; ;) {
 
@@ -181,8 +303,8 @@ BinaryNode.prototype.findParentFor = function (box) {
             }
         }
 
-        let aCost = a.costForInclusion(box);
-        let bCost = b.costForInclusion(box);
+        aCost = a.costForInclusion(box);
+        bCost = b.costForInclusion(box);
 
         if (aCost === bCost) {
 
@@ -196,9 +318,9 @@ BinaryNode.prototype.findParentFor = function (box) {
 
             }
 
-            //change costs to be surface areas instead
-            aCost = a.computeSAH();
-            bCost = b.computeSAH();
+            //change costs to be based on balance
+            aCost = a.leafNodeCount / boxSurfaceArea2(a);
+            bCost = b.leafNodeCount / boxSurfaceArea2(b);
         }
 
         if (aCost === bCost) {
@@ -419,11 +541,12 @@ BinaryNode.prototype.bubbleRefit = function () {
         n = n.parentNode;
 
         if (n === null) {
+            // hit the root
             return;
         }
 
-        //check if this node violates bounds of the parent
 
+        //check if this node violates bounds of the parent
         let flag = false;
 
         if (_x0 < n.x0) {
@@ -518,26 +641,29 @@ function countLeaves(node) {
 }
 
 /**
- *
+ * @deprecated Incorrect usage of SAH
  * @return {number}
  */
 BinaryNode.prototype.computeSAH = function () {
     let leftLeaves, rightLeaves, leftArea, rightArea;
 
-    if (this.left === null) {
+    const left = this.left;
+
+    if (left === null) {
         leftArea = 0;
         leftLeaves = 0;
     } else {
-        leftArea = boxSurfaceArea2(this.left);
-        leftLeaves = this.left.leafNodeCount;
+        leftArea = boxSurfaceArea2(left);
+        leftLeaves = left.leafNodeCount;
     }
 
-    if (this.right === null) {
+    const right = this.right;
+    if (right === null) {
         rightArea = 0;
         rightLeaves = 0;
     } else {
-        rightArea = boxSurfaceArea2(this.right);
-        rightLeaves = this.right.leafNodeCount;
+        rightArea = boxSurfaceArea2(right);
+        rightLeaves = right.leafNodeCount;
     }
 
     const thisArea = boxSurfaceArea2(this);
@@ -1065,34 +1191,96 @@ function transplantNewCommonParent(node, child) {
 
     parent.bubbleExpandToFit(bNode);
 
+    parent.updateLeafNodeCount();
+
     return bNode;
 }
 
+
 /**
  *
  * @param {Node|BinaryNode|LeafNode} child
  */
 BinaryNode.prototype.insertNode = function (child) {
-    assert.notEqual(child, null, "child node is null");
-    assert.notEqual(child, undefined, "child node is undefined");
-    assert.ok(child instanceof Node, undefined, "child node is not an instance of Node");
+
+    assert.notNull(child, "child");
+    assert.defined(child, "child");
+    assert.isInstanceOf(child, Node, 'child', "Node");
+    assert.equal(child.parentNode, null, "parentNode must be null, otherwise Node still belongs to another tree");
+
+    const sibling = this.__insertion_findSiblingFor(child);
+
+    const sibling_parent = sibling.parentNode;
+    if (sibling_parent === null) {
+        // root node
+
+        if (sibling.left === null) {
+            sibling.setChildLeft(child);
+        } else if (sibling.right === null) {
+            sibling.setChildRight(child);
+        } else {
+            const parent = new BinaryNode();
+
+            parent.setChildren(sibling.right, child);
+            sibling.right = parent;
+            parent.parentNode = sibling;
+        }
+
+    } else {
+
+        // non-root
+
+        if (sibling_parent.left === sibling && sibling_parent.right === null) {
+
+            // right node is free, take it
+            sibling_parent.setChildRight(child);
+
+        } else if (sibling_parent.right === sibling && sibling_parent.left === null) {
+
+            // left node is free, take it
+            sibling_parent.setChildLeft(child);
+
+        } else {
+
+            transplantNewCommonParent(sibling, child)
+
+        }
+
+        sibling_parent.bubbleRefit();
+
+    }
+}
+
+/**
+ * @deprecated
+ * @param {Node|BinaryNode|LeafNode} child
+ */
+BinaryNode.prototype.insertNode_old = function (child) {
+    assert.notNull(child, "child");
+    assert.defined(child, "child");
+    assert.isInstanceOf(child, Node, 'child', "Node");
     assert.equal(child.parentNode, null, "parentNode must be null, otherwise Node still belongs to another tree");
 
     const node = this.findParentFor(child);
 
     let bNode;
 
-    if (node.isBinaryNode) {
-        if ((node.isProtected() && node !== this)) {
-            transplantNewCommonParent(node, child);
-        } else if (node.left === null) {
+    if (
+        node.isBinaryNode &&
+        !(node.isProtected() && node !== this) // protected node, can't insert into this subtree
+    ) {
+
+        if (node.left === null) {
             node.left = child;
             child.parentNode = node;
             node.bubbleExpandToFit(child);
+
         } else if (node.right === null) {
+
             node.right = child;
             child.parentNode = node;
             node.bubbleExpandToFit(child);
+
         } else {
             //take right child and insert another binary node there
             bNode = new BinaryNode();
@@ -1106,18 +1294,17 @@ BinaryNode.prototype.insertNode = function (child) {
         node.updateLeafNodeCount();
     } else {
         //need to do transplanting and introduce a new common parent
-        bNode = transplantNewCommonParent(node, child);
+        transplantNewCommonParent(node, child);
 
-        bNode.updateLeafNodeCount();
     }
 
 };
 
 /**
- *
+ * @param {boolean} deep
  * @returns {BinaryNode}
  */
-BinaryNode.prototype.clone = function (deep) {
+BinaryNode.prototype.clone = function (deep = false) {
     const clone = new BinaryNode();
 
     clone.x0 = this.x0;

package/core/bvh2/Node.d.ts

@@ -3,4 +3,7 @@ import {BinaryNode} from "./BinaryNode";
 
 export class Node<T> extends AABB3 {
     public parentNode: BinaryNode<T>
+
+
+    readonly leafNodeCount: number
 }

package/core/bvh2/aabb3/AABB3.js

@@ -6,7 +6,7 @@
 import { aabb3_computeDistanceAbovePlane } from "../../geom/3d/aabb/aabb3_computeDistanceAbovePlane.js";
 import { computeAABB3PlaneSide } from "../../geom/3d/aabb/computeAABB3PlaneSide.js";
 import computeMortonCode from "../../geom/3d/morton/Morton.js";
-import { _boxSurfaceArea2, intersectRay, intersectSegment } from "./AABB3Math.js";
+import { boxSurfaceArea, intersectRay, intersectSegment } from "./AABB3Math.js";
 import { aabb3_build_corners } from "../../geom/3d/aabb/aabb3_build_corners.js";
 import { assert } from "../../assert.js";
 
@@ -81,7 +81,7 @@ AABB3.prototype.computeMortonCode = function () {
  * @returns {number}
  */
 AABB3.prototype.computeSurfaceArea = function () {
-    return _boxSurfaceArea2(this.x0, this.y0, this.z0, this.x1, this.y1, this.z1);
+    return boxSurfaceArea(this.x0, this.y0, this.z0, this.x1, this.y1, this.z1);
 };
 
 /**
@@ -296,7 +296,8 @@ AABB3.prototype.costForInclusion = function (other) {
 };
 
 /**
- *
+ * Surface area delta when including a given AABB
+ * 0 means that including a given AABB would not cause any change to total surface area
  * @param {number} x0
  * @param {number} y0
  * @param {number} z0

package/core/bvh2/aabb3/AABB3Math.js

@@ -540,7 +540,7 @@ function boxSurfaceArea(x0, y0, z0, x1, y1, z1) {
     const dx = x1 - x0;
     const dy = y1 - y0;
     const dz = z1 - z0;
-    return (dx * dy + dy * dz + dz * dx) * 2; //2 of each side
+    return (dy * (dx + dz) + dz * dx) * 2; //2 of each side
 }
 
 /**

package/core/bvh2/transform/RotationOptimizer.js

@@ -1,8 +1,7 @@
-import { boxSurfaceArea2 as computeArea, scoreBoxesSAH as computeAreaFor2 } from "../aabb3/AABB3Math.js";
 import { BinaryNode } from "../BinaryNode.js";
 import { isLeaf } from "../LeafNode.js";
-import { surfaceAreaHeuristic as sah } from "../sah/surfaceAreaHeuristic.js";
 import { StacklessTraverser } from "../StacklessTraverser.js";
+import { tryRotateSingleNode } from "./tryRotateSingleNode.js";
 
 
 /**
@@ -73,266 +72,12 @@ function getLeafCount(node, leafCounts) {
     return result;
 }
 
-/**
- *
- * @param {Node} node
- * @param {BinaryNode} parent
- */
-function setParent(node, parent) {
-    node.parentNode = parent;
-}
-
-/**
- * Based on paper "Fast, Effective BVH Updates for Animated Scenes" Kopta et. al. (url: http://www.cs.utah.edu/~thiago/papers/rotations.pdf)
- * @param {BinaryNode} node
- * @param {Map.<NodeDescription,int>} leafCounts
- * @returns {int} value from 0 to 6, 0 means no rotation has taken place
- */
-function tryRotateSingleNode(node, leafCounts) {
-
-
-    const left = node.left;
-    const right = node.right;
-
-    if (left === null || right === null) {
-        return 0;
-    }
-
-    let bestRotation = 0;
-
-
-    const nodeArea = computeArea(node);
-    const leftArea = computeArea(left);
-    const rightArea = computeArea(right);
-
-    const leftLeaves = left.leafNodeCount;
-    const rightLeaves = right.leafNodeCount;
-
-
-    let bestCost = sah(
-        nodeArea,
-        leftArea,
-        rightArea,
-        leftLeaves,
-        rightLeaves
-    );
-
-    let candidateCost;
-
-    let leftLeftArea,
-        leftRightArea,
-        rightLeftArea,
-        rightRightArea;
-
-    let leftLeft,
-        leftRight,
-        rightLeft,
-        rightRight;
-
-    let leftLeftLeaves,
-        leftRightLeaves,
-        rightLeftLeaves,
-        rightRightLeaves;
-
-    let considerLeft = !isLeaf(left);
-
-    if (considerLeft) {
-        leftLeft = left.left;
-        leftRight = left.right;
-
-        considerLeft = (leftLeft !== null && leftRight !== null);
-        if (considerLeft) {
-
-            leftLeftArea = computeArea(leftLeft);
-            leftRightArea = computeArea(leftRight);
-
-            leftLeftLeaves = leftLeft.leafNodeCount;
-            leftRightLeaves = leftRight.leafNodeCount;
-
-            // (1)    N                     N      //
-            //       / \                   / \     //
-            //      L   R     ----->      L   LL   //
-            //     / \                   / \       //
-            //   LL   LR                R   LR     //
-            candidateCost = sah(nodeArea, computeAreaFor2(right, leftRight), leftLeftArea, rightLeaves + leftRightLeaves, leftLeftLeaves);
-
-            if (candidateCost < bestCost) {
-                bestRotation = 1;
-                bestCost = candidateCost;
-            }
-
-            // (2)    N                     N      //
-            //       / \                   / \     //
-            //      L   R     ----->      L   LR   //
-            //     / \                   / \       //
-            //   LL   LR               LL   R      //
-            candidateCost = sah(nodeArea, computeAreaFor2(leftLeft, right), leftRightArea, leftLeftLeaves + rightLeaves, leftRightLeaves);
-
-
-            if (candidateCost < bestCost) {
-                bestRotation = 2;
-                bestCost = candidateCost;
-            }
-        }
-    }
-    if (!isLeaf(right)) {
-        rightLeft = right.left;
-        rightRight = right.right;
-        if (rightLeft !== null && rightRight !== null) {
-
-            rightLeftArea = computeArea(rightLeft);
-            rightRightArea = computeArea(rightRight);
-
-            rightLeftLeaves = rightLeft.leafNodeCount;
-            rightRightLeaves = rightRight.leafNodeCount;
-
-            // (3)    N                     N        //
-            //       / \                   / \       //
-            //      L   R     ----->     RL   R      //
-            //         / \                   / \     //
-            //       RL   RR                L   RR   //
-            candidateCost = sah(nodeArea, rightLeftArea, computeAreaFor2(left, rightRight), rightLeftLeaves, leftLeaves + rightRightLeaves);
-
-            if (candidateCost < bestCost) {
-                bestRotation = 3;
-                bestCost = candidateCost;
-            }
-
-            // (4)    N                     N       //
-            //       / \                   / \      //
-            //      L   R     ----->     RR   R     //
-            //         / \                   / \    //
-            //       RL   RR               RL   L   //
-            candidateCost = sah(nodeArea, rightRightArea, computeAreaFor2(rightLeft, left), rightRightLeaves, rightLeftLeaves + leftLeaves);
-
-
-            if (candidateCost < bestCost) {
-                bestRotation = 4;
-                bestCost = candidateCost;
-            }
-
-            if (considerLeft) {
-                //both child nodes are not leaf
-
-                // (5)       N                      N        //
-                //         /   \                  /   \      //
-                //        L     R     ----->     L     R     //
-                //       / \   / \              / \   / \    //
-                //      LL LR RL RR            LL RL LR RR   //
-                candidateCost = sah(
-                    nodeArea,
-                    computeAreaFor2(leftLeft, rightLeft),
-                    computeAreaFor2(leftRight, rightRight),
-                    leftLeftLeaves + rightLeftLeaves,
-                    leftRightLeaves + rightRightLeaves
-                );
-
-
-                if (candidateCost < bestCost) {
-                    bestRotation = 5;
-                    bestCost = candidateCost;
-                }
-
-                // (6)       N                      N        //
-                //         /   \                  /   \      //
-                //        L     R     ----->     L     R     //
-                //       / \   / \              / \   / \    //
-                //      LL LR RL RR            LL RR RL LR   //
-                candidateCost = sah(
-                    nodeArea,
-                    computeAreaFor2(leftLeft, rightRight),
-                    computeAreaFor2(rightLeft, leftRight),
-                    leftLeftLeaves + rightRightLeaves,
-                    rightLeftLeaves + leftRightLeaves
-                );
-
-                if (candidateCost < bestCost) {
-                    bestRotation = 6;
-                }
-            }
-        }
-    }
-
-    switch (bestRotation) {
-        case 0:
-            //no rotation
-            break;
-        case 1:
-            node.right = leftLeft;
-            setParent(leftLeft, node);
-            left.left = right;
-            setParent(right, left);
-
-            left.refit();
-            //update leaf count
-            node.left.updateLeafNodeCount();
-            break;
-        case 2:
-            node.right = leftRight;
-            setParent(leftRight, node);
-            left.right = right;
-            setParent(right, left);
-
-            left.refit();
-            //update leaf count
-            node.left.updateLeafNodeCount();
-            break;
-        case 3:
-            node.left = rightLeft;
-            setParent(rightLeft, node);
-            right.left = left;
-            setParent(left, right);
-
-            right.refit();
-            //update leaf count
-            node.right.updateLeafNodeCount();
-            break;
-        case 4:
-            node.left = rightRight;
-            setParent(rightRight, node);
-            right.right = left;
-            setParent(left, right);
-
-            right.refit();
-            //update leaf count
-            node.right.updateLeafNodeCount();
-            break;
-        case 5:
-            left.right = rightLeft;
-            setParent(rightLeft, left);
-            right.left = leftRight;
-            setParent(leftRight, right);
-
-            left.refit();
-            right.refit();
-
-            //update leaf count
-            node.left.updateLeafNodeCount();
-            node.right.updateLeafNodeCount();
-            break;
-        case 6:
-            left.right = rightRight;
-            setParent(rightRight, left);
-            right.right = leftRight;
-            setParent(leftRight, right);
-
-            left.refit();
-            right.refit();
-            //update leaf count
-            node.left.updateLeafNodeCount();
-            node.right.updateLeafNodeCount();
-            break;
-    }
-
-    return bestRotation;
-}
-
 /**
  *
  * @param {BinaryNode} root
  * @param {int} maxIterations
  */
-function optimize(root, maxIterations = 1000) {
+export function optimize(root, maxIterations = 1000) {
     const traverser = new StacklessTraverser();
 
     traverser.init(root);
@@ -376,8 +121,3 @@ function optimize(root, maxIterations = 1000) {
 
     return changeCounter;
 }
-
-export {
-    optimize,
-    tryRotateSingleNode
-};